agentxchain 2.146.0 → 2.148.0

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) {

package/src/lib/continuous-run.js

@@ -99,6 +99,9 @@ function describeContinuousTerminalStep(step, contOpts) {
     return `Continuous loop failed: ${reason}. Check "agentxchain status" for details.`;
   }
   if (step.status === 'blocked') {
+    if (step.recovery_action) {
+      return `Continuous loop paused on blocker. Recovery: ${step.recovery_action}`;
+    }
     return 'Continuous loop paused on blocker. Use "agentxchain unblock <id>" to resume.';
   }
   return null;
@@ -116,6 +119,14 @@ function isBlockedContinuousExecution(execution) {
     || stopReason === 'reject_exhausted';
 }
 
+function getBlockedRecoveryAction(state) {
+  return state?.blocked_reason?.recovery?.recovery_action || null;
+}
+
+function getBlockedCategory(state) {
+  return state?.blocked_reason?.category || null;
+}
+
 // ---------------------------------------------------------------------------
 // Intake queue check
 // ---------------------------------------------------------------------------
@@ -361,7 +372,14 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
     if (governedState?.status === 'blocked') {
       // Still blocked — stay paused, do not attempt new work
       writeContinuousSession(root, session);
-      return { ok: true, status: 'blocked', action: 'still_blocked', run_id: session.current_run_id };
+      return {
+        ok: true,
+        status: 'blocked',
+        action: 'still_blocked',
+        run_id: session.current_run_id,
+        recovery_action: getBlockedRecoveryAction(governedState),
+        blocked_category: getBlockedCategory(governedState),
+      };
     }
     // Unblocked — resume by continuing the existing governed run directly.
     // Skip the intake pipeline: the run is already in progress, and startIntent
@@ -388,10 +406,20 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
     const resumeStopReason = execution.result?.stop_reason;
 
     if (isBlockedContinuousExecution(execution)) {
+      const blockedRecoveryAction = getBlockedRecoveryAction(execution?.result?.state || loadProjectState(root, context.config));
       session.status = 'paused';
-      log('Resumed run blocked again — continuous loop re-paused.');
+      log(blockedRecoveryAction
+        ? `Resumed run blocked again — continuous loop re-paused. Recovery: ${blockedRecoveryAction}`
+        : 'Resumed run blocked again — continuous loop re-paused.');
       writeContinuousSession(root, session);
-      return { ok: true, status: 'blocked', action: 'run_blocked', run_id: session.current_run_id };
+      return {
+        ok: true,
+        status: 'blocked',
+        action: 'run_blocked',
+        run_id: session.current_run_id,
+        recovery_action: blockedRecoveryAction,
+        blocked_category: getBlockedCategory(execution?.result?.state || loadProjectState(root, context.config)),
+      };
     }
 
     if (execution.exitCode !== 0 || !execution.result) {
@@ -473,9 +501,35 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
     return { ok: false, status: 'failed', action: 'prepare_failed', stop_reason: preparedIntent.error, intent_id: targetIntentId };
   }
 
+  // BUG-53: Auto-chain audit trail. When this advance step seeds a NEXT run
+  // (i.e., at least one prior run already completed in this session), emit a
+  // `session_continuation` event so operators have a visible record that the
+  // loop auto-derived the next vision objective without intervention. Event
+  // is emitted BEFORE we overwrite session.current_run_id so previous_run_id
+  // reflects the just-completed run and next_run_id reflects the newly
+  // prepared one. See HUMAN-ROADMAP BUG-53 fix #4.
+  const previousRunId = session.current_run_id;
+  const nextObjective = visionObjective || preparedIntent.intent?.charter || null;
+  if ((session.runs_completed || 0) >= 1 && previousRunId && previousRunId !== preparedIntent.run_id) {
+    emitRunEvent(root, 'session_continuation', {
+      run_id: preparedIntent.run_id,
+      phase: null,
+      status: 'active',
+      payload: {
+        session_id: session.session_id,
+        previous_run_id: previousRunId,
+        next_run_id: preparedIntent.run_id,
+        next_objective: nextObjective,
+        next_intent_id: targetIntentId,
+        runs_completed: session.runs_completed || 0,
+        trigger: visionObjective ? 'vision_scan' : 'intake',
+      },
+    });
+  }
+
   // Execute the governed run
   session.current_run_id = preparedIntent.run_id;
-  session.current_vision_objective = visionObjective || preparedIntent.intent?.charter || null;
+  session.current_vision_objective = nextObjective;
   session.status = 'running';
   writeContinuousSession(root, session);
 
@@ -519,6 +573,7 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
   }
 
   if (isBlockedContinuousExecution(execution)) {
+    const blockedRecoveryAction = getBlockedRecoveryAction(execution?.result?.state || loadProjectState(root, context.config));
     const resolved = resolveIntent(root, targetIntentId);
     if (!resolved.ok) {
       log(`Continuous resolve error: ${resolved.error}`);
@@ -527,9 +582,19 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
       return { ok: false, status: 'failed', action: 'resolve_failed', stop_reason: resolved.error, intent_id: targetIntentId };
     }
     session.status = 'paused';
-    log('Run blocked — continuous loop paused. Use `agentxchain unblock <id>` to resume.');
+    log(blockedRecoveryAction
+      ? `Run blocked — continuous loop paused. Recovery: ${blockedRecoveryAction}`
+      : 'Run blocked — continuous loop paused. Use `agentxchain unblock <id>` to resume.');
     writeContinuousSession(root, session);
-    return { ok: true, status: 'blocked', action: 'run_blocked', run_id: session.current_run_id, intent_id: targetIntentId };
+    return {
+      ok: true,
+      status: 'blocked',
+      action: 'run_blocked',
+      run_id: session.current_run_id,
+      intent_id: targetIntentId,
+      recovery_action: blockedRecoveryAction,
+      blocked_category: getBlockedCategory(execution?.result?.state || loadProjectState(root, context.config)),
+    };
   }
 
   if (stopReason === 'caller_stopped') {

package/src/lib/dispatch-bundle.js

@@ -55,7 +55,7 @@ const RESERVED_PATHS = [
  * Write a dispatch bundle for the currently assigned turn.
  *
  * @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} [opts]
  * @param {string} [opts.turnId]

package/src/lib/dispatch-progress.js

@@ -71,9 +71,10 @@ export function createDispatchProgressTracker(root, turn, options = {}) {
     runtime_id: turn.runtime_id || null,
     adapter_type,
     started_at: null,
+    first_output_at: null,
     last_activity_at: null,
-    activity_type: 'output',
-    activity_summary: 'Dispatch starting',
+    activity_type: 'starting',
+    activity_summary: 'Waiting for first output',
     output_lines: 0,
     stderr_lines: 0,
     silent_since: null,
@@ -123,7 +124,7 @@ export function createDispatchProgressTracker(root, turn, options = {}) {
       const now = new Date().toISOString();
       state.started_at = now;
       state.last_activity_at = now;
-      state.activity_type = 'output';
+      state.activity_type = 'starting';
       state.activity_summary = 'Subprocess started';
       dirty = true;
       writeProgress();
@@ -137,6 +138,7 @@ export function createDispatchProgressTracker(root, turn, options = {}) {
       const now = new Date().toISOString();
       const wasSilent = state.activity_type === 'silent';
       state.last_activity_at = now;
+      state.first_output_at = state.first_output_at || now;
       state.activity_type = 'output';
       state.silent_since = null;
       if (stream === 'stderr') {

package/src/lib/governed-state.js

@@ -955,6 +955,67 @@ function writeState(root, state) {
   safeWriteJson(join(root, STATE_PATH), stripLegacyCurrentTurn(state));
 }
 
+export function transitionActiveTurnLifecycle(root, turnId, nextStatus, options = {}) {
+  const state = readState(root);
+  if (!state) {
+    return { ok: false, error: 'No governed state found' };
+  }
+
+  const activeTurns = { ...(state.active_turns || {}) };
+  const turn = activeTurns[turnId];
+  if (!turn) {
+    return { ok: false, error: `Turn ${turnId} not found in active turns` };
+  }
+
+  const nowIso = options.at || new Date().toISOString();
+  const nextTurn = { ...turn };
+
+  if (nextStatus === 'dispatched') {
+    nextTurn.status = 'dispatched';
+    nextTurn.dispatched_at = nowIso;
+    delete nextTurn.started_at;
+    delete nextTurn.worker_attached_at;
+    delete nextTurn.worker_pid;
+    delete nextTurn.first_output_at;
+    delete nextTurn.first_output_stream;
+    emitRunEvent(root, 'turn_dispatched', {
+      run_id: state.run_id,
+      phase: state.phase,
+      status: state.status,
+      turn: { turn_id: turnId, role_id: turn.assigned_role },
+      intent_id: turn.intake_context?.intent_id || null,
+    });
+  } else if (nextStatus === 'starting') {
+    nextTurn.status = 'starting';
+    nextTurn.started_at = nowIso;
+    nextTurn.worker_attached_at = nowIso;
+    if (options.pid != null) {
+      nextTurn.worker_pid = options.pid;
+    }
+  } else if (nextStatus === 'running') {
+    nextTurn.status = 'running';
+    nextTurn.started_at = nextTurn.started_at || nowIso;
+    nextTurn.first_output_at = nextTurn.first_output_at || nowIso;
+    if (options.stream) {
+      nextTurn.first_output_stream = nextTurn.first_output_stream || options.stream;
+    }
+  } else {
+    return { ok: false, error: `Unsupported turn lifecycle status: ${nextStatus}` };
+  }
+
+  activeTurns[turnId] = nextTurn;
+  const nextState = {
+    ...state,
+    active_turns: activeTurns,
+  };
+  writeState(root, nextState);
+  return {
+    ok: true,
+    state: attachLegacyCurrentTurnAlias(nextState),
+    turn: attachLegacyCurrentTurnAlias(nextState).active_turns[turnId],
+  };
+}
+
 function appendJsonl(root, relPath, entry) {
   const filePath = join(root, relPath);
   mkdirSync(dirname(filePath), { recursive: true });
@@ -2459,6 +2520,144 @@ export function reactivateGovernedRun(root, state, details = {}) {
   };
 }
 
+export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null) {
+  const currentState = state && typeof state === 'object' ? state : readState(root);
+  if (!currentState) {
+    return { ok: false, error: 'No governed state.json found' };
+  }
+
+  if (currentState.status !== 'active' || getActiveTurnCount(currentState) > 0) {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      advanced: false,
+    };
+  }
+
+  const gateFailure = currentState.last_gate_failure;
+  if (gateFailure?.gate_type !== 'phase_transition') {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      advanced: false,
+    };
+  }
+
+  const historyEntries = readJsonlEntries(root, HISTORY_PATH);
+  const phaseSource = findHistoryTurnRequest(
+    historyEntries,
+    gateFailure.requested_by_turn || currentState.last_completed_turn_id || null,
+    'phase_transition',
+  );
+  if (!phaseSource?.phase_transition_request) {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      advanced: false,
+    };
+  }
+
+  const gateResult = evaluatePhaseExit({
+    state: { ...currentState, history: historyEntries },
+    config,
+    acceptedTurn: phaseSource,
+    root,
+  });
+
+  if (gateResult.action === 'awaiting_human_approval') {
+    const pausedState = {
+      ...currentState,
+      status: 'paused',
+      blocked_on: `human_approval:${gateResult.gate_id}`,
+      blocked_reason: null,
+      pending_phase_transition: {
+        from: currentState.phase,
+        to: gateResult.next_phase,
+        gate: gateResult.gate_id,
+        requested_by_turn: phaseSource.turn_id,
+        requested_at: new Date().toISOString(),
+      },
+    };
+    writeState(root, pausedState);
+    const approved = approvePhaseTransition(root, config);
+    return {
+      ok: approved.ok,
+      error: approved.error,
+      state: approved.state || attachLegacyCurrentTurnAlias(readState(root)),
+      advanced: approved.ok,
+      from_phase: currentState.phase,
+      to_phase: approved.state?.phase || gateResult.next_phase || null,
+      gate_id: gateResult.gate_id || null,
+      gateResult,
+    };
+  }
+
+  if (gateResult.action !== 'advance') {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      advanced: false,
+      gateResult,
+    };
+  }
+
+  const now = new Date().toISOString();
+  const prevPhase = currentState.phase;
+  const nextState = {
+    ...currentState,
+    phase: gateResult.next_phase,
+    phase_entered_at: now,
+    blocked_on: null,
+    blocked_reason: null,
+    last_gate_failure: null,
+    pending_phase_transition: null,
+    queued_phase_transition: null,
+    phase_gate_status: {
+      ...(currentState.phase_gate_status || {}),
+      [gateResult.gate_id || 'no_gate']: 'passed',
+    },
+  };
+
+  writeState(root, nextState);
+  const retiredIntentIds = retireApprovedPhaseScopedIntents(root, nextState, config, prevPhase, now);
+  if (retiredIntentIds.length > 0) {
+    emitRunEvent(root, 'intent_retired_by_phase_advance', {
+      run_id: nextState.run_id,
+      phase: nextState.phase,
+      status: nextState.status,
+      turn: phaseSource.turn_id ? { turn_id: phaseSource.turn_id, role_id: phaseSource.role || phaseSource.assigned_role || null } : undefined,
+      payload: {
+        exited_phase: prevPhase,
+        entered_phase: gateResult.next_phase,
+        retired_count: retiredIntentIds.length,
+        retired_intent_ids: retiredIntentIds,
+      },
+    });
+  }
+  emitRunEvent(root, 'phase_entered', {
+    run_id: nextState.run_id,
+    phase: nextState.phase,
+    status: nextState.status,
+    turn: phaseSource.turn_id ? { turn_id: phaseSource.turn_id, role_id: phaseSource.role || phaseSource.assigned_role || null } : undefined,
+    payload: {
+      from: prevPhase,
+      to: gateResult.next_phase,
+      gate_id: gateResult.gate_id || 'no_gate',
+      trigger: 'reconciled_before_dispatch',
+    },
+  });
+
+  return {
+    ok: true,
+    state: attachLegacyCurrentTurnAlias(nextState),
+    advanced: true,
+    from_phase: prevPhase,
+    to_phase: gateResult.next_phase,
+    gate_id: gateResult.gate_id || null,
+    gateResult,
+  };
+}
+
 // ── Core Operations ──────────────────────────────────────────────────────────
 
 /**
@@ -2760,9 +2959,9 @@ export function assignGovernedTurn(root, config, roleId, options = {}) {
   const newTurn = {
     turn_id: turnId,
     assigned_role: roleId,
-    status: 'running',
+    status: 'assigned',
     attempt: 1,
-    started_at: now,
+    assigned_at: now,
     deadline_at: new Date(Date.now() + timeoutMinutes * 60 * 1000).toISOString(),
     runtime_id: runtimeId,
     baseline,
@@ -2812,14 +3011,6 @@ export function assignGovernedTurn(root, config, roleId, options = {}) {
 
   writeState(root, updatedState);
 
-  emitRunEvent(root, 'turn_dispatched', {
-    run_id: updatedState.run_id,
-    phase: updatedState.phase,
-    status: updatedState.status,
-    turn: { turn_id: turnId, role_id: roleId },
-    intent_id: options.intakeContext?.intent_id || null,
-  });
-
   // Session checkpoint — non-fatal, written after every successful turn assignment.
   // Pass the captured baseline so session.json agrees with state.json (BUG-2 fix).
   writeSessionCheckpoint(root, updatedState, 'turn_assigned', {
@@ -3032,9 +3223,9 @@ export function reissueTurn(root, config, opts = {}) {
   const newTurn = {
     turn_id: newTurnId,
     assigned_role: roleId,
-    status: 'running',
+    status: 'assigned',
     attempt: (oldTurn.attempt || 1) + 1,
-    started_at: now,
+    assigned_at: now,
     deadline_at: new Date(Date.now() + timeoutMinutes * 60 * 1000).toISOString(),
     runtime_id: currentRuntimeId,
     baseline: newBaseline,
@@ -3053,10 +3244,30 @@ export function reissueTurn(root, config, opts = {}) {
   delete newActiveTurns[turnId];
   newActiveTurns[newTurnId] = newTurn;
 
+  // BUG-51 fix #6 (reissue path): release the old turn's reservation and create
+  // a fresh reservation for the new turn. Without this, an operator who runs
+  // `reissue-turn` before the watchdog fires (e.g., drift recovery, or
+  // operator-initiated reissue) leaves the old turn's reservation lingering in
+  // budget_reservations and the new turn carries no budget tracking at all.
+  // The watchdog paths (reconcileStaleTurns / failTurnStartup) already release
+  // on stalled/failed_start; this closes the same hole on the reissue surface.
+  const newReservations = { ...(state.budget_reservations || {}) };
+  delete newReservations[turnId];
+  const reissueEstimate = estimateTurnBudget(config, roleId);
+  if (reissueEstimate > 0) {
+    newReservations[newTurnId] = {
+      reserved_usd: reissueEstimate,
+      role_id: roleId,
+      created_at: now,
+      reissued_from: oldTurn.turn_id,
+    };
+  }
+
   const updatedState = {
     ...state,
     turn_sequence: nextSequence,
     active_turns: newActiveTurns,
+    budget_reservations: newReservations,
   };
 
   writeState(root, updatedState);
@@ -3518,8 +3729,37 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     ],
   );
   if (!dirtyParity.clean) {
-    transitionToFailedAcceptance(root, state, currentTurn, dirtyParity.reason, {
-      error_code: 'artifact_dirty_tree_mismatch',
+    // BUG-55 sub-defect B: when the turn declared verification commands or
+    // machine evidence, undeclared dirty files are most likely verification
+    // outputs that need classification under verification.produced_files
+    // (disposition 'ignore' to clean up, or 'artifact' to include in the
+    // checkpoint). Surface a dedicated error class + message so the agent
+    // knows the correct remediation surface, instead of the generic
+    // files_changed-or-produced_files-or-clean advice that the non-
+    // verification path emits.
+    const verification = turnResult.verification && typeof turnResult.verification === 'object'
+      ? turnResult.verification
+      : {};
+    const declaredVerificationCommands = Array.isArray(verification.commands)
+      && verification.commands.some((c) => typeof c === 'string' && c.trim().length > 0);
+    const declaredMachineEvidence = Array.isArray(verification.machine_evidence)
+      && verification.machine_evidence.some((e) => e && typeof e === 'object' && typeof e.command === 'string' && e.command.trim().length > 0);
+    const verificationWasDeclared = declaredVerificationCommands || declaredMachineEvidence;
+
+    let failureReason = dirtyParity.reason;
+    let failureErrorCode = 'artifact_dirty_tree_mismatch';
+    if (verificationWasDeclared) {
+      failureErrorCode = 'undeclared_verification_outputs';
+      const undeclared = Array.isArray(dirtyParity.unexpected_dirty_files)
+        ? dirtyParity.unexpected_dirty_files
+        : [];
+      const listForMessage = undeclared.slice(0, 5).join(', ')
+        + (undeclared.length > 5 ? '...' : '');
+      failureReason = `Verification was declared (commands or machine_evidence), but these files are dirty and not classified: ${listForMessage}. Classify each under verification.produced_files with disposition "ignore" (the file should be cleaned up after replay) or "artifact" (the file should be checkpointed as part of the turn), OR add it to files_changed if it is a core turn mutation. Acceptance cannot proceed until the declared contract matches the working tree.`;
+    }
+
+    transitionToFailedAcceptance(root, state, currentTurn, failureReason, {
+      error_code: failureErrorCode,
       stage: 'artifact_observation',
       extra: {
         unexpected_dirty_files: dirtyParity.unexpected_dirty_files,
@@ -3528,13 +3768,14 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     });
     return {
       ok: false,
-      error: dirtyParity.reason,
+      error: failureReason,
+      error_code: failureErrorCode,
       validation: {
         ...validation,
         ok: false,
         stage: 'artifact_observation',
         error_class: 'artifact_error',
-        errors: [dirtyParity.reason],
+        errors: [failureReason],
         warnings: validation.warnings,
       },
     };
@@ -5175,7 +5416,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
  * Reject a governed turn.
  *
  * 1. Preserve the invalid staged artifact under .agentxchain/dispatch/rejected/
- * 2. Increment current_turn.attempt or escalate if retries exhausted
+ * 2. Increment the active turn's attempt counter or escalate if retries exhausted
  * 3. Clear staging file
  *
  * Does NOT append to history.jsonl or decision-ledger.jsonl.

package/src/lib/intake.js

@@ -8,6 +8,7 @@ import {
   assignGovernedTurn,
   getActiveTurns,
   getActiveTurnCount,
+  transitionActiveTurnLifecycle,
   STATE_PATH,
 } from './governed-state.js';
 import { loadProjectContext, loadProjectState } from './config.js';
@@ -1090,10 +1091,18 @@ export function startIntent(root, intentId, options = {}) {
       return { ok: false, error: `dispatch bundle failed: ${bundleResult.error}`, exitCode: 1 };
     }
 
-    finalizeDispatchManifest(root, assignedTurn.turn_id, {
+    const manifestResult = finalizeDispatchManifest(root, assignedTurn.turn_id, {
       run_id: state.run_id,
       role: assignedTurn.assigned_role,
     });
+    if (!manifestResult.ok) {
+      return { ok: false, error: `dispatch manifest failed: ${manifestResult.error}`, exitCode: 1 };
+    }
+    const dispatched = transitionActiveTurnLifecycle(root, assignedTurn.turn_id, 'dispatched');
+    if (!dispatched.ok) {
+      return { ok: false, error: `dispatch lifecycle transition failed: ${dispatched.error}`, exitCode: 1 };
+    }
+    state = dispatched.state;
   }
 
   // Update intent: planned → executing