@sema-agent/core 7.11.0 → 7.11.2

package/dist/core/runner/run-reasoning-seat.js

@@ -0,0 +1,48 @@
+import { resolveReasoning } from "../../brain/reasoning.js";
+import { emitTrace } from "../trace.js";
+export function runReasoningSeat(input) {
+    const { prepared, rs, taskIdRef, reasoningResolution } = input;
+    reasoningResolution.current = prepared.thinking && prepared.thinking !== "off" ? resolveReasoning(prepared.thinking, prepared.model) : undefined;
+    const publishReasoningResolution = (r) => {
+        reasoningResolution.current = r;
+        if (taskIdRef)
+            taskIdRef.effectiveReasoning = r;
+        emitTrace(rs.telemetry.tracer, () => ({
+            kind: "reasoning.resolved",
+            version: 1,
+            taskId: rs.telemetry.taskId,
+            model: prepared.model.id,
+            requested: r.requested,
+            effective: r.effective,
+            graded: r.graded,
+            clamped: r.clamped,
+            format: r.format,
+            endpoint: r.endpoint,
+            ...(r.dropped === true ? { dropped: true } : {}),
+            ts: Date.now(),
+        }));
+    };
+    if (reasoningResolution.current !== undefined)
+        publishReasoningResolution(reasoningResolution.current);
+    let reasoningFactsConsumed = false;
+    const observeReasoningWireFacts = (facts) => {
+        if (reasoningFactsConsumed)
+            return;
+        reasoningFactsConsumed = true;
+        if (prepared.thinking === undefined || prepared.thinking === "off")
+            return;
+        const next = resolveReasoning(prepared.thinking, prepared.model, facts);
+        const current = reasoningResolution.current;
+        if (current !== undefined &&
+            current.effective === next.effective &&
+            current.graded === next.graded &&
+            current.clamped === next.clamped &&
+            current.format === next.format &&
+            current.endpoint === next.endpoint &&
+            current.dropped === next.dropped) {
+            return;
+        }
+        publishReasoningResolution(next);
+    };
+    return { observeReasoningWireFacts };
+}

package/dist/core/runner/run-recovery-lanes.d.ts

@@ -0,0 +1,54 @@
+import type { Model } from "../../internal/llm.js";
+import { type MaybeCompactOptions } from "../auto-compaction.js";
+import type { HookInvocationIdentity } from "../hooks.js";
+import type { PushQueue } from "../push-queue.js";
+import type { Brain, TaskEvent, TaskSpec } from "../types.js";
+import type { Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
+export interface RunRecoveryLanesInput {
+    /** borrowed-readonly — the task spec: the compaction settings / instructions and the key-and-headers seat. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the leg's prepared seat: the loop recovery chain is installed on its harness, the arm-B seat
+     *  on `microCompact.inTurnCompactionRef`, the MC-R clears on `microCompact.ledger`; the abort signal, the pause
+     *  holder, the session, the compaction model and the cache-break detector are read. */
+    prepared: Prepared;
+    /** borrowed-mutable — the run's event queue: the `compacted` and `compaction_outcome` frames of both arms. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-mutable — the run's mutable state: the anti-thrash floor (`counters.compactionFloor`) is raised and
+     *  consulted, the post-compact announce latch armed and the cadence windows rebased on `attach.attachState`. */
+    rs: RunState;
+    /** borrowed-readonly — the run's event-identity mint. */
+    ident: () => {
+        eventId: string;
+        parentToolCallId?: string;
+        sourceTaskId?: string;
+    };
+    /** borrowed-readonly — the ACCOUNTED compaction brain (the compaction-machinery lane's), handed to every pass. */
+    compactionBrain: Brain;
+    /** borrowed-mutable — the shared consecutive-failure breaker: read by the gates, zeroed on a landing (and on a
+     *  noop), bumped on a burned pass. */
+    compactionBreaker: {
+        failures: number;
+    };
+    /** borrowed-readonly — the window-safety option builder (the compaction-machinery lane's), per pass. */
+    windowSafetyOptions: (mainModel: Model) => Pick<MaybeCompactOptions, "fallbackBudget" | "onWindowSafety">;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError`). */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the Runner's three compaction methods as delegates: the Seam C reuse options, the hook
+     *  option wrapper and the reuse counter. The method bodies stay the Runner's; the pass calls them as the run body did. */
+    compactionSeats: {
+        seamCCompactionOptions: (prepared: Prepared) => Pick<MaybeCompactOptions, "summaryProvider" | "onCompaction" | "maxConsecutiveProviderReuse" | "consecutiveProviderReuse"> | undefined;
+        compactionHookOptions: (spec: TaskSpec, sessionId: string, trigger: "auto" | "manual" | "forced", identity?: HookInvocationIdentity, seatBound?: {
+            timeoutMs: number;
+            signal?: AbortSignal;
+        }) => Pick<MaybeCompactOptions, "trigger" | "preCompact" | "postCompact">;
+        recordCompactionReuse: (prepared: Prepared, comp: {
+            compacted: boolean;
+            reused?: boolean;
+        }) => void;
+    };
+}
+/** Nothing comes back: the lane's products are INSTALLED on the seats it borrowed — the harness's loop recovery
+ *  chain and the microCompact arm-B seat — and the shared pass is read by those two installations alone. */
+export interface RunRecoveryLanesResult {
+}
+export declare function runRecoveryLanes(input: RunRecoveryLanesInput): RunRecoveryLanesResult;

package/dist/core/runner/run-recovery-lanes.js

@@ -0,0 +1,180 @@
+import { DEFAULT_COMPACTION_SETTINGS } from "../../internal/harness.js";
+import { planRejectionClears } from "../context-edit.js";
+import { DEFAULT_COMPACTION_INSTRUCTIONS, maybeCompact } from "../auto-compaction.js";
+import { emitTrace } from "../trace.js";
+import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
+import { rebaseCadenceWindows } from "./turn-attachments.js";
+import { buildWorkingFileAttachments, centerAdoptionOption, contextInstructionFilesOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
+import { gitRestateOption } from "./git-leg-delivery.js";
+import { COMPACTION_FREED_EPSILON, COMPACTION_REGROWTH_FACTOR, MAX_CONSECUTIVE_COMPACTION_FAILURES } from "./compaction-knobs.js";
+export function runRecoveryLanes(input) {
+    const { spec, prepared, queue, rs, ident, compactionBrain, compactionBreaker, windowSafetyOptions, runner, compactionSeats } = input;
+    const runForcedCompactionPass = async (lane, turnSignal) => {
+        if (!(spec.compaction?.enabled ?? true))
+            return false;
+        if (compactionBreaker.failures >= MAX_CONSECUTIVE_COMPACTION_FAILURES)
+            return false;
+        const passSignal = turnSignal !== undefined ? AbortSignal.any([prepared.abortController.signal, turnSignal]) : prepared.abortController.signal;
+        try {
+            const comp = await maybeCompact({
+                session: prepared.session,
+                epochDeclaredSections: prepared.epochDeclaredSections,
+                ...centerAdoptionOption(prepared),
+                model: prepared.harness.getModel(),
+                compactionModel: prepared.compModel,
+                ...forkContextOption(prepared, true),
+                brain: compactionBrain,
+                getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
+                thinking: prepared.thinking,
+                settings: { ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction },
+                customInstructions: spec.compaction?.instructions ?? DEFAULT_COMPACTION_INSTRUCTIONS,
+                signal: passSignal,
+                minTokens: 0,
+                force: true,
+                overheadTokens: prepared.promptOverheadTokens,
+                ...(prepared.activeTools.size > 0 ? { activeTools: [...prepared.activeTools] } : {}),
+                onInputTruncated: emitInputTruncated(rs.telemetry.tracer, rs.telemetry.taskId),
+                workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
+                ...contextInstructionFilesOption(prepared),
+                ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
+                ...compactionSeats.seamCCompactionOptions(prepared),
+                ...gitRestateOption(prepared),
+                ...windowSafetyOptions(prepared.harness.getModel()),
+                ...compactionSeats.compactionHookOptions(spec, prepared.sessionId, "forced", prepared.hookIdentity, { timeoutMs: prepared.hookTimeoutMs, signal: passSignal }),
+            });
+            if (comp.compacted) {
+                compactionBreaker.failures = 0;
+                compactionSeats.recordCompactionReuse(prepared, comp);
+                if ((comp.freedTokens ?? 0) >= COMPACTION_FREED_EPSILON) {
+                    const postSize = comp.postTriggerTokens ?? Math.max(0, (comp.triggerTokens ?? comp.tokensBefore ?? 0) - (comp.freedTokens ?? 0));
+                    rs.counters.compactionFloor = Math.ceil(postSize * COMPACTION_REGROWTH_FACTOR);
+                }
+                queue.push({
+                    type: "compacted",
+                    trigger: "forced",
+                    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 (rs.attach.attachState !== undefined) {
+                    rs.attach.attachState.postCompactPending = true;
+                    rebaseCadenceWindows(rs.attach.attachState, rs.counters.cadenceTurns);
+                }
+            }
+            else {
+                if (comp.noop) {
+                    compactionBreaker.failures = 0;
+                }
+                else {
+                    compactionBreaker.failures += 1;
+                }
+                const declineReason = lane === "rejection" ? "prompt-too-long recovery pass did not land" : "guard-chain forced compaction pass did not land";
+                if (!comp.noop) {
+                    runner.deps.onError?.(new Error(declineReason), { phase: "compaction", sessionId: prepared.sessionId });
+                }
+                queue.push({
+                    type: "compaction_outcome",
+                    outcome: comp.noop ? "noop" : "failed",
+                    trigger: "forced",
+                    reason: declineReason,
+                    ...ident(),
+                });
+            }
+            return comp.compacted === true;
+        }
+        catch (err) {
+            if (turnSignal?.aborted === true && !prepared.abortController.signal.aborted) {
+                const interruptReason = lane === "rejection"
+                    ? "prompt-too-long recovery pass cut short by a turn interrupt"
+                    : "guard-chain forced compaction cut short by a turn interrupt";
+                queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "forced", reason: interruptReason, ...ident() });
+                return false;
+            }
+            compactionBreaker.failures += 1;
+            runner.deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "compaction", sessionId: prepared.sessionId });
+            const msg = String(err instanceof Error ? err.message : err);
+            queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "forced", reason: msg.length > 512 ? `${msg.slice(0, 512)}…` : msg, ...ident() });
+            return false;
+        }
+    };
+    prepared.harness.setLoopRecovery({
+        truncatedOutput: {},
+        malformedToolUse: {},
+        thinkingOnly: {},
+        degenerateOutput: { detect: (m) => isDegenerateCutMessage(m) },
+        promptTooLong: {
+            recover: async (attempt, turnSignal) => {
+                if (prepared.abortController.signal.aborted || prepared.pausedRef.current !== undefined)
+                    return false;
+                if (turnSignal?.aborted === true)
+                    return false;
+                if (prepared.microCompact.clearOnRejection && attempt === 1) {
+                    const proj = prepared.microCompact.projectionRef.current;
+                    const compactionAvailable = (spec.compaction?.enabled ?? true) && compactionBreaker.failures < MAX_CONSECUTIVE_COMPACTION_FAILURES;
+                    const declineArm = compactionAvailable ? "forced_compaction" : "none";
+                    const plan = proj === undefined
+                        ? { declined: "no_candidates" }
+                        : planRejectionClears(proj.messages, {
+                            keyOf: proj.keyOf,
+                            ...(prepared.microCompact.offloadPersist ? { offload: { persist: prepared.microCompact.offloadPersist } } : {}),
+                        });
+                    if ("declined" in plan) {
+                        emitTrace(rs.telemetry.tracer, () => ({
+                            kind: "context.mc_null",
+                            version: 1,
+                            taskId: rs.telemetry.taskId,
+                            reason: plan.declined,
+                            nextArm: declineArm,
+                            ts: Date.now(),
+                        }));
+                    }
+                    else {
+                        for (const e of plan.cleared) {
+                            prepared.microCompact.ledger.entries.set(e.key, { marker: e.marker, groupCount: e.groupCount, fp: e.fp });
+                        }
+                        emitTrace(rs.telemetry.tracer, () => ({
+                            kind: "context.mc_clear",
+                            version: 1,
+                            taskId: rs.telemetry.taskId,
+                            clearedCount: plan.cleared.length,
+                            tokensSavedEstimate: plan.tokensSavedEstimate,
+                            trigger: "refusal",
+                            ts: Date.now(),
+                        }));
+                        return true;
+                    }
+                }
+                return runForcedCompactionPass("rejection", turnSignal);
+            },
+        },
+    });
+    prepared.microCompact.inTurnCompactionRef.current = async (turnSignal, anchoredEstimate) => {
+        if (prepared.abortController.signal.aborted || prepared.pausedRef.current !== undefined)
+            return false;
+        if (turnSignal?.aborted === true)
+            return false;
+        if (anchoredEstimate !== undefined && rs.counters.compactionFloor > 0 && anchoredEstimate < rs.counters.compactionFloor) {
+            const floor = rs.counters.compactionFloor;
+            emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.suppressed", version: 1, taskId: rs.telemetry.taskId, estTokens: anchoredEstimate, floor, ts: Date.now() }));
+            queue.push({ type: "compaction_outcome", outcome: "suppressed", trigger: "forced", ...ident() });
+            return false;
+        }
+        return runForcedCompactionPass("guard", turnSignal);
+    };
+    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;