agentxchain 2.146.0 → 2.147.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,7 @@ import {
   getTurnStagingResultPath,
 } from '../turn-paths.js';
 import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
+import { hasMeaningfulStagedResult } from '../staged-result-proof.js';
 
 /**
  * Launch a local CLI subprocess for a governed turn.
@@ -37,7 +38,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 +49,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) {
@@ -118,17 +127,74 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
         env: { ...process.env, AGENTXCHAIN_TURN_ID: turn.turn_id },
       });
     } catch (err) {
-      resolve({ ok: false, error: `Failed to spawn "${command}": ${err.message}`, logs });
+      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 startupWatchdog = null;
+    let startupTimedOut = false;
+    let startupFailureType = null;
+
     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.`);
+        try {
+          child.kill('SIGTERM');
+        } catch {}
+      }, startupWatchdogMs);
+    };
+
+    const recordFirstOutput = (stream) => {
+      if (firstOutputAt) return;
+      firstOutputAt = new Date().toISOString();
+      clearStartupWatchdog();
+      if (onFirstOutput) {
+        try {
+          onFirstOutput({ pid: child.pid ?? null, at: firstOutputAt, stream });
+        } catch {}
+      }
+    };
+
+    child.once('spawn', () => {
+      spawnConfirmedAt = new Date().toISOString();
+      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) {
       try {
@@ -143,6 +209,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     if (child.stdout) {
       child.stdout.on('data', (chunk) => {
         const text = chunk.toString();
+        recordFirstOutput('stdout');
         logs.push(text);
         if (onStdout) onStdout(text);
       });
@@ -151,6 +218,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     if (child.stderr) {
       child.stderr.on('data', (chunk) => {
         const text = chunk.toString();
+        recordFirstOutput('stderr');
         logs.push('[stderr] ' + text);
         if (onStderr) onStderr(text);
       });
@@ -180,6 +248,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 +266,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 +280,59 @@ 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');
+      }
 
       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 +340,18 @@ 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 });
+      settle({
+        ok: false,
+        startupFailure: !firstOutputAt,
+        startupFailureType: !firstOutputAt ? 'runtime_spawn_failed' : null,
+        firstOutputAt,
+        error: `Subprocess error: ${err.message}`,
+        logs,
+      });
     });
   });
 }
@@ -322,15 +442,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) {

package/src/lib/adapters/manual-adapter.js

@@ -10,17 +10,18 @@
  * auto-route, and does not pretend to be an orchestrator.
  */
 
-import { existsSync, readFileSync, statSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import {
   getDispatchPromptPath,
   getTurnStagingResultPath,
 } from '../turn-paths.js';
+import { hasMeaningfulStagedResult } from '../staged-result-proof.js';
 
 /**
  * Print operator instructions for a manual turn.
  *
- * @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 {string} [options.turnId]
@@ -282,16 +283,14 @@ export async function waitForStagedResult(root, options = {}) {
 }
 
 /**
- * Check if the staged result file exists and is non-empty.
+ * 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);
 }
 
 /**

package/src/lib/adapters/mcp-adapter.js

@@ -12,6 +12,7 @@ import {
   getTurnStagingResultPath,
 } from '../turn-paths.js';
 import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
+import { hasMinimumTurnResultShape } from '../turn-result-shape.js';
 
 export const DEFAULT_MCP_TOOL_NAME = 'agentxchain_turn';
 export const DEFAULT_MCP_TRANSPORT = 'stdio';
@@ -237,7 +238,7 @@ export function extractTurnResultFromMcpToolResult(toolResult) {
 
   for (const block of textBlocks) {
     const parsed = tryParseJson(block.text);
-    if (looksLikeTurnResult(parsed) || isPlainObject(parsed)) {
+    if (looksLikeTurnResult(parsed)) {
       return { ok: true, result: parsed };
     }
   }
@@ -336,10 +337,7 @@ function isPlainObject(value) {
 }
 
 function looksLikeTurnResult(value) {
-  if (!isPlainObject(value)) return false;
-  const hasIdentity = 'run_id' in value || 'turn_id' in value;
-  const hasLifecycle = 'status' in value || 'role' in value || 'runtime_id' in value;
-  return hasIdentity && hasLifecycle;
+  return hasMinimumTurnResultShape(value);
 }
 
 function tryParseJson(value) {

package/src/lib/adapters/remote-agent-adapter.js

@@ -24,6 +24,7 @@ import {
   getTurnStagingResultPath,
 } from '../turn-paths.js';
 import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
+import { hasMinimumTurnResultShape } from '../turn-result-shape.js';
 
 /** Default timeout for remote agent requests (ms). */
 export const DEFAULT_REMOTE_AGENT_TIMEOUT_MS = 120_000;
@@ -195,7 +196,7 @@ export async function dispatchRemoteAgent(root, state, config, options = {}) {
 
     // Validate turn result structure (lightweight — full validation happens in the acceptance pipeline)
     if (!looksLikeTurnResult(responseData)) {
-      logs.push('[remote] Response missing required turn-result fields (need at least run_id/turn_id + status/role)');
+      logs.push('[remote] Response missing minimum governed turn-result fields (need schema_version + identity + lifecycle fields)');
       return {
         ok: false,
         error: 'Remote agent response does not contain a valid turn result',
@@ -230,10 +231,7 @@ export async function dispatchRemoteAgent(root, state, config, options = {}) {
  * Full validation happens later via validateStagedTurnResult.
  */
 function looksLikeTurnResult(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  const hasIdentity = 'run_id' in value || 'turn_id' in value;
-  const hasLifecycle = 'status' in value || 'role' in value || 'runtime_id' in value;
-  return hasIdentity && hasLifecycle;
+  return hasMinimumTurnResultShape(value);
 }
 
 function resolveTargetTurn(state, turnId) {