agentxchain 2.46.0 → 2.47.0

package/src/lib/export.js

@@ -6,6 +6,7 @@ import { join, relative, resolve } from 'node:path';
 import { loadProjectContext, loadProjectState } from './config.js';
 import { loadCoordinatorConfig, COORDINATOR_CONFIG_FILE } from './coordinator-config.js';
 import { loadCoordinatorState } from './coordinator-state.js';
+import { normalizeRunProvenance } from './run-provenance.js';
 
 const EXPORT_SCHEMA_VERSION = '0.3';
 
@@ -296,6 +297,7 @@ export function buildRunExport(startDir = process.cwd()) {
         run_id: state?.run_id || null,
         status: state?.status || null,
         phase: state?.phase || null,
+        provenance: normalizeRunProvenance(state?.provenance),
         active_turn_ids: activeTurns,
         retained_turn_ids: retainedTurns,
         history_entries: countJsonl(files, '.agentxchain/history.jsonl'),

package/src/lib/governed-state.js

@@ -20,11 +20,15 @@ import { join, dirname } from 'path';
 import { randomBytes, createHash } from 'crypto';
 import { safeWriteJson } from './safe-write.js';
 import { validateStagedTurnResult } from './turn-result-validator.js';
-import { evaluatePhaseExit, evaluateRunCompletion } from './gate-evaluator.js';
+import { evaluatePhaseExit, evaluateRunCompletion, getNextPhase } from './gate-evaluator.js';
+import { evaluateApprovalPolicy } from './approval-policy.js';
 import { evaluatePolicies } from './policy-evaluator.js';
+import { buildTimeoutBlockedReason, evaluateTimeouts } from './timeout-evaluator.js';
 import {
   captureBaseline,
   observeChanges,
+  attributeObservedChangesToTurn,
+  buildConflictCandidateFiles,
   classifyObservedChanges,
   buildObservedArtifact,
   normalizeVerification,
@@ -38,6 +42,7 @@ import { runHooks } from './hook-runner.js';
 import { emitNotifications } from './notification-runner.js';
 import { writeSessionCheckpoint } from './session-checkpoint.js';
 import { recordRunHistory } from './run-history.js';
+import { buildDefaultRunProvenance } from './run-provenance.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -57,6 +62,92 @@ function generateId(prefix) {
   return `${prefix}_${randomBytes(8).toString('hex')}`;
 }
 
+function getInitialPhase(config) {
+  return Object.keys(config?.routing || {})[0] || 'planning';
+}
+
+function buildInitialPhaseGateStatus(config) {
+  return Object.fromEntries(
+    [...new Set(
+      Object.values(config?.routing || {})
+        .map((route) => route?.exit_gate)
+        .filter(Boolean)
+    )].map((gateId) => [gateId, 'pending'])
+  );
+}
+
+function buildFreshIdleStateForNewRun(state, config) {
+  return {
+    schema_version: state?.schema_version || GOVERNED_SCHEMA_VERSION,
+    run_id: null,
+    project_id: state?.project_id || config?.project?.id || null,
+    status: 'idle',
+    phase: getInitialPhase(config),
+    accepted_integration_ref: null,
+    active_turns: {},
+    turn_sequence: 0,
+    last_completed_turn_id: null,
+    blocked_on: null,
+    blocked_reason: null,
+    escalation: null,
+    pending_phase_transition: null,
+    pending_run_completion: null,
+    queued_phase_transition: null,
+    queued_run_completion: null,
+    last_gate_failure: null,
+    phase_gate_status: buildInitialPhaseGateStatus(config),
+    budget_reservations: {},
+    budget_status: {
+      spent_usd: 0,
+      remaining_usd: config?.budget?.per_run_max_usd ?? null,
+    },
+  };
+}
+
+function normalizeGateFailure(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return {
+    gate_type: value.gate_type === 'run_completion' ? 'run_completion' : 'phase_transition',
+    gate_id: typeof value.gate_id === 'string' && value.gate_id.length > 0 ? value.gate_id : null,
+    phase: typeof value.phase === 'string' && value.phase.length > 0 ? value.phase : 'unknown',
+    from_phase: typeof value.from_phase === 'string' && value.from_phase.length > 0 ? value.from_phase : null,
+    to_phase: typeof value.to_phase === 'string' && value.to_phase.length > 0 ? value.to_phase : null,
+    requested_by_turn: typeof value.requested_by_turn === 'string' && value.requested_by_turn.length > 0 ? value.requested_by_turn : null,
+    failed_at: typeof value.failed_at === 'string' && value.failed_at.length > 0 ? value.failed_at : null,
+    queued_request: value.queued_request === true,
+    reasons: Array.isArray(value.reasons) ? value.reasons.filter((reason) => typeof reason === 'string' && reason.length > 0) : [],
+    missing_files: Array.isArray(value.missing_files) ? value.missing_files.filter((path) => typeof path === 'string' && path.length > 0) : [],
+    missing_verification: value.missing_verification === true,
+  };
+}
+
+function buildGateFailureRecord({
+  gateType,
+  gateResult,
+  phase,
+  fromPhase = null,
+  toPhase = null,
+  requestedByTurn = null,
+  failedAt,
+  queuedRequest,
+}) {
+  return normalizeGateFailure({
+    gate_type: gateType,
+    gate_id: gateResult?.gate_id || null,
+    phase,
+    from_phase: fromPhase,
+    to_phase: toPhase,
+    requested_by_turn: requestedByTurn,
+    failed_at: failedAt,
+    queued_request: queuedRequest,
+    reasons: Array.isArray(gateResult?.reasons) ? gateResult.reasons : [],
+    missing_files: Array.isArray(gateResult?.missing_files) ? gateResult.missing_files : [],
+    missing_verification: gateResult?.missing_verification === true,
+  });
+}
+
 function emitBlockedNotification(root, config, state, details = {}, turn = null) {
   if (!config?.notifications?.webhooks?.length) {
     return;
@@ -608,6 +699,7 @@ function normalizeV1toV1_1(state) {
         : {},
     queued_phase_transition: state.queued_phase_transition ?? null,
     queued_run_completion: state.queued_run_completion ?? null,
+    last_gate_failure: normalizeGateFailure(state.last_gate_failure),
   };
 }
 
@@ -880,8 +972,8 @@ function cleanupTurnArtifacts(root, turnId) {
   } catch { /* best-effort */ }
 }
 
-function detectAcceptanceConflict(targetTurn, observedArtifact, historyEntries) {
-  const observedFiles = [...new Set(getObservedFiles({ observed_artifact: observedArtifact }))];
+function detectAcceptanceConflict(targetTurn, conflictFiles, historyEntries) {
+  const observedFiles = [...new Set(Array.isArray(conflictFiles) ? conflictFiles : [])];
   if (observedFiles.length === 0) {
     return null;
   }
@@ -1000,6 +1092,101 @@ function buildBlockedReason({ category, recovery, turnId, blockedAt = new Date()
   };
 }
 
+function buildTimeoutLedgerEntry(timeoutResult, timestamp, turnId, phase, type = 'timeout') {
+  return {
+    type,
+    scope: timeoutResult.scope,
+    phase: timeoutResult.phase || phase || null,
+    turn_id: turnId || null,
+    limit_minutes: timeoutResult.limit_minutes,
+    elapsed_minutes: timeoutResult.elapsed_minutes,
+    exceeded_by_minutes: timeoutResult.exceeded_by_minutes,
+    action: timeoutResult.action,
+    timestamp,
+  };
+}
+
+function attemptTimeoutPhaseSkip({ root, config, updatedState, nextHistoryEntries, historyEntry, timeoutResult, now }) {
+  const currentPhase = updatedState.phase;
+  const nextPhase = getNextPhase(currentPhase, config.routing || {});
+  if (!nextPhase) {
+    return {
+      ok: false,
+      error: `Phase "${currentPhase}" has no next phase to skip to`,
+    };
+  }
+
+  const syntheticTurn = {
+    ...historyEntry,
+    verification: historyEntry.verification || {},
+    phase_transition_request: nextPhase,
+  };
+  const postAcceptanceState = {
+    ...updatedState,
+    history: nextHistoryEntries,
+  };
+  const gateResult = evaluatePhaseExit({
+    state: postAcceptanceState,
+    config,
+    acceptedTurn: syntheticTurn,
+    root,
+  });
+
+  if (gateResult.action === 'advance') {
+    return {
+      ok: true,
+      gateResult,
+      updatedState: {
+        ...updatedState,
+        phase: gateResult.next_phase,
+        phase_entered_at: now,
+        last_gate_failure: null,
+        phase_gate_status: {
+          ...(updatedState.phase_gate_status || {}),
+          [gateResult.gate_id || 'no_gate']: 'passed',
+        },
+      },
+      ledgerEntry: {
+        ...buildTimeoutLedgerEntry(timeoutResult, now, historyEntry.turn_id, currentPhase, 'timeout_skip'),
+        from_phase: currentPhase,
+        to_phase: gateResult.next_phase,
+        gate_id: gateResult.gate_id || null,
+      },
+    };
+  }
+
+  const reasons = gateResult.action === 'awaiting_human_approval'
+    ? [`Gate "${gateResult.gate_id || 'unknown'}" still requires human approval; timeout skip cannot auto-advance`]
+    : Array.isArray(gateResult.reasons) && gateResult.reasons.length > 0
+      ? gateResult.reasons
+      : ['Timeout skip failed for an unknown reason'];
+  const gateFailure = buildGateFailureRecord({
+    gateType: 'phase_transition',
+    gateResult: {
+      ...gateResult,
+      reasons,
+    },
+    phase: currentPhase,
+    fromPhase: currentPhase,
+    toPhase: nextPhase,
+    requestedByTurn: historyEntry.turn_id,
+    failedAt: now,
+    queuedRequest: false,
+  });
+
+  return {
+    ok: false,
+    gateFailure,
+    ledgerEntry: {
+      ...buildTimeoutLedgerEntry(timeoutResult, now, historyEntry.turn_id, currentPhase, 'timeout_skip_failed'),
+      from_phase: currentPhase,
+      to_phase: nextPhase,
+      gate_id: gateResult.gate_id || null,
+      reasons,
+    },
+  };
+}
+
 function slugifyEscalationReason(reason) {
   if (typeof reason !== 'string') {
     return 'operator';
@@ -1410,6 +1597,15 @@ export function normalizeGovernedStateShape(state) {
     changed = true;
   }
 
+  const normalizedLastGateFailure = normalizeGateFailure(nextState.last_gate_failure);
+  if (JSON.stringify(nextState.last_gate_failure ?? null) !== JSON.stringify(normalizedLastGateFailure)) {
+    nextState = {
+      ...nextState,
+      last_gate_failure: normalizedLastGateFailure,
+    };
+    changed = true;
+  }
+
   return { state: stripLegacyCurrentTurn(nextState), changed };
 }
 
@@ -1613,30 +1809,40 @@ export function reactivateGovernedRun(root, state, details = {}) {
  * @param {object} config - normalized config
  * @returns {{ ok: boolean, error?: string, state?: object }}
  */
-export function initializeGovernedRun(root, config) {
-  const state = readState(root);
+export function initializeGovernedRun(root, config, options = {}) {
+  let state = readState(root);
   if (!state) {
     return { ok: false, error: 'No governed state.json found' };
   }
-  if (state.status === 'completed') {
+  const allowTerminalRestart = options.allow_terminal_restart === true
+    && (state.status === 'completed' || state.status === 'blocked');
+  if (state.status === 'completed' && !allowTerminalRestart) {
     return { ok: false, error: 'Cannot initialize run: this run is already completed. Start a new project or reset state.' };
   }
   const allowBlockedBootstrap = state.status === 'blocked' && state.run_id === null && getActiveTurnCount(state) === 0;
-  if (state.status !== 'idle' && state.status !== 'paused' && !allowBlockedBootstrap) {
+  if (state.status !== 'idle' && state.status !== 'paused' && !allowBlockedBootstrap && !allowTerminalRestart) {
     return { ok: false, error: `Cannot initialize run: status is "${state.status}", expected "idle", "paused", or pre-run "blocked"` };
   }
+  if (allowTerminalRestart) {
+    state = buildFreshIdleStateForNewRun(state, config);
+  }
 
   const runId = generateId('run');
+  const now = new Date().toISOString();
+  const provenance = buildDefaultRunProvenance(options.provenance);
   const updatedState = {
     ...state,
     run_id: runId,
+    created_at: now,
+    phase_entered_at: now,
     status: 'active',
     blocked_on: null,
     blocked_reason: null,
     budget_status: {
       spent_usd: 0,
       remaining_usd: config.budget?.per_run_max_usd ?? null
-    }
+    },
+    provenance,
   };
 
   writeState(root, updatedState);
@@ -2092,7 +2298,9 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const stagingFile = join(root, resolvedStagingPath);
   const now = new Date().toISOString();
   const baseline = currentTurn.baseline || null;
-  const observation = observeChanges(root, baseline);
+  const rawObservation = observeChanges(root, baseline);
+  const historyEntries = readJsonlEntries(root, HISTORY_PATH);
+  const observation = attributeObservedChangesToTurn(rawObservation, currentTurn, historyEntries);
   const role = config.roles?.[turnResult.role];
   const runtimeId = turnResult.runtime_id;
   const runtime = config.runtimes?.[runtimeId];
@@ -2125,7 +2333,6 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   const normalizedVerification = normalizeVerification(turnResult.verification, runtimeType);
   const artifactType = turnResult.artifact?.type || 'review';
   const derivedRef = deriveAcceptedRef(observation, artifactType, state.accepted_integration_ref);
-  const historyEntries = readJsonlEntries(root, HISTORY_PATH);
 
   // Policy evaluation — declarative governance rules (spec: POLICY_ENGINE_SPEC.md)
   const policyResult = evaluatePolicies(config.policies || [], {
@@ -2203,7 +2410,11 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     };
   }
 
-  const conflict = detectAcceptanceConflict(currentTurn, observedArtifact, historyEntries);
+  const conflict = detectAcceptanceConflict(
+    currentTurn,
+    buildConflictCandidateFiles(rawObservation, observation, turnResult.files_changed || []),
+    historyEntries,
+  );
 
   if (conflict) {
     const detectionCount = (currentTurn.conflict_state?.detection_count || 0) + 1;
@@ -2338,6 +2549,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     cost: turnResult.cost || {},
     accepted_at: now,
   };
+  const nextHistoryEntries = [...historyEntries, historyEntry];
   // Build ledger entries for the journal
   const ledgerEntries = [];
   if (turnResult.decisions && turnResult.decisions.length > 0) {
@@ -2451,6 +2663,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
 
   let gateResult = null;
   let completionResult = null;
+  let timeoutResult = null;
   const hasRemainingTurns = Object.keys(remainingTurns).length > 0;
   if (turnResult.status !== 'needs_human') {
     if (hasRemainingTurns) {
@@ -2469,7 +2682,6 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         };
       }
     } else {
-      const nextHistoryEntries = [...historyEntries, historyEntry];
       const postAcceptanceState = {
         ...state,
         active_turns: remainingTurns,
@@ -2491,6 +2703,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         if (completionResult.action === 'complete') {
           updatedState.status = 'completed';
           updatedState.completed_at = now;
+          updatedState.last_gate_failure = null;
           if (completionResult.gate_id) {
             updatedState.phase_gate_status = {
               ...(updatedState.phase_gate_status || {}),
@@ -2500,16 +2713,71 @@ function _acceptGovernedTurnLocked(root, config, opts) {
           updatedState.queued_run_completion = null;
           updatedState.queued_phase_transition = null;
         } else if (completionResult.action === 'awaiting_human_approval') {
-          updatedState.status = 'paused';
-          updatedState.blocked_on = `human_approval:${completionResult.gate_id}`;
-          updatedState.blocked_reason = null;
-          updatedState.pending_run_completion = {
-            gate: completionResult.gate_id,
-            requested_by_turn: completionSource.turn_id,
-            requested_at: now,
-          };
+          // Evaluate approval policy — may auto-approve
+          const approvalResult = evaluateApprovalPolicy({
+            gateResult: completionResult,
+            gateType: 'run_completion',
+            state: { ...updatedState, history: nextHistoryEntries },
+            config,
+          });
+
+          if (approvalResult.action === 'auto_approve') {
+            updatedState.status = 'completed';
+            updatedState.completed_at = now;
+            updatedState.last_gate_failure = null;
+            if (completionResult.gate_id) {
+              updatedState.phase_gate_status = {
+                ...(updatedState.phase_gate_status || {}),
+                [completionResult.gate_id]: 'passed',
+              };
+            }
+            updatedState.queued_run_completion = null;
+            updatedState.queued_phase_transition = null;
+            ledgerEntries.push({
+              type: 'approval_policy',
+              gate_type: 'run_completion',
+              action: 'auto_approve',
+              matched_rule: approvalResult.matched_rule,
+              reason: approvalResult.reason,
+              gate_id: completionResult.gate_id,
+              timestamp: now,
+            });
+          } else {
+            updatedState.status = 'paused';
+            updatedState.blocked_on = `human_approval:${completionResult.gate_id}`;
+            updatedState.blocked_reason = null;
+            updatedState.last_gate_failure = null;
+            updatedState.pending_run_completion = {
+              gate: completionResult.gate_id,
+              requested_by_turn: completionSource.turn_id,
+              requested_at: now,
+            };
+            updatedState.queued_run_completion = null;
+            updatedState.queued_phase_transition = null;
+          }
+        } else if (completionResult.action === 'gate_failed') {
+          const gateFailure = buildGateFailureRecord({
+            gateType: 'run_completion',
+            gateResult: completionResult,
+            phase: state.phase,
+            fromPhase: state.phase,
+            toPhase: null,
+            requestedByTurn: completionSource?.turn_id || state.queued_run_completion?.requested_by_turn || null,
+            failedAt: now,
+            queuedRequest: Boolean(state.queued_run_completion && !turnResult.run_completion_request),
+          });
+          updatedState.last_gate_failure = gateFailure;
+          if (completionResult.gate_id) {
+            updatedState.phase_gate_status = {
+              ...(updatedState.phase_gate_status || {}),
+              [completionResult.gate_id]: 'failed',
+            };
+          }
           updatedState.queued_run_completion = null;
-          updatedState.queued_phase_transition = null;
+          ledgerEntries.push({
+            type: 'gate_failure',
+            ...gateFailure,
+          });
         } else if (state.queued_run_completion) {
           updatedState.queued_run_completion = null;
         }
@@ -2531,22 +2799,78 @@ function _acceptGovernedTurnLocked(root, config, opts) {
 
         if (gateResult.action === 'advance') {
           updatedState.phase = gateResult.next_phase;
+          updatedState.phase_entered_at = now;
+          updatedState.last_gate_failure = null;
           updatedState.phase_gate_status = {
             ...(updatedState.phase_gate_status || {}),
             [gateResult.gate_id || 'no_gate']: 'passed',
           };
           updatedState.queued_phase_transition = null;
         } else if (gateResult.action === 'awaiting_human_approval') {
-          updatedState.status = 'paused';
-          updatedState.blocked_on = `human_approval:${gateResult.gate_id}`;
-          updatedState.blocked_reason = null;
-          updatedState.pending_phase_transition = {
-            from: state.phase,
-            to: gateResult.next_phase,
-            gate: gateResult.gate_id,
-            requested_by_turn: phaseSource.turn_id,
-          };
+          // Evaluate approval policy — may auto-approve
+          const approvalResult = evaluateApprovalPolicy({
+            gateResult,
+            gateType: 'phase_transition',
+            state: { ...updatedState, history: nextHistoryEntries },
+            config,
+          });
+
+          if (approvalResult.action === 'auto_approve') {
+            updatedState.phase = gateResult.next_phase;
+            updatedState.phase_entered_at = now;
+            updatedState.last_gate_failure = null;
+            updatedState.phase_gate_status = {
+              ...(updatedState.phase_gate_status || {}),
+              [gateResult.gate_id || 'no_gate']: 'passed',
+            };
+            updatedState.queued_phase_transition = null;
+            ledgerEntries.push({
+              type: 'approval_policy',
+              gate_type: 'phase_transition',
+              action: 'auto_approve',
+              matched_rule: approvalResult.matched_rule,
+              from_phase: state.phase,
+              to_phase: gateResult.next_phase,
+              reason: approvalResult.reason,
+              gate_id: gateResult.gate_id,
+              timestamp: now,
+            });
+          } else {
+            updatedState.status = 'paused';
+            updatedState.blocked_on = `human_approval:${gateResult.gate_id}`;
+            updatedState.blocked_reason = null;
+            updatedState.last_gate_failure = null;
+            updatedState.pending_phase_transition = {
+              from: state.phase,
+              to: gateResult.next_phase,
+              gate: gateResult.gate_id,
+              requested_by_turn: phaseSource.turn_id,
+            };
+            updatedState.queued_phase_transition = null;
+          }
+        } else if (gateResult.action === 'gate_failed') {
+          const gateFailure = buildGateFailureRecord({
+            gateType: 'phase_transition',
+            gateResult,
+            phase: state.phase,
+            fromPhase: state.phase,
+            toPhase: gateResult.transition_request || state.queued_phase_transition?.to || null,
+            requestedByTurn: phaseSource?.turn_id || state.queued_phase_transition?.requested_by_turn || null,
+            failedAt: now,
+            queuedRequest: Boolean(state.queued_phase_transition && !turnResult.phase_transition_request),
+          });
+          updatedState.last_gate_failure = gateFailure;
+          if (gateResult.gate_id) {
+            updatedState.phase_gate_status = {
+              ...(updatedState.phase_gate_status || {}),
+              [gateResult.gate_id]: 'failed',
+            };
+          }
           updatedState.queued_phase_transition = null;
+          ledgerEntries.push({
+            type: 'gate_failure',
+            ...gateFailure,
+          });
         } else if (state.queued_phase_transition) {
           updatedState.queued_phase_transition = null;
         }
@@ -2554,6 +2878,77 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }
   }
 
+  const timeoutEvaluation = evaluateTimeouts({
+    config,
+    state: updatedState,
+    turn: currentTurn,
+    turnResult,
+    now,
+  });
+  for (const warning of timeoutEvaluation.warnings) {
+    ledgerEntries.push(buildTimeoutLedgerEntry(warning, now, currentTurn.turn_id, updatedState.phase, 'timeout_warning'));
+  }
+
+  if (updatedState.status === 'active' && timeoutEvaluation.exceeded.length > 0) {
+    timeoutResult = timeoutEvaluation.exceeded[0];
+
+    if (timeoutResult.action === 'skip_phase' && timeoutResult.scope === 'phase') {
+      const skipAttempt = attemptTimeoutPhaseSkip({
+        root,
+        config,
+        updatedState,
+        nextHistoryEntries,
+        historyEntry,
+        timeoutResult,
+        now,
+      });
+
+      if (skipAttempt.ok) {
+        updatedState.phase = skipAttempt.updatedState.phase;
+        updatedState.phase_entered_at = skipAttempt.updatedState.phase_entered_at;
+        updatedState.last_gate_failure = skipAttempt.updatedState.last_gate_failure;
+        updatedState.phase_gate_status = skipAttempt.updatedState.phase_gate_status;
+        ledgerEntries.push(skipAttempt.ledgerEntry);
+      } else {
+        const escalatedTimeout = { ...timeoutResult, action: 'escalate' };
+        timeoutResult = escalatedTimeout;
+        updatedState.status = 'blocked';
+        updatedState.blocked_on = `timeout:${escalatedTimeout.scope}`;
+        updatedState.blocked_reason = buildBlockedReason({
+          ...buildTimeoutBlockedReason(escalatedTimeout, {
+            turnRetained: Object.keys(getActiveTurns(updatedState)).length > 0,
+          }),
+          turnId: currentTurn.turn_id,
+          blockedAt: now,
+        });
+        updatedState.last_gate_failure = skipAttempt.gateFailure || null;
+        if (skipAttempt.gateFailure?.gate_id) {
+          updatedState.phase_gate_status = {
+            ...(updatedState.phase_gate_status || {}),
+            [skipAttempt.gateFailure.gate_id]: 'failed',
+          };
+          ledgerEntries.push({
+            type: 'gate_failure',
+            ...skipAttempt.gateFailure,
+          });
+        }
+        ledgerEntries.push(skipAttempt.ledgerEntry);
+        ledgerEntries.push(buildTimeoutLedgerEntry(escalatedTimeout, now, currentTurn.turn_id, updatedState.phase));
+      }
+    } else if (timeoutResult.action === 'escalate') {
+      updatedState.status = 'blocked';
+      updatedState.blocked_on = `timeout:${timeoutResult.scope}`;
+      updatedState.blocked_reason = buildBlockedReason({
+        ...buildTimeoutBlockedReason(timeoutResult, {
+          turnRetained: Object.keys(getActiveTurns(updatedState)).length > 0,
+        }),
+        turnId: currentTurn.turn_id,
+        blockedAt: now,
+      });
+      ledgerEntries.push(buildTimeoutLedgerEntry(timeoutResult, now, currentTurn.turn_id, updatedState.phase));
+    }
+  }
+
   // ── Transaction journal: prepare before committing writes ──────────────
   const transactionId = generateId('txn');
   const journal = {
@@ -2974,9 +3369,11 @@ export function approvePhaseTransition(root, config) {
   const updatedState = {
     ...state,
     phase: transition.to,
+    phase_entered_at: new Date().toISOString(),
     status: 'active',
     blocked_on: null,
     blocked_reason: null,
+    last_gate_failure: null,
     pending_phase_transition: null,
     phase_gate_status: {
       ...(state.phase_gate_status || {}),
@@ -3071,6 +3468,7 @@ export function approveRunCompletion(root, config) {
     completed_at: new Date().toISOString(),
     blocked_on: null,
     blocked_reason: null,
+    last_gate_failure: null,
     pending_run_completion: null,
     phase_gate_status: {
       ...(state.phase_gate_status || {}),