agentxchain 2.146.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

@@ -3,18 +3,18 @@
  *
  * Two-tier lazy idle-threshold detection:
  *
- * 1. **Fast startup watchdog (BUG-51):** if an active turn has been dispatched
- *    for >30 seconds with NO dispatch-progress file, NO staged result, and NO
- *    recent events, it is a "ghost turn" — the subprocess never attached.
- *    Transitions to `failed_start` immediately.
+ * 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 turn-scoped
- *    dispatch-progress rather than `stdout.log` existence. Dispatch-progress is
- *    a framework-authored signal with a stable per-turn contract across runtime
- *    wiring; `stdout.log` is adapter-authored visibility output and is allowed
- *    to be best-effort. Using dispatch-progress therefore gives us the same
- *    operator-facing "no first byte / no worker heartbeat" detection without
- *    coupling the watchdog to adapter-specific log-attachment details.
+ *    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,
@@ -36,6 +36,7 @@ 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
@@ -103,12 +104,11 @@ export function detectStaleTurns(root, state, config) {
 /**
  * BUG-51: Detect ghost-dispatched turns — subprocess never started.
  *
- * A ghost turn is one that has been in "running" or "retrying" status for
- * longer than the startup watchdog threshold (default 30s) AND has:
- *   - no dispatch-progress file (framework-observed proof that no subprocess
- *     output or heartbeat was attached)
+ * 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
- *   - no recent turn-scoped events (beyond the initial turn_dispatched)
  *
  * This is a stricter, faster check than detectStaleTurns (BUG-47).
  * Ghost turns transition to "failed_start" rather than "stalled".
@@ -125,31 +125,22 @@ export function detectGhostTurns(root, state, config) {
   const startupThreshold = resolveStartupThreshold(config);
 
   for (const [turnId, turn] of Object.entries(activeTurns)) {
-    if (turn.status !== 'running' && turn.status !== 'retrying') continue;
-    if (!turn.started_at) continue;
+    if (!['dispatched', 'starting', 'running', 'retrying'].includes(turn.status)) continue;
 
-    const startedAt = new Date(turn.started_at).getTime();
-    if (isNaN(startedAt)) continue;
+    const lifecycleStart = parseGhostLifecycleStart(turn);
+    if (!Number.isFinite(lifecycleStart)) continue;
 
-    const runningMs = now - startedAt;
+    const runningMs = now - lifecycleStart;
     if (runningMs < startupThreshold) continue;
 
-    // Ghost detection: NO dispatch-progress file means subprocess never attached
     const progressPath = join(root, getDispatchProgressRelativePath(turnId));
-    const hasProgress = existsSync(progressPath);
+    const progress = readDispatchProgressSafe(progressPath);
 
-    // If dispatch-progress exists, subprocess started — this is NOT a ghost turn.
-    // The regular stale-turn watchdog (BUG-47) will handle it if it goes silent.
-    if (hasProgress) continue;
-
-    // Also check for staged result (unlikely without progress, but be safe)
     if (hasTurnScopedStagedResult(root, turnId)) continue;
-
-    // Check for any turn-scoped events beyond the initial dispatch event
-    if (hasRecentTurnEventActivity(root, turnId, startedAt, startupThreshold, now)) continue;
+    if (hasStartupProof(turn, progress)) continue;
 
     const runningSeconds = Math.floor(runningMs / 1000);
-    const failureType = 'no_subprocess_output';
+    const failureType = classifyStartupFailureType(turn, progress);
     ghosts.push({
       turn_id: turnId,
       role: turn.assigned_role || 'unknown',
@@ -200,37 +191,11 @@ export function reconcileStaleTurns(root, state, config) {
 
   // Process ghost turns (BUG-51) — transition to failed_start
   for (const entry of ghosts) {
-    const turn = activeTurns[entry.turn_id];
-    if (!turn || (turn.status !== 'running' && turn.status !== 'retrying')) continue;
-
-    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`,
-    };
-    changed = true;
-
-    // BUG-51 fix #6: Release budget reservation for ghost turns
-    delete budgetReservations[entry.turn_id];
-
-    emitRunEvent(root, 'turn_start_failed', {
-      run_id: state?.run_id || null,
-      phase: state?.phase || null,
-      status: 'blocked',
-      turn: { turn_id: entry.turn_id, role_id: entry.role },
-      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 applied = applyStartupFailureToActiveTurn(activeTurns, budgetReservations, entry, nowIso);
+    if (applied) {
+      emitStartupFailureEvent(root, state, entry);
+      changed = true;
+    }
   }
 
   // Process stale turns (BUG-47) — transition to stalled
@@ -271,32 +236,9 @@ export function reconcileStaleTurns(root, state, config) {
     return { stale_turns: stale, ghost_turns: ghosts, state, changed: false };
   }
 
-  const allDetected = [...ghosts, ...stale];
-  const primary = allDetected[0];
+  const nextState = buildBlockedStateFromEntries(state, activeTurns, budgetReservations, ghosts, stale, nowIso);
+  const primary = [...ghosts, ...stale][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';
-
-  const nextState = {
-    ...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,
-      },
-    },
-  };
 
   safeWriteJson(join(root, '.agentxchain', 'state.json'), nextState);
   emitRunEvent(root, 'run_blocked', {
@@ -340,13 +282,63 @@ function resolveStartupThreshold(config) {
   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' || event.event_type === 'turn_start_failed') 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;
@@ -360,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;
   }
 

package/src/lib/turn-result-shape.js

@@ -0,0 +1,38 @@
+/**
+ * Lightweight staged turn-result shape guard.
+ *
+ * This is intentionally weaker than full acceptance validation. It exists for
+ * adapter pre-stage checks so obviously incomplete payloads (`{}`,
+ * `{"turn_id":"t1"}`, etc.) are rejected before they can be written into the
+ * governed staging path and mistaken for meaningful execution output.
+ */
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+/**
+ * Returns true when `value` has the minimum governed turn-result envelope:
+ *   - `schema_version`
+ *   - at least one identity field (`run_id` or `turn_id`)
+ *   - at least one lifecycle field (`status`, `role`, or `runtime_id`)
+ *
+ * Full schema validation still happens later via `validateStagedTurnResult`.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function hasMinimumTurnResultShape(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  const candidate = /** @type {Record<string, unknown>} */ (value);
+  const hasSchemaVersion = isNonEmptyString(candidate.schema_version);
+  const hasIdentity = isNonEmptyString(candidate.run_id) || isNonEmptyString(candidate.turn_id);
+  const hasLifecycle = isNonEmptyString(candidate.status)
+    || isNonEmptyString(candidate.role)
+    || isNonEmptyString(candidate.runtime_id);
+
+  return hasSchemaVersion && hasIdentity && hasLifecycle;
+}

package/src/lib/turn-result-validator.js

@@ -75,7 +75,10 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
   const normContext = {};
   if (state) {
     normContext.phase = state.phase;
-    // Support both active_turns (v2+) and legacy current_turn formats
+    // Prefer active_turns (the persisted schema field); fall back to the
+    // current_turn compatibility alias for callers that pass a state shape
+    // built outside loadProjectState() (e.g. raw fixtures). Both surfaces are
+    // live per DEC-CURRENT-TURN-COMPAT-ALIAS-001 — current_turn is not legacy.
     const activeTurn = getActiveTurn(state) || state.current_turn;
     if (activeTurn) {
       const roleKey = activeTurn.assigned_role || activeTurn.role;