agentxchain 2.148.0 → 2.149.2

package/src/commands/connector.js

@@ -5,6 +5,17 @@ import { DEFAULT_VALIDATE_TIMEOUT_MS, validateConfiguredConnector } from '../lib
 import { DEFAULT_TIMEOUT_MS, probeConfiguredConnectors } from '../lib/connector-probe.js';
 import { buildRuntimeCapabilityReport } from '../lib/runtime-capabilities.js';
 
+function warningDetail(warning) {
+  if (typeof warning === 'string') {
+    return warning;
+  }
+  return warning?.detail || JSON.stringify(warning);
+}
+
+function warningFix(warning) {
+  return typeof warning === 'object' && warning?.fix ? warning.fix : null;
+}
+
 function printJson(result, exitCode) {
   console.log(JSON.stringify(result, null, 2));
   process.exit(exitCode);
@@ -49,11 +60,15 @@ function printText(result, exitCode) {
       console.log(`        ${chalk.dim('Time:')}   ${connector.latency_ms}ms`);
     }
     console.log(`        ${chalk.dim('Detail:')} ${connector.detail}`);
+    if (connector.fix) {
+      console.log(`        ${chalk.dim('Fix:')}    ${connector.fix}`);
+    }
     if (Array.isArray(connector.authority_warnings) && connector.authority_warnings.length > 0) {
       for (const warning of connector.authority_warnings) {
-        console.log(`        ${chalk.yellow('⚠')} ${warning.detail}`);
-        if (warning.fix) {
-          console.log(`          ${chalk.dim('Fix:')} ${warning.fix}`);
+        console.log(`        ${chalk.yellow('⚠')} ${warningDetail(warning)}`);
+        const fix = warningFix(warning);
+        if (fix) {
+          console.log(`          ${chalk.dim('Fix:')} ${fix}`);
         }
       }
     }
@@ -161,7 +176,11 @@ function printValidateText(result, exitCode) {
   if (Array.isArray(result.warnings) && result.warnings.length > 0) {
     console.log('');
     for (const warning of result.warnings) {
-      console.log(`  ${chalk.yellow('!')} ${warning}`);
+      console.log(`  ${chalk.yellow('!')} ${warningDetail(warning)}`);
+      const fix = warningFix(warning);
+      if (fix) {
+        console.log(`    ${chalk.dim('Fix:')} ${fix}`);
+      }
     }
   }
 

package/src/commands/doctor.js

@@ -21,6 +21,7 @@ import { detectActiveTurnBindingDrift, detectStateBundleDesync } from '../lib/go
 import { findPendingApprovedIntents } from '../lib/intake.js';
 import { checkCleanBaseline } from '../lib/repo-observer.js';
 import { probeRuntimeSpawnContext } from '../lib/runtime-spawn-context.js';
+import { getClaudeSubprocessAuthIssue } from '../lib/claude-local-auth.js';
 
 export async function doctorCommand(opts = {}) {
   const root = findProjectRoot(process.cwd());
@@ -58,7 +59,7 @@ export async function doctorCommand(opts = {}) {
 
 // ── Governed (v4) Doctor ────────────────────────────────────────────────────
 
-function governedDoctor(root, rawConfig, opts) {
+async function governedDoctor(root, rawConfig, opts) {
   const checks = [];
   const cliVersionHealth = getCliVersionHealth();
   let stateRunId = null;
@@ -92,7 +93,7 @@ function governedDoctor(root, rawConfig, opts) {
   const runtimes = (normalized && normalized.runtimes) || rawConfig.runtimes || {};
   const rolesByRuntime = buildRolesByRuntime(normalized?.roles || {});
   for (const [rtId, rt] of Object.entries(runtimes)) {
-    const check = checkRuntimeReachable(root, rtId, rt, rolesByRuntime[rtId] || []);
+    const check = await checkRuntimeReachable(root, rtId, rt, rolesByRuntime[rtId] || []);
     checks.push(check);
   }
   const connectorProbe = getConnectorProbeRecommendation(runtimes);
@@ -487,7 +488,7 @@ function buildCliVersionCheck(cliVersionHealth) {
   };
 }
 
-function checkRuntimeReachable(root, rtId, rt, boundRoleEntries = []) {
+async function checkRuntimeReachable(root, rtId, rt, boundRoleEntries = []) {
   const base = { id: `runtime_${rtId}`, name: `Runtime: ${rtId}` };
 
   if (!rt || !rt.type) {
@@ -500,6 +501,16 @@ function checkRuntimeReachable(root, rtId, rt, boundRoleEntries = []) {
 
     case 'local_cli': {
       const probe = probeRuntimeSpawnContext(root, rt, { runtimeId: rtId });
+      if (probe.ok) {
+        const claudeAuthIssue = await getClaudeSubprocessAuthIssue(rt);
+        if (claudeAuthIssue) {
+          return attachRuntimeContract({
+            ...base,
+            level: 'warn',
+            detail: `${probe.detail} ${claudeAuthIssue.detail} ${claudeAuthIssue.fix}`,
+          }, rtId, rt, boundRoleEntries);
+        }
+      }
       return attachRuntimeContract({ ...base, level: probe.ok ? 'pass' : 'fail', detail: probe.detail }, rtId, rt, boundRoleEntries);
     }
 

package/src/commands/init.js

@@ -98,7 +98,7 @@ const GOVERNED_ROLES = {
 
 const DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME = Object.freeze({
   type: 'local_cli',
-  command: ['claude', '--print', '--dangerously-skip-permissions'],
+  command: ['claude', '--print', '--dangerously-skip-permissions', '--bare'],
   cwd: '.',
   prompt_transport: 'stdin',
 });

package/src/commands/run.js

@@ -25,6 +25,7 @@ import { validateParentRun } from '../lib/run-history.js';
 import { dispatchApiProxy } from '../lib/adapters/api-proxy-adapter.js';
 import {
   dispatchLocalCli,
+  resolveStartupWatchdogMs,
   saveDispatchLogs,
   resolvePromptTransport,
 } from '../lib/adapters/local-cli-adapter.js';
@@ -52,6 +53,7 @@ import { emitRunEvent } from '../lib/run-events.js';
 import { checkpointAcceptedTurn } from '../lib/turn-checkpoint.js';
 import { failTurnStartup } from '../lib/stale-turn-watchdog.js';
 import { hasMinimumTurnResultShape } from '../lib/turn-result-shape.js';
+import { isKnownTurnRunningProofStream } from '../lib/dispatch-streams.js';
 
 export async function runCommand(opts) {
   const context = loadProjectContext();
@@ -343,7 +345,10 @@ export async function executeGovernedRun(context, opts = {}) {
         });
       };
 
-      const ensureRunningState = (stream = 'stdout', at = new Date().toISOString()) => {
+      const ensureRunningState = (stream = null, at = new Date().toISOString()) => {
+        if (stream != null && !isKnownTurnRunningProofStream(stream)) {
+          return;
+        }
         if (runningMarked) return;
         runningMarked = true;
         transitionActiveTurnLifecycle(projectRoot, turn.turn_id, 'running', { stream, at });
@@ -359,7 +364,16 @@ export async function executeGovernedRun(context, opts = {}) {
       };
 
       const recordOutputActivity = (stream, text) => {
-        ensureRunningState(stream);
+        // DEC-BUG54-STDERR-IS-NOT-STARTUP-PROOF-002 (Turn 88) extended to the
+        // run-command lifecycle in Turn 89: stderr activity must NOT promote a
+        // turn from `starting` to `running`. stdout (or the adapter's
+        // onFirstOutput callback, which is stdout/staged_result only post-Turn
+        // 88) is the only signal that satisfies the lifecycle transition.
+        // stderr is still tracked by the progress tracker for silence detection
+        // and operator diagnostics.
+        if (stream != null && isKnownTurnRunningProofStream(stream)) {
+          ensureRunningState(stream);
+        }
         const lines = text.split('\n').length - 1 || 1;
         const wasSilent = tracker.onOutput(stream, lines);
         if (wasSilent) {
@@ -473,9 +487,10 @@ export async function executeGovernedRun(context, opts = {}) {
 
       if (adapterResult.startupFailure) {
         const freshState = loadProjectState(projectRoot, cfg) || state;
+        const startupThresholdMs = resolveStartupWatchdogMs(cfg, runtime);
         failTurnStartup(projectRoot, freshState, cfg, turn.turn_id, {
           failure_type: adapterResult.startupFailureType || 'no_subprocess_output',
-          threshold_ms: cfg?.run_loop?.startup_watchdog_ms ?? 30_000,
+          threshold_ms: startupThresholdMs,
           running_ms: freshState?.active_turns?.[turn.turn_id]?.started_at
             ? Math.max(0, Date.now() - new Date(freshState.active_turns[turn.turn_id].started_at).getTime())
             : 0,

package/src/commands/status.js

@@ -383,7 +383,7 @@ function renderGovernedStatus(context, opts) {
         console.log(`      ${chalk.dim('     or:')} ${chalk.cyan(`agentxchain accept-turn --turn ${turn.turn_id}`)} — re-attempt acceptance`);
       }
       if (turn.status === 'failed_start') {
-        console.log(`      ${chalk.dim('Reason:')}  ${turn.failed_start_reason || 'no_subprocess_output'}`);
+        console.log(`      ${chalk.dim('Reason:')}  ${normalizeStartupFailureReasonForDisplay(turn.failed_start_reason)}`);
         const recover = turn.recovery_command || `agentxchain reissue-turn --turn ${turn.turn_id} --reason ghost`;
         console.log(`      ${chalk.dim('Recover:')} ${chalk.cyan(recover)}`);
       }
@@ -443,7 +443,7 @@ function renderGovernedStatus(context, opts) {
       console.log(`  ${chalk.dim('     or:')}  ${chalk.cyan(mergeAction.command)}`);
     }
     if (singleActiveTurn.status === 'failed_start') {
-      console.log(`  ${chalk.dim('Reason:')}   ${singleActiveTurn.failed_start_reason || 'no_subprocess_output'}`);
+      console.log(`  ${chalk.dim('Reason:')}   ${normalizeStartupFailureReasonForDisplay(singleActiveTurn.failed_start_reason)}`);
       const recover = singleActiveTurn.recovery_command || `agentxchain reissue-turn --turn ${singleActiveTurn.turn_id} --reason ghost`;
       console.log(`  ${chalk.dim('Recover:')}  ${chalk.cyan(recover)}`);
     }
@@ -883,6 +883,24 @@ function pluralizeRepoDecisionCount(count, singular, plural) {
   return `${count} ${count === 1 ? singular : plural}`;
 }
 
+// BUG-54 vocabulary discipline (`DEC-BUG54-OPERATOR-SUBTYPE-DISPLAY-001`).
+// Operator-facing status surfaces must render a typed startup-failure subtype,
+// not the raw adapter signal `no_subprocess_output`. Public docs
+// (website-v2/docs/cli.mdx) only document `runtime_spawn_failed` and
+// `stdout_attach_failed` as the operator-visible subtypes; the `no_subprocess_output`
+// label is an internal adapter/classification fallback and must not leak to the
+// CLI status display. The adapter semantics for `no_subprocess_output` ("we
+// watched for stdout and saw none inside the startup watchdog window") are
+// identical to the operator subtype `stdout_attach_failed`, so that is the
+// correct display normalization.
+const TYPED_STARTUP_FAILURE_SUBTYPES = new Set(['runtime_spawn_failed', 'stdout_attach_failed']);
+function normalizeStartupFailureReasonForDisplay(rawReason) {
+  if (typeof rawReason === 'string' && TYPED_STARTUP_FAILURE_SUBTYPES.has(rawReason)) {
+    return rawReason;
+  }
+  return 'stdout_attach_failed';
+}
+
 function filterDispatchProgressForActiveTurns(progressByTurn, activeTurns) {
   const filtered = {};
   if (!progressByTurn || typeof progressByTurn !== 'object') {
@@ -897,7 +915,7 @@ function filterDispatchProgressForActiveTurns(progressByTurn, activeTurns) {
   return filtered;
 }
 
-function formatDispatchActivityLine(progress) {
+export function formatDispatchActivityLine(progress) {
   if (!progress || typeof progress !== 'object') return null;
   const lastAct = progress.last_activity_at ? new Date(progress.last_activity_at) : null;
   const agoSec = lastAct && !Number.isNaN(lastAct.getTime())
@@ -918,6 +936,15 @@ function formatDispatchActivityLine(progress) {
   if (progress.activity_type === 'response') {
     return chalk.green('API response received');
   }
+  // DEC-BUG54-DIAGNOSTIC-ACTIVITY-TYPE-001 (Turn 91): stderr-only activity
+  // must be rendered as yellow "Diagnostic output only" — never as the green
+  // "Producing output" signal that previously leaked onto the operator
+  // surface for failing-startup subprocesses whose stdout never attached.
+  if (progress.activity_type === 'diagnostic_only') {
+    const agoLabel = agoSec != null && agoSec > 0 ? `, last ${agoSec}s ago` : '';
+    return chalk.yellow('Diagnostic output only') +
+      ` (${progress.stderr_lines || 0} stderr lines, no stdout yet${agoLabel})`;
+  }
   const agoLabel = agoSec != null && agoSec > 0 ? `, last ${agoSec}s ago` : '';
   return chalk.green('Producing output') + ` (${progress.output_lines || 0} lines${agoLabel})`;
 }

package/src/commands/step.js

@@ -49,6 +49,7 @@ import {
 } from '../lib/adapters/manual-adapter.js';
 import {
   dispatchLocalCli,
+  resolveStartupWatchdogMs,
   saveDispatchLogs,
   resolvePromptTransport,
 } from '../lib/adapters/local-cli-adapter.js';
@@ -73,6 +74,7 @@ import { shouldSuggestManualQaFallback } from '../lib/manual-qa-fallback.js';
 import { evaluateApprovalSlaReminders } from '../lib/notification-runner.js';
 import { consumeNextApprovedIntent } from '../lib/intake.js';
 import { failTurnStartup, reconcileStaleTurns } from '../lib/stale-turn-watchdog.js';
+import { isKnownTurnRunningProofStream } from '../lib/dispatch-streams.js';
 
 export async function stepCommand(opts) {
   const context = loadProjectContext();
@@ -697,7 +699,10 @@ export async function stepCommand(opts) {
         state = starting.state;
       }
     };
-    const ensureRunningState = (stream = 'stdout', at = new Date().toISOString()) => {
+    const ensureRunningState = (stream = null, at = new Date().toISOString()) => {
+      if (stream != null && !isKnownTurnRunningProofStream(stream)) {
+        return;
+      }
       if (runningMarked) return;
       runningMarked = true;
       const running = transitionActiveTurnLifecycle(root, turn.turn_id, 'running', { stream, at });
@@ -756,9 +761,10 @@ export async function stepCommand(opts) {
 
     if (cliResult.startupFailure) {
       const freshState = loadProjectState(root, config) || state;
+      const startupThresholdMs = resolveStartupWatchdogMs(config, runtime);
       const failed = failTurnStartup(root, freshState, config, turn.turn_id, {
         failure_type: cliResult.startupFailureType || 'no_subprocess_output',
-        threshold_ms: config?.run_loop?.startup_watchdog_ms ?? 30_000,
+        threshold_ms: startupThresholdMs,
         running_ms: freshState?.active_turns?.[turn.turn_id]?.started_at
           ? Math.max(0, Date.now() - new Date(freshState.active_turns[turn.turn_id].started_at).getTime())
           : 0,

package/src/lib/adapters/local-cli-adapter.js

@@ -30,6 +30,7 @@ import {
 } from '../turn-paths.js';
 import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
 import { hasMeaningfulStagedResult } from '../staged-result-proof.js';
+import { getClaudeSubprocessAuthIssue } from '../claude-local-auth.js';
 
 const DIAGNOSTIC_ENV_KEYS = [
   'PATH',
@@ -39,6 +40,7 @@ const DIAGNOSTIC_ENV_KEYS = [
   'TMPDIR',
   'AGENTXCHAIN_TURN_ID',
 ];
+const DIAGNOSTIC_STDERR_EXCERPT_LIMIT = 800;
 
 /**
  * Launch a local CLI subprocess for a governed turn.
@@ -64,7 +66,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     onStderr,
     onSpawnAttached,
     onFirstOutput,
-    startupWatchdogMs = config?.run_loop?.startup_watchdog_ms ?? 30_000,
+    startupWatchdogMs: startupWatchdogOverrideMs,
     turnId,
   } = options;
 
@@ -85,6 +87,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
   if (!runtime) {
     return { ok: false, error: `Runtime "${runtimeId}" not found in config` };
   }
+  const startupWatchdogMs = startupWatchdogOverrideMs ?? resolveStartupWatchdogMs(config, runtime);
 
   // Read the dispatch bundle prompt
   const promptPath = join(root, getDispatchPromptPath(turn.turn_id));
@@ -125,6 +128,22 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
   const spawnEnv = { ...process.env, AGENTXCHAIN_TURN_ID: turn.turn_id };
   const stdinBytes = transport === 'stdin' ? Buffer.byteLength(fullPrompt, 'utf8') : 0;
   const diagnosticArgs = redactPromptArgs(args, fullPrompt, transport);
+  const claudeAuthIssue = await getClaudeSubprocessAuthIssue(runtime, spawnEnv);
+
+  if (claudeAuthIssue) {
+    appendDiagnostic(logs, 'claude_auth_preflight_failed', {
+      runtime_id: runtimeId,
+      turn_id: turn.turn_id,
+      auth_env_present: claudeAuthIssue.auth_env_present,
+      smoke_probe: claudeAuthIssue.smoke_probe,
+      recommendation: claudeAuthIssue.fix,
+    });
+    return {
+      ok: false,
+      error: `${claudeAuthIssue.detail} ${claudeAuthIssue.fix}`,
+      logs,
+    };
+  }
 
   return new Promise((resolve) => {
     if (signal?.aborted) {
@@ -163,6 +182,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
     let settled = false;
     let firstOutputAt = null;
+    let firstOutputStream = null;
     let spawnConfirmedAt = null;
     let spawnConfirmedAtMs = null;
     let firstOutputLatencyMs = null;
@@ -171,6 +191,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     let startupFailureType = null;
     let stdoutBytes = 0;
     let stderrBytes = 0;
+    let stderrExcerpt = '';
 
     const settle = (result) => {
       if (settled) return;
@@ -211,6 +232,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     const recordFirstOutput = (stream) => {
       if (firstOutputAt) return;
       firstOutputAt = new Date().toISOString();
+      firstOutputStream = stream;
       firstOutputLatencyMs = spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs);
       clearStartupWatchdog();
       appendDiagnostic(logs, 'first_output', {
@@ -280,7 +302,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       child.stderr.on('data', (chunk) => {
         const text = chunk.toString();
         stderrBytes += Buffer.byteLength(text);
-        recordFirstOutput('stderr');
+        stderrExcerpt = appendDiagnosticExcerpt(stderrExcerpt, text, DIAGNOSTIC_STDERR_EXCERPT_LIMIT);
         logs.push('[stderr] ' + text);
         if (onStderr) onStderr(text);
       });
@@ -349,14 +371,20 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
         pid: child.pid ?? null,
         exit_code: exitCode,
         signal: killSignal,
+        exit_signal: killSignal,
         spawn_confirmed_at: spawnConfirmedAt,
         elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
         first_output_at: firstOutputAt,
+        first_output_stream: firstOutputStream,
         startup_latency_ms: firstOutputLatencyMs,
         stdout_bytes: stdoutBytes,
         stderr_bytes: stderrBytes,
         staged_result_ready: hasResult,
+        watchdog_fired: startupTimedOut,
       };
+      if (stderrExcerpt) {
+        exitDiagnostic.stderr_excerpt = stderrExcerpt;
+      }
       if (startupTimedOut) {
         exitDiagnostic.startup_failure_type = startupFailureType || 'no_subprocess_output';
       } else if (!spawnConfirmedAt) {
@@ -543,6 +571,16 @@ function resolvePromptTransport(runtime) {
   return hasPlaceholder ? 'argv' : 'dispatch_bundle_only';
 }
 
+function resolveStartupWatchdogMs(config, runtime) {
+  if (runtime?.type === 'local_cli' && Number.isInteger(runtime?.startup_watchdog_ms) && runtime.startup_watchdog_ms > 0) {
+    return runtime.startup_watchdog_ms;
+  }
+  if (Number.isInteger(config?.run_loop?.startup_watchdog_ms) && config.run_loop.startup_watchdog_ms > 0) {
+    return config.run_loop.startup_watchdog_ms;
+  }
+  return 30_000;
+}
+
 /**
  * Check if the staged result file exists and has meaningful content.
  * Delegates to the shared `hasMeaningfulStagedResult` helper so watchdog,
@@ -595,4 +633,14 @@ function normalizeDiagnosticError(err) {
   };
 }
 
+function appendDiagnosticExcerpt(existing, chunk, limit) {
+  const combined = `${existing}${chunk}`;
+  if (combined.length <= limit) {
+    return combined;
+  }
+  return combined.slice(combined.length - limit);
+}
+
+export { resolveCommand };
 export { resolvePromptTransport };
+export { resolveStartupWatchdogMs };

package/src/lib/claude-local-auth.js

@@ -0,0 +1,237 @@
+import { spawn } from 'node:child_process';
+
+const CLAUDE_ENV_AUTH_KEYS = [
+  'ANTHROPIC_API_KEY',
+  'CLAUDE_API_KEY',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_BEDROCK',
+];
+
+const DEFAULT_SMOKE_PROBE_TIMEOUT_MS = 10_000;
+const DEFAULT_SMOKE_PROBE_STDIN = 'ok';
+
+function normalizeCommandTokens(runtime) {
+  if (Array.isArray(runtime?.command)) {
+    return runtime.command.flatMap((element) =>
+      typeof element === 'string' ? element.trim().split(/\s+/).filter(Boolean) : []
+    );
+  }
+  if (typeof runtime?.command === 'string' && runtime.command.trim()) {
+    return runtime.command.trim().split(/\s+/).filter(Boolean);
+  }
+  return [];
+}
+
+export function isClaudeLocalCliRuntime(runtime) {
+  const tokens = normalizeCommandTokens(runtime);
+  if (tokens.length === 0) {
+    return false;
+  }
+  const head = tokens[0].toLowerCase();
+  return head === 'claude' || head.endsWith('/claude');
+}
+
+export function hasClaudeBareFlag(runtime) {
+  return normalizeCommandTokens(runtime).includes('--bare');
+}
+
+export function getClaudeEnvAuthPresence(env = process.env) {
+  return Object.fromEntries(
+    CLAUDE_ENV_AUTH_KEYS.map((key) => [key, Boolean(env?.[key])]),
+  );
+}
+
+export function hasClaudeEnvAuth(env = process.env) {
+  return Object.values(getClaudeEnvAuthPresence(env)).some(Boolean);
+}
+
+function buildClaudeSubprocessAuthIssue(env, smokeProbe = null) {
+  const auth_env_present = getClaudeEnvAuthPresence(env);
+  return {
+    auth_env_present,
+    smoke_probe: smokeProbe,
+    detail: 'Claude local_cli runtime has no env-based auth and is missing "--bare"; non-interactive subprocesses can hang on macOS keychain reads.',
+    fix: 'Export ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN before running AgentXchain, or add "--bare" to the Claude command if you intentionally want env-only auth.',
+  };
+}
+
+function resolveSmokeProbeTimeoutMs(env, options = {}) {
+  if (Number.isFinite(options?.timeoutMs) && options.timeoutMs > 0) {
+    return options.timeoutMs;
+  }
+  const raw = env?.AGENTXCHAIN_CLAUDE_AUTH_PROBE_TIMEOUT_MS;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_SMOKE_PROBE_TIMEOUT_MS;
+}
+
+export async function getClaudeSubprocessAuthIssue(runtime, env = process.env, options = {}) {
+  if (!isClaudeLocalCliRuntime(runtime)) {
+    return null;
+  }
+
+  if (hasClaudeBareFlag(runtime) || hasClaudeEnvAuth(env)) {
+    return null;
+  }
+
+  const smokeProbe = await runClaudeSmokeProbe({
+    runtime,
+    env,
+    timeoutMs: resolveSmokeProbeTimeoutMs(env, options),
+    stdinPayload: options?.stdinPayload,
+    spawnImpl: options?.spawnImpl,
+  });
+
+  if (smokeProbe.kind === 'stdout_observed' || smokeProbe.kind === 'spawn_error' || smokeProbe.kind === 'skipped') {
+    return null;
+  }
+
+  if (smokeProbe.kind === 'hang' || smokeProbe.kind === 'exit_nonzero' || smokeProbe.kind === 'stderr_only') {
+    return buildClaudeSubprocessAuthIssue(env, smokeProbe);
+  }
+
+  return null;
+}
+
+/**
+ * Bounded smoke probe that spawns the runtime's actual Claude command with a
+ * tiny prompt on stdin and a watchdog. Returns a classification:
+ *
+ *   { kind: 'stdout_observed' }      — real stdout arrived before watchdog;
+ *                                      the setup is NOT hanging on auth.
+ *   { kind: 'hang', elapsed_ms }     — watchdog fired with no stdout/stderr
+ *                                      bytes; the keychain-hang shape (BUG-54).
+ *   { kind: 'stderr_only', ... }     — process wrote stderr but no stdout
+ *                                      before watchdog (auth error or similar).
+ *   { kind: 'exit_nonzero', ... }    — process exited non-zero with no stdout
+ *                                      (explicit auth failure — not a hang).
+ *   { kind: 'spawn_error', ... }     — spawn itself failed (ENOENT / EPERM).
+ *   { kind: 'skipped', reason }      — probe disabled or unavailable.
+ *
+ * This is the positive-case-testable alternative to the static shape-check in
+ * `getClaudeSubprocessAuthIssue`: it observes what the subprocess actually
+ * does rather than predicting what it *might* do from config shape alone.
+ *
+ * Added 2026-04-21 for the BUG-56 false-positive fix. See
+ * `.planning/BUG_56_FALSE_POSITIVE_RETRO.md` for the decision trail.
+ *
+ * @param {{ runtime: object, env?: object, timeoutMs?: number, stdinPayload?: string, spawnImpl?: Function }} opts
+ * @returns {Promise<object>}
+ */
+export async function runClaudeSmokeProbe(opts) {
+  const runtime = opts?.runtime ?? null;
+  const env = opts?.env ?? process.env;
+  const timeoutMs = Number.isFinite(opts?.timeoutMs) ? opts.timeoutMs : DEFAULT_SMOKE_PROBE_TIMEOUT_MS;
+  const stdinPayload = typeof opts?.stdinPayload === 'string' ? opts.stdinPayload : DEFAULT_SMOKE_PROBE_STDIN;
+  const spawnImpl = typeof opts?.spawnImpl === 'function' ? opts.spawnImpl : spawn;
+
+  if (!isClaudeLocalCliRuntime(runtime)) {
+    return { kind: 'skipped', reason: 'not_claude_local_cli' };
+  }
+
+  const tokens = normalizeCommandTokens(runtime);
+  if (tokens.length === 0) {
+    return { kind: 'skipped', reason: 'empty_command' };
+  }
+  const [command, ...args] = tokens;
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl(command, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env,
+      });
+    } catch (error) {
+      resolve({
+        kind: 'spawn_error',
+        errno: error?.errno ?? null,
+        code: error?.code ?? null,
+        message: error?.message ?? String(error),
+      });
+      return;
+    }
+
+    if (!child || typeof child.on !== 'function') {
+      resolve({ kind: 'spawn_error', code: 'NO_CHILD_HANDLE', message: 'spawn returned no child handle' });
+      return;
+    }
+
+    const start = Date.now();
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stderrBuf = '';
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      try { child.kill('SIGTERM'); } catch { /* ignore */ }
+      resolve(result);
+    };
+
+    const watchdog = setTimeout(() => {
+      const elapsed_ms = Date.now() - start;
+      if (stdoutBytes > 0) {
+        finish({ kind: 'stdout_observed', elapsed_ms });
+      } else if (stderrBytes > 0) {
+        finish({ kind: 'stderr_only', elapsed_ms, stderr_snippet: stderrBuf.slice(0, 500) });
+      } else {
+        finish({ kind: 'hang', elapsed_ms });
+      }
+    }, timeoutMs);
+    if (typeof watchdog.unref === 'function') watchdog.unref();
+
+    child.stdout?.on('data', (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > 0 && !settled) {
+        clearTimeout(watchdog);
+        finish({ kind: 'stdout_observed', elapsed_ms: Date.now() - start });
+      }
+    });
+
+    child.stderr?.on('data', (chunk) => {
+      stderrBytes += chunk.length;
+      stderrBuf += chunk.toString('utf8');
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(watchdog);
+      finish({
+        kind: 'spawn_error',
+        errno: error?.errno ?? null,
+        code: error?.code ?? null,
+        message: error?.message ?? String(error),
+      });
+    });
+
+    child.on('exit', (code, signal) => {
+      if (settled) return;
+      clearTimeout(watchdog);
+      const elapsed_ms = Date.now() - start;
+      if (stdoutBytes > 0) {
+        finish({ kind: 'stdout_observed', elapsed_ms });
+      } else if (code !== 0) {
+        finish({
+          kind: 'exit_nonzero',
+          elapsed_ms,
+          exit_code: code,
+          exit_signal: signal,
+          stderr_snippet: stderrBuf.slice(0, 500),
+        });
+      } else if (stderrBytes > 0) {
+        finish({ kind: 'stderr_only', elapsed_ms, stderr_snippet: stderrBuf.slice(0, 500) });
+      } else {
+        finish({ kind: 'hang', elapsed_ms });
+      }
+    });
+
+    try {
+      child.stdin?.end(`${stdinPayload}\n`);
+    } catch {
+      // best-effort; error will surface via 'error' event if real
+    }
+  });
+}
+
+export { CLAUDE_ENV_AUTH_KEYS, normalizeCommandTokens };