chainlesschain 0.162.188 → 0.162.193

package/src/runtime/headless-runner.js

@@ -22,6 +22,7 @@
  *  - bypassPermissions                   → AUTOPILOT (everything allowed)
  */
 
+import { randomUUID } from "node:crypto";
 import { bootstrap } from "./bootstrap.js";
 import {
   buildSystemPrompt,
@@ -46,7 +47,10 @@ import {
   appendLlmRetryCompact as jsonlAppendLlmRetryCompact,
   appendCompactEvent as jsonlAppendCompactEvent,
   appendEvent as jsonlAppendEvent,
+  appendAuthorityEvent as jsonlAppendAuthorityEvent,
   readEvents as jsonlReadEvents,
+  readVerifiedEvents as jsonlReadVerifiedEvents,
+  findLatestEvent as jsonlFindLatestEvent,
   rebuildMessages as jsonlRebuildMessages,
   sessionExists as jsonlSessionExists,
   getLastSessionId as jsonlGetLastSessionId,
@@ -60,6 +64,13 @@ import {
 } from "../lib/side-effect-ledger.js";
 import { DiffReviewFollowUpTracker } from "../lib/diff-review-follow-up.js";
 import { SIDE_EFFECT_LEDGER_EVENT } from "../lib/side-effect-ledger-store.js";
+import {
+  createSessionMcpLedgerSink,
+  formatMcpLedgerRecoveryNotice,
+  loadMcpLedgerRecovery,
+} from "../lib/mcp-call-ledger-store.js";
+import { createMcpHostRecoveryRuntime } from "../lib/mcp-host-recovery-runtime.js";
+import { readSessionHostResumeState } from "../lib/session-host-snapshot.js";
 import { TurnBindingLog, createTurnBindingFeed } from "../lib/turn-binding.js";
 import { TURN_BINDING_EVENT } from "../lib/turn-binding-store.js";
 import { operationIdempotencyKey } from "../lib/idempotency.js";
@@ -99,6 +110,7 @@ import {
 } from "../lib/repl-denials.js";
 import executionBroker from "../lib/process-execution-broker/index.js";
 import { extractPluginUsageAttribution } from "../lib/plugin-usage-attribution.js";
+import { formatManagedCheckpointEvent } from "../lib/managed-checkpoint-render.js";
 
 const goalBrokerRunner = executionBroker.spawnSync.bind(executionBroker);
 
@@ -295,7 +307,7 @@ export function resolveHeadlessSession(options = {}, store = {}, fallbackId) {
  * apart from the injected store's side effect; both `sessionExists`/`forkSession`
  * are injection seams so this is unit-testable without disk.
  *
- * @param {{forkSession?:boolean, sessionId?:string|null}} opts
+ * @param {{forkSession?:boolean, sessionId?:string|null, forkRequestId?:string}} opts
  * @param {{sessionExists?:Function, forkSession?:Function}} store
  * @returns {{ sessionId:string|null, forkedFrom:string|null, missing:boolean }}
  */
@@ -306,8 +318,14 @@ export function applyForkSession(opts = {}, store = {}) {
   if (typeof store.sessionExists === "function" && !store.sessionExists(id)) {
     return { sessionId: id, forkedFrom: null, missing: true };
   }
+  const requestId =
+    typeof opts.forkRequestId === "string" && opts.forkRequestId.length > 0
+      ? opts.forkRequestId
+      : `cli-${randomUUID()}`;
   const newId =
-    typeof store.forkSession === "function" ? store.forkSession(id) : null;
+    typeof store.forkSession === "function"
+      ? store.forkSession(id, { requestId })
+      : null;
   if (!newId) return { sessionId: id, forkedFrom: null, missing: false };
   return { sessionId: newId, forkedFrom: id, missing: false };
 }
@@ -341,7 +359,7 @@ export function applyForkSession(opts = {}, store = {}) {
  * @param {boolean} [options.expandFileRefs=true] Expand `@path` file references
  *                                             in the prompt into context blocks.
  * @param {object} [deps]                       Injection seam for tests.
- * @returns {Promise<{ exitCode:number, result:string, isError:boolean }>}
+ * @returns {Promise<{ exitCode:number, result:string, isError:boolean, sessionSnapshot?:object }>}
  */
 export async function runAgentHeadless(options = {}, deps = {}) {
   const trustedWorkspaceRoot = options.cwd || process.cwd();
@@ -365,6 +383,80 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     );
   }
 
+  const isStream = outputFormat === "stream-json";
+  const isJson = outputFormat === "json";
+  const isText = outputFormat === "text";
+  const writeOut = deps.writeOut || ((s) => process.stdout.write(s));
+  const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
+  if (!deps.writeOut && !deps.writeErr) installPipeSafety();
+
+  const hasInjectedSessionStore =
+    typeof deps.sessionExists === "function" ||
+    typeof deps.rebuildMessages === "function" ||
+    typeof deps.appendEvent === "function" ||
+    typeof deps.appendAuthorityEvent === "function" ||
+    typeof deps.readVerifiedEvents === "function";
+  const { sessionId, resumeId, persist } = resolveHeadlessSession(
+    options,
+    { getLastSessionId: deps.getLastSessionId || jsonlGetLastSessionId },
+    `headless-${Date.now()}-${process.pid}`,
+  );
+
+  const emitHeadlessError = (resultMsg) => {
+    if (isStream) {
+      writeOut(
+        JSON.stringify({
+          type: "result",
+          subtype: "error",
+          is_error: true,
+          error: resultMsg,
+        }) + "\n",
+      );
+    } else if (isJson) {
+      writeOut(
+        JSON.stringify(
+          buildResultEnvelope({
+            subtype: "error",
+            isError: true,
+            result: resultMsg,
+            sessionId,
+            toolCalls: [],
+            usage: {},
+            numTurns: 0,
+            durationMs: 0,
+          }),
+        ) + "\n",
+      );
+    }
+  };
+
+  // Resume authority is the first host boundary after argument validation.
+  // In particular this precedes /config writes, slash-macro bang expansion,
+  // settings/plugin loading, bootstrap, model access, hooks, MCP and tools.
+  const canReadCanonicalResume =
+    !hasInjectedSessionStore || typeof deps.readVerifiedEvents === "function";
+  const canonicalResume =
+    resumeId && canReadCanonicalResume
+      ? readSessionHostResumeState(resumeId, {
+          sessionExists: deps.sessionExists || jsonlSessionExists,
+          readVerifiedEvents:
+            deps.readVerifiedEvents || jsonlReadVerifiedEvents,
+        })
+      : null;
+  if (canonicalResume && !canonicalResume.snapshot.verified) {
+    const message =
+      "CC_SESSION_HOST_SNAPSHOT_UNVERIFIED: canonical JSONL session is not " +
+      "fully verified; resume was refused";
+    emitHeadlessError(message);
+    writeErr(`${message}\n`);
+    return {
+      exitCode: 1,
+      result: message,
+      isError: true,
+      sessionSnapshot: canonicalResume.snapshot,
+    };
+  }
+
   // `let` (not const): a custom-command macro's `model:` frontmatter may
   // override it below (when the user passed no explicit --model), mirroring
   // `cc command run`.
@@ -418,16 +510,20 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   let settingsHooks = options.settingsHooks || null;
   if (!settingsHooks) {
     try {
-      const { loadHooks, projectHookTrustNotice } =
+      const { loadHooks, projectHookTrustNotice, attachAuthorityErrors } =
         await import("../lib/settings-hooks.cjs");
       const loaded = loadHooks({ cwd, settingsFile: options.settingsFile });
       // Fold in installed plugins' hooks/hooks.json (Phase 3.3c) — plugins ADD
       // to the user's settings hooks, never replace them.
       const { mergePluginHooks } =
         await import("../lib/plugin-runtime/hooks.js");
-      const effectiveHooks = mergePluginHooks(loaded.hooks, { cwd });
+      const effectiveHooks = mergePluginHooks(
+        attachAuthorityErrors(loaded.hooks, loaded.authorityErrors),
+        { cwd },
+      );
       settingsHooks =
-        effectiveHooks && Object.keys(effectiveHooks).length > 0
+        Object.keys(effectiveHooks).length > 0 ||
+        effectiveHooks._authorityErrors.length > 0
           ? effectiveHooks
           : null;
       // First-run trust notice for an untrusted/cloned repo's shell-running
@@ -441,8 +537,17 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       } catch {
         /* trust notice is best-effort */
       }
-    } catch {
-      settingsHooks = null; // fail-open
+    } catch (error) {
+      settingsHooks = {};
+      Object.defineProperty(settingsHooks, "_authorityErrors", {
+        value: Object.freeze([
+          Object.freeze({
+            sourceFile: null,
+            code: error?.code || "CC_HOOK_AUTHORITY_LOAD_FAILED",
+          }),
+        ]),
+        enumerable: false,
+      });
     }
   }
 
@@ -493,18 +598,36 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       const m = await import("../lib/session-core-singletons.js");
       return m.getApprovalGate();
     });
-  // stdout carries the machine-consumable payload; stderr carries the human
-  // trace so `cc agent -p ... > out.txt` keeps `out.txt` clean.
-  const writeOut = deps.writeOut || ((s) => process.stdout.write(s));
-  const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
-  // Only when we own the real stdout/stderr (no injected seams = production,
-  // not tests): guard against a downstream `| head` closing the pipe, which
-  // would otherwise crash with an unhandled EPIPE. Idempotent across calls.
-  if (!deps.writeOut && !deps.writeErr) {
-    installPipeSafety();
-  }
   // Session persistence seam (file-based JSONL; DB-free, like the rest of
   // headless). Defaults to the real store; tests inject fakes.
+  const storeReadEvents = deps.readEvents || jsonlReadEvents;
+  const unavailableAuthorityCapability = (operation) => () => {
+    const error = new Error(
+      `Injected session store must provide ${operation} for MCP authority`,
+    );
+    error.code = "SESSION_AUTHORITY_CAPABILITY_UNAVAILABLE";
+    throw error;
+  };
+  const storeFindLatestEvent =
+    deps.findLatestEvent ||
+    (deps.readEvents
+      ? (sessionId, type, predicate = null) => {
+          const events = storeReadEvents(sessionId) || [];
+          const wanted = Array.isArray(type) ? new Set(type) : null;
+          for (let index = events.length - 1; index >= 0; index -= 1) {
+            const event = events[index];
+            const typeMatches = wanted
+              ? wanted.has(event?.type)
+              : type == null || event?.type === type;
+            if (!typeMatches) continue;
+            if (typeof predicate === "function" && !predicate(event)) continue;
+            return event;
+          }
+          return null;
+        }
+      : hasInjectedSessionStore
+        ? () => null
+        : jsonlFindLatestEvent);
   const store = {
     sessionExists: deps.sessionExists || jsonlSessionExists,
     rebuildMessages: deps.rebuildMessages || jsonlRebuildMessages,
@@ -514,19 +637,34 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       deps.appendAssistantMessage || jsonlAppendAssistantMessage,
     appendTokenUsage: deps.appendTokenUsage || jsonlAppendTokenUsage,
     appendToolCallCompact:
-      deps.appendToolCallCompact || jsonlAppendToolCallCompact,
+      deps.appendToolCallCompact ||
+      (hasInjectedSessionStore ? () => true : jsonlAppendToolCallCompact),
     appendLlmRetryCompact:
-      deps.appendLlmRetryCompact || jsonlAppendLlmRetryCompact,
-    appendCompactEvent: deps.appendCompactEvent || jsonlAppendCompactEvent,
-    appendEvent: deps.appendEvent || jsonlAppendEvent,
-    readEvents: deps.readEvents || jsonlReadEvents,
+      deps.appendLlmRetryCompact ||
+      (hasInjectedSessionStore ? () => true : jsonlAppendLlmRetryCompact),
+    appendCompactEvent:
+      deps.appendCompactEvent ||
+      (hasInjectedSessionStore ? () => true : jsonlAppendCompactEvent),
+    appendEvent:
+      deps.appendEvent ||
+      (hasInjectedSessionStore ? () => true : jsonlAppendEvent),
+    appendAuthorityEvent:
+      deps.appendAuthorityEvent ||
+      (hasInjectedSessionStore
+        ? unavailableAuthorityCapability("appendAuthorityEvent")
+        : jsonlAppendAuthorityEvent),
+    readEvents: storeReadEvents,
+    readVerifiedEvents:
+      deps.readVerifiedEvents ||
+      (hasInjectedSessionStore
+        ? unavailableAuthorityCapability("readVerifiedEvents")
+        : jsonlReadVerifiedEvents),
+    findLatestEvent: storeFindLatestEvent,
     getLastSessionId: deps.getLastSessionId || jsonlGetLastSessionId,
-    verifySession: deps.verifySession || jsonlVerifySession,
+    verifySession:
+      deps.verifySession ||
+      (hasInjectedSessionStore ? () => null : jsonlVerifySession),
   };
-  const isStream = outputFormat === "stream-json";
-  const isJson = outputFormat === "json";
-  const isText = outputFormat === "text";
-
   // ── Headless `/config` directive (Claude-Code 2.1.181: /config in -p mode) ──
   // A leading `/config …` prompt is a one-shot config get/set/show, not a task
   // for the LLM — handled before bootstrap/session/model so it never spends a
@@ -571,6 +709,10 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     return { exitCode: isError ? 1 : 0, result: text, isError };
   }
 
+  if (options.continueSession === true && !resumeId && isText) {
+    writeErr("No previous session to continue; starting a new one.\n");
+  }
+
   // ── Custom slash-command macros (Claude-Code parity: a .claude/commands/*
   // command runs in `-p` mode too, not just the interactive REPL). A leading
   // `/name …` that resolves to a user/project command is expanded into its
@@ -661,50 +803,6 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     // Continue without DB — static-prompt fallback.
   }
 
-  // ── Resolve session continuity (--resume / --continue) ─────────────────
-  const { sessionId, resumeId, persist } = resolveHeadlessSession(
-    options,
-    store,
-    `headless-${Date.now()}-${process.pid}`,
-  );
-  if (options.continueSession === true && !resumeId && isText) {
-    writeErr("No previous session to continue; starting a new one.\n");
-  }
-
-  // Machine-readable modes (`--output-format json` / `stream-json`) must ALWAYS
-  // end with a terminal result envelope — a consumer parsing stdout otherwise
-  // gets nothing and can't tell success from failure. Several setup-phase error
-  // paths below early-return BEFORE the main loop's try/catch envelope (and
-  // before `system/init`), so route them through this so stdout is never empty.
-  // No-op in text mode (those paths already writeErr a human message).
-  const emitHeadlessError = (resultMsg) => {
-    if (isStream) {
-      writeOut(
-        JSON.stringify({
-          type: "result",
-          subtype: "error",
-          is_error: true,
-          error: resultMsg,
-        }) + "\n",
-      );
-    } else if (isJson) {
-      writeOut(
-        JSON.stringify(
-          buildResultEnvelope({
-            subtype: "error",
-            isError: true,
-            result: resultMsg,
-            sessionId,
-            toolCalls: [],
-            usage: {},
-            numTurns: 0,
-            durationMs: 0,
-          }),
-        ) + "\n",
-      );
-    }
-  };
-
   const setupHooks = await executeLifecycleHooks(
     "Setup",
     {
@@ -747,15 +845,19 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   }
   userContent = expansion.prompt;
 
-  // Load prior conversation when resuming an existing session. The fresh
-  // system prompt always leads; we drop any persisted system turns so it is
-  // never duplicated.
+  // Load prior conversation when resuming an existing session. The fresh host
+  // system prompt always leads; all system turns from the same verified
+  // canonical sample follow it (including compact checkpoint summaries).
   let history = [];
-  if (resumeId && store.sessionExists(resumeId)) {
-    // Tamper gate: a broken transcript hash chain means the file was edited
+  if (canonicalResume) {
+    history = canonicalResume.messages.filter(Boolean);
+  } else if (resumeId && store.sessionExists(resumeId)) {
+    // Compatibility gate for injected stores without a verified event reader.
+    // Real JSONL resumes were handled above and never reach this branch. A
+    // broken transcript hash chain means the file was edited
     // outside the store. Headless runs fail closed — a tampered transcript is
     // never silently rebuilt into trusted model context. Escape hatch:
-    // CC_ALLOW_TAMPERED_RESUME=1 resumes with a stderr warning.
+    // CC_ALLOW_TAMPERED_RESUME=1 is retained only for this injected-store path.
     let trust = null;
     try {
       trust = store.verifySession(resumeId);
@@ -825,6 +927,9 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   let sideEffectSeq = 0;
   let currentSideEffectOpId = null;
   let resumeSideEffectContext = null;
+  let resumeMcpCallContext = null;
+  let resumeMcpRecovery = null;
+  let resumeMcpRecoveryError = null;
   let resumeAsyncHookContext = null;
   const persistSideEffectLedger = () => {
     if (!persist) return;
@@ -862,18 +967,13 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   let turnBindingLoadError = null;
   if (persist) {
     try {
-      const events = store.readEvents(sessionId) || [];
-      for (let i = events.length - 1; i >= 0; i--) {
-        const e = events[i];
-        if (
-          e &&
-          e.type === TURN_BINDING_EVENT &&
-          e.data &&
-          Array.isArray(e.data.turns)
-        ) {
-          turnBindingLog = TurnBindingLog.fromJSON(e.data);
-          break;
-        }
+      const event = store.findLatestEvent(
+        sessionId,
+        TURN_BINDING_EVENT,
+        (candidate) => Array.isArray(candidate?.data?.turns),
+      );
+      if (event) {
+        turnBindingLog = TurnBindingLog.fromJSON(event.data);
       }
     } catch (cause) {
       const error = new Error(
@@ -918,20 +1018,15 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   };
   if (persist) {
     try {
-      const events = store.readEvents(sessionId) || [];
-      for (let i = events.length - 1; i >= 0; i--) {
-        const e = events[i];
-        if (
-          e &&
-          e.type === SIDE_EFFECT_LEDGER_EVENT &&
-          e.data &&
-          Array.isArray(e.data.ops)
-        ) {
-          sideEffectLedger = SideEffectLedger.fromJSON(e.data, {
-            clock: deps.now || null,
-          });
-          break;
-        }
+      const event = store.findLatestEvent(
+        sessionId,
+        SIDE_EFFECT_LEDGER_EVENT,
+        (candidate) => Array.isArray(candidate?.data?.ops),
+      );
+      if (event) {
+        sideEffectLedger = SideEffectLedger.fromJSON(event.data, {
+          clock: deps.now || null,
+        });
       }
     } catch (cause) {
       const error = new Error(
@@ -978,6 +1073,41 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       } catch {
         resumeSideEffectContext = null;
       }
+      // MCP calls have their own content-free started/settled ledger. A
+      // started-only record means the external server may have completed the
+      // operation before the process died, so replay must stop for inspection.
+      try {
+        const mcpRecovery =
+          canonicalResume?.recovery ||
+          loadMcpLedgerRecovery(resumeId, {
+            readVerifiedEvents: store.readVerifiedEvents,
+          });
+        resumeMcpRecovery = mcpRecovery;
+        resumeMcpCallContext = formatMcpLedgerRecoveryNotice(mcpRecovery);
+        if (resumeMcpCallContext) {
+          const risky = mcpRecovery.unsettled.filter(
+            (record) => record.effectContract?.effect !== "read",
+          ).length;
+          writeErr(
+            `⚠ ${mcpRecovery.unsettled.length} interrupted MCP call(s) and ${mcpRecovery.incidents.length} ledger incident(s) require inspection before replay (resume ${resumeId}).\n`,
+          );
+          if (risky > 0 || mcpRecovery.incidents.length > 0) {
+            _bgPhase.reportUncertainSideEffects(
+              risky + mcpRecovery.incidents.length,
+            );
+          }
+        }
+      } catch (error) {
+        resumeMcpRecoveryError = error;
+        resumeMcpCallContext =
+          "MCP recovery notice — the durable MCP call ledger could not be read. " +
+          "Do not execute or retry MCP tools until the session transcript has " +
+          `been inspected (${error?.code || "CC_MCP_LEDGER_EVENT_READ_FAILED"}).`;
+        writeErr(
+          `⚠ MCP ledger recovery failed closed for resume ${resumeId}; MCP calls require inspection.\n`,
+        );
+        _bgPhase.reportUncertainSideEffects(1);
+      }
       // On resume, recover any async-hook REWAKE (a background check that opted
       // in and FAILED) that the previous run parked but died before draining —
       // surface it to the model instead of silently swallowing the failure. The
@@ -1232,6 +1362,9 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     ...(resumeSideEffectContext
       ? [{ role: "system", content: resumeSideEffectContext }]
       : []),
+    ...(resumeMcpCallContext
+      ? [{ role: "system", content: resumeMcpCallContext }]
+      : []),
     ...(resumeAsyncHookContext
       ? [{ role: "system", content: resumeAsyncHookContext }]
       : []),
@@ -1328,18 +1461,33 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     }
   }
 
+  const mcpRecoveryRuntime = createMcpHostRecoveryRuntime({
+    bundle: mcp,
+    sessionId,
+    sink: persist
+      ? createSessionMcpLedgerSink(sessionId, {
+          appendEvent: store.appendAuthorityEvent,
+        })
+      : null,
+    recovery: resumeMcpRecovery,
+    recoveryError: resumeMcpRecoveryError,
+  });
+  const hostMcp = mcp
+    ? { ...mcp, mcpClient: mcpRecoveryRuntime.client || mcp.mcpClient }
+    : null;
+
   // Seed MCP roots for --add-dir (Claude-Code roots/list_changed parity): a
   // headless session started with extra workspace roots must advertise the FULL
   // root list to connected MCP servers, exactly like the REPL /add-dir path —
   // otherwise a server's roots/list only ever sees the cwd. Only meaningful when
   // extra roots exist (setRoots fires only when the list actually changes); no
   // --add-dir → workspaceRootDirs = [cwd] and this is a no-op. Best-effort.
-  if (mcp?.mcpClient && additionalDirectories.length > 0) {
+  if (hostMcp?.mcpClient && additionalDirectories.length > 0) {
     try {
       const { notifyMcpRootsChanged, workspaceRootDirs } =
         await import("../repl/add-dir.js");
       notifyMcpRootsChanged(
-        [mcp.mcpClient],
+        [hostMcp.mcpClient],
         workspaceRootDirs(options.cwd || process.cwd(), additionalDirectories),
       );
     } catch {
@@ -1357,7 +1505,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       await import("../lib/ide-context.js");
     const last = messages[messages.length - 1];
     const ideCtx = await (deps.buildIdePromptContext || buildIdePromptContext)(
-      mcp,
+      hostMcp,
     );
     if (ideCtx) {
       last.content = appendTextToContent(last.content, ideCtx);
@@ -1366,7 +1514,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     // (Claude-Code parity). Scan the ORIGINAL prompt so injected file-ref
     // blocks can't spoof a mention; append the expansion to the in-flight
     // message only (ephemeral, like the ambient block above).
-    const mentioned = await expandIdeMentions(prompt, mcp);
+    const mentioned = await expandIdeMentions(prompt, hostMcp);
     for (const w of mentioned.warnings) writeErr(`  @ide: ${w}\n`);
     if (mentioned.block) {
       last.content = appendTextToContent(last.content, mentioned.block);
@@ -1401,7 +1549,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       approvalGate.setConfirmer(
         _bgPhase.wrapConfirmer(
           makePermissionPromptConfirmer({
-            mcpClient: mcp.mcpClient,
+            mcpClient: hostMcp.mcpClient,
             server: ppt.server,
             tool: ppt.tool,
             writeErr,
@@ -1572,6 +1720,9 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     additionalDirectories,
     sandbox: options.sandbox || null,
     sessionId,
+    // Content-free continuity metadata from the same verified sample used for
+    // replay history and MCP recovery authority.
+    sessionHostSnapshot: canonicalResume?.snapshot || null,
     // Auto-pin (default ON since 2026-07-07): pin the original task through
     // compaction. Precedence: --auto-pin flag > CC_AUTO_PIN ("1"/"0") >
     // config context.autoPin > default on. Falsy → agent-core passes no pin
@@ -1579,6 +1730,9 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     autoPin: _autoPinResolved,
     autoCheckpoint: options.autoCheckpoint || false,
     checkpointSession: options.checkpointSession || sessionId,
+    managedCheckpoint: options.managedCheckpoint === true,
+    managedCheckpointStateDir: options.managedCheckpointStateDir || null,
+    managedCheckpointExclusions: options.managedCheckpointExclusions || [],
     hookDb: db,
     approvalGate,
     permissionRules,
@@ -1634,9 +1788,16 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       : {}),
     // --mcp-config wiring: tool defs for the LLM + dispatch map + live client.
     mcpClient: mcp?.mcpClient || null,
+    mcpHostClient: mcpRecoveryRuntime.client || mcp?.mcpClient || null,
     extraToolDefinitions: mcp?.extraToolDefinitions || undefined,
     externalToolExecutors: mcp?.externalToolExecutors || undefined,
     externalToolDescriptors: mcp?.externalToolDescriptors || undefined,
+    // Persist every MCP started/settled record into this exact canonical
+    // session. Unknown/write/destructive prewrite failure then blocks before
+    // the external call; a settlement failure leaves a recoverable started row.
+    // Keep the guarded in-memory ledger when persistence is disabled so an
+    // outcome-unknown call still latches UNSAFE for the rest of this process.
+    mcpCallLedger: mcpRecoveryRuntime.ledger,
     // chatFn passthrough lets tests drive the loop deterministically.
     chatFn: deps.chatFn || options.chatFn || undefined,
     signal: options.signal || undefined,
@@ -1725,6 +1886,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   // so a non-interactive run surfaces what got blocked the way the REPL's
   // `/permissions denials` does (Claude-Code 2.1.193 denial reasons).
   const denials = [];
+  const compactionDegradations = [];
   const usage = {
     input_tokens: 0,
     output_tokens: 0,
@@ -1910,15 +2072,10 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       let restoredSnap = null;
       if (resumeId) {
         try {
-          const events = store.readEvents(resumeId) || [];
-          for (let i = events.length - 1; i >= 0; i--) {
-            const ev = events[i];
-            if (ev && ev.type === "goal_snapshot") {
-              const snap = ev.data;
-              if (snap && snap.state && snap.state.done !== true)
-                restoredSnap = snap;
-              break; // only the latest goal_snapshot matters
-            }
+          const event = store.findLatestEvent(resumeId, "goal_snapshot");
+          const snap = event?.data;
+          if (snap && snap.state && snap.state.done !== true) {
+            restoredSnap = snap;
           }
         } catch {
           restoredSnap = null; // unreadable transcript → start fresh
@@ -2006,6 +2163,14 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       for await (const event of runLoop(messages, loopOptions)) {
         if (turnBindingFeed) turnBindingFeed.handleEvent(event);
         switch (event.type) {
+          case "managed-checkpoint":
+          case "managed-checkpoint-settled":
+          case "managed-checkpoint-error": {
+            const line = formatManagedCheckpointEvent(event);
+            if (isText && line) writeErr(`${line}\n`);
+            if (isStream) emitStream(event);
+            break;
+          }
           case "checkpoint": {
             if (isText)
               writeErr(`  ⎌ checkpoint ${event.id} (before ${event.tool})\n`);
@@ -2138,6 +2303,23 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
             }
             break;
           }
+          case "compaction-degraded": {
+            const reason = String(event.reason || "semantic-summary-degraded")
+              .replace(/\s+/g, " ")
+              .slice(0, 500);
+            const degradation = {
+              reason,
+              summary_mode: event.summaryMode || "none",
+            };
+            compactionDegradations.push(degradation);
+            if (isText) {
+              writeErr(
+                `  Semantic compaction degraded to ${degradation.summary_mode}: ${reason}\n`,
+              );
+            }
+            emitStream({ ...event, reason });
+            break;
+          }
           case "token-usage": {
             if (event.attribution) {
               // Child-loop (sub-agent / isolated-skill) spend: excluded from
@@ -2164,6 +2346,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
               provider: event.provider,
               model: event.model,
               usage: event.usage,
+              ...(event.source ? { source: event.source } : {}),
             });
             if (costBudget) {
               costBudget.add({
@@ -2419,6 +2602,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
             numTurns: budget.consumed,
             durationMs: (deps.now ? deps.now() : Date.now()) - startedAt,
             denials,
+            compactionDegradations,
           }),
         ) + "\n",
       );
@@ -2700,6 +2884,9 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       num_turns: budget.consumed,
       duration_ms: durationMs,
       usage,
+      ...(compactionDegradations.length
+        ? { compaction_degradations: compactionDegradations }
+        : {}),
     });
   } else if (isJson) {
     writeOut(
@@ -2714,6 +2901,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
           numTurns: budget.consumed,
           durationMs,
           denials,
+          compactionDegradations,
         }),
       ) + "\n",
     );
@@ -2773,6 +2961,7 @@ function buildResultEnvelope({
   numTurns,
   durationMs,
   denials,
+  compactionDegradations,
 }) {
   const env = {
     type: "result",
@@ -2788,5 +2977,8 @@ function buildResultEnvelope({
   // Only present when something was blocked — keeps the no-denial envelope
   // byte-identical to before (Claude-Code 2.1.193 denial reasons, json mode).
   if (Array.isArray(denials) && denials.length) env.denials = denials;
+  if (Array.isArray(compactionDegradations) && compactionDegradations.length) {
+    env.compaction_degradations = compactionDegradations;
+  }
   return env;
 }