agentxchain 2.45.0 → 2.46.2

package/src/lib/governed-state.js

@@ -20,10 +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,
@@ -56,6 +61,50 @@ function generateId(prefix) {
   return `${prefix}_${randomBytes(8).toString('hex')}`;
 }
 
+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;
@@ -350,6 +399,58 @@ export function deriveDispatchRecoveryAction(state, config, options = {}) {
   return `Resolve the dispatch issue, then run ${command}`;
 }
 
+function normalizePolicyId(policyId) {
+  if (typeof policyId !== 'string') {
+    return null;
+  }
+  const trimmed = policyId.trim();
+  return trimmed || null;
+}
+
+function getPolicyIdFromBlockedState(state) {
+  if (typeof state?.blocked_on !== 'string' || !state.blocked_on.startsWith('policy:')) {
+    return null;
+  }
+  return normalizePolicyId(state.blocked_on.slice('policy:'.length));
+}
+
+export function derivePolicyEscalationDetail(state, options = {}) {
+  if (typeof options.detail === 'string' && options.detail.trim()) {
+    return options.detail.trim();
+  }
+
+  if (typeof state?.blocked_reason === 'string' && state.blocked_reason.trim()) {
+    return state.blocked_reason.trim();
+  }
+
+  const policyId = normalizePolicyId(options.policyId) || getPolicyIdFromBlockedState(state);
+  return policyId ? `Policy "${policyId}" triggered` : (state?.blocked_on || 'Policy escalation');
+}
+
+export function derivePolicyEscalationRecoveryAction(state, config, options = {}) {
+  const command = deriveBlockedRecoveryCommand(state, config, {
+    turnRetained: options.turnRetained,
+    turnId: options.turnId,
+  });
+  const policyId = normalizePolicyId(options.policyId) || getPolicyIdFromBlockedState(state);
+  return policyId
+    ? `Resolve policy "${policyId}" condition, then run ${command}`
+    : `Resolve the policy condition, then run ${command}`;
+}
+
+export function readTurnCostUsd(turnResult) {
+  if (!turnResult || typeof turnResult !== 'object') {
+    return null;
+  }
+  if (typeof turnResult.cost?.usd === 'number') {
+    return turnResult.cost.usd;
+  }
+  if (typeof turnResult.cost?.total_usd === 'number') {
+    return turnResult.cost.total_usd;
+  }
+  return null;
+}
+
 export function deriveHookTamperRecoveryAction(state, config, options = {}) {
   const command = deriveBlockedRecoveryCommand(state, config, {
     turnRetained: options.turnRetained,
@@ -555,6 +656,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),
   };
 }
 
@@ -827,8 +929,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;
   }
@@ -947,6 +1049,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';
@@ -1149,6 +1346,13 @@ export function reconcileRecoveryActionsWithConfig(state, config) {
         turnId,
       });
     }
+  } else if (typedReason === 'policy_escalation') {
+    nextAction = derivePolicyEscalationRecoveryAction(state, config, {
+      turnRetained,
+      turnId,
+      policyId: getPolicyIdFromBlockedState(state),
+    });
+    shouldRefresh = currentAction !== nextAction;
   } else if (typedReason === 'conflict_loop') {
     shouldRefresh = isLegacyConflictLoopRecoveryAction(currentAction);
     if (shouldRefresh) {
@@ -1262,6 +1466,25 @@ function inferBlockedReasonFromState(state) {
     });
   }
 
+  if (state.blocked_on.startsWith('policy:')) {
+    const policyId = getPolicyIdFromBlockedState(state);
+    return buildBlockedReason({
+      category: 'policy_escalation',
+      recovery: {
+        typed_reason: 'policy_escalation',
+        owner: 'human',
+        recovery_action: derivePolicyEscalationRecoveryAction(state, null, {
+          turnRetained,
+          turnId: activeTurn?.turn_id ?? state.blocked_reason?.turn_id ?? null,
+          policyId,
+        }),
+        turn_retained: turnRetained,
+        detail: derivePolicyEscalationDetail(state, { policyId }),
+      },
+      turnId: activeTurn?.turn_id ?? state.blocked_reason?.turn_id ?? null,
+    });
+  }
+
   return null;
 }
 
@@ -1331,6 +1554,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 };
 }
 
@@ -1548,9 +1780,12 @@ export function initializeGovernedRun(root, config) {
   }
 
   const runId = generateId('run');
+  const now = new Date().toISOString();
   const updatedState = {
     ...state,
     run_id: runId,
+    created_at: now,
+    phase_entered_at: now,
     status: 'active',
     blocked_on: null,
     blocked_reason: null,
@@ -2013,7 +2248,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];
@@ -2046,8 +2283,88 @@ 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);
-  const conflict = detectAcceptanceConflict(currentTurn, observedArtifact, historyEntries);
+
+  // Policy evaluation — declarative governance rules (spec: POLICY_ENGINE_SPEC.md)
+  const policyResult = evaluatePolicies(config.policies || [], {
+    currentPhase: state.phase,
+    turnRole: turnResult.role,
+    turnStatus: turnResult.status,
+    turnCostUsd: readTurnCostUsd(turnResult),
+    history: historyEntries,
+  });
+
+  if (policyResult.blocks.length > 0) {
+    const blockMessages = policyResult.blocks.map((v) => v.message);
+    return {
+      ok: false,
+      error: `Policy violation: ${blockMessages.join('; ')}`,
+      error_code: 'policy_violation',
+      policy_violations: policyResult.violations,
+    };
+  }
+
+  if (policyResult.escalations.length > 0) {
+    const escalationMessages = policyResult.escalations.map((v) => v.message);
+    const policyId = policyResult.escalations[0].policy_id;
+    const turnRetained = getActiveTurnCount(state) > 0;
+    const recovery = {
+      typed_reason: 'policy_escalation',
+      owner: 'human',
+      recovery_action: derivePolicyEscalationRecoveryAction(state, config, {
+        turnRetained,
+        turnId: currentTurn.turn_id,
+        policyId,
+      }),
+      turn_retained: turnRetained,
+      detail: derivePolicyEscalationDetail(state, {
+        policyId,
+        detail: escalationMessages.join('; '),
+      }),
+    };
+    const blockedState = {
+      ...state,
+      status: 'blocked',
+      blocked_on: `policy:${policyId}`,
+      blocked_reason: buildBlockedReason({
+        category: 'policy_escalation',
+        recovery,
+        turnId: currentTurn.turn_id,
+        blockedAt: now,
+      }),
+    };
+    writeState(root, blockedState);
+    recordRunHistory(root, blockedState, config, 'blocked');
+    emitBlockedNotification(root, config, blockedState, {
+      category: 'policy_escalation',
+      blockedOn: blockedState.blocked_on,
+      recovery,
+    }, currentTurn);
+    appendJsonl(root, LEDGER_PATH, {
+      timestamp: now,
+      decision: 'policy_escalation',
+      turn_id: currentTurn.turn_id,
+      role: turnResult.role,
+      phase: state.phase,
+      violations: policyResult.escalations.map((v) => ({
+        policy_id: v.policy_id,
+        rule: v.rule,
+        message: v.message,
+      })),
+    });
+    return {
+      ok: false,
+      error: `Policy escalation: ${escalationMessages.join('; ')}`,
+      error_code: 'policy_escalation',
+      state: attachLegacyCurrentTurnAlias(blockedState),
+      policy_violations: policyResult.violations,
+    };
+  }
+
+  const conflict = detectAcceptanceConflict(
+    currentTurn,
+    buildConflictCandidateFiles(rawObservation, observation, turnResult.files_changed || []),
+    historyEntries,
+  );
 
   if (conflict) {
     const detectionCount = (currentTurn.conflict_state?.detection_count || 0) + 1;
@@ -2182,6 +2499,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) {
@@ -2295,6 +2613,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) {
@@ -2313,7 +2632,6 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         };
       }
     } else {
-      const nextHistoryEntries = [...historyEntries, historyEntry];
       const postAcceptanceState = {
         ...state,
         active_turns: remainingTurns,
@@ -2335,6 +2653,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 || {}),
@@ -2344,16 +2663,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;
         }
@@ -2375,22 +2749,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;
         }
@@ -2398,6 +2828,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 = {
@@ -2527,6 +3028,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     completionResult,
     hookResults,
     ...(budgetWarning ? { budget_warning: budgetWarning } : {}),
+    ...(policyResult.warnings.length > 0 ? { policy_warnings: policyResult.warnings } : {}),
   };
 }
 
@@ -2817,9 +3319,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 || {}),
@@ -2914,6 +3418,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 || {}),