fix(dev): detect and skip container runtime shims that masquerade as real runtimes

The container runtime detection previously only checked `which` + `--version`
to validate a runtime. Toolbox shims (e.g., ~/.toolbox/bin/finch wrapping ada)
pass both checks but don't support container operations like build/run.

Add a `build --help` probe after the version check. Skip the runtime if:
- The probe exits with non-zero code, OR
- The probe exits 0 but stderr contains "unknown command" or "not found"
  (handles shims that always exit 0 regardless of errors)

Constraint: Cannot use `docker info` as it requires daemon access and triggers password prompts
Rejected: Only checking exit code | ada shim exits 0 for all commands
Confidence: high
Scope-risk: narrow
Not-tested: Shims that swallow stderr entirely (would need stdout content validation)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jesseturner21

src/cli/external-requirements/__tests__/detect.test.ts

@@ -20,6 +20,7 @@ describe('detectContainerRuntime', () => {
     mockCheckSubprocess.mockResolvedValue(true);
     mockRunSubprocessCapture.mockImplementation((_bin: string, args: string[]) => {
       if (args[0] === '--version') return Promise.resolve({ code: 0, stdout: 'Docker version 24.0.0\n', stderr: '' });
+      if (args[0] === 'build') return Promise.resolve({ code: 0, stdout: '', stderr: '' });
       return Promise.resolve({ code: 1, stdout: '', stderr: '' });
     });
 
@@ -36,6 +37,7 @@ describe('detectContainerRuntime', () => {
     mockRunSubprocessCapture.mockImplementation((bin: string, args: string[]) => {
       if (bin === 'podman' && args[0] === '--version')
         return Promise.resolve({ code: 0, stdout: 'podman version 4.5.0\n', stderr: '' });
+      if (bin === 'podman' && args[0] === 'build') return Promise.resolve({ code: 0, stdout: '', stderr: '' });
       return Promise.resolve({ code: 1, stdout: '', stderr: '' });
     });
 
@@ -57,6 +59,7 @@ describe('detectContainerRuntime', () => {
       if (bin === 'docker' && args[0] === '--version') return Promise.resolve({ code: 1, stdout: '', stderr: 'error' });
       if (bin === 'podman' && args[0] === '--version')
         return Promise.resolve({ code: 0, stdout: 'podman version 4.5.0\n', stderr: '' });
+      if (bin === 'podman' && args[0] === 'build') return Promise.resolve({ code: 0, stdout: '', stderr: '' });
       // finch --version also fails
       if (bin === 'finch' && args[0] === '--version') return Promise.resolve({ code: 1, stdout: '', stderr: 'error' });
       return Promise.resolve({ code: 1, stdout: '', stderr: '' });
@@ -71,6 +74,7 @@ describe('detectContainerRuntime', () => {
     mockRunSubprocessCapture.mockImplementation((_bin: string, args: string[]) => {
       if (args[0] === '--version')
         return Promise.resolve({ code: 0, stdout: 'Docker version 24.0.0\nExtra info line\n', stderr: '' });
+      if (args[0] === 'build') return Promise.resolve({ code: 0, stdout: '', stderr: '' });
       return Promise.resolve({ code: 1, stdout: '', stderr: '' });
     });
 
@@ -82,6 +86,7 @@ describe('detectContainerRuntime', () => {
     mockCheckSubprocess.mockResolvedValue(true);
     mockRunSubprocessCapture.mockImplementation((_bin: string, args: string[]) => {
       if (args[0] === '--version') return Promise.resolve({ code: 0, stdout: '', stderr: '' });
+      if (args[0] === 'build') return Promise.resolve({ code: 0, stdout: '', stderr: '' });
       return Promise.resolve({ code: 1, stdout: '', stderr: '' });
     });
 
@@ -90,20 +95,30 @@ describe('detectContainerRuntime', () => {
     expect(result.runtime?.version).toBe('');
   });
 
-  it('does not call docker info to check daemon status', async () => {
+  it('skips runtime when build --help check fails with non-zero exit', async () => {
     mockCheckSubprocess.mockResolvedValue(true);
     mockRunSubprocessCapture.mockImplementation((_bin: string, args: string[]) => {
-      if (args[0] === '--version') return Promise.resolve({ code: 0, stdout: 'Docker version 24.0.0\n', stderr: '' });
+      if (args[0] === '--version') return Promise.resolve({ code: 0, stdout: '1.0.0\n', stderr: '' });
+      if (args[0] === 'build') return Promise.resolve({ code: 1, stdout: '', stderr: 'unknown command "build"' });
       return Promise.resolve({ code: 1, stdout: '', stderr: '' });
     });
 
-    await detectContainerRuntime();
+    const result = await detectContainerRuntime();
+    expect(result.runtime).toBeNull();
+  });
+
+  it('skips runtime when build --help exits 0 but stderr indicates unknown command (shim/wrapper)', async () => {
+    mockCheckSubprocess.mockResolvedValue(true);
+    mockRunSubprocessCapture.mockImplementation((_bin: string, args: string[]) => {
+      // Shim exits 0 for everything but prints error to stderr
+      if (args[0] === '--version') return Promise.resolve({ code: 0, stdout: '1.0.0\n', stderr: '' });
+      if (args[0] === 'build')
+        return Promise.resolve({ code: 0, stdout: '', stderr: 'Error: unknown command "build" for "ada"' });
+      return Promise.resolve({ code: 0, stdout: '', stderr: '' });
+    });
 
-    // Verify 'info' was never called — this is the key behavioral change
-    const infoCalls = mockRunSubprocessCapture.mock.calls.filter(
-      (call: unknown[]) => (call[1] as string[])[0] === 'info'
-    );
-    expect(infoCalls).toHaveLength(0);
+    const result = await detectContainerRuntime();
+    expect(result.runtime).toBeNull();
   });
 });
 
@@ -112,6 +127,7 @@ describe('requireContainerRuntime', () => {
     mockCheckSubprocess.mockResolvedValue(true);
     mockRunSubprocessCapture.mockImplementation((_bin: string, args: string[]) => {
       if (args[0] === '--version') return Promise.resolve({ code: 0, stdout: 'Docker version 24.0.0\n', stderr: '' });
+      if (args[0] === 'build') return Promise.resolve({ code: 0, stdout: '', stderr: '' });
       return Promise.resolve({ code: 1, stdout: '', stderr: '' });
     });
 

src/cli/external-requirements/detect.ts

@@ -20,11 +20,8 @@ export interface DetectionResult {
 
 /**
  * Detect available container runtime.
- * Checks docker, podman, finch in order; returns the first that is installed.
- * Does not probe the daemon (e.g., `docker info`) — that would require socket
- * access and can trigger OS password prompts on systems where the user is not
- * in the docker group. Actual daemon availability is validated when the runtime
- * is used (build, run, etc.).
+ * Checks docker, podman, finch in order; returns the first that is installed
+ * and capable of running container operations.
  */
 export async function detectContainerRuntime(): Promise<DetectionResult> {
   for (const runtime of CONTAINER_RUNTIMES) {
@@ -36,6 +33,14 @@ export async function detectContainerRuntime(): Promise<DetectionResult> {
     const result = await runSubprocessCapture(runtime, ['--version']);
     if (result.code !== 0) continue;
 
+    // Validate the binary actually supports container operations.
+    // Some environments have shims (e.g., toolbox wrappers) that respond to
+    // --version but don't support build/run commands. These shims may exit 0
+    // even on failure, so also check stderr for error indicators.
+    const buildCheck = await runSubprocessCapture(runtime, ['build', '--help']);
+    if (buildCheck.code !== 0) continue;
+    if (buildCheck.stderr && /unknown command|not found/i.test(buildCheck.stderr)) continue;
+
     const version = result.stdout.trim().split('\n')[0] ?? 'unknown';
     return { runtime: { runtime, binary: runtime, version } };
   }