agentxchain 2.148.0 → 2.149.1

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());
@@ -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 = 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/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,21 @@ 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 = 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,
+      recommendation: claudeAuthIssue.fix,
+    });
+    return {
+      ok: false,
+      error: `${claudeAuthIssue.detail} ${claudeAuthIssue.fix}`,
+      logs,
+    };
+  }
 
   return new Promise((resolve) => {
     if (signal?.aborted) {
@@ -163,6 +181,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 +190,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 +231,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 +301,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 +370,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 +570,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 +632,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,61 @@
+const CLAUDE_ENV_AUTH_KEYS = [
+  'ANTHROPIC_API_KEY',
+  'CLAUDE_API_KEY',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_BEDROCK',
+];
+
+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);
+}
+
+export function getClaudeSubprocessAuthIssue(runtime, env = process.env) {
+  if (!isClaudeLocalCliRuntime(runtime)) {
+    return null;
+  }
+
+  if (hasClaudeBareFlag(runtime) || hasClaudeEnvAuth(env)) {
+    return null;
+  }
+
+  const auth_env_present = getClaudeEnvAuthPresence(env);
+  return {
+    auth_env_present,
+    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.',
+  };
+}
+
+export { CLAUDE_ENV_AUTH_KEYS, normalizeCommandTokens };

package/src/lib/connector-probe.js

@@ -4,6 +4,7 @@ import {
   PROVIDER_ENDPOINTS,
 } from './adapters/api-proxy-adapter.js';
 import { probeRuntimeSpawnContext } from './runtime-spawn-context.js';
+import { getClaudeSubprocessAuthIssue, normalizeCommandTokens } from './claude-local-auth.js';
 
 const PROBEABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
 const DEFAULT_TIMEOUT_MS = 8_000;
@@ -165,6 +166,38 @@ async function probeLocalCommand(runtimeId, runtime, probeKindLabel, options = {
   }
 
   const spawnProbe = probeRuntimeSpawnContext(options.root || process.cwd(), runtime, { runtimeId });
+  const claudeAuthIssue = getClaudeSubprocessAuthIssue(runtime);
+
+  // DEC-BUG54-CLAUDE-AUTH-PREFLIGHT-001 / DEC-BUG54-VALIDATE-AUTH-PREFLIGHT-001
+  // Auth-preflight is a config-shape defect that must fire regardless of whether
+  // the binary currently resolves on PATH. Matches connector-validate.js:108-138
+  // ordering: a Claude local_cli runtime with no env auth and no --bare is a
+  // deterministic hang-on-spawn shape the operator must fix before anything
+  // else. If they fix auth (or add --bare) but still do not have claude
+  // installed, the next connector check surfaces command_presence after they
+  // fix the config — that is the correct operator progression.
+  if (claudeAuthIssue) {
+    return {
+      ...base,
+      level: 'fail',
+      probe_kind: 'auth_preflight',
+      command: spawnProbe.command || head,
+      error_code: 'claude_auth_preflight_failed',
+      detail: claudeAuthIssue.detail,
+      fix: claudeAuthIssue.fix,
+      auth_env_present: claudeAuthIssue.auth_env_present,
+    };
+  }
+
+  if (!spawnProbe.ok) {
+    return {
+      ...base,
+      level: 'fail',
+      command: spawnProbe.command || head,
+      detail: spawnProbe.detail,
+    };
+  }
+
   if (spawnProbe.ok) {
     return {
       ...base,
@@ -173,13 +206,6 @@ async function probeLocalCommand(runtimeId, runtime, probeKindLabel, options = {
       detail: spawnProbe.detail,
     };
   }
-
-  return {
-    ...base,
-    level: 'fail',
-    command: spawnProbe.command || head,
-    detail: spawnProbe.detail,
-  };
 }
 
 async function probeApiProxy(runtimeId, runtime, timeoutMs) {
@@ -375,6 +401,7 @@ function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
   // Prompt transport validation
   const transport = runtime.prompt_transport || 'dispatch_bundle_only';
   const knownTransports = KNOWN_CLI_TRANSPORTS[binaryName];
+  const claudeAuthIssue = getClaudeSubprocessAuthIssue(runtime);
 
   if (transport === 'argv' && !commandTokens.some((token) => token.includes('{prompt}'))) {
     warnings.push({
@@ -395,24 +422,21 @@ function analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles) {
     });
   }
 
+  if (claudeAuthIssue) {
+    warnings.push({
+      probe_kind: 'auth_preflight',
+      level: 'warn',
+      detail: claudeAuthIssue.detail,
+      fix: claudeAuthIssue.fix,
+    });
+  }
+
   return { warnings };
 }
 
 /**
  * Normalize a runtime's command field into an array of tokens.
  */
-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 async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
   const roles = options.roles || null;
@@ -433,8 +457,11 @@ export async function probeConnectorRuntime(runtimeId, runtime, options = {}) {
     // Add authority-intent and transport analysis when roles are available
     if (roles) {
       const { warnings } = analyzeLocalCliAuthorityIntent(runtimeId, runtime, roles);
-      if (warnings.length > 0) {
-        result.authority_warnings = warnings;
+      const visibleWarnings = result.error_code === 'claude_auth_preflight_failed'
+        ? warnings.filter((warning) => warning.probe_kind !== 'auth_preflight')
+        : warnings;
+      if (visibleWarnings.length > 0) {
+        result.authority_warnings = visibleWarnings;
         // Promote result level to 'warn' if binary is present but authority intent is wrong
         if (result.level === 'pass') {
           result.level = 'warn';

package/src/lib/connector-validate.js

@@ -24,6 +24,7 @@ import { getDispatchPromptPath, getTurnStagingResultPath } from './turn-paths.js
 import { validateStagedTurnResult } from './turn-result-validator.js';
 import { probeRuntimeSpawnContext } from './runtime-spawn-context.js';
 import { buildConnectorSchemaContract } from './connector-schema-contract.js';
+import { getClaudeSubprocessAuthIssue } from './claude-local-auth.js';
 
 const VALIDATABLE_RUNTIME_TYPES = new Set(['local_cli', 'api_proxy', 'mcp', 'remote_agent']);
 const DEFAULT_VALIDATE_TIMEOUT_MS = 120_000;
@@ -104,6 +105,39 @@ export async function validateConfiguredConnector(sourceRoot, options = {}) {
     };
   }
 
+  // DEC-BUG54-CLAUDE-AUTH-PREFLIGHT-001 — refuse the known-hanging Claude
+  // local_cli shape before burning the scratch-workspace + synthetic-dispatch
+  // ceremony. The adapter also refuses this shape via `claude_auth_preflight_failed`,
+  // but the operator gets a faster, identical-fix message if we catch it here.
+  const claudeAuthIssue = getClaudeSubprocessAuthIssue(runtime);
+  if (claudeAuthIssue) {
+    return {
+      ok: false,
+      exitCode: 1,
+      overall: 'fail',
+      runtime_id: runtimeId,
+      runtime_type: runtime.type,
+      role_id: roleSelection.roleId,
+      timeout_ms: timeoutMs,
+      warnings: [
+        ...roleSelection.warnings,
+        {
+          probe_kind: 'auth_preflight',
+          level: 'fail',
+          detail: claudeAuthIssue.detail,
+          fix: claudeAuthIssue.fix,
+        },
+      ],
+      error_code: 'claude_auth_preflight_failed',
+      error: claudeAuthIssue.detail,
+      auth_env_present: claudeAuthIssue.auth_env_present,
+      fix: claudeAuthIssue.fix,
+      dispatch: null,
+      validation: null,
+      scratch_root: null,
+    };
+  }
+
   const tempBase = mkdtempSync(join(tmpdir(), 'axc-connector-validate-'));
   const scratchRoot = join(tempBase, 'workspace');
   const warnings = [...roleSelection.warnings];

package/src/lib/dispatch-progress.js

@@ -11,6 +11,10 @@
 
 import { writeFileSync, unlinkSync, readFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
+import {
+  isDispatchProgressDiagnosticStream,
+  isDispatchProgressProofOutputStream,
+} from './dispatch-streams.js';
 
 export const LEGACY_DISPATCH_PROGRESS_PATH = '.agentxchain/dispatch-progress.json';
 export const DISPATCH_PROGRESS_FILE_PREFIX = '.agentxchain/dispatch-progress-';
@@ -138,15 +142,37 @@ export function createDispatchProgressTracker(root, turn, options = {}) {
       const now = new Date().toISOString();
       const wasSilent = state.activity_type === 'silent';
       state.last_activity_at = now;
-      state.first_output_at = state.first_output_at || now;
-      state.activity_type = 'output';
-      state.silent_since = null;
-      if (stream === 'stderr') {
+      // DEC-BUG54-STDERR-IS-NOT-STARTUP-PROOF-002 (Turn 88) extended to the
+      // progress tracker in Turn 89: stderr is diagnostic evidence, not usable
+      // startup proof. Only stdout may set `first_output_at`. stderr still
+      // increments `stderr_lines` for silence detection and diagnostics.
+      let recognizedActivity = false;
+      if (isDispatchProgressDiagnosticStream(stream)) {
         state.stderr_lines += lineCount;
-      } else {
+        recognizedActivity = true;
+      } else if (isDispatchProgressProofOutputStream(stream)) {
+        state.first_output_at = state.first_output_at || now;
         state.output_lines += lineCount;
+        recognizedActivity = true;
+      }
+      // DEC-BUG54-DIAGNOSTIC-ACTIVITY-TYPE-001 (Turn 91): activity_type and
+      // activity_summary must reflect whether operator-usable stdout proof has
+      // arrived. A stderr-only subprocess that never attached stdout must NOT
+      // be rendered as "Producing output" on the operator status surface —
+      // that is a false live-progress signal for a failing startup. Only when
+      // `output_lines > 0` may we claim 'output'; otherwise recognized stderr
+      // activity is surfaced as 'diagnostic_only'. Unknown stream labels do
+      // not mutate activity_type (Turn 90 closed-vocabulary contract).
+      if (recognizedActivity) {
+        if (state.output_lines > 0) {
+          state.activity_type = 'output';
+          state.activity_summary = `Producing output (${state.output_lines} lines)`;
+        } else {
+          state.activity_type = 'diagnostic_only';
+          state.activity_summary = `Diagnostic output only (${state.stderr_lines} stderr lines)`;
+        }
+        state.silent_since = null;
       }
-      state.activity_summary = `Producing output (${state.output_lines} lines)`;
       dirty = true;
       maybeWrite();
       if (adapter_type === 'local_cli') {