@sema-agent/core 7.11.2 → 7.12.0

package/dist/core/runner/run-settle-and-teardown.js

@@ -0,0 +1,324 @@
+import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
+import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
+import { resolveCheckpointStore } from "../checkpoint-store.js";
+import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
+import { hasDestroy, isIsolated } from "../remote-env.js";
+import { defaultTaskRegistry } from "../task-registry.js";
+import { emitTrace } from "../trace.js";
+import { assembleResult } from "./assemble-result.js";
+import { TIMER_LATENESS_REPORT_MS } from "./clock-and-limits.js";
+import { resumeDecisionWasNegative } from "./decide-continuation.js";
+import { drainForwardedFramesBeforeDone, forwardsSubagentEvents } from "./prepare-run-refs.js";
+import { settleTeardownLeg } from "./teardown-bounded.js";
+import { amendTerminal, terminalProjection } from "./terminal-projection.js";
+export async function runSettleAndTeardown(input) {
+    const { spec, queue, prepared, resume, internals, rs, stats, ident, parentToolCallId, subagentName, loopLatch, timeout, ownCommittedTailRef, emitDelegationLifecycle, taskIdRef, manualCompactRef, drainManualCompact, final, threw, abortedLive, strandedHumanAnswers, reasoningResolution, comp, setResult, onSuggestions, onSuspend, runner, sessions, suggestNextPrompts, teardownOwnedEnv } = input;
+    try {
+        if (comp?.compacted) {
+            queue.push({
+                type: "compacted",
+                trigger: "auto",
+                tokensBefore: comp.tokensBefore ?? 0,
+                ...(comp.postTriggerTokens !== undefined ? { tokensAfter: comp.postTriggerTokens } : {}),
+                ...(comp.triggerTokens !== undefined ? { triggerTokensBefore: comp.triggerTokens } : {}),
+                ...(comp.durationMs !== undefined ? { durationMs: comp.durationMs } : {}),
+                ...(comp.phaseDurations !== undefined ? { phaseDurations: comp.phaseDurations } : {}),
+                ...(comp.firstKeptEntryId !== undefined ? { preserved_segment: { firstKeptEntryId: comp.firstKeptEntryId } } : {}),
+                ...(comp.attachedFiles !== undefined ? { attachedFiles: comp.attachedFiles } : {}),
+                ...(comp.modelFallback ? { modelFallback: true } : {}),
+                ...(comp.fallbackReason !== undefined ? { fallbackReason: comp.fallbackReason } : {}),
+                ...(comp.clampedRatio !== undefined ? { clampedRatio: comp.clampedRatio } : {}),
+                ...(comp.clampReason !== undefined ? { clampReason: comp.clampReason } : {}),
+                ...ident(),
+            });
+            if (comp.phaseDurations !== undefined && comp.durationMs !== undefined) {
+                const pd = comp.phaseDurations;
+                const pdDur = comp.durationMs;
+                emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.phase_timings", version: 1, taskId: rs.telemetry.taskId, ...pd, durationMs: pdDur, ts: Date.now() }));
+            }
+            prepared.cacheBreakDetector?.notifyCompaction();
+        }
+        if (prepared.nestedStats.tasks > 0) {
+            stats.nested = {
+                tokens: prepared.nestedStats.tokens,
+                turns: prepared.nestedStats.turns,
+                tasks: prepared.nestedStats.tasks,
+                ...(prepared.nestedStats.anyUnpriced ? {} : { costMicroUsd: prepared.nestedStats.costMicroUsd }),
+            };
+        }
+        if (stats.totalInputTokens > 0) {
+            const rawHit = stats.cachedTokens / stats.totalInputTokens;
+            if (stats.cachedTokens > stats.totalInputTokens) {
+                runner.deps.onError?.(new Error(`prompt-cache: usage/api mismatch — cachedTokens (${stats.cachedTokens}) > totalInputTokens (${stats.totalInputTokens}); the cache family is likely wrong. Does model.api match the brain serving it? Override with model.params.promptCacheFamily = "input-includes-cached" | "input-excludes-cached".`), { phase: "prompt-cache", sessionId: prepared.sessionId });
+            }
+            stats.cacheHitRate = Math.min(1, rawHit);
+            if (!rs.telemetry.cacheBreakReported && stats.turns >= 2 && stats.totalInputTokens >= 8000 && stats.cacheHitRate < 0.15) {
+                const cacheWritten = stats.cacheWriteTokens + stats.cacheWriteTokensLong;
+                const cause = rs.degrade.degraded
+                    ? `a mid-task model switch (${rs.degrade.degraded.from} → ${rs.degrade.degraded.to}, degradation) reset the prefix cache — this is the likely cause`
+                    : cacheWritten > 0
+                        ? `this task reported ${cacheWritten} cache-write tokens across its calls (compaction included) but served almost none back as reads — consistent with a prompt prefix that CHANGES between turns (client-side: volatile content up front, or per-turn tool churn/reorder) and, less often, with server-side eviction. Keep volatile content (memory/timestamps/ids) out of the prefix and the tool list stable in membership AND order`
+                        : `no call in this task reported any cache-write tokens — and this API family may not report them at all (an openai-shaped usage row carries cached READS only), so the write side is no evidence here; check that the prompt prefix (system prompt + tool list, membership AND order) is byte-stable across turns and that this route caches this model`;
+                runner.deps.onError?.(new Error(`prompt-cache: low prefix-cache hit rate ${(stats.cacheHitRate * 100).toFixed(0)}% over ${stats.turns} turns (${stats.totalInputTokens} prompt tokens) — ${cause}. See design/09.`), { phase: "prompt-cache", sessionId: prepared.sessionId });
+            }
+        }
+        if (prepared.resourceLedger &&
+            (resume?.cp.gate.kind === "resource_limit" || prepared.pausedRef.current?.cause.gate.kind === "resource_limit")) {
+            stats.costMicroUsd += prepared.resourceLedger.spentMicroUsd;
+            stats.tokens += prepared.resourceLedger.spentTokens;
+            stats.turns += prepared.resourceLedger.spentTurns;
+        }
+        if (prepared.humanReviewRef.count > 0) {
+            stats.humanReview = {
+                count: prepared.humanReviewRef.count,
+                totalWaitMs: prepared.humanReviewRef.totalWaitMs,
+                gates: [...prepared.humanReviewRef.gates],
+            };
+        }
+        const reminderDisclosuresActive = Object.keys(prepared.reminderDisclosureCounts).length > 0;
+        if (rs.counters.finalVerifyInjections > 0 || rs.attach.attachmentsInjected > 0 || rs.counters.repetitionCuts > 0 || rs.counters.repetitionSpared > 0 || rs.counters.approachNoticesSent > 0 || reminderDisclosuresActive) {
+            stats.mechanisms = {
+                ...(rs.counters.finalVerifyInjections > 0 ? { finalVerifyInjected: true } : {}),
+                ...(rs.counters.finalVerifyInjections > 0 ? { finalVerifyInjections: rs.counters.finalVerifyInjections } : {}),
+                ...(rs.attach.attachmentsInjected > 0 ? { attachmentsInjected: rs.attach.attachmentsInjected } : {}),
+                ...(rs.counters.approachNoticesSent > 0 ? { approachNoticesSent: rs.counters.approachNoticesSent } : {}),
+                ...(rs.counters.repetitionCuts > 0 ? { repetitionCuts: rs.counters.repetitionCuts } : {}),
+                ...(rs.counters.repetitionSpared > 0 ? { repetitionSpared: rs.counters.repetitionSpared } : {}),
+                ...(rs.counters.repetitionEvents.length > 0 ? { repetitionEvents: rs.counters.repetitionEvents } : {}),
+                ...(reminderDisclosuresActive ? { reminderDisclosures: { ...prepared.reminderDisclosureCounts } } : {}),
+            };
+        }
+        const result = assembleResult(spec, prepared.sessionId, final, stats, {
+            threw,
+            runId: prepared.runId,
+            model: prepared.model.id,
+            unpricedSpend: rs.telemetry.unpricedSpend,
+            rewindNotes: prepared.rewindNotes,
+            editedFiles: prepared.editedFilesSnapshot(),
+            haltedOnUserRejection: prepared.batchHaltRef.current !== undefined,
+            userHalted: loopLatch.userHalted,
+            strandedHumanAnswers,
+            remoteEnvFailures: prepared.remoteEnvFailures,
+            effectiveReadFace: prepared.effectiveReadFace,
+            effectiveReadDenyPatterns: prepared.effectiveReadDenyPatterns,
+            effectiveMemoryScopes: prepared.effectiveMemoryScopes,
+            effectiveReasoning: reasoningResolution.current,
+            retryAfterMs: rs.limits.platformTerminal?.retryAfterMs,
+            abortedForTimeout: timeout.fired,
+            abortedForTurns: rs.limits.turnsExceeded,
+            abortedLive,
+            budgetHit: rs.limits.budgetHit,
+            budgetAxis: rs.limits.budgetAxis,
+            blockedReason: prepared.blockedRef.reason,
+            conflict: prepared.conflictRef.hit,
+            gitCoreOverBudget: prepared.gitStatusRef.terminalCode === "irreducible_core_over_budget",
+            outputInvalid: rs.degrade.outputInvalid,
+            suspendLoop: prepared.suspendLoopRef.hit,
+            ...(prepared.pausedRef.current !== undefined ? { paused: prepared.pausedRef.current.cause } : {}),
+        });
+        if (resume !== undefined &&
+            resume.pendingActionStarted !== true &&
+            result.terminal.kind !== "completed" &&
+            result.terminal.kind !== "paused" &&
+            !(resumeDecisionWasNegative(resume) && resume.decisionDelivered === true) &&
+            resume.onEnvRestoreFailed !== undefined) {
+            try {
+                await resume.onEnvRestoreFailed("env_failed");
+                amendTerminal(result, "resume.reopened_unstarted", (m) => `${m ?? "the resume leg did not complete"} — the approved action never started, so the checkpoint was REOPENED (pending): the same approval can be resumed again, do not ask for a fresh one`);
+            }
+            catch {
+                amendTerminal(result, "resume.reopen_failed_unstarted", (m) => `${m ?? "the resume leg did not complete"} — the approved action never started, and reopening the checkpoint FAILED: its state is unprovable from here. Re-read it before deciding; do NOT issue a fresh approval on the assumption the old one is dead`);
+            }
+        }
+        prepared.sealReadStateSeat?.(ownCommittedTailRef.current);
+        {
+            const wss = prepared.workspaceStateSettle;
+            if (wss !== undefined && result.terminal.kind !== "paused") {
+                const curCwd = prepared.cwdRef?.current !== undefined && prepared.cwdRef.current !== wss.rootCanonical ? prepared.cwdRef.current : undefined;
+                const curWt = prepared.worktreeSessionRef?.current;
+                const changed = curCwd !== wss.restoredHandsCwd || curWt?.worktreeDir !== wss.restoredWorktreeDir;
+                if (curCwd !== undefined || curWt !== undefined || changed || wss.baselineUnknown === true) {
+                    await settleTeardownLeg(() => prepared.session.appendWorkspaceState({
+                        taskRoot: wss.rootCanonical,
+                        ...(curCwd !== undefined ? { handsCwd: curCwd } : {}),
+                        ...(curWt !== undefined ? { activeWorktree: { ...curWt } } : {}),
+                    }), "session.appendWorkspaceState (settle leg)", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+                }
+            }
+        }
+        const stopFailureHook = (spec.hooks ?? runner.deps.hooks)?.stopFailure;
+        if (stopFailureHook !== undefined &&
+            result.terminal.kind === "failed" &&
+            final?.stopReason === "error" &&
+            !isDegenerateCutMessage(final) &&
+            threw === undefined &&
+            rs.limits.budgetHit === undefined &&
+            !rs.degrade.outputInvalid &&
+            !prepared.suspendLoopRef.hit &&
+            !abortedLive &&
+            result.terminal.code !== "conflict") {
+            const failedCause = result.terminal;
+            try {
+                const failureSeat = await runHookSeat("stopFailure", { timeoutMs: prepared.hookTimeoutMs }, (sig) => stopFailureHook({
+                    identity: prepared.hookIdentity,
+                    error: failedCause.message ?? "model error",
+                    ...(failedCause.code !== undefined ? { errorKind: failedCause.code } : {}),
+                    turns: stats.turns,
+                    signal: sig,
+                }));
+                if (failureSeat.expired) {
+                    try {
+                        runner.deps.onError?.(hookSeatExpiredError("stopFailure", prepared.hookTimeoutMs, failureSeat.cause, "the terminal observation was abandoned; the assembled TaskResult is unchanged"), { phase: "hook", sessionId: prepared.sessionId });
+                    }
+                    catch {
+                    }
+                }
+            }
+            catch (err) {
+                try {
+                    runner.deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "hook", sessionId: prepared.sessionId });
+                }
+                catch {
+                }
+            }
+        }
+        const terminalFace = terminalProjection(result.terminal);
+        emitDelegationLifecycle({
+            phase: "terminal",
+            identity: prepared.hookIdentity,
+            status: terminalFace.status,
+            turns: stats.turns,
+            ...(terminalFace.errorCode !== undefined ? { errorCode: terminalFace.errorCode } : {}),
+        });
+        if (taskIdRef !== undefined)
+            taskIdRef.delegationTerminalOwed = undefined;
+        if (rs.degrade.degraded)
+            result.degraded = rs.degrade.degraded;
+        if (prepared.outputRef.set)
+            result.structuredOutput = prepared.outputRef.value;
+        const committedToken = prepared.pausedRef.current?.cause.token;
+        const committedScope = prepared.pausedRef.current?.scope;
+        if (committedToken !== undefined) {
+            const store = resolveCheckpointStore(spec, runner.deps);
+            if (store && committedScope !== undefined) {
+                onSuspend({
+                    env: prepared.ownedEnv,
+                    token: committedToken,
+                    scope: committedScope,
+                    store,
+                    sessionId: prepared.sessionId,
+                });
+            }
+        }
+        if (resume && committedToken === undefined) {
+            await settleTeardownLeg(() => sessions.unpin?.(resume.cp.sessionId), "sessions.unpin (resumed-terminal leg)", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+        }
+        if (prepared.memoryEngineSession) {
+            const mes = prepared.memoryEngineSession;
+            await settleTeardownLeg(() => mes.harvest(), "memoryEngineSession.harvest (settle leg)", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+        }
+        emitTrace(rs.telemetry.tracer, () => ({
+            kind: "task.end",
+            version: 1,
+            taskId: rs.telemetry.taskId,
+            runId: rs.telemetry.runId,
+            status: terminalFace.status,
+            errorCode: terminalFace.errorCode,
+            turns: stats.turns,
+            tokens: stats.tokens,
+            ...(rs.telemetry.unpricedSpend ? {} : { costMicroUsd: stats.costMicroUsd }),
+            durationMs: Date.now() - rs.telemetry.taskStart,
+            ...(prepared.outputRef.set ? { hasStructuredOutput: true } : {}),
+            ...(stats.mechanisms !== undefined
+                ? { mechanisms: (({ repetitionEvents: _events, ...scalars }) => scalars)(stats.mechanisms) }
+                : {}),
+            ...(timeout.latenessMs !== undefined && timeout.latenessMs > TIMER_LATENESS_REPORT_MS
+                ? { timerLatenessMs: timeout.latenessMs }
+                : {}),
+            ...(rs.counters.walltimeSyncBackstopFired ? { walltimeSyncBackstop: true } : {}),
+            ts: Date.now(),
+        }));
+        setResult(result);
+        if (parentToolCallId !== undefined && result.terminal.kind !== "paused") {
+            const terminalTick = {
+                type: "task_progress",
+                taskId: rs.telemetry.taskId,
+                ...(internals?.delegationTaskType !== undefined ? { taskType: internals.delegationTaskType } : {}),
+                ...(internals?.cycleSeq !== undefined ? { seq: internals.cycleSeq } : {}),
+                ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
+                ...(subagentName ? { name: subagentName } : {}),
+                model: prepared.model.id,
+                usage: { totalTokens: stats.tokens, toolUses: stats.toolCalls, durationMs: Date.now() - rs.telemetry.taskStart },
+                status: result.terminal.kind === "completed" ? "completed" : "failed",
+                ...ident(),
+            };
+            queue.push(terminalTick);
+            try {
+                internals?.onForwardEvent?.(terminalTick);
+            }
+            catch {
+            }
+        }
+        if (manualCompactRef.waiters.length > 0) {
+            queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason: "task_ending", ...ident() });
+            drainManualCompact("mooted");
+        }
+        manualCompactRef.emitMooted = undefined;
+        if (forwardsSubagentEvents(spec))
+            await drainForwardedFramesBeforeDone();
+        queue.push({ type: "done", result });
+        queue.close();
+        await prepared.fileHistoryBoundary?.settle();
+        if (spec.suggestNextPrompts && result.terminal.kind === "completed") {
+            onSuggestions(suggestNextPrompts(spec, prepared, result));
+        }
+    }
+    finally {
+        const ownedEnvDying = prepared.ownedEnv !== undefined &&
+            hasDestroy(prepared.ownedEnv) &&
+            isIsolated(prepared.ownedEnv) &&
+            prepared.pausedRef.current === undefined;
+        await settleTeardownLeg(() => defaultTaskRegistry.settleKilledForOwner({ owner: spec.taskId ?? prepared.sessionId, scope: spec.principal ?? "default", sessionId: prepared.sessionId }, {
+            source: abortedLive &&
+                !timeout.fired &&
+                !rs.limits.turnsExceeded &&
+                rs.limits.budgetHit === undefined &&
+                prepared.pausedRef.current === undefined
+                ? "user"
+                : "parent",
+            skipSessionScoped: true,
+            envDying: ownedEnvDying,
+            retainProcesses: spec.retainBackgroundProcesses === true,
+        }), "taskRegistry.settleKilledForOwner", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+        const bgEnv = prepared.ownedEnv ?? runner.deps.executionEnv;
+        const retainBgBySpec = spec.retainBackgroundProcesses === true && !ownedEnvDying;
+        if (bgEnv && hasBackgroundShell(bgEnv) && !retainBgBySpec) {
+            try {
+                const keepAlive = ownedEnvDying && bgEnv === prepared.ownedEnv
+                    ? []
+                    : [
+                        ...defaultTaskRegistry.sessionResidentShellIds(prepared.sessionId, bgEnv),
+                        ...defaultTaskRegistry.timeoutResidentShellIds(bgEnv),
+                        ...defaultTaskRegistry.retainedShellIds(bgEnv),
+                    ];
+                await settleTeardownLeg(() => sweepBackgroundShells(bgEnv, defaultTaskRegistry, keepAlive.length > 0 ? { except: keepAlive } : undefined), "sweepBackgroundShells", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+            }
+            catch (e) {
+                runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId });
+            }
+        }
+        defaultTaskRegistry.clearBackgroundForOwner({
+            owner: spec.taskId ?? prepared.sessionId,
+            scope: spec.principal ?? "default",
+        });
+        defaultTaskRegistry.abortBackgroundAgentsForOwner({
+            owner: spec.taskId ?? prepared.sessionId,
+            scope: spec.principal ?? "default",
+        }, { skipSessionScoped: true });
+        if (prepared.subagentRetain) {
+            await settleTeardownLeg(() => prepared.subagentRetain.disposeAll(), "subagentRetain.disposeAll", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+        }
+        await settleTeardownLeg(() => teardownOwnedEnv(prepared), "teardownOwnedEnv", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+    }
+    return {};
+}

package/dist/core/runner/run-terminal-adoption.d.ts

@@ -0,0 +1,99 @@
+/**
+ * design/393 S6 — the run body's TERMINAL ADOPTION (R14), verbatim from `Runner.runLocked`, between the leg's finally and
+ * the settle: the typed causes lifted over the leg's anonymous end (the brain-call guardrail's stall, the tool gate's own
+ * stop, the platform lane's external cause — which alone overrides a real throw), the usage ledger's FINAL charge with its
+ * slow-charge disclosure, the live-abort orphan reconcile and its synthetic `tool_end` frames, the held session-write
+ * drain, the user-interruption marker, the durable park's carried caller input and the held agent_end account's settle,
+ * the dropped post-compact announce disclosure, and the end-of-task compaction pass (`finish`).
+ *
+ * Async (six first-level awaits, the same awaits at the same positions). It ends by entering the settle lane (`next`) in
+ * its LAST continuation — the settle's first read sits on the tick `finish` resolved on, as it did in the one-function
+ * body — and returns what it returns. What crosses the boundary is exactly what the settle reads of this lane's work: the
+ * ADOPTED cause (`threw`, possibly lifted here) and the compaction outcome (`comp`); the pause / interruption / reconcile
+ * facts are consumed here.
+ */
+import type { AssistantMessage } from "../../internal/llm.js";
+import type { Model } from "../../internal/llm.js";
+import type { MaybeCompactOptions } from "../auto-compaction.js";
+import type { PushQueue } from "../push-queue.js";
+import { type Brain, type TaskEvent, type TaskSpec } from "../types.js";
+import { type Stats } from "./assemble-result.js";
+import type { EndOfTaskCompaction, Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
+export interface RunTerminalAdoptionInput<R> {
+    /** borrowed-readonly — the task spec: the task id the account's notices name; `finish`'s first argument. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the run's event queue: the reconcile's synthetic `tool_end` frames and the end-of-task compaction's failure frame. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-mutable — the leg's prepared seat: the guardrail / gate-stop / paused refs are read, the usage ledger charged, the session
+     *  reconciled and the marker appended, the harness's parkable inputs read and dropped. */
+    prepared: Prepared;
+    /** borrowed-readonly — the run's mutable state: the platform terminal, the limit flags, the attachment state and the telemetry seat. */
+    rs: RunState;
+    /** borrowed-readonly — this leg's usage counters (the final charge's cumulative total). */
+    stats: Stats;
+    /** borrowed-readonly — the run's event-identity mint (the synthetic `tool_end` frames, the compaction failure frame). */
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    /** borrowed-readonly — the `message_committed` mint (the reconcile's appended toolResults, the marker). */
+    emitCommitted: (entryId: string, role: "user" | "assistant" | "toolResult", toolCallId?: string) => void;
+    /** borrowed-readonly — the observed tool-start ids the reconcile splits orphans by (EMPTIED by the reconcile's commit). */
+    startedToolCallIds: Set<string>;
+    /** borrowed-readonly — the label map the synthetic `tool_end` frames carry. */
+    toolLabels: Map<string, string>;
+    /** borrowed-readonly — the hard walltime timer: `fired` is one of the interruption facts. */
+    timeout: {
+        readonly fired: boolean;
+    };
+    /** borrowed-readonly — the compaction machinery's accounted brain (the end-of-task summary call is accounted too). */
+    compactionBrain: Brain;
+    /** borrowed-readonly — the shared compaction breaker: an open breaker skips the end-of-task attempt. */
+    compactionBreaker: {
+        readonly failures: number;
+    };
+    /** borrowed-readonly — the window-safety builder the end-of-task lane shares with the boundary / PTL lanes. */
+    windowSafetyOptions: (mainModel: Model) => Pick<MaybeCompactOptions, "fallbackBudget" | "onWindowSafety">;
+    /** borrowed-readonly — the held agent_end account, as the read face on the identity lane's Result (backlog #389). */
+    undrainedUserAtEnd: {
+        readonly current: {
+            steer: number;
+            followUp: number;
+        } | undefined;
+    };
+    /** borrowed-readonly — the leg lane's final assistant message (its `stopReason` is one of the interruption facts). */
+    final: AssistantMessage | undefined;
+    /** borrowed-readonly — what the leg threw (undefined on a clean end); this lane may LIFT a typed cause over it and hands the adopted value on. */
+    threw: unknown;
+    /** borrowed-readonly — the live-abort flag the leg captured before its release-abort. */
+    abortedLive: boolean;
+    /** borrowed-readonly — the leg's snapshot of `loopLatch.userInterrupted` (gates the interruption marker). */
+    userInterruptedLive: boolean;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError`, `checkpointStore`, `onNotice`); the one home of why it is
+     *  a seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the Runner's end-of-task compaction pass (its private method, as a delegate). */
+    finish: (spec: TaskSpec, prepared: Prepared, opts: {
+        skipCompaction?: boolean;
+        minTokens?: number;
+        brain?: Brain;
+        windowSafety?: Pick<MaybeCompactOptions, "fallbackBudget" | "onWindowSafety">;
+        onCompactionFailed?: (reason: string) => void;
+        telemetry?: {
+            tracer: TaskSpec["tracer"];
+            taskId: string;
+        };
+        cancelled?: boolean;
+    }) => Promise<EndOfTaskCompaction>;
+    /** borrowed-readonly — the settle lane, entered in this lane's last continuation with the adopted cause and the compaction outcome. */
+    next: (adopted: RunTerminalAdoptionResult) => Promise<R>;
+}
+/** What the settle reads of this lane's work. */
+export interface RunTerminalAdoptionResult {
+    /** The ADOPTED terminal cause: the leg's throw, or the typed cause lifted over it here (guardrail stall / gate stop / platform terminal). */
+    threw: unknown;
+    /** The end-of-task compaction pass's outcome. */
+    comp: EndOfTaskCompaction;
+}
+export declare function runTerminalAdoption<R>(input: RunTerminalAdoptionInput<R>): Promise<R>;

package/dist/core/runner/run-terminal-adoption.js

@@ -0,0 +1,120 @@
+import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
+import { appendInterruptionMarker, reconcileInterruptedSession } from "../session-reconcile.js";
+import { emitTrace } from "../trace.js";
+import { deliverEngineNotice, undrainedUserInputNotices } from "../types.js";
+import { errorCodeOf } from "./assemble-result.js";
+import { awaitChargeWithSlowDisclosure } from "./clock-and-limits.js";
+import { MAX_CONSECUTIVE_COMPACTION_FAILURES } from "./compaction-knobs.js";
+import { reconciledToolEndBody } from "./tool-end-body.js";
+export async function runTerminalAdoption(input) {
+    const { spec, queue, prepared, rs, stats, ident, emitCommitted, startedToolCallIds, toolLabels, timeout, compactionBrain, compactionBreaker, windowSafetyOptions, undrainedUserAtEnd, final, abortedLive, userInterruptedLive, runner, finish, next } = input;
+    let { threw } = input;
+    if (threw === undefined && prepared.brainCallGuardrailRef.timedOut !== undefined) {
+        threw = prepared.brainCallGuardrailRef.timedOut;
+    }
+    if (threw === undefined && prepared.gateStopRef.terminal !== undefined) {
+        threw = prepared.gateStopRef.terminal;
+    }
+    if (rs.limits.platformTerminal !== undefined) {
+        threw = rs.limits.platformTerminal;
+    }
+    if (prepared.usageGovernance !== undefined) {
+        try {
+            await awaitChargeWithSlowDisclosure(prepared.usageGovernance.commit(stats.tokens, rs.telemetry.unpricedSpend ? undefined : stats.costMicroUsd, Date.now()), () => runner.deps.onError?.(new Error("the usage ledger's FINAL charge has not settled after 10s — still waiting (a charge is never abandoned: walking away would double-charge on a later flush). A wedged ledger store wedges this teardown, now visibly."), { phase: "config", sessionId: prepared.sessionId }));
+        }
+        catch (flushErr) {
+            runner.deps.onError?.(flushErr, { phase: "config", sessionId: prepared.sessionId });
+        }
+    }
+    const committedPause = prepared.pausedRef.current;
+    const durablyPaused = committedPause !== undefined;
+    const interrupted = !durablyPaused &&
+        (threw !== undefined || timeout.fired || rs.limits.turnsExceeded || rs.limits.budgetHit !== undefined || abortedLive || final?.stopReason === "aborted");
+    let orphansClosed = 0;
+    let reconcileComplete = false;
+    if (interrupted) {
+        try {
+            const report = await reconcileInterruptedSession(prepared.session, prepared.toolEffects, undefined, startedToolCallIds);
+            orphansClosed = report.recovered.length;
+            for (const orphan of report.recovered) {
+                queue.push({ type: "tool_end", toolCallId: orphan.toolCallId, toolName: orphan.toolName, ...(toolLabels.has(orphan.toolName) ? { label: toolLabels.get(orphan.toolName) } : {}), isError: true, ...reconciledToolEndBody(orphan, prepared.structuredProjector), ...ident() });
+                emitCommitted(orphan.entryId, "toolResult", orphan.toolCallId);
+            }
+            reconcileComplete = true;
+        }
+        catch (reconcileErr) {
+            runner.deps.onError?.(reconcileErr instanceof Error ? reconcileErr : new Error(String(reconcileErr)), {
+                phase: "interrupt-reconcile",
+                sessionId: prepared.sessionId,
+            });
+        }
+        try {
+            await prepared.harness.flushQueuedSessionWrites();
+        }
+        catch (flushErr) {
+            runner.deps.onError?.(flushErr instanceof Error ? flushErr : new Error(String(flushErr)), {
+                phase: "interrupt-reconcile",
+                sessionId: prepared.sessionId,
+            });
+        }
+    }
+    if (interrupted && userInterruptedLive && reconcileComplete) {
+        try {
+            const entryId = await appendInterruptionMarker(prepared.session, { toolUseInFlight: orphansClosed > 0 });
+            emitCommitted(entryId, "user");
+        }
+        catch (markerErr) {
+            runner.deps.onError?.(markerErr instanceof Error ? markerErr : new Error(String(markerErr)), {
+                phase: "interrupt-reconcile",
+                sessionId: prepared.sessionId,
+            });
+        }
+    }
+    let migratedParked = { steer: 0, followUp: 0 };
+    if (committedPause !== undefined && runner.deps.checkpointStore !== undefined) {
+        const parkToken = committedPause.cause.token;
+        const parkScope = committedPause.scope;
+        const store = runner.deps.checkpointStore;
+        const carried = [];
+        for (const record of prepared.harness.readParkableUserInputs()) {
+            try {
+                if (!(await store.setPendingSteer(parkToken, parkScope, record)))
+                    break;
+                carried.push(record);
+            }
+            catch (parkErr) {
+                runner.deps.onError?.(parkErr instanceof Error ? parkErr : new Error(String(parkErr)), {
+                    phase: "config",
+                    sessionId: prepared.sessionId,
+                });
+                const parkCode = errorCodeOf(parkErr);
+                if (parkCode === "steering.invalid_content" || parkCode === "steering.queue_full")
+                    continue;
+                break;
+            }
+        }
+        migratedParked = prepared.harness.dropParkedUserInputs(carried);
+    }
+    if (undrainedUserAtEnd.current !== undefined) {
+        const remaining = {
+            steer: Math.max(0, undrainedUserAtEnd.current.steer - migratedParked.steer),
+            followUp: Math.max(0, undrainedUserAtEnd.current.followUp - migratedParked.followUp),
+        };
+        for (const notice of undrainedUserInputNotices(remaining, spec.taskId ?? prepared.sessionId, prepared.sessionId, prepared.runId)) {
+            deliverEngineNotice(runner.deps.onNotice, notice);
+        }
+    }
+    if (rs.attach.attachState?.postCompactPending === true && (rs.attach.attachmentsCfg?.backgroundTasks ?? eventDefaultOn("background_tasks")) === true) {
+        emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.announce_dropped", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
+    }
+    const comp = await finish(spec, prepared, {
+        telemetry: { tracer: rs.telemetry.tracer, taskId: rs.telemetry.taskId },
+        skipCompaction: durablyPaused || compactionBreaker.failures >= MAX_CONSECUTIVE_COMPACTION_FAILURES,
+        minTokens: rs.counters.compactionFloor,
+        brain: compactionBrain,
+        windowSafety: windowSafetyOptions(prepared.model),
+        onCompactionFailed: (reason) => queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "auto", reason, ...ident() }),
+        cancelled: abortedLive,
+    });
+    return await next({ threw, comp });
+}

package/dist/core/runner/runtask.d.ts

@@ -21,9 +21,6 @@ export declare class Runner implements RunnerSelfSeat {
      *  authority: a durable resume's checkpoint seed wins on its leg, and a miss (cross-process,
      *  evicted) falls back to the transcript-replay rung. See {@link SessionReadFileStates}. */
     private readonly sessionReadStates;
-    /** #616 — the per-session breaker read face's record (see {@link RunInternals.autoModeBreakerLedger}). Runner-lived:
-     *  a trip in one leg is what the session's next leg reports. */
-    private readonly autoModeBreakerLedger;
     /** task notifications born BETWEEN turns (run torn down / harness already idle), parked
      *  per session and drained into the session's next run at its first boundary. Runner-lived (outlives any
      *  single run, like the registry handles that produce into it); bounded + drop-disclosing, see
@@ -136,6 +133,20 @@ export declare class Runner implements RunnerSelfSeat {
      *  happen. Iterating just observes events (the buffer is backpressure-free); `.result()` awaits completion. */
     runTaskStream(spec: TaskSpec, resume?: ResumeRun, internals?: RunInternals): TaskStream;
     private runLocked;
+    /**
+     * design/393 S6 — the run body after `prepared` exists: the seat lanes R1–R3 (design/393 S5) — the identity wiring, the
+     * telemetry and budget seats, and the attachment seats, whose continuation carries the rest. Entered by the notification
+     * lane in its last continuation, with what it prepared and bound. Not `async`: it hands back the attachment lane's own
+     * promise, so the driver adds no frame — and no microtask — of its own between the lanes and `runLocked`'s settlement.
+     */
+    private runSeatLanes;
+    /**
+     * design/393 S6 — the run body after the seat lanes' async rung: the seat lanes R4–R12 (design/393 S5), the two assemblies
+     * the driver keeps (the harness handlers, the turn boundary) and the leg lanes. Entered by the attachment-seats lane in
+     * its last continuation, with what the notification lane prepared and what the identity / budget lanes handed back.
+     * Not `async` for the same reason as `runSeatLanes`: the leg lane's promise IS this method's.
+     */
+    private runAssembliesAndLegs;
     /**
      * design/100 §E12 — the post-completion prompt-suggestion pass. Never throws (failures route to
      * `onError(phase:"suggestions")` and resolve to `[]`), so it is fire-and-forget safe and `suggestions()`