chainlesschain 0.162.197 → 0.162.200

package/src/runtime/headless-runner.js

@@ -53,6 +53,8 @@ import {
   findLatestEvent as jsonlFindLatestEvent,
   rebuildMessages as jsonlRebuildMessages,
   sessionExists as jsonlSessionExists,
+  sessionHasPersistedEvidence as jsonlSessionHasPersistedEvidence,
+  resolveSessionAuthority as jsonlResolveSessionAuthority,
   getLastSessionId as jsonlGetLastSessionId,
   verifySession as jsonlVerifySession,
 } from "../harness/jsonl-session-store.js";
@@ -71,6 +73,7 @@ import {
 } 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 { acquireSessionHostLease } from "../lib/session-host-lease.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";
@@ -153,6 +156,15 @@ const VALID_OUTPUT_FORMATS = Object.freeze(["text", "json", "stream-json"]);
 // the stream-json driver + REPL); re-exported here for existing importers.
 export { installPipeSafety } from "./pipe-safety.js";
 import { installPipeSafety } from "./pipe-safety.js";
+import { createHeadlessOutputBackpressure } from "./output-backpressure.js";
+import {
+  cleanupDeadlineError,
+  createCleanupDeadline,
+} from "./cleanup-deadline.js";
+import {
+  createSessionPersistenceFailure,
+  projectSessionPersistenceFailure,
+} from "../lib/session-persistence-failure.js";
 
 /**
  * Normalize a public --permission-mode spelling to the canonical internal mode.
@@ -288,6 +300,19 @@ export function resolveHeadlessSession(options = {}, store = {}, fallbackId) {
   } else if (typeof resume === "string" && resume.trim()) {
     resumeId = resume.trim();
   }
+  if (resumeId && typeof store.resolveSessionAuthority === "function") {
+    const authority = store.resolveSessionAuthority(resumeId);
+    if (authority && !authority.readable) {
+      const error = new Error(
+        `Canonical session ${authority.id} is not resumable (${authority.presence})`,
+      );
+      error.code = "SESSION_CANONICAL_UNAVAILABLE";
+      error.sessionId = authority.id;
+      error.presence = authority.presence;
+      throw error;
+    }
+    if (authority?.id) resumeId = authority.id;
+  }
   const persist =
     ephemeral === true
       ? false
@@ -361,14 +386,161 @@ export function applyForkSession(opts = {}, store = {}) {
  * @param {object} [deps]                       Injection seam for tests.
  * @returns {Promise<{ exitCode:number, result:string, isError:boolean, sessionSnapshot?:object }>}
  */
+const HEADLESS_SESSION_RESOLUTION = Symbol("headlessSessionResolution");
+const HEADLESS_SESSION_HOST_LEASE = Symbol("headlessSessionHostLease");
+
+async function withHeadlessSessionHostLease(options, deps, task) {
+  const prompt = (options.prompt || "").trim();
+  if (!prompt) {
+    throw new Error(
+      "runAgentHeadless requires a non-empty prompt (use -p, a positional arg, or pipe stdin).",
+    );
+  }
+  const outputFormat = options.outputFormat || "text";
+  if (!VALID_OUTPUT_FORMATS.includes(outputFormat)) {
+    throw new Error(
+      `Invalid --output-format "${outputFormat}". Expected one of: ${VALID_OUTPUT_FORMATS.join(", ")}`,
+    );
+  }
+  const hasInjectedSessionStore =
+    typeof deps.sessionHasPersistedEvidence === "function" ||
+    typeof deps.sessionExists === "function" ||
+    typeof deps.rebuildMessages === "function" ||
+    typeof deps.appendEvent === "function" ||
+    typeof deps.appendAuthorityEvent === "function" ||
+    typeof deps.readVerifiedEvents === "function";
+  const resolution = resolveHeadlessSession(
+    options,
+    {
+      getLastSessionId: deps.getLastSessionId || jsonlGetLastSessionId,
+      resolveSessionAuthority:
+        deps.resolveSessionAuthority ||
+        (!hasInjectedSessionStore ? jsonlResolveSessionAuthority : undefined),
+    },
+    `headless-${Date.now()}-${process.pid}`,
+  );
+  const authoritySessionId =
+    resolution.resumeId || (resolution.persist ? resolution.sessionId : null);
+  const acquireHostLease =
+    deps.acquireSessionHostLease ||
+    (!hasInjectedSessionStore ? acquireSessionHostLease : null);
+  let lease = null;
+  try {
+    if (authoritySessionId && typeof acquireHostLease === "function") {
+      lease = acquireHostLease(authoritySessionId, { hostKind: "headless" });
+    }
+    const scopedOptions = lease?.signal
+      ? {
+          ...options,
+          signal: options.signal
+            ? AbortSignal.any([options.signal, lease.signal])
+            : lease.signal,
+        }
+      : options;
+    return await task(scopedOptions, {
+      ...deps,
+      [HEADLESS_SESSION_RESOLUTION]: resolution,
+      [HEADLESS_SESSION_HOST_LEASE]: lease,
+    });
+  } finally {
+    lease?.release?.();
+  }
+}
+
 export async function runAgentHeadless(options = {}, deps = {}) {
   const trustedWorkspaceRoot = options.cwd || process.cwd();
-  return runWithHostHooksV2Workspace(trustedWorkspaceRoot, () =>
-    runAgentHeadlessInWorkspace(options, deps),
-  );
+  const pipeState = { closed: false };
+  const stdout = deps.stdout || process.stdout;
+  const stderr = deps.stderr || process.stderr;
+  const shouldInstallPipeSafety =
+    typeof deps.installPipeSafety === "function" ||
+    (!deps.writeOut && !deps.writeErr);
+  const pipeAbort = shouldInstallPipeSafety ? new AbortController() : null;
+  const managesNativeOutput = !deps.writeOut || !deps.writeErr;
+  const outputAbort = managesNativeOutput ? new AbortController() : null;
+  const handlePipeClosed = () => {
+    if (pipeState.closed) return;
+    pipeState.closed = true;
+    process.exitCode = 0;
+    pipeAbort?.abort();
+  };
+  const outputFlow =
+    deps.outputFlow ||
+    createHeadlessOutputBackpressure({
+      stdout,
+      stderr,
+      writeOut: deps.writeOut,
+      writeErr: deps.writeErr,
+      maxQueuedBytes: deps.outputBackpressureMaxBytes,
+      drainTimeoutMs: deps.outputBackpressureTimeoutMs,
+      onFailure: (error) => {
+        outputAbort?.abort(error);
+        if (error?.code === "EPIPE") handlePipeClosed();
+      },
+    });
+  const abortSignals = [
+    options.signal,
+    pipeAbort?.signal,
+    outputAbort?.signal,
+  ].filter(Boolean);
+  const runtimeOptions =
+    abortSignals.length === 0
+      ? options
+      : {
+          ...options,
+          signal:
+            abortSignals.length === 1
+              ? abortSignals[0]
+              : AbortSignal.any(abortSignals),
+        };
+  const runtimeDeps = {
+    ...deps,
+    writeOut: outputFlow.writeOut,
+    writeErr: outputFlow.writeErr,
+    outputFlow,
+  };
+  const installSafety = deps.installPipeSafety || installPipeSafety;
+  const disposePipeSafety = shouldInstallPipeSafety
+    ? installSafety([stdout, stderr], handlePipeClosed)
+    : null;
+
+  let outcome;
+  let failure = null;
+  try {
+    outcome = await runWithHostHooksV2Workspace(trustedWorkspaceRoot, () =>
+      withHeadlessSessionHostLease(
+        runtimeOptions,
+        runtimeDeps,
+        (scopedOptions, scopedDeps) =>
+          runAgentHeadlessInWorkspace(scopedOptions, scopedDeps, pipeState),
+      ),
+    );
+  } catch (error) {
+    failure = error;
+  } finally {
+    try {
+      await outputFlow.wait();
+    } catch (error) {
+      failure ||= error;
+    }
+    outputFlow.dispose();
+    disposePipeSafety?.();
+  }
+
+  if (pipeState.closed) {
+    return outcome
+      ? { ...outcome, exitCode: 0, isError: false }
+      : { exitCode: 0, result: "", isError: false };
+  }
+  if (failure) throw failure;
+  return outcome;
 }
 
-async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
+async function runAgentHeadlessInWorkspace(
+  options = {},
+  deps = {},
+  pipeState = { closed: false },
+) {
   const prompt = (options.prompt || "").trim();
   if (!prompt) {
     throw new Error(
@@ -386,21 +558,33 @@ 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 writeOut = deps.writeOut;
+  const writeErr = deps.writeErr;
+  const cleanupDeadline = createCleanupDeadline({
+    timeoutMs: deps.cleanupDeadlineMs,
+    label: "headless-runner-cleanup",
+  });
 
   const hasInjectedSessionStore =
+    typeof deps.sessionHasPersistedEvidence === "function" ||
     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 { sessionId, resumeId, persist } =
+    deps[HEADLESS_SESSION_RESOLUTION] ||
+    resolveHeadlessSession(
+      options,
+      {
+        getLastSessionId: deps.getLastSessionId || jsonlGetLastSessionId,
+        resolveSessionAuthority:
+          deps.resolveSessionAuthority ||
+          (!hasInjectedSessionStore ? jsonlResolveSessionAuthority : undefined),
+      },
+      `headless-${Date.now()}-${process.pid}`,
+    );
+  const sessionHostLease = deps[HEADLESS_SESSION_HOST_LEASE] || null;
 
   const emitHeadlessError = (resultMsg) => {
     if (isStream) {
@@ -435,27 +619,36 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   // settings/plugin loading, bootstrap, model access, hooks, MCP and tools.
   const canReadCanonicalResume =
     !hasInjectedSessionStore || typeof deps.readVerifiedEvents === "function";
-  const canonicalResume =
-    resumeId && canReadCanonicalResume
-      ? readSessionHostResumeState(resumeId, {
+  const canonicalAdmissionId = resumeId || (persist ? sessionId : null);
+  const canonicalAdmission =
+    canonicalAdmissionId && canReadCanonicalResume
+      ? readSessionHostResumeState(canonicalAdmissionId, {
+          sessionHasPersistedEvidence:
+            deps.sessionHasPersistedEvidence ||
+            (!hasInjectedSessionStore
+              ? jsonlSessionHasPersistedEvidence
+              : undefined),
           sessionExists: deps.sessionExists || jsonlSessionExists,
           readVerifiedEvents:
             deps.readVerifiedEvents || jsonlReadVerifiedEvents,
         })
       : null;
-  if (canonicalResume && !canonicalResume.snapshot.verified) {
+  if (canonicalAdmission && !canonicalAdmission.snapshot.verified) {
     const message =
       "CC_SESSION_HOST_SNAPSHOT_UNVERIFIED: canonical JSONL session is not " +
-      "fully verified; resume was refused";
+      "fully verified; resume/write admission was refused";
     emitHeadlessError(message);
     writeErr(`${message}\n`);
     return {
       exitCode: 1,
       result: message,
       isError: true,
-      sessionSnapshot: canonicalResume.snapshot,
+      sessionSnapshot: canonicalAdmission.snapshot,
     };
   }
+  // A persist-only target must pass the same canonical admission boundary,
+  // but it does not opt into replaying the target's prior conversation.
+  const canonicalResume = resumeId ? canonicalAdmission : null;
 
   // `let` (not const): a custom-command macro's `model:` frontmatter may
   // override it below (when the user passed no explicit --model), mirroring
@@ -533,7 +726,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
           cwd,
           settingsFile: options.settingsFile,
         });
-        if (notice) process.stderr.write(notice + "\n");
+        if (notice) writeErr(notice + "\n");
       } catch {
         /* trust notice is best-effort */
       }
@@ -935,7 +1128,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     if (!persist) return;
     if (sideEffectLedgerLoadError) throw sideEffectLedgerLoadError;
     try {
-      const persisted = store.appendEvent(
+      const persisted = store.appendAuthorityEvent(
         sessionId,
         SIDE_EFFECT_LEDGER_EVENT,
         sideEffectLedger.toJSON(),
@@ -990,13 +1183,16 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   // (createTurnBindingFeed) so the interactive REPL producer can never drift
   // from this runner's mapping. No feed at all for non-persisted runs.
   const turnBindingFeed = persist
-    ? createTurnBindingFeed({ log: turnBindingLog, nonce: sideEffectRunNonce })
+    ? createTurnBindingFeed({
+        log: turnBindingLog,
+        nonce: sideEffectRunNonce,
+      })
     : null;
   const persistTurnBindingLog = () => {
     if (!turnBindingFeed || !turnBindingFeed.isDirty()) return;
     if (turnBindingLoadError) throw turnBindingLoadError;
     try {
-      const persisted = store.appendEvent(
+      const persisted = store.appendAuthorityEvent(
         sessionId,
         TURN_BINDING_EVENT,
         turnBindingLog.toJSON(),
@@ -1180,7 +1376,9 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   }
 
   const budget = Number.isFinite(options.maxTurns)
-    ? new IterationBudget({ limit: Math.max(1, Math.floor(options.maxTurns)) })
+    ? new IterationBudget({
+        limit: Math.max(1, Math.floor(options.maxTurns)),
+      })
     : new IterationBudget();
 
   // Effective system prompt: built-in base, optionally replaced by
@@ -1372,9 +1570,10 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     { role: "user", content: userMessageContent },
   ]);
 
-  // Persist the user turn up front (best-effort) so a session is recoverable
-  // even if the run crashes mid-loop. startSession is append-safe: only seed
-  // the header when the file does not yet exist.
+  // Persist the user turn before model/tool side effects. A full or read-only
+  // session disk is a recoverability contract failure, so it fails closed
+  // while the requested turn is still side-effect free. startSession is
+  // append-safe: only seed the header when the file does not yet exist.
   if (persist) {
     try {
       if (!store.sessionExists(sessionId)) {
@@ -1387,8 +1586,62 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       // Persist the expanded content so a resumed session faithfully replays
       // what the model actually saw (the file snapshot, not just the @token).
       store.appendUserMessage(sessionId, userContent);
-    } catch {
-      // Persistence is best-effort — never fail the run over it.
+    } catch (error) {
+      const persistenceError = createSessionPersistenceFailure(error, {
+        sessionId,
+        operation: "user-turn-append",
+      });
+      const persistence = projectSessionPersistenceFailure(persistenceError, {
+        phase: "before-model",
+      });
+      if (persistence) {
+        try {
+          deps.onPersistenceFailure?.(persistence);
+        } catch {
+          // Observability cannot change persistence semantics.
+        }
+        const resultMsg = `${persistence.code}: session turn was not durably persisted`;
+        if (isStream) {
+          writeOut(
+            JSON.stringify({
+              type: "result",
+              subtype: "error_persistence",
+              is_error: true,
+              error: resultMsg,
+              session_id: sessionId,
+              persistence,
+            }) + "\n",
+          );
+        } else if (isJson) {
+          writeOut(
+            JSON.stringify(
+              buildResultEnvelope({
+                subtype: "error_persistence",
+                isError: true,
+                result: resultMsg,
+                sessionId,
+                toolCalls: [],
+                usage: {},
+                numTurns: 0,
+                durationMs: 0,
+                persistence,
+              }),
+            ) + "\n",
+          );
+        } else {
+          writeErr(
+            `${resultMsg} (${persistence.fs_code}; ${persistence.commit_state})\n`,
+          );
+        }
+        return {
+          exitCode: 1,
+          result: resultMsg,
+          isError: true,
+          persistence,
+        };
+      }
+      // Preserve legacy best-effort handling for errors outside the explicit
+      // ENOSPC/EROFS durability contract.
     }
   }
 
@@ -1465,9 +1718,12 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     bundle: mcp,
     sessionId,
     sink: persist
-      ? createSessionMcpLedgerSink(sessionId, {
-          appendEvent: store.appendAuthorityEvent,
-        })
+      ? createSessionMcpLedgerSink(
+          sessionId,
+          hasInjectedSessionStore
+            ? { appendEvent: store.appendAuthorityEvent }
+            : { recovery: resumeMcpRecovery },
+        )
       : null,
     recovery: resumeMcpRecovery,
     recoveryError: resumeMcpRecoveryError,
@@ -1536,7 +1792,13 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       ppt = resolvePermissionPromptTool(mcp, options.permissionPromptTool);
     } catch (err) {
       writeErr(`Error: ${err.message}\n`);
-      if (mcp?.mcpClient) await mcp.mcpClient.disconnectAll().catch(() => {});
+      await cleanupDeadline.run("mcp", () => mcp?.mcpClient?.disconnectAll?.());
+      const cleanupReport = cleanupDeadline.report();
+      try {
+        deps.onCleanupReport?.(cleanupReport);
+      } catch {
+        // Metrics/reporting cannot change cleanup semantics.
+      }
       emitHeadlessError(err.message);
       // A bad --permission-prompt-tool reference is a CONFIG error.
       return {
@@ -1831,6 +2093,24 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       const suffix = retryIn > 0 ? ` · will retry in ${retryIn}s` : "";
       writeErr(`  ⏳ waiting for API response (silent ${silent}s)${suffix}…\n`);
     },
+    onProviderFallback: (info) => {
+      if (isStream) {
+        emitStream({
+          type: "raw",
+          subtype: "provider_fallback",
+          text:
+            info.message || `provider switched from ${info.from} to ${info.to}`,
+          from: info.from,
+          to: info.to,
+          reason: info.reason,
+          session_id: sessionId,
+        });
+      } else {
+        writeErr(
+          `[provider] ${info.message || `switched from ${info.from} to ${info.to}`}\n`,
+        );
+      }
+    },
   };
 
   // Goal binding (cc goal, Phase 1). `--goal <id>` binds explicitly; `--goal`
@@ -2149,8 +2429,11 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
   process.once("SIGINT", _onHardSignal);
   process.once("SIGTERM", _onHardSignal);
 
+  let loopFailureOutcome = null;
+  let cleanupFailure = null;
   try {
     while (true) {
+      sessionHostLease?.assert?.();
       // P1 turn→checkpoint binding: one drain of the loop = one turn. Anchor
       // the conversation offset before the model sees the new user turn. A
       // `--worktree` run stamps its isolation worktree (branch name, threaded
@@ -2174,7 +2457,11 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
           case "checkpoint": {
             if (isText)
               writeErr(`  ⎌ checkpoint ${event.id} (before ${event.tool})\n`);
-            emitStream({ type: "checkpoint", id: event.id, tool: event.tool });
+            emitStream({
+              type: "checkpoint",
+              id: event.id,
+              tool: event.tool,
+            });
             break;
           }
           case "tool-executing": {
@@ -2218,6 +2505,11 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
                   })
                   .start(opId);
                 persistSideEffectLedger();
+                // The generator executes the tool only after this yielded
+                // prewrite is handled. Recheck the same durable lease at that
+                // final host boundary so a fenced host never resumes into the
+                // external operation.
+                sessionHostLease?.assert?.();
               }
             }
             break;
@@ -2421,6 +2713,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
             if (isStream && event.type) emitStream(event);
             break;
         }
+        await deps.outputFlow?.wait?.();
         // Hard cost cap reached: stop consuming the loop so no further paid LLM
         // call is made (break out of the for-await, not just the switch).
         if (stopForCost) break;
@@ -2611,16 +2904,18 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     }
     // Provider/transport failures get their own exit code (5) so CI can tell
     // "the model call failed" from "the run itself errored" (1).
-    return { exitCode: classifyLoopError(err), result: message, isError: true };
+    loopFailureOutcome = {
+      exitCode: classifyLoopError(err),
+      result: message,
+      isError: true,
+    };
   } finally {
     // Capture body-cache hits/misses caused by list_skills/run_skill during the
     // turn. `cc context --sources` reads the newest snapshot.
     persistContextSources();
-    try {
-      _backgroundInteraction?.close?.();
-    } catch {
-      // Best-effort listener cleanup; never mask the run result.
-    }
+    await cleanupDeadline.run("background-interaction", () =>
+      _backgroundInteraction?.close?.(),
+    );
     // Drop the signal handlers first — a normal return must not leave a
     // process-wide SIGINT/SIGTERM listener behind (a later Ctrl-C would wrongly
     // exit with 130, and repeated in-process runs would leak listeners).
@@ -2629,136 +2924,158 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     // Tear down ad-hoc MCP servers (--mcp-config) before returning, whether the
     // loop completed or threw. Best-effort: a failed disconnect never masks the
     // run's own outcome.
-    if (mcp?.mcpClient) {
-      try {
-        await mcp.mcpClient.disconnectAll();
-      } catch {
-        // ignore — disconnect is best-effort
-      }
-    }
+    await cleanupDeadline.run("mcp", () => mcp?.mcpClient?.disconnectAll?.());
     // Kill any background run_shell tasks this run spawned so a backgrounded
     // command (e.g. a dev server) doesn't outlive the headless invocation.
-    try {
-      killAllBackgroundShellTasks();
-    } catch {
-      // best-effort — never mask the run's own outcome
-    }
+    await cleanupDeadline.run("background-shells", () =>
+      killAllBackgroundShellTasks(),
+    );
     // Tear down the --remote-control approval bridge + its self-hosted WS
     // server so the run's port/socket never outlives the invocation.
-    if (_remoteApproval) {
-      try {
-        await _remoteApproval.close();
-      } catch {
-        // best-effort — never mask the run's own outcome
-      }
-    }
+    await cleanupDeadline.run("remote-approval", () =>
+      _remoteApproval?.close?.(),
+    );
     // settings.json Stop + SessionEnd hooks when the run finishes. Stop is the
     // canonical async-hook trigger ("run the test suite at turn end"); fire its
     // async hooks fire-and-forget, then settle so a fast background check can
     // report back within this one-shot run.
-    if (settingsHooks) {
-      try {
-        const { runObserveHooks, dispatchAsyncHooks } =
-          await import("../lib/settings-hook-events.js");
-        const stopPayload = { reason: endReason, cwd, session_id: sessionId };
-        const stopOutcome = runObserveHooks(
-          settingsHooks,
-          "Stop",
-          stopPayload,
-          { cwd },
-        );
-        const stopFailures = (stopOutcome?.results || []).filter(
-          (result) =>
-            result?.nonBlockingError === true ||
-            result?.malformedDecision === true ||
-            result?.breakerOpen === true,
-        );
-        if (stopFailures.length > 0) {
-          emitHooksV2Event("StopFailure", {
-            schema_version: 1,
-            session_id: sessionId,
-            phase: "stop-hook",
-            failures: stopFailures.map((failure) => ({
-              command: failure.command || null,
-              exit_code: failure.exitCode ?? null,
-              reason: failure.reason || failure.error || null,
-            })),
-          });
-        }
-        // Skip the async Stop dispatch/settle here if the auto-rewake re-drive
-        // loop already fired + drained it this run (avoids double-execution).
-        if (_hookSupervisor && !_asyncStopHandled) {
-          dispatchAsyncHooks(settingsHooks, "Stop", stopPayload, {
+    await cleanupDeadline.run("settings-hooks", async () => {
+      if (settingsHooks) {
+        try {
+          const { runObserveHooks, dispatchAsyncHooks } =
+            await import("../lib/settings-hook-events.js");
+          const stopPayload = {
+            reason: pipeState.closed ? "pipe_closed" : endReason,
             cwd,
-            supervisor: _hookSupervisor,
-          });
-          // Bounded settle: wait for in-flight async hooks (Stop + any
-          // PostToolUse dispatched during the loop) to finish, capped so a
-          // slow/hung check can never stall the run. Default 5s; tunable.
-          const waitMs = Number.isFinite(options.asyncHookWaitMs)
-            ? options.asyncHookWaitMs
-            : 5000;
-          const started = Date.now();
-          while (
-            _hookSupervisor.runningCount() > 0 &&
-            Date.now() - started < waitMs
-          ) {
-            await new Promise((r) => setTimeout(r, 50));
-          }
-          // Surface any results/rewakes out-of-band on stderr (never touches the
-          // stdout envelope). A rewake means a background check FAILED and would
-          // re-engage the agent in an interactive session — flag it clearly so a
-          // headless caller/CI can react.
-          for (const rw of _hookSupervisor.drainRewakes()) {
+            session_id: sessionId,
+          };
+          const stopOutcome = runObserveHooks(
+            settingsHooks,
+            "Stop",
+            stopPayload,
+            { cwd },
+          );
+          const stopFailures = (stopOutcome?.results || []).filter(
+            (result) =>
+              result?.nonBlockingError === true ||
+              result?.malformedDecision === true ||
+              result?.breakerOpen === true,
+          );
+          if (stopFailures.length > 0) {
             emitHooksV2Event("StopFailure", {
               schema_version: 1,
               session_id: sessionId,
-              phase: "async-stop-hook",
-              command: rw.command || null,
-              exit_code: rw.exitCode ?? null,
-              reason: rw.error || "async stop hook requested rewake",
+              phase: "stop-hook",
+              failures: stopFailures.map((failure) => ({
+                command: failure.command || null,
+                exit_code: failure.exitCode ?? null,
+                reason: failure.reason || failure.error || null,
+              })),
             });
-            writeErr(
-              `[async-hook REWAKE] ${rw.command} failed` +
-                `${rw.exitCode != null ? ` (exit ${rw.exitCode})` : ""}` +
-                `${rw.error ? `: ${rw.error}` : ""}\n`,
-            );
           }
-          for (const rs of _hookSupervisor.drainResults()) {
-            if (rs.additionalContext) {
-              writeErr(`[async-hook] ${rs.command}: ${rs.additionalContext}\n`);
+          // Skip the async Stop dispatch/settle here if the auto-rewake re-drive
+          // loop already fired + drained it this run (avoids double-execution).
+          if (_hookSupervisor && !_asyncStopHandled) {
+            dispatchAsyncHooks(settingsHooks, "Stop", stopPayload, {
+              cwd,
+              supervisor: _hookSupervisor,
+            });
+            // Bounded settle: wait for in-flight async hooks (Stop + any
+            // PostToolUse dispatched during the loop) to finish, capped so a
+            // slow/hung check can never stall the run. Default 5s; tunable.
+            const waitMs = Number.isFinite(options.asyncHookWaitMs)
+              ? options.asyncHookWaitMs
+              : 5000;
+            const started = Date.now();
+            while (
+              _hookSupervisor.runningCount() > 0 &&
+              Date.now() - started < waitMs
+            ) {
+              await new Promise((r) => setTimeout(r, 50));
+            }
+            // Surface any results/rewakes out-of-band on stderr (never touches the
+            // stdout envelope). A rewake means a background check FAILED and would
+            // re-engage the agent in an interactive session — flag it clearly so a
+            // headless caller/CI can react.
+            for (const rw of _hookSupervisor.drainRewakes()) {
+              emitHooksV2Event("StopFailure", {
+                schema_version: 1,
+                session_id: sessionId,
+                phase: "async-stop-hook",
+                command: rw.command || null,
+                exit_code: rw.exitCode ?? null,
+                reason: rw.error || "async stop hook requested rewake",
+              });
+              writeErr(
+                `[async-hook REWAKE] ${rw.command} failed` +
+                  `${rw.exitCode != null ? ` (exit ${rw.exitCode})` : ""}` +
+                  `${rw.error ? `: ${rw.error}` : ""}\n`,
+              );
+            }
+            for (const rs of _hookSupervisor.drainResults()) {
+              if (rs.additionalContext) {
+                writeErr(
+                  `[async-hook] ${rs.command}: ${rs.additionalContext}\n`,
+                );
+              }
             }
           }
+          // Always reap the supervisor (kills any straggler child + detaches the
+          // exit reaper), whether the async Stop was handled here or in re-drive.
+          if (_hookSupervisor) _hookSupervisor.stopAll();
+          runObserveHooks(
+            settingsHooks,
+            "SessionEnd",
+            {
+              reason: pipeState.closed ? "pipe_closed" : "completed",
+              cwd,
+              session_id: sessionId,
+            },
+            { cwd },
+          );
+        } catch (error) {
+          emitHooksV2Event("StopFailure", {
+            schema_version: 1,
+            session_id: sessionId,
+            phase: "stop-hook-dispatch",
+            reason: error?.message || String(error),
+          });
+          // observe-only + best-effort async surfacing
         }
-        // Always reap the supervisor (kills any straggler child + detaches the
-        // exit reaper), whether the async Stop was handled here or in re-drive.
-        if (_hookSupervisor) _hookSupervisor.stopAll();
-        runObserveHooks(
-          settingsHooks,
-          "SessionEnd",
-          { reason: "completed", cwd, session_id: sessionId },
-          { cwd },
-        );
-      } catch (error) {
-        emitHooksV2Event("StopFailure", {
-          schema_version: 1,
-          session_id: sessionId,
-          phase: "stop-hook-dispatch",
-          reason: error?.message || String(error),
-        });
-        // observe-only + best-effort async surfacing
       }
+    });
+    const cleanupReport = cleanupDeadline.report();
+    try {
+      deps.onCleanupReport?.(cleanupReport);
+    } catch {
+      // Metrics/reporting cannot change cleanup semantics.
+    }
+    if (cleanupReport.timedOut) {
+      cleanupFailure = cleanupDeadlineError(cleanupReport);
     }
   }
 
+  // Preserve the primary model/runtime failure. A simultaneous cleanup timeout
+  // remains observable through onCleanupReport but must not replace it.
+  if (loopFailureOutcome) return loopFailureOutcome;
+  if (cleanupFailure) throw cleanupFailure;
+
+  // A downstream consumer closed stdout/stderr. The abort above unwound the
+  // model loop through the same `finally` as every other termination, so MCP,
+  // background tasks, approval bridges, and hooks are settled. Do not attempt
+  // more writes to the closed pipe or persist a partial assistant answer.
+  if (pipeState.closed) {
+    return { exitCode: 0, result: finalText, isError: false };
+  }
+
   // coreAgentLoop emits run-ended reason "budget-exhausted" when the iteration
   // cap is hit; treat that as the max-turns error surface. A cost-budget stop
   // (--max-budget-usd) is its own error surface so callers can tell them apart.
   const exhausted =
     endReason === "budget-exhausted" || endReason === "max_turns";
   const costStopped = endReason === "cost-budget-exhausted";
-  const isError = exhausted || costStopped || endReason === "no-response";
-  const subtype = exhausted
+  let isError = exhausted || costStopped || endReason === "no-response";
+  let subtype = exhausted
     ? "error_max_turns"
     : costStopped
       ? "error_max_budget"
@@ -2766,6 +3083,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
         ? "error"
         : "success";
   const durationMs = (deps.now ? deps.now() : Date.now()) - startedAt;
+  let persistenceFailure = null;
 
   // Persist the assistant turn so a later --resume / --continue replays it.
   // The user turn was already recorded up front; only append on a clean run.
@@ -2792,8 +3110,30 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
         store.appendTokenUsage(sessionId, au);
       }
       store.appendTokenUsage(sessionId, usage);
-    } catch {
-      // Persistence is best-effort — never fail the run over it.
+    } catch (error) {
+      const persistenceError = createSessionPersistenceFailure(error, {
+        sessionId,
+        operation: "assistant-turn-append",
+      });
+      persistenceFailure = projectSessionPersistenceFailure(persistenceError, {
+        phase: "after-model",
+      });
+      if (persistenceFailure) {
+        isError = true;
+        subtype = "error_persistence";
+        try {
+          deps.onPersistenceFailure?.(persistenceFailure);
+        } catch {
+          // Observability cannot change persistence semantics.
+        }
+        if (isText) {
+          writeErr(
+            `CC_SESSION_PERSISTENCE_FAILED: assistant turn durability is ${persistenceFailure.commit_state} (${persistenceFailure.fs_code})\n`,
+          );
+        }
+      }
+      // Preserve legacy best-effort handling for errors outside the explicit
+      // ENOSPC/EROFS durability contract.
     }
   }
 
@@ -2854,7 +3194,9 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     if (isText) {
       writeErr(
         `\n  ${denials.length} tool call(s) were denied by policy this run:\n` +
-          formatDenials(denials, { now: deps.now ? deps.now() : Date.now() }) +
+          formatDenials(denials, {
+            now: deps.now ? deps.now() : Date.now(),
+          }) +
           "\n",
       );
     } else if (isStream) {
@@ -2887,6 +3229,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
       ...(compactionDegradations.length
         ? { compaction_degradations: compactionDegradations }
         : {}),
+      ...(persistenceFailure ? { persistence: persistenceFailure } : {}),
     });
   } else if (isJson) {
     writeOut(
@@ -2902,6 +3245,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
           durationMs,
           denials,
           compactionDegradations,
+          persistence: persistenceFailure,
         }),
       ) + "\n",
     );
@@ -2923,12 +3267,10 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
         );
         if (!isStream) {
           const sum = _otlpRecorder.summary();
-          process.stderr.write(
-            `[otlp] ${sum.spanCount} span(s) → ${options.otlp}\n`,
-          );
+          writeErr(`[otlp] ${sum.spanCount} span(s) → ${options.otlp}\n`);
         }
       } catch (err) {
-        process.stderr.write(`[otlp] export failed: ${err.message}\n`);
+        writeErr(`[otlp] export failed: ${err.message}\n`);
       }
     }
     if (_collectorEnabled) {
@@ -2948,6 +3290,7 @@ async function runAgentHeadlessInWorkspace(options = {}, deps = {}) {
     exitCode: exitCodeForEndReason(endReason, isError),
     result: finalText,
     isError,
+    ...(persistenceFailure ? { persistence: persistenceFailure } : {}),
   };
 }
 
@@ -2962,6 +3305,7 @@ function buildResultEnvelope({
   durationMs,
   denials,
   compactionDegradations,
+  persistence,
 }) {
   const env = {
     type: "result",
@@ -2980,5 +3324,6 @@ function buildResultEnvelope({
   if (Array.isArray(compactionDegradations) && compactionDegradations.length) {
     env.compaction_degradations = compactionDegradations;
   }
+  if (persistence) env.persistence = persistence;
   return env;
 }