agentxchain 2.146.0 → 2.148.0

package/src/commands/status.js

@@ -382,6 +382,16 @@ function renderGovernedStatus(context, opts) {
         console.log(`      ${chalk.dim('Recover:')} ${chalk.cyan(`agentxchain reject-turn --turn ${turn.turn_id}`)} — reject and retry`);
         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'}`);
+        const recover = turn.recovery_command || `agentxchain reissue-turn --turn ${turn.turn_id} --reason ghost`;
+        console.log(`      ${chalk.dim('Recover:')} ${chalk.cyan(recover)}`);
+      }
+      if (turn.status === 'stalled') {
+        console.log(`      ${chalk.dim('Reason:')}  ${turn.stalled_reason || 'no_output_within_threshold'}`);
+        const recover = turn.recovery_command || `agentxchain reissue-turn --turn ${turn.turn_id} --reason stale`;
+        console.log(`      ${chalk.dim('Recover:')} ${chalk.cyan(recover)}`);
+      }
     }
   } else if (singleActiveTurn) {
     console.log(`  ${chalk.dim('Turn:')}     ${singleActiveTurn.turn_id}`);
@@ -432,6 +442,16 @@ function renderGovernedStatus(context, opts) {
       console.log(`  ${chalk.dim('Resolve:')}  ${chalk.cyan(reassignAction.command)}`);
       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'}`);
+      const recover = singleActiveTurn.recovery_command || `agentxchain reissue-turn --turn ${singleActiveTurn.turn_id} --reason ghost`;
+      console.log(`  ${chalk.dim('Recover:')}  ${chalk.cyan(recover)}`);
+    }
+    if (singleActiveTurn.status === 'stalled') {
+      console.log(`  ${chalk.dim('Reason:')}   ${singleActiveTurn.stalled_reason || 'no_output_within_threshold'}`);
+      const recover = singleActiveTurn.recovery_command || `agentxchain reissue-turn --turn ${singleActiveTurn.turn_id} --reason stale`;
+      console.log(`  ${chalk.dim('Recover:')}  ${chalk.cyan(recover)}`);
+    }
   } else {
     console.log(`  ${chalk.dim('Turn:')}     ${chalk.yellow('No active turn')}`);
   }

package/src/commands/step.js

@@ -35,7 +35,9 @@ import {
   getActiveTurnCount,
   getActiveTurns,
   reactivateGovernedRun,
+  reconcilePhaseAdvanceBeforeDispatch,
   refreshTurnBaselineSnapshot,
+  transitionActiveTurnLifecycle,
   STATE_PATH,
 } from '../lib/governed-state.js';
 import { getMaxConcurrentTurns } from '../lib/normalized-config.js';
@@ -70,7 +72,7 @@ import { resolveGovernedRole } from '../lib/role-resolution.js';
 import { shouldSuggestManualQaFallback } from '../lib/manual-qa-fallback.js';
 import { evaluateApprovalSlaReminders } from '../lib/notification-runner.js';
 import { consumeNextApprovedIntent } from '../lib/intake.js';
-import { reconcileStaleTurns } from '../lib/stale-turn-watchdog.js';
+import { failTurnStartup, reconcileStaleTurns } from '../lib/stale-turn-watchdog.js';
 
 export async function stepCommand(opts) {
   const context = loadProjectContext();
@@ -260,39 +262,14 @@ export async function stepCommand(opts) {
       printDispatchBundleWarnings(bundleResult);
     }
 
-    // Handle paused + failed/retrying turn → re-dispatch
-    if (!skipAssignment && state.status === 'paused' && activeCount > 0) {
-      const pausedTurn = targetTurn || Object.values(activeTurns)[0];
-      const turnStatus = pausedTurn?.status;
-      if (turnStatus === 'failed' || turnStatus === 'retrying') {
-        console.log(chalk.yellow(`Re-dispatching failed turn: ${pausedTurn.turn_id}`));
-        const reactivated = reactivateGovernedRun(root, state, { via: 'step --resume', notificationConfig: config });
-        if (!reactivated.ok) {
-          console.log(chalk.red(`Failed to reactivate run: ${reactivated.error}`));
-          process.exit(1);
-        }
-        state = reactivated.state;
-        if (reactivated.migration_notice) {
-          console.log(chalk.yellow(reactivated.migration_notice));
-        }
-        if (reactivated.phantom_notice) {
-          console.log(chalk.yellow(reactivated.phantom_notice));
-        }
-        skipAssignment = true;
-
-        // BUG-1 fix: refresh baseline snapshot to capture files dirtied between assignment and dispatch
-        refreshTurnBaselineSnapshot(root, pausedTurn.turn_id);
-        state = JSON.parse(readFileSync(join(root, '.agentxchain/state.json'), 'utf8'));
-
-        const bundleResult = writeDispatchBundle(root, state, config);
-        if (!bundleResult.ok) {
-          console.log(chalk.red(`Failed to write dispatch bundle: ${bundleResult.error}`));
-          process.exit(1);
-        }
-        bundleWritten = true;
-        printDispatchBundleWarnings(bundleResult);
-      }
-    }
+    // Removed (Turn 25): the `paused + failed/retrying retained turn → re-dispatch`
+    // branch is unreachable under the current schema. See the matching deletion in
+    // `cli/src/commands/resume.js` for the full citation chain (schema.js:184 +
+    // governed-state.js:2191-2204 + the line-187 short-circuit above). The reachable
+    // retained-turn re-dispatch path for `step --resume` is the `state.status ===
+    // 'blocked' && activeCount > 0` branch at line 193 above. Per
+    // `DEC-UNREACHABLE-BRANCH-COVERAGE-001`, dead branches are removed once the
+    // schema citation + migration citation are documented.
 
     // idle → initialize run
     if (!skipAssignment && state.status === 'idle' && !state.run_id) {
@@ -344,6 +321,27 @@ export async function stepCommand(opts) {
       }
     }
 
+    if (!skipAssignment) {
+      const phaseReconciliation = reconcilePhaseAdvanceBeforeDispatch(root, config, state);
+      if (!phaseReconciliation.ok && !phaseReconciliation.state) {
+        console.log(chalk.red(`Failed to reconcile phase gate before dispatch: ${phaseReconciliation.error}`));
+        process.exit(1);
+      }
+      state = phaseReconciliation.state || state;
+      if (phaseReconciliation.advanced) {
+        console.log(chalk.green(`Advanced phase before dispatch: ${phaseReconciliation.from_phase} → ${phaseReconciliation.to_phase}`));
+      }
+      if (state.pending_phase_transition || state.pending_run_completion) {
+        evaluateApprovalSlaReminders(root, config, state);
+        printRecoverySummary(state, 'This run is awaiting approval.', config);
+        process.exit(1);
+      }
+      if (state.status === 'blocked') {
+        printRecoverySummary(state, 'This run is blocked.', config);
+        process.exit(1);
+      }
+    }
+
     // Assign the turn
     if (!skipAssignment) {
       const roleId = resolveTargetRole(opts, state, config);
@@ -448,6 +446,10 @@ export async function stepCommand(opts) {
       console.log(chalk.red(`Failed to finalize dispatch manifest: ${manifestResult.error}`));
       process.exit(1);
     }
+    const dispatched = transitionActiveTurnLifecycle(root, turn.turn_id, 'dispatched');
+    if (dispatched.ok) {
+      state = dispatched.state;
+    }
   }
 
   const controller = new AbortController();
@@ -456,6 +458,13 @@ export async function stepCommand(opts) {
   });
 
   if (runtimeType === 'api_proxy') {
+    const running = transitionActiveTurnLifecycle(root, turn.turn_id, 'running', {
+      stream: 'request',
+      at: new Date().toISOString(),
+    });
+    if (running.ok) {
+      state = running.state;
+    }
     console.log(chalk.cyan(`Dispatching to API proxy: ${runtime?.provider || '(unknown)'} / ${runtime?.model || '(unknown)'}`));
     console.log(chalk.dim(`Turn: ${turn.turn_id}  Role: ${roleId}  Phase: ${state.phase}`));
 
@@ -535,6 +544,13 @@ export async function stepCommand(opts) {
     }
     console.log('');
   } else if (runtimeType === 'mcp') {
+    const running = transitionActiveTurnLifecycle(root, turn.turn_id, 'running', {
+      stream: 'request',
+      at: new Date().toISOString(),
+    });
+    if (running.ok) {
+      state = running.state;
+    }
     const mcpTransport = resolveMcpTransport(runtime);
     console.log(chalk.cyan(`Dispatching to MCP ${mcpTransport}: ${describeMcpRuntimeTarget(runtime)}`));
     console.log(chalk.dim(`Turn: ${turn.turn_id}  Role: ${roleId}  Phase: ${state.phase}  Tool: ${runtime?.tool_name || 'agentxchain_turn'}`));
@@ -589,6 +605,13 @@ export async function stepCommand(opts) {
     console.log(chalk.green(`MCP tool completed${mcpResult.toolName ? ` (${mcpResult.toolName})` : ''}. Staged result detected.`));
     console.log('');
   } else if (runtimeType === 'remote_agent') {
+    const running = transitionActiveTurnLifecycle(root, turn.turn_id, 'running', {
+      stream: 'request',
+      at: new Date().toISOString(),
+    });
+    if (running.ok) {
+      state = running.state;
+    }
     console.log(chalk.cyan(`Dispatching to remote agent: ${describeRemoteAgentTarget(runtime)}`));
     console.log(chalk.dim(`Turn: ${turn.turn_id}  Role: ${roleId}  Phase: ${state.phase}`));
 
@@ -667,8 +690,25 @@ export async function stepCommand(opts) {
 
     // BUG-6: stream subprocess output by default (--stream or --verbose), suppress with --quiet
     const shouldStream = opts.stream || opts.verbose || false;
+    let runningMarked = false;
+    const ensureStartingState = (pid = null, at = new Date().toISOString()) => {
+      const starting = transitionActiveTurnLifecycle(root, turn.turn_id, 'starting', { pid, at });
+      if (starting.ok) {
+        state = starting.state;
+      }
+    };
+    const ensureRunningState = (stream = 'stdout', at = new Date().toISOString()) => {
+      if (runningMarked) return;
+      runningMarked = true;
+      const running = transitionActiveTurnLifecycle(root, turn.turn_id, 'running', { stream, at });
+      if (running.ok) {
+        state = running.state;
+      }
+    };
     const cliResult = await dispatchLocalCli(root, state, config, {
       signal: controller.signal,
+      onSpawnAttached: ({ pid, at }) => ensureStartingState(pid, at),
+      onFirstOutput: ({ at, stream }) => ensureRunningState(stream, at),
       onStdout: shouldStream ? (text) => process.stdout.write(chalk.dim(text)) : undefined,
       onStderr: shouldStream ? (text) => process.stderr.write(chalk.yellow(text)) : undefined,
       verifyManifest: true,
@@ -714,6 +754,28 @@ export async function stepCommand(opts) {
       process.exit(1);
     }
 
+    if (cliResult.startupFailure) {
+      const freshState = loadProjectState(root, config) || state;
+      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,
+        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,
+        recommendation: `Turn ${turn.turn_id} failed to start within the startup watchdog window. Run \`agentxchain reissue-turn --turn ${turn.turn_id} --reason ghost\` to recover.`,
+      });
+      if (failed.ok) {
+        state = failed.state;
+      }
+
+      console.log('');
+      console.log(chalk.red(`Turn startup failed: ${cliResult.error}`));
+      console.log(chalk.dim('The turn was retained as failed_start. You can:'));
+      console.log(chalk.dim(`  - Reissue immediately: agentxchain reissue-turn --turn ${turn.turn_id} --reason ghost`));
+      console.log(chalk.dim('  - Inspect status: agentxchain status'));
+      process.exit(1);
+    }
+
     if (!cliResult.ok) {
       const blocked = markRunBlocked(root, {
         blockedOn: `dispatch:${cliResult.exitCode != null ? `exit-${cliResult.exitCode}` : 'subprocess_failed'}`,
@@ -744,6 +806,10 @@ export async function stepCommand(opts) {
       process.exit(1);
     }
 
+    if (!runningMarked) {
+      ensureRunningState('staged_result', cliResult.firstOutputAt || new Date().toISOString());
+    }
+
     console.log(chalk.green('Subprocess completed. Staged result detected.'));
     console.log('');
   } else {

package/src/lib/adapters/api-proxy-adapter.js

@@ -29,6 +29,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
 import { join } from 'path';
 import { evaluateTokenBudget, SYSTEM_PROMPT, SEPARATOR } from '../token-budget.js';
+import { hasMinimumTurnResultShape } from '../turn-result-shape.js';
 import {
   getDispatchApiRequestPath,
   getDispatchContextPath,
@@ -1072,6 +1073,13 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
     turnResult.cost = { ...aggregateUsage };
   }
 
+  if (!hasMinimumTurnResultShape(turnResult)) {
+    return {
+      ok: false,
+      error: 'API response did not contain a valid turn result with the minimum governed turn-result fields',
+    };
+  }
+
   // Stage the turn result
   try {
     writeFileSync(

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

@@ -18,7 +18,7 @@
  */
 
 import { spawn } from 'child_process';
-import { existsSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import {
   getDispatchContextPath,
@@ -29,6 +29,16 @@ import {
   getTurnStagingResultPath,
 } from '../turn-paths.js';
 import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
+import { hasMeaningfulStagedResult } from '../staged-result-proof.js';
+
+const DIAGNOSTIC_ENV_KEYS = [
+  'PATH',
+  'HOME',
+  'PWD',
+  'SHELL',
+  'TMPDIR',
+  'AGENTXCHAIN_TURN_ID',
+];
 
 /**
  * Launch a local CLI subprocess for a governed turn.
@@ -37,7 +47,7 @@ import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
  * passes them as the prompt to the configured CLI command.
  *
  * @param {string} root - project root directory
- * @param {object} state - current governed state (must have current_turn)
+ * @param {object} state - current governed state (must expose an active turn via active_turns; current_turn is a non-enumerable compatibility alias re-attached on load, not a persisted schema field)
  * @param {object} config - normalized config
  * @param {object} [options]
  * @param {AbortSignal} [options.signal] - abort signal for cancellation
@@ -48,7 +58,15 @@ import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
  * @returns {Promise<{ ok: boolean, exitCode?: number, timedOut?: boolean, aborted?: boolean, error?: string, logs?: string[] }>}
  */
 export async function dispatchLocalCli(root, state, config, options = {}) {
-  const { signal, onStdout, onStderr, turnId } = options;
+  const {
+    signal,
+    onStdout,
+    onStderr,
+    onSpawnAttached,
+    onFirstOutput,
+    startupWatchdogMs = config?.run_loop?.startup_watchdog_ms ?? 30_000,
+    turnId,
+  } = options;
 
   const turn = resolveTargetTurn(state, turnId);
   if (!turn) {
@@ -103,6 +121,10 @@ 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);
 
   return new Promise((resolve) => {
     if (signal?.aborted) {
@@ -112,37 +134,143 @@ 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) {
-      resolve({ ok: false, error: `Failed to spawn "${command}": ${err.message}`, logs });
+      appendDiagnostic(logs, 'spawn_error', normalizeDiagnosticError(err));
+      resolve({
+        ok: false,
+        startupFailure: true,
+        startupFailureType: 'runtime_spawn_failed',
+        error: `Failed to spawn "${command}": ${err.message}`,
+        logs,
+      });
       return;
     }
 
     let settled = false;
+    let firstOutputAt = 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;
+
     const settle = (result) => {
       if (settled) return;
       settled = true;
       resolve(result);
     };
 
+    const clearStartupWatchdog = () => {
+      if (startupWatchdog) {
+        clearTimeout(startupWatchdog);
+        startupWatchdog = null;
+      }
+    };
+
+    const armStartupWatchdog = () => {
+      if (startupWatchdog || !(startupWatchdogMs > 0 && Number.isFinite(startupWatchdogMs))) {
+        return;
+      }
+      startupWatchdog = setTimeout(() => {
+        if (firstOutputAt || isStagedResultReady(join(root, getTurnStagingResultPath(turn.turn_id)))) {
+          return;
+        }
+        startupTimedOut = true;
+        startupFailureType = 'no_subprocess_output';
+        logs.push(`[adapter] Startup watchdog fired after ${Math.round(startupWatchdogMs / 1000)}s with no output.`);
+      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);
+    };
+
+    const recordFirstOutput = (stream) => {
+      if (firstOutputAt) return;
+      firstOutputAt = new Date().toISOString();
+      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 });
+        } catch {}
+      }
+    };
+
+    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 });
+        } catch {}
+      }
+      armStartupWatchdog();
+    });
+
     // 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);
       });
@@ -151,6 +279,8 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     if (child.stderr) {
       child.stderr.on('data', (chunk) => {
         const text = chunk.toString();
+        stderrBytes += Buffer.byteLength(text);
+        recordFirstOutput('stderr');
         logs.push('[stderr] ' + text);
         if (onStderr) onStderr(text);
       });
@@ -180,6 +310,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     // Abort signal handling
     const onAbort = () => {
       logs.push('[adapter] Abort signal received. Sending SIGTERM.');
+      clearStartupWatchdog();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
       try {
@@ -197,6 +328,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
     // Process exit
     child.on('close', (exitCode, killSignal) => {
+      clearStartupWatchdog();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
       if (signal) signal.removeEventListener('abort', onAbort);
@@ -210,17 +342,81 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
       // Check if staged result was written (regardless of exit code)
       const hasResult = isStagedResultReady(join(root, getTurnStagingResultPath(turn.turn_id)));
+      if (hasResult && !firstOutputAt) {
+        recordFirstOutput('staged_result');
+      }
+      const exitDiagnostic = {
+        pid: child.pid ?? null,
+        exit_code: exitCode,
+        signal: killSignal,
+        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,
+        staged_result_ready: hasResult,
+      };
+      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 });
+        settle({ ok: true, exitCode, timedOut: false, aborted: false, logs, firstOutputAt });
+      } else if (startupTimedOut) {
+        settle({
+          ok: false,
+          exitCode,
+          timedOut: false,
+          aborted: false,
+          startupFailure: true,
+          startupFailureType: startupFailureType || 'no_subprocess_output',
+          startupWatchdogMs,
+          firstOutputAt,
+          error: `Subprocess produced no output within ${Math.round(startupWatchdogMs / 1000)}s and did not stage a turn result.`,
+          logs,
+        });
+      } else if (!spawnConfirmedAt) {
+        settle({
+          ok: false,
+          exitCode,
+          timedOut: false,
+          aborted: false,
+          startupFailure: true,
+          startupFailureType: 'runtime_spawn_failed',
+          firstOutputAt,
+          error: `Subprocess exited (code ${exitCode}) before reporting a successful spawn or staging a turn result.`,
+          logs,
+        });
       } else if (timedOut) {
         settle({ ok: false, exitCode, timedOut: true, aborted: false, error: 'Turn timed out without producing a staged result.', logs });
+      } else if (!firstOutputAt) {
+        settle({
+          ok: false,
+          exitCode,
+          timedOut: false,
+          aborted: false,
+          startupFailure: true,
+          startupFailureType: 'no_subprocess_output',
+          startupWatchdogMs,
+          firstOutputAt,
+          error: `Subprocess exited (code ${exitCode}) before producing output or staging a turn result.`,
+          logs,
+        });
       } else {
         settle({
           ok: false,
           exitCode,
           timedOut: false,
           aborted: false,
+          firstOutputAt,
           error: `Subprocess exited (code ${exitCode}) without writing a staged turn result to ${getTurnStagingResultPath(turn.turn_id)}.`,
           logs,
         });
@@ -228,10 +424,37 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     });
 
     child.on('error', (err) => {
+      clearStartupWatchdog();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
       if (signal) signal.removeEventListener('abort', onAbort);
-      settle({ ok: false, error: `Subprocess error: ${err.message}`, logs });
+      // 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,
+        startupFailureType: !firstOutputAt ? 'runtime_spawn_failed' : null,
+        firstOutputAt,
+        error: `Subprocess error: ${err.message}`,
+        logs,
+      });
     });
   });
 }
@@ -322,15 +545,13 @@ function resolvePromptTransport(runtime) {
 
 /**
  * Check if the staged result file exists and has meaningful content.
+ * Delegates to the shared `hasMeaningfulStagedResult` helper so watchdog,
+ * manual adapter, and local-cli adapter all agree on what counts as proof.
+ * Per DEC-BUG51-STAGING-PLACEHOLDER-NOT-PROOF-001, placeholders (`{}`, blank,
+ * whitespace-only, or `{}\n`) are cleanup artifacts, not evidence.
  */
 function isStagedResultReady(filePath) {
-  try {
-    if (!existsSync(filePath)) return false;
-    const stat = statSync(filePath);
-    return stat.size > 2; // Must be more than just "{}" or empty
-  } catch {
-    return false;
-  }
+  return hasMeaningfulStagedResult(filePath);
 }
 
 function resolveTargetTurn(state, turnId) {
@@ -340,4 +561,38 @@ 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),
+  };
+}
+
 export { resolvePromptTransport };