@sema-agent/core 7.11.1 → 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-stop-and-final-verify.d.ts

@@ -0,0 +1,32 @@
+import type { PushQueue } from "../push-queue.js";
+import type { TaskEvent, TaskSpec } from "../types.js";
+import type { Stats } from "./assemble-result.js";
+import type { Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
+export interface RunStopAndFinalVerifyInput {
+    /** borrowed-readonly — the task spec: the hooks slot and the `finalVerification` opt-in. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the leg's prepared seat: the stop gate is installed on its harness; the abort signal, the
+     *  pause and halt holders, the output seat, the session, the hook bound and identity are read inside the gate. */
+    prepared: Prepared;
+    /** borrowed-mutable — the run's event queue: the injection echo frames. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-mutable — the run's mutable state: the injection counter (`counters.finalVerifyInjections`) is bumped;
+     *  the grounding latches, the write latch and the turn cap are read. */
+    rs: RunState;
+    /** borrowed-readonly — the run's usage counters, read by the headroom guards. */
+    stats: Stats;
+    /** borrowed-readonly — the run's event-identity mint (the echo frames). */
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    /** borrowed-readonly — the monotonic walltime deadline (the clock lane's), read by the budget fill. */
+    walltimeMonotonicDeadline: number | undefined;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`hooks` at resolution, `onError` in the gate). */
+    runner: RunnerDepsSeat;
+}
+/** Nothing comes back: the gate is INSTALLED on the borrowed harness, and the seat's closures are read by it alone. */
+export interface RunStopAndFinalVerifyResult {
+}
+export declare function runStopAndFinalVerify(input: RunStopAndFinalVerifyInput): RunStopAndFinalVerifyResult;

package/dist/core/runner/run-stop-and-final-verify.js

@@ -0,0 +1,159 @@
+import { openSystemReminder } from "../reminder-mint.js";
+import { formatHookFeedback, hookSeatExpiredError, runHookSeat } from "../hooks.js";
+const STOP_HOOK_BLOCK_CAP = 8;
+export function runStopAndFinalVerify(input) {
+    const { spec, prepared, queue, rs, stats, ident, walltimeMonotonicDeadline, runner } = input;
+    const stopHook = (spec.hooks ?? runner.deps.hooks)?.stop;
+    const finalVerificationOn = spec.finalVerification === true;
+    const finalVerifyBudgetFill = () => {
+        let worst = 0;
+        if (rs.budget.maxTokensWindow !== undefined && rs.budget.maxTokensWindow > 0)
+            worst = Math.max(worst, stats.tokens / rs.budget.maxTokensWindow);
+        if (rs.budget.maxCostMicroUsd !== undefined && rs.budget.maxCostMicroUsd > 0)
+            worst = Math.max(worst, stats.costMicroUsd / rs.budget.maxCostMicroUsd);
+        if (walltimeMonotonicDeadline !== undefined && prepared.suspendForResource === undefined) {
+            const windowMs = walltimeMonotonicDeadline - rs.telemetry.taskStartMonotonic;
+            if (windowMs > 0)
+                worst = Math.max(worst, (performance.now() - rs.telemetry.taskStartMonotonic) / windowMs);
+        }
+        return worst;
+    };
+    const emitFinalVerifyEcho = (body) => {
+        queue.push({ type: "steering_injected", source: "final_verification", preview: body.slice(0, 220), ...ident() });
+    };
+    if (stopHook || finalVerificationOn) {
+        let consecutiveBlocks = 0;
+        prepared.harness.setStopGate(async () => {
+            if (prepared.abortController.signal.aborted || prepared.pausedRef.current !== undefined || prepared.batchHaltRef.current !== undefined)
+                return [];
+            if (finalVerificationOn &&
+                (rs.counters.finalVerifyInjections === 0 || (rs.counters.finalVerifyInjections === 1 && rs.counters.groundingSignalPreR9 && !rs.counters.groundingSignalPostR9)) &&
+                rs.counters.wroteThisRun &&
+                prepared.outputRef.set !== true &&
+                !(rs.limits.effectiveMaxTurns !== undefined && rs.limits.effectiveMaxTurns > 0 && stats.turns >= rs.limits.effectiveMaxTurns - 1) &&
+                finalVerifyBudgetFill() < 0.9) {
+                rs.counters.finalVerifyInjections += 1;
+                if (rs.counters.finalVerifyInjections === 2) {
+                    const reentryBody = openSystemReminder(prepared.reminderMark) +
+                        "[final verification] Your tool calls in this run worked with raw bytes, structural parsing, " +
+                        "or checksum/digest computation — the deliverable very likely embeds verifiable structure (structural fields, an " +
+                        "embedded checksum-family value, reference data it must match, or a replayable deterministic path). You MUST " +
+                        "execute the grounding check that structure supports — recompute the embedded value and compare it against the " +
+                        "declared one, re-parse the structure from the raw bytes and reconcile it with your output, compare against the " +
+                        "reference data, or replay the deterministic path — and REPORT the check's concrete result before finishing. " +
+                        "A closing statement without a reported check result is not verification. If you already ran such a check, state " +
+                        "its concrete result now; if the check mismatches, fix the deliverable first. This is the final reminder from " +
+                        "this verification gate — it will not intervene again.</system-reminder>";
+                    emitFinalVerifyEcho(reentryBody);
+                    return [
+                        {
+                            role: "user",
+                            engineMinted: true,
+                            content: reentryBody,
+                            timestamp: Date.now(),
+                        },
+                    ];
+                }
+                const nudgeBody = openSystemReminder(prepared.reminderMark) +
+                    "[final verification] Before finishing: re-verify the FINAL deliverable through its REAL entry point, " +
+                    "exactly as the acceptance criteria would exercise it — execute the binary/function/endpoint directly and read the ACTUAL " +
+                    "output and exit code. Do NOT rely on earlier self-tests, shell redirections, or assumptions (a program that prints to " +
+                    "stdout is not a program that writes the required file). If anything mismatches the task's requirements, fix it before " +
+                    "finishing. " +
+                    "Treat verification writes as state-harmless: when the deliverable itself is a persisted final " +
+                    "state (for example a committed or pushed file, a deployed artifact, or a required output file), " +
+                    "do not change that state merely to test it. This constrains HOW you verify — it is never a " +
+                    "license to skip the real acceptance path or to check a substitute of your own making: expected " +
+                    "values must come from the task's requirements, never from content you generated. If the real " +
+                    "acceptance path requires a write, use disposable inputs or an isolated target, end in the exact " +
+                    "required final state, and verify that final state before finishing. " +
+                    "If the work relied on a third-party API, library, or model, check the usage contract the object itself declares " +
+                    "(docstrings, metadata, configuration — e.g. prompt conventions shipped with a model) and confirm your calls follow " +
+                    "it rather than a default symmetric usage. Verify not only that the deliverable EXISTS but that the METHOD that " +
+                    "produced it matches the task's requirements. " +
+                    "Choose the verification SURFACE deliberately: check against the reference data, oracle, or evaluation tooling the " +
+                    "task itself provides — re-running your own implementation and getting the same answer is self-consistency, not " +
+                    "correctness — and cross-check through an independent second path where the task or environment offers one " +
+                    "(checksums, runtime artifacts). Verify the PERSISTED artifact — re-read what is actually on disk or committed, " +
+                    "not in-memory state — against every hard constraint from the original task text (numeric bounds, allowed-value " +
+                    "lists, naming semantics, required files), reconciling whole-set completeness: nothing missing, nothing duplicated. " +
+                    "If the deliverable embeds verifiable structure — structural fields, an embedded checksum-family value, " +
+                    "reference data it must match, or a replayable deterministic path — you MUST execute the grounding check " +
+                    "that structure supports and REPORT its concrete result in your closing summary: for such a deliverable, " +
+                    "no reported check result means the work is not finished. " +
+                    "If the task produced neither an executable deliverable nor any verifiable structure or acceptance " +
+                    "oracle to check against, briefly confirm completion and stop. " +
+                    "Residue YOUR OWN testing created (scratch files, running processes, generated outputs the task does not ask for) " +
+                    "is not protected state — if the task's required final state is a clean target, removing your own residue is part " +
+                    "of delivering it. " +
+                    "Verification must never LAUNDER uncertainty: if part of your conclusion was uncertain before this check, keep " +
+                    "reporting it as uncertain unless the check you actually ran resolved it — a re-stated conclusion is not new " +
+                    "evidence.</system-reminder>";
+                emitFinalVerifyEcho(nudgeBody);
+                return [
+                    {
+                        role: "user",
+                        engineMinted: true,
+                        content: nudgeBody,
+                        timestamp: Date.now(),
+                    },
+                ];
+            }
+            if (!stopHook)
+                return [];
+            let result;
+            try {
+                const stopSeat = await runHookSeat("stop", { timeoutMs: prepared.hookTimeoutMs, signal: prepared.abortController.signal, abortEnds: true }, (sig) => stopHook({
+                    stopHookActive: consecutiveBlocks > 0,
+                    consecutiveBlocks,
+                    getBranch: () => prepared.session.getBranch(),
+                    identity: prepared.hookIdentity,
+                    signal: sig,
+                }));
+                if (stopSeat.expired) {
+                    if (stopSeat.cause === "timeout") {
+                        runner.deps.onError?.(hookSeatExpiredError("stop", prepared.hookTimeoutMs, stopSeat.cause, "the run was allowed to END (the seat's own no-opinion answer); no pushback and no additional context were injected"), { phase: "hook", sessionId: prepared.sessionId });
+                    }
+                    consecutiveBlocks = 0;
+                    return [];
+                }
+                result = stopSeat.value;
+            }
+            catch (err) {
+                runner.deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "hook", sessionId: prepared.sessionId });
+                return [];
+            }
+            const messages = [];
+            if (result?.additionalContext) {
+                messages.push({
+                    role: "user",
+                    engineMinted: true,
+                    content: formatHookFeedback(`Stop hook additional context: ${result.additionalContext}`, prepared.reminderMark),
+                    timestamp: Date.now(),
+                });
+            }
+            if (messages.length === 0 && !result?.block) {
+                consecutiveBlocks = 0;
+                return messages;
+            }
+            consecutiveBlocks++;
+            const cap = STOP_HOOK_BLOCK_CAP;
+            if (consecutiveBlocks > cap) {
+                runner.deps.onError?.(new Error(`a Stop hook kept the turn from ending ${consecutiveBlocks} consecutive times — overriding and ending the run. ` +
+                    `Both a block and an additionalContext-only push-back count (CC 2.1.220). ` +
+                    `Check ctx.stopHookActive in the hook and return success while it's true.`), { phase: "hook", sessionId: prepared.sessionId });
+                return [];
+            }
+            if (result?.block) {
+                messages.push({
+                    role: "user",
+                    engineMinted: true,
+                    content: formatHookFeedback(`Stop hook stopped continuation: ${result.block}`, prepared.reminderMark),
+                    timestamp: Date.now(),
+                });
+            }
+            return messages;
+        });
+    }
+    return {};
+}

package/dist/core/runner/run-telemetry-and-budget-seats.d.ts

@@ -0,0 +1,38 @@
+import { type ModelPricing } from "../pricing.js";
+import type { SessionStore } from "../session.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Stats } from "./assemble-result.js";
+import type { Prepared, ResumeRun, RunnerDepsSeat, RunState, TaskIdRef } from "./contracts.js";
+export interface RunTelemetryAndBudgetSeatsInput {
+    /** borrowed-readonly — the task spec: limits, degrade, tracer, output retries, the resource-suspend totals. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the leg's prepared seat: `liveSpendRef.get` is installed, `humanReviewRef` and `planModeRef`
+     *  are written on a resume; the model, the ledger, the session id and the usage governance are read. */
+    prepared: Prepared;
+    /** borrowed-readonly — the resume plan when this leg resumes a checkpoint (the human-review latency, the plan re-arm). */
+    resume: ResumeRun | undefined;
+    /** borrowed-readonly — the run's usage counters (this leg's own spend), read by the live-spend and budget closures. */
+    stats: Stats;
+    /** borrowed-mutable — the stream layer's backstop carrier: the effective task id and session id are published here. */
+    taskIdRef: TaskIdRef | undefined;
+    /** borrowed-readonly — the invocation's frozen tracer (#499), absence included; undefined when the seat was omitted. */
+    entryTracer: {
+        tracer: TaskSpec["tracer"];
+    } | undefined;
+    /** borrowed-readonly — the model catalog generation this task resolved against (pinned before prepare for swapDeps). */
+    modelCatalog: RunnerDeps["models"];
+    /** borrowed-readonly — the run's canonical task id (`spec.taskId ?? sessionId`), shared with the identity mint. */
+    runSourceTaskId: string;
+    /** borrowed-mutable — the run's mutable state: this lane is the WRITER of the `telemetry`, `degrade`, `limits` and
+     *  `budget` groups' initial values and function members. */
+    rs: RunState;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`pricing`, `onError`, `tracer`). */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the Runner's session store: the run is recorded on it (`noteTaskRun`, best-effort, loud). */
+    sessions: SessionStore;
+}
+export interface RunTelemetryAndBudgetSeatsResult {
+    /** #462: the price-table door — a table adopted MID-RUN that cannot price marks the spend unpriced. */
+    noteUnevaluablePriceTable: (p: ModelPricing) => void;
+}
+export declare function runTelemetryAndBudgetSeats(input: RunTelemetryAndBudgetSeatsInput): RunTelemetryAndBudgetSeatsResult;