agentxchain 2.145.0 → 2.147.0

package/src/lib/run-loop.js

@@ -31,6 +31,7 @@ import {
   getActiveTurnCount,
   getActiveTurns,
   getMaxConcurrentTurns,
+  transitionActiveTurnLifecycle,
   RUNNER_INTERFACE_VERSION,
 } from './runner-interface.js';
 
@@ -40,6 +41,18 @@ import { join, dirname } from 'path';
 import { evaluateApprovalSlaReminders } from './notification-runner.js';
 import { validatePreemptionMarker } from './intake.js';
 import { buildTimeoutBlockedReason, evaluateTimeouts } from './timeout-evaluator.js';
+import { hasMinimumTurnResultShape } from './turn-result-shape.js';
+
+// Per DEC-RUN-LOOP-MIN-SHAPE-SYMMETRY-001 (Turn 33): runLoop is the SDK boundary
+// any third-party runner can wire (see website-v2/docs/build-your-own-runner.mdx).
+// In-repo adapters (api_proxy, mcp, local_cli, remote_agent) already validate
+// staged-result shape before write per DEC-MINIMUM-TURN-RESULT-SHAPE-001, and
+// run.js's dispatch callback re-validates before returning per
+// DEC-RUN-STAGED-READ-SHAPE-GUARD-001. Third-party callbacks have no such
+// obligation. runLoop must therefore validate dispatchResult.turnResult shape
+// before persisting it as a governed staged-result artifact.
+const MIN_SHAPE_REJECTION_REASON =
+  'staged result missing minimum governed envelope (schema_version + identity + lifecycle fields)';
 
 const DEFAULT_MAX_TURNS = 50;
 
@@ -182,7 +195,7 @@ async function executeSequentialTurn(root, config, state, callbacks, emit, error
   let assignState;
   const activeTurn = getActiveTurn(state);
 
-  if (activeTurn && (activeTurn.status === 'running' || activeTurn.status === 'retrying')) {
+  if (activeTurn && isDispatchableActiveTurn(activeTurn)) {
     turn = activeTurn;
     assignState = state;
   } else {
@@ -224,7 +237,7 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
   const activeTurns = getActiveTurns(state);
   const turnsToDispatch = [];
   for (const turn of Object.values(activeTurns)) {
-    if (turn.status === 'running' || turn.status === 'retrying') {
+    if (isDispatchableActiveTurn(turn)) {
       turnsToDispatch.push({ turn, state });
     }
   }
@@ -317,6 +330,7 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
       errors.push(`writeDispatchBundle(${turn.assigned_role}): ${bundleResult.error}`);
       continue;
     }
+    transitionActiveTurnLifecycle(root, turn.turn_id, 'dispatched');
     const stagingPath = getTurnStagingResultPath(turn.turn_id);
     contexts.push({
       turn,
@@ -362,6 +376,23 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
       continue;
     }
 
+    if (dispatchResult.accept && !hasMinimumTurnResultShape(dispatchResult.turnResult)) {
+      // DEC-RUN-LOOP-MIN-SHAPE-SYMMETRY-001: third-party dispatch callback claimed
+      // accept=true but returned a payload missing the minimum envelope. Refuse to
+      // stage; convert to standard rejection so the run state advances cleanly.
+      const validationResult = { stage: 'dispatch', errors: [MIN_SHAPE_REJECTION_REASON] };
+      rejectTurn(root, config, validationResult, MIN_SHAPE_REJECTION_REASON, { turnId: turn.turn_id });
+      history.push({ role: roleId, turn_id: turn.turn_id, accepted: false });
+      emit({ type: 'turn_rejected', turn, role: roleId, reason: MIN_SHAPE_REJECTION_REASON });
+      const postRejectState = loadState(root, config);
+      if (postRejectState?.status === 'blocked') {
+        errors.push(`Turn rejected for ${roleId}, retries exhausted`);
+        emit({ type: 'blocked', state: postRejectState });
+        return { terminal: true, ok: false, stop_reason: 'reject_exhausted', history, acceptedCount };
+      }
+      continue;
+    }
+
     if (dispatchResult.accept) {
       const absStaging = join(root, ctx.stagingPath);
       mkdirSync(dirname(absStaging), { recursive: true });
@@ -409,6 +440,12 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
       }
       emit({ type: 'turn_accepted', turn, role: roleId, state: acceptResult.state });
     } else {
+      if (dispatchResult?.blocked === true) {
+        history.push({ role: roleId, turn_id: turn.turn_id, accepted: false, blocked: true });
+        const blockedState = loadState(root, config);
+        emit({ type: 'blocked', state: blockedState });
+        return { terminal: true, ok: false, stop_reason: 'blocked', history, acceptedCount };
+      }
       const validationResult = {
         stage: 'dispatch',
         errors: [dispatchResult.reason || 'Dispatch callback rejected the turn'],
@@ -449,6 +486,10 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
   return { terminal: false, history, acceptedCount };
 }
 
+function isDispatchableActiveTurn(turn) {
+  return ['assigned', 'dispatched', 'starting', 'running', 'retrying'].includes(turn?.status);
+}
+
 /**
  * Dispatch a single turn and process its result.
  */
@@ -463,6 +504,7 @@ async function dispatchAndProcess(root, config, turn, assignState, callbacks, em
     errors.push(`writeDispatchBundle(${roleId}): ${bundleResult.error}`);
     return { terminal: true, ok: false, stop_reason: 'blocked', history };
   }
+  transitionActiveTurnLifecycle(root, turn.turn_id, 'dispatched');
 
   const stagingPath = getTurnStagingResultPath(turn.turn_id);
   const context = {
@@ -488,6 +530,22 @@ async function dispatchAndProcess(root, config, turn, assignState, callbacks, em
     return { terminal: true, ok: false, stop_reason: 'blocked', history };
   }
 
+  if (dispatchResult.accept && !hasMinimumTurnResultShape(dispatchResult.turnResult)) {
+    // DEC-RUN-LOOP-MIN-SHAPE-SYMMETRY-001: same boundary as parallel branch.
+    // Refuse to stage; convert to a standard rejection.
+    const validationResult = { stage: 'dispatch', errors: [MIN_SHAPE_REJECTION_REASON] };
+    rejectTurn(root, config, validationResult, MIN_SHAPE_REJECTION_REASON);
+    history.push({ role: roleId, turn_id: turn.turn_id, accepted: false });
+    emit({ type: 'turn_rejected', turn, role: roleId, reason: MIN_SHAPE_REJECTION_REASON });
+    const postRejectState = loadState(root, config);
+    if (postRejectState?.status === 'blocked') {
+      errors.push(`Turn rejected for ${roleId}, retries exhausted`);
+      emit({ type: 'blocked', state: postRejectState });
+      return { terminal: true, ok: false, stop_reason: 'reject_exhausted', history };
+    }
+    return { terminal: false, accepted: false, history };
+  }
+
   if (dispatchResult.accept) {
     const absStaging = join(root, stagingPath);
     mkdirSync(dirname(absStaging), { recursive: true });
@@ -537,6 +595,13 @@ async function dispatchAndProcess(root, config, turn, assignState, callbacks, em
     return { terminal: false, accepted: true, history };
   }
 
+  if (dispatchResult?.blocked === true) {
+    history.push({ role: roleId, turn_id: turn.turn_id, accepted: false, blocked: true });
+    const blockedState = loadState(root, config);
+    emit({ type: 'blocked', state: blockedState });
+    return { terminal: true, ok: false, stop_reason: 'blocked', history };
+  }
+
   // Rejection
   const validationResult = {
     stage: 'dispatch',

package/src/lib/runner-interface.js

@@ -41,6 +41,7 @@ export {
   releaseAcceptanceLock as releaseLock,
   refreshTurnBaselineSnapshot,
   reissueTurn,
+  transitionActiveTurnLifecycle,
 } from './governed-state.js';
 
 // ── Dispatch ────────────────────────────────────────────────────────────────

package/src/lib/schema.js

@@ -35,6 +35,13 @@ export function validateGovernedStateSchema(data) {
   // but validators and read-only surfaces still tolerate reserved/manual states.
   const VALID_RUN_STATUSES = ['idle', 'active', 'paused', 'blocked', 'completed', 'failed'];
   const isV1_1 = data?.schema_version === '1.1';
+  // NOTE: `current_turn` is the persisted v1.0 schema field. Under v1.1 it is
+  // not a persisted field at all — `loadProjectState()` re-attaches it as a
+  // non-enumerable getter alias over `active_turns` after normalization
+  // (DEC-CURRENT-TURN-COMPAT-ALIAS-001). This validator runs against the
+  // persisted shape, so an `own` property named `current_turn` on a v1.1 doc
+  // means "stray persisted-shape leak from a legacy write" and is rejected
+  // below — it does NOT mean the runtime alias is going away.
   const hasLegacyCurrentTurn = Object.prototype.hasOwnProperty.call(data || {}, 'current_turn');
 
   function validateTurn(turn, label) {

package/src/lib/schemas/agentxchain-config.schema.json

@@ -85,7 +85,21 @@
       "type": "object"
     },
     "run_loop": {
-      "type": "object"
+      "type": "object",
+      "description": "Runner control knobs for execution watchdogs and automation behavior.",
+      "properties": {
+        "startup_watchdog_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Milliseconds to wait after dispatch for worker attach/first-output proof before retaining the turn as failed_start. Default 30000."
+        },
+        "stale_turn_threshold_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Milliseconds to wait before a started turn that previously produced output is treated as stale. Default 600000 for local_cli turns and 300000 for api_proxy turns."
+        }
+      },
+      "additionalProperties": true
     },
     "mission_planner": {
       "type": "object"

package/src/lib/staged-result-proof.js

@@ -0,0 +1,43 @@
+/**
+ * Staged turn-result proof helpers.
+ *
+ * Per DEC-BUG51-STAGING-PLACEHOLDER-NOT-PROOF-001: a turn-scoped staged-result
+ * file is proof of execution only when it contains meaningful result content.
+ * Adapter-authored placeholders (`{}`, blank, whitespace-only) are cleanup
+ * artifacts — watchdog, adapter, and recovery code must treat them as absent.
+ *
+ * This module centralizes that check so every surface (local-cli adapter,
+ * manual adapter, stale-turn watchdog) uses the same rule.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+/**
+ * Returns true when the staged-result file at `filePath` exists AND contains
+ * content that is not a placeholder (empty, whitespace-only, or `{}`).
+ *
+ * Trim-aware: `{}\n`, `  {}\n`, and `{}` are all rejected. Legitimate turn
+ * results carry the full governed schema and are far larger than the
+ * placeholder shapes this function filters.
+ *
+ * @param {string} filePath - absolute path to the staged-result file
+ * @returns {boolean}
+ */
+export function hasMeaningfulStagedResult(filePath) {
+  if (!existsSync(filePath)) {
+    return false;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return false;
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed === '' || trimmed === '{}') {
+    return false;
+  }
+  return true;
+}

package/src/lib/stale-turn-watchdog.js

@@ -1,16 +1,32 @@
 /**
- * Stale Turn Watchdog — BUG-47
+ * Stale Turn Watchdog — BUG-47 + BUG-51
  *
- * Lazy idle-threshold detection: if an active turn has status "running"
- * for >N seconds with no event log activity AND no staged result file,
- * report it as stalled.
+ * Two-tier lazy idle-threshold detection:
+ *
+ * 1. **Fast startup watchdog (BUG-51):** if an active turn has been
+ *    `dispatched`/`starting`/`running` for >30 seconds with NO startup proof
+ *    (no first-byte output recorded on the turn or in dispatch-progress) and
+ *    NO staged result, it is a "ghost turn" — the subprocess never reached a
+ *    healthy running state. Transitions to `failed_start` immediately.
+ *
+ *    Design note: the watchdog intentionally keys on first-output proof from
+ *    the framework-owned dispatch-progress contract rather than `stdout.log`
+ *    existence. `stdout.log` is adapter-authored visibility output and may be
+ *    absent even when the adapter is wired correctly. First-output timestamps
+ *    and output-line counters are the stable health contract across runtime
+ *    wiring.
+ *
+ * 2. **Stale turn watchdog (BUG-47):** if an active turn has status "running"
+ *    for >N minutes with no event log activity AND no staged result file,
+ *    report it as stalled.
  *
  * Fires on CLI invocations (status, resume, step --resume) rather than
  * requiring a background daemon.
  *
  * Default thresholds:
- *   - local_cli turns: 10 minutes
- *   - api_proxy turns: 5 minutes
+ *   - Startup watchdog: 30 seconds (configurable via run_loop.startup_watchdog_ms)
+ *   - local_cli stale turns: 10 minutes
+ *   - api_proxy stale turns: 5 minutes
  *   - Configurable via run_loop.stale_turn_threshold_ms in agentxchain.json
  */
 
@@ -20,9 +36,11 @@ import { safeWriteJson } from './safe-write.js';
 import { emitRunEvent, readRunEvents } from './run-events.js';
 import { getTurnStagingResultPath } from './turn-paths.js';
 import { getDispatchProgressRelativePath } from './dispatch-progress.js';
+import { hasMeaningfulStagedResult } from './staged-result-proof.js';
 
 const DEFAULT_LOCAL_CLI_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
 const DEFAULT_API_PROXY_THRESHOLD_MS = 5 * 60 * 1000;  // 5 minutes
+const DEFAULT_STARTUP_WATCHDOG_MS = 30 * 1000;          // 30 seconds (BUG-51)
 const LEGACY_STAGING_PATH = '.agentxchain/staging/turn-result.json';
 
 /**
@@ -83,6 +101,62 @@ export function detectStaleTurns(root, state, config) {
   return stale;
 }
 
+/**
+ * BUG-51: Detect ghost-dispatched turns — subprocess never started.
+ *
+ * A ghost turn is one that has been in `dispatched`, `starting`, `running`, or
+ * `retrying` longer than the startup watchdog threshold (default 30s) AND has:
+ *   - no startup proof (no `first_output_at` on the turn or dispatch-progress,
+ *     and no recorded output line counts)
+ *   - no staged result file
+ *
+ * This is a stricter, faster check than detectStaleTurns (BUG-47).
+ * Ghost turns transition to "failed_start" rather than "stalled".
+ *
+ * @param {string} root - project root directory
+ * @param {object} state - current governed state
+ * @param {object} config - normalized config
+ * @returns {Array<{ turn_id: string, role: string, runtime_id: string, running_ms: number, threshold_ms: number, recommendation: string, failure_type: string }>}
+ */
+export function detectGhostTurns(root, state, config) {
+  const activeTurns = state?.active_turns || {};
+  const ghosts = [];
+  const now = Date.now();
+  const startupThreshold = resolveStartupThreshold(config);
+
+  for (const [turnId, turn] of Object.entries(activeTurns)) {
+    if (!['dispatched', 'starting', 'running', 'retrying'].includes(turn.status)) continue;
+
+    const lifecycleStart = parseGhostLifecycleStart(turn);
+    if (!Number.isFinite(lifecycleStart)) continue;
+
+    const runningMs = now - lifecycleStart;
+    if (runningMs < startupThreshold) continue;
+
+    const progressPath = join(root, getDispatchProgressRelativePath(turnId));
+    const progress = readDispatchProgressSafe(progressPath);
+
+    if (hasTurnScopedStagedResult(root, turnId)) continue;
+    if (hasStartupProof(turn, progress)) continue;
+
+    const runningSeconds = Math.floor(runningMs / 1000);
+    const failureType = classifyStartupFailureType(turn, progress);
+    ghosts.push({
+      turn_id: turnId,
+      role: turn.assigned_role || 'unknown',
+      runtime_id: turn.runtime_id || 'unknown',
+      running_ms: runningMs,
+      threshold_ms: startupThreshold,
+      failure_type: failureType,
+      recommendation: `Turn ${turnId} has been dispatched for ${runningSeconds}s with no subprocess output. `
+        + `The subprocess likely never started. `
+        + `Run \`agentxchain reissue-turn --turn ${turnId} --reason ghost\` to recover.`,
+    });
+  }
+
+  return ghosts;
+}
+
 /**
  * Detect stale turns and emit turn_stalled events for each.
  * Returns the stale turn list for caller display.
@@ -95,18 +169,36 @@ export function detectAndEmitStaleTurns(root, state, config) {
 
 export function reconcileStaleTurns(root, state, config) {
   if (!state || typeof state !== 'object') {
-    return { stale_turns: [], state, changed: false };
+    return { stale_turns: [], ghost_turns: [], state, changed: false };
   }
 
-  const stale = detectStaleTurns(root, state, config);
-  if (stale.length === 0) {
-    return { stale_turns: [], state, changed: false };
+  // BUG-51: Fast startup watchdog — detect ghost turns first (30s threshold)
+  const ghosts = detectGhostTurns(root, state, config);
+
+  // BUG-47: Stale turn watchdog — detect turns that started but went silent (10m threshold)
+  // Exclude turns already caught by ghost detection to avoid double-counting
+  const ghostIds = new Set(ghosts.map(g => g.turn_id));
+  const stale = detectStaleTurns(root, state, config).filter(s => !ghostIds.has(s.turn_id));
+
+  if (ghosts.length === 0 && stale.length === 0) {
+    return { stale_turns: [], ghost_turns: [], state, changed: false };
   }
 
   const nowIso = new Date().toISOString();
   const activeTurns = { ...(state.active_turns || {}) };
+  const budgetReservations = { ...(state.budget_reservations || {}) };
   let changed = false;
 
+  // Process ghost turns (BUG-51) — transition to failed_start
+  for (const entry of ghosts) {
+    const applied = applyStartupFailureToActiveTurn(activeTurns, budgetReservations, entry, nowIso);
+    if (applied) {
+      emitStartupFailureEvent(root, state, entry);
+      changed = true;
+    }
+  }
+
+  // Process stale turns (BUG-47) — transition to stalled
   for (const entry of stale) {
     const turn = activeTurns[entry.turn_id];
     if (!turn || (turn.status !== 'running' && turn.status !== 'retrying')) continue;
@@ -123,6 +215,9 @@ export function reconcileStaleTurns(root, state, config) {
     };
     changed = true;
 
+    // BUG-51 fix #6: Release budget reservation for stale turns too
+    delete budgetReservations[entry.turn_id];
+
     emitRunEvent(root, 'turn_stalled', {
       run_id: state?.run_id || null,
       phase: state?.phase || null,
@@ -138,28 +233,12 @@ export function reconcileStaleTurns(root, state, config) {
   }
 
   if (!changed) {
-    return { stale_turns: stale, state, changed: false };
+    return { stale_turns: stale, ghost_turns: ghosts, state, changed: false };
   }
 
-  const primary = stale[0];
-  const nextState = {
-    ...state,
-    status: 'blocked',
-    active_turns: activeTurns,
-    blocked_on: stale.length === 1 ? `turn:stalled:${primary.turn_id}` : 'turns:stalled',
-    blocked_reason: {
-      category: 'stale_turn',
-      blocked_at: nowIso,
-      turn_id: primary.turn_id,
-      recovery: {
-        typed_reason: 'stale_turn',
-        owner: 'human',
-        recovery_action: primary.recommendation,
-        turn_retained: true,
-        detail: primary.recommendation,
-      },
-    },
-  };
+  const nextState = buildBlockedStateFromEntries(state, activeTurns, budgetReservations, ghosts, stale, nowIso);
+  const primary = [...ghosts, ...stale][0];
+  const category = ghosts.length > 0 ? 'ghost_turn' : 'stale_turn';
 
   safeWriteJson(join(root, '.agentxchain', 'state.json'), nextState);
   emitRunEvent(root, 'run_blocked', {
@@ -168,11 +247,12 @@ export function reconcileStaleTurns(root, state, config) {
     status: 'blocked',
     turn: { turn_id: primary.turn_id, role_id: primary.role },
     payload: {
-      category: 'stale_turn',
+      category,
+      ghost_turn_ids: ghosts.map((entry) => entry.turn_id),
       stalled_turn_ids: stale.map((entry) => entry.turn_id),
     },
   });
-  return { stale_turns: stale, state: nextState, changed: true };
+  return { stale_turns: stale, ghost_turns: ghosts, state: nextState, changed: true };
 }
 
 function resolveThreshold(turn, config) {
@@ -194,13 +274,71 @@ function resolveThreshold(turn, config) {
   return DEFAULT_LOCAL_CLI_THRESHOLD_MS;
 }
 
+function resolveStartupThreshold(config) {
+  const configThreshold = config?.run_loop?.startup_watchdog_ms;
+  if (typeof configThreshold === 'number' && configThreshold > 0) {
+    return configThreshold;
+  }
+  return DEFAULT_STARTUP_WATCHDOG_MS;
+}
+
+export function failTurnStartup(root, state, config, turnId, details = {}) {
+  if (!state || typeof state !== 'object') {
+    return { ok: false, error: 'No governed state found' };
+  }
+
+  const turn = state.active_turns?.[turnId];
+  if (!turn) {
+    return { ok: false, error: `Turn ${turnId} not found in active turns` };
+  }
+
+  const nowIso = new Date().toISOString();
+  const activeTurns = { ...(state.active_turns || {}) };
+  const budgetReservations = { ...(state.budget_reservations || {}) };
+  const entry = {
+    turn_id: turnId,
+    role: turn.assigned_role || 'unknown',
+    runtime_id: turn.runtime_id || 'unknown',
+    running_ms: details.running_ms ?? computeLifecycleAgeMs(turn),
+    threshold_ms: details.threshold_ms ?? resolveStartupThreshold(config),
+    failure_type: classifyStartupFailureType(turn, null, details.failure_type || 'no_subprocess_output'),
+    recommendation: details.recommendation
+      || `Turn ${turnId} failed to start cleanly. Run \`agentxchain reissue-turn --turn ${turnId} --reason ghost\` to recover.`,
+  };
+
+  if (!applyStartupFailureToActiveTurn(activeTurns, budgetReservations, entry, nowIso)) {
+    return { ok: false, error: `Turn ${turnId} is not eligible for startup failure transition` };
+  }
+
+  const nextState = buildBlockedStateFromEntries(state, activeTurns, budgetReservations, [entry], [], nowIso);
+  safeWriteJson(join(root, '.agentxchain', 'state.json'), nextState);
+  emitStartupFailureEvent(root, state, entry);
+  emitRunEvent(root, 'run_blocked', {
+    run_id: nextState.run_id || null,
+    phase: nextState.phase || null,
+    status: 'blocked',
+    turn: { turn_id: entry.turn_id, role_id: entry.role },
+    payload: {
+      category: 'ghost_turn',
+      ghost_turn_ids: [entry.turn_id],
+      stalled_turn_ids: [],
+    },
+  });
+  return { ok: true, state: nextState, turn: nextState.active_turns?.[turnId] || null };
+}
+
 function hasRecentTurnEventActivity(root, turnId, startedAt, threshold, now) {
   try {
     const events = readRunEvents(root, { limit: 200 });
     for (let i = events.length - 1; i >= 0; i--) {
       const event = events[i];
       if (event?.turn?.turn_id !== turnId) continue;
-      if (event.event_type === 'turn_stalled') continue;
+      if (
+        event.event_type === 'turn_stalled'
+        || event.event_type === 'turn_start_failed'
+        || event.event_type === 'runtime_spawn_failed'
+        || event.event_type === 'stdout_attach_failed'
+      ) continue;
       const timestamp = Date.parse(event.timestamp || '');
       if (!Number.isFinite(timestamp)) continue;
       if (timestamp < startedAt) continue;
@@ -214,9 +352,145 @@ function hasRecentTurnEventActivity(root, turnId, startedAt, threshold, now) {
   return false;
 }
 
+function applyStartupFailureToActiveTurn(activeTurns, budgetReservations, entry, nowIso) {
+  const turn = activeTurns[entry.turn_id];
+  if (!turn || !['dispatched', 'starting', 'running', 'retrying'].includes(turn.status)) {
+    return false;
+  }
+
+  activeTurns[entry.turn_id] = {
+    ...turn,
+    status: 'failed_start',
+    failed_start_at: nowIso,
+    failed_start_reason: entry.failure_type,
+    failed_start_previous_status: turn.status,
+    failed_start_threshold_ms: entry.threshold_ms,
+    failed_start_running_ms: entry.running_ms,
+    recovery_command: `agentxchain reissue-turn --turn ${entry.turn_id} --reason ghost`,
+  };
+  delete budgetReservations[entry.turn_id];
+  return true;
+}
+
+function emitStartupFailureEvent(root, state, entry) {
+  const payload = {
+    running_ms: entry.running_ms,
+    threshold_ms: entry.threshold_ms,
+    runtime_id: entry.runtime_id,
+    failure_type: entry.failure_type,
+    recommendation: entry.recommendation,
+  };
+  const details = {
+    run_id: state?.run_id || null,
+    phase: state?.phase || null,
+    status: 'blocked',
+    turn: { turn_id: entry.turn_id, role_id: entry.role },
+    payload,
+  };
+  emitRunEvent(root, 'turn_start_failed', details);
+  const failureEventType = mapStartupFailureEventType(entry.failure_type);
+  if (failureEventType) {
+    emitRunEvent(root, failureEventType, details);
+  }
+}
+
+function buildBlockedStateFromEntries(state, activeTurns, budgetReservations, ghosts, stale, nowIso) {
+  const allDetected = [...ghosts, ...stale];
+  const primary = allDetected[0];
+  const category = ghosts.length > 0 ? 'ghost_turn' : 'stale_turn';
+  const blockedOn = allDetected.length === 1
+    ? `turn:${primary.failure_type ? 'failed_start' : 'stalled'}:${primary.turn_id}`
+    : ghosts.length > 0 ? 'turns:failed_start' : 'turns:stalled';
+
+  return {
+    ...state,
+    status: 'blocked',
+    active_turns: activeTurns,
+    budget_reservations: budgetReservations,
+    blocked_on: blockedOn,
+    blocked_reason: {
+      category,
+      blocked_at: nowIso,
+      turn_id: primary.turn_id,
+      recovery: {
+        typed_reason: category,
+        owner: 'human',
+        recovery_action: primary.recommendation,
+        turn_retained: true,
+        detail: primary.recommendation,
+      },
+    },
+  };
+}
+
+function parseGhostLifecycleStart(turn) {
+  if (turn.status === 'dispatched') {
+    return Date.parse(turn.dispatched_at || turn.assigned_at || '');
+  }
+  return Date.parse(turn.started_at || turn.dispatched_at || turn.assigned_at || '');
+}
+
+function computeLifecycleAgeMs(turn) {
+  const start = parseGhostLifecycleStart(turn);
+  if (!Number.isFinite(start)) return 0;
+  return Math.max(0, Date.now() - start);
+}
+
+function readDispatchProgressSafe(progressPath) {
+  if (!existsSync(progressPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(progressPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function classifyStartupFailureType(turn, progress, fallback = 'no_subprocess_output') {
+  if (fallback === 'runtime_spawn_failed' || fallback === 'stdout_attach_failed') {
+    return fallback;
+  }
+  if (turn?.status === 'dispatched') {
+    return 'runtime_spawn_failed';
+  }
+  const hasWorkerAttachProof = Boolean(
+    turn?.worker_attached_at
+    || turn?.worker_pid != null
+    || progress?.pid != null,
+  );
+  if (turn?.status === 'starting' || hasWorkerAttachProof) {
+    return 'stdout_attach_failed';
+  }
+  return fallback;
+}
+
+function mapStartupFailureEventType(failureType) {
+  if (failureType === 'runtime_spawn_failed') {
+    return 'runtime_spawn_failed';
+  }
+  if (failureType === 'stdout_attach_failed') {
+    return 'stdout_attach_failed';
+  }
+  return null;
+}
+
+function hasStartupProof(turn, progress) {
+  if (turn.first_output_at) {
+    return true;
+  }
+  if (!progress || typeof progress !== 'object') {
+    return false;
+  }
+  if (progress.first_output_at) {
+    return true;
+  }
+  return Number(progress.output_lines || 0) > 0 || Number(progress.stderr_lines || 0) > 0;
+}
+
 function hasTurnScopedStagedResult(root, turnId) {
   const turnScopedPath = join(root, getTurnStagingResultPath(turnId));
-  if (existsSync(turnScopedPath)) {
+  if (hasMeaningfulStagedResult(turnScopedPath)) {
     return true;
   }