agentxchain 2.147.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,17 @@ 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',
+  'HOME',
+  'PWD',
+  'SHELL',
+  'TMPDIR',
+  'AGENTXCHAIN_TURN_ID',
+];
+const DIAGNOSTIC_STDERR_EXCERPT_LIMIT = 800;
 
 /**
  * Launch a local CLI subprocess for a governed turn.
@@ -55,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;
 
@@ -76,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));
@@ -112,6 +124,25 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
   // Capture logs for dispatch record
   const logs = [];
+  const runtimeCwd = runtime.cwd ? join(root, runtime.cwd) : root;
+  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) {
@@ -121,12 +152,23 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
     let child;
     try {
+      appendDiagnostic(logs, 'spawn_prepare', {
+        runtime_id: runtimeId,
+        turn_id: turn.turn_id,
+        command,
+        args: diagnosticArgs,
+        cwd: runtimeCwd,
+        prompt_transport: transport,
+        stdin_bytes: stdinBytes,
+        env: pickDiagnosticEnv(spawnEnv),
+      });
       child = spawn(command, args, {
-        cwd: runtime.cwd ? join(root, runtime.cwd) : root,
+        cwd: runtimeCwd,
         stdio: ['pipe', 'pipe', 'pipe'],
-        env: { ...process.env, AGENTXCHAIN_TURN_ID: turn.turn_id },
+        env: spawnEnv,
       });
     } catch (err) {
+      appendDiagnostic(logs, 'spawn_error', normalizeDiagnosticError(err));
       resolve({
         ok: false,
         startupFailure: true,
@@ -139,10 +181,16 @@ 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;
     let startupWatchdog = null;
     let startupTimedOut = false;
     let startupFailureType = null;
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stderrExcerpt = '';
 
     const settle = (result) => {
       if (settled) return;
@@ -168,8 +216,14 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
         startupTimedOut = true;
         startupFailureType = 'no_subprocess_output';
         logs.push(`[adapter] Startup watchdog fired after ${Math.round(startupWatchdogMs / 1000)}s with no output.`);
-        try {
-          child.kill('SIGTERM');
+      appendDiagnostic(logs, 'startup_watchdog_fired', {
+        startup_watchdog_ms: startupWatchdogMs,
+        pid: child.pid ?? null,
+        spawn_confirmed_at: spawnConfirmedAt,
+        elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
+      });
+      try {
+        child.kill('SIGTERM');
         } catch {}
       }, startupWatchdogMs);
     };
@@ -177,7 +231,15 @@ 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', {
+        at: firstOutputAt,
+        stream,
+        pid: child.pid ?? null,
+        startup_latency_ms: firstOutputLatencyMs,
+      });
       if (onFirstOutput) {
         try {
           onFirstOutput({ pid: child.pid ?? null, at: firstOutputAt, stream });
@@ -186,7 +248,13 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     };
 
     child.once('spawn', () => {
+      spawnConfirmedAtMs = Date.now();
       spawnConfirmedAt = new Date().toISOString();
+      appendDiagnostic(logs, 'spawn_attached', {
+        pid: child.pid ?? null,
+        at: spawnConfirmedAt,
+        startup_watchdog_ms: startupWatchdogMs,
+      });
       if (onSpawnAttached) {
         try {
           onSpawnAttached({ pid: child.pid ?? null, at: spawnConfirmedAt });
@@ -197,18 +265,32 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
     // Deliver prompt via stdin if transport is "stdin"; otherwise close immediately
     if (child.stdin) {
+      child.stdin.on('error', (err) => {
+        appendDiagnostic(logs, 'stdin_error', {
+          at: new Date().toISOString(),
+          stdin_bytes: stdinBytes,
+          ...normalizeDiagnosticError(err),
+        });
+      });
       try {
         if (transport === 'stdin') {
           child.stdin.write(fullPrompt);
         }
         child.stdin.end();
-      } catch {}
+      } catch (err) {
+        appendDiagnostic(logs, 'stdin_error', {
+          at: new Date().toISOString(),
+          stdin_bytes: stdinBytes,
+          ...normalizeDiagnosticError(err),
+        });
+      }
     }
 
     // Collect stdout/stderr
     if (child.stdout) {
       child.stdout.on('data', (chunk) => {
         const text = chunk.toString();
+        stdoutBytes += Buffer.byteLength(text);
         recordFirstOutput('stdout');
         logs.push(text);
         if (onStdout) onStdout(text);
@@ -218,7 +300,8 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     if (child.stderr) {
       child.stderr.on('data', (chunk) => {
         const text = chunk.toString();
-        recordFirstOutput('stderr');
+        stderrBytes += Buffer.byteLength(text);
+        stderrExcerpt = appendDiagnosticExcerpt(stderrExcerpt, text, DIAGNOSTIC_STDERR_EXCERPT_LIMIT);
         logs.push('[stderr] ' + text);
         if (onStderr) onStderr(text);
       });
@@ -283,6 +366,34 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       if (hasResult && !firstOutputAt) {
         recordFirstOutput('staged_result');
       }
+      const exitDiagnostic = {
+        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) {
+        exitDiagnostic.startup_failure_type = 'runtime_spawn_failed';
+      } else if (timedOut) {
+        exitDiagnostic.timed_out = true;
+      } else if (!firstOutputAt) {
+        exitDiagnostic.startup_failure_type = 'no_subprocess_output';
+      }
+      appendDiagnostic(logs, 'process_exit', exitDiagnostic);
 
       if (hasResult) {
         settle({ ok: true, exitCode, timedOut: false, aborted: false, logs, firstOutputAt });
@@ -344,6 +455,25 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
       if (signal) signal.removeEventListener('abort', onAbort);
+      // BUG-54 hypothesis #1 fix: explicitly release stdio streams on the
+      // error path so Node reclaims pipe handles immediately instead of
+      // waiting for GC. Without this, repeated `runtime_spawn_failed` turns
+      // leak ~4 handles per failure until the next GC sweep, which in a
+      // long-running `run --continuous` session can push the parent process
+      // toward its fd limit and cascade additional spawn failures.
+      try { child.stdin?.destroy(); } catch {}
+      try { child.stdout?.destroy(); } catch {}
+      try { child.stderr?.destroy(); } catch {}
+      appendDiagnostic(logs, 'spawn_error', {
+        pid: child.pid ?? null,
+        spawn_confirmed_at: spawnConfirmedAt,
+        elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
+        first_output_at: firstOutputAt,
+        startup_latency_ms: firstOutputLatencyMs,
+        stdout_bytes: stdoutBytes,
+        stderr_bytes: stderrBytes,
+        ...normalizeDiagnosticError(err),
+      });
       settle({
         ok: false,
         startupFailure: !firstOutputAt,
@@ -440,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,
@@ -458,4 +598,48 @@ function resolveTargetTurn(state, turnId) {
   return state?.current_turn || Object.values(state?.active_turns || {})[0];
 }
 
+function appendDiagnostic(logs, label, payload) {
+  logs.push(`[adapter:diag] ${label} ${JSON.stringify(payload)}\n`);
+}
+
+function pickDiagnosticEnv(env) {
+  return Object.fromEntries(
+    DIAGNOSTIC_ENV_KEYS
+      .filter((key) => typeof env?.[key] === 'string' && env[key].length > 0)
+      .map((key) => [key, env[key]]),
+  );
+}
+
+function redactPromptArgs(args, fullPrompt, transport) {
+  const promptPlaceholder = `<prompt:${Buffer.byteLength(fullPrompt, 'utf8')} bytes>`;
+  return args.map((arg) => {
+    if (typeof arg !== 'string') {
+      return arg;
+    }
+    if (transport === 'argv' && arg === fullPrompt) {
+      return promptPlaceholder;
+    }
+    return arg;
+  });
+}
+
+function normalizeDiagnosticError(err) {
+  return {
+    code: err?.code || null,
+    errno: err?.errno || null,
+    syscall: err?.syscall || null,
+    message: err?.message || String(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 };