@sema-agent/core 7.6.3 → 7.7.0

package/CHANGELOG.md

@@ -1,22 +1,45 @@
 # Changelog
 
-## 7.6.3 — 2026-09-08
+## 7.7.0 — 2026-09-07
 
-Maintenance patch on the 7.6.x line: one correction to 7.6.2's forwarding drain.
+One version for the first refactor wave and its bug fixes (the 7.6.2 patch folded in: main already carries the store-contract change, so the fix ships with it). #618 / B-040: The classifier request shape changes on the wire; the explicit "off" tier changes on both brain lanes.
 
-### Fixed
-- **forwardSubagentEvents drain gate** — 7.6.2 gated the drain inside an `async` helper and awaited it unconditionally, so a run that did NOT opt in still yielded one extra microtask before its terminal push (the black-box round measured parent `done` at hop 356 vs 355 on 7.6.1). The gate is now a synchronous predicate at both terminal pushes and the helper is a plain Promise factory; the non-forwarding terminal depth is pinned (ratchet 58, the unconditional-await form reds it at 59). No change for opted-in runs.
+**BREAKING (store contract).** #602 — the durable half of a post-CAS veto. A person approved a parked call, the deployment's own re-check refused the approver's edit on the resumed leg, `tool_end.gate` said `denied/policy` beside the `human_allowed` settlement — and the row still said `resolvedOutcome.gateOutcome.disposition = allowed`, because the store contract had no verb for "how was the decided action finally disposed". A consumer rebuilding the run from the row after the stream broke read the pre-execution allow and nothing else.
+
+### BREAKING — `CheckpointStore` gains two REQUIRED members
+- `readonly execution: { readonly outcome: true }` — a declaration, read at the first read of the store seat (`resolveCheckpointStore`): a store without it is refused with `config.invalid_checkpoint_store` (the same door as the retired `null` spelling), naming the seat (`TaskSpec.checkpointStore` / `RunnerDeps.checkpointStore`) and the missing declaration. A store that satisfies the TypeScript type carries it; a JavaScript caller is told at prepare what the type would have told it.
+- `recordExecutionOutcome(token, scope, gate: GateOutcome): Promise<"recorded" | "already_recorded" | "not_resolved" | "absent">` — the CAS `status='resolved' AND execution_outcome IS NULL`; the same record again is idempotent (`already_recorded`, structural equality over the record's JSON); a DIFFERENT record throws `checkpoint.execution_outcome_conflict` (`ExecutionOutcomeConflictError`, carrying `recorded` + `attempted`); pending/expired rows answer `not_resolved`, missing and wrong-scope rows `absent`. Never touches `status` / `rev` / `resolvedOutcome` / `reopenReason`.
+- `reopen` gains the predicate `AND execution_outcome IS NULL` — a row whose decided action is already disposed is settled, never reopenable (the reopen answers `false`; the engine's compensation reads it as `checkpoint.reopen_failed`, definitive). Behaviour narrowing: an `env_failed` retry is offered only for a row whose action never reached its disposition.
+- Deployment stores (server's two) need two columns, `execution_outcome` (json) + `execution_at_ms`, the record CAS, and the reopen predicate; the store-contract kit (`checkpointStoreContract`) carries the six cases. The in-tree file store writes a new ledger event kind (`execution`); a binary older than 7.7.0 refuses to replay a directory whose live ledger carries one (loud) — but once compaction has folded the event into a snapshot row, that older binary reads the row with a field it does not know and its `reopen` ignores the record (the same rollback shape the parked-steer queue event disclosed in its release; a rollback across a recorded row is not supported).
 
-## 7.6.2 — 2026-09-08
+### Added
+- `CheckpointRow.executionOutcome?: GateOutcome` + `executionAtMs?: number` (additive row keys, present together) — the record the resumed call's `tool_end.gate` carried, written by the engine on EVERY resolution (an executed allow too); absence has one meaning: unknown, never "allowed". `resolvedOutcome.gateOutcome` stays the immutable record of the decision, so a vetoed row reads `allowed` there and `denied/policy` here.
+- `executionVerdict(cp)` → `{ kind: "executed", gate } | { kind: "unknown" }` — the one read face of the column (`type ExecutionVerdict`).
+- `EXECUTION_OUTCOME_RECORD_WORDS` / `type ExecutionOutcomeRecordWord` / `isExecutionOutcomeRecordWord`, the disposition table `EXECUTION_RECORD_LEAVES_ROW_UNRECORDED` (+ fence `ExecutionRecordTableCoversEveryWord`; registered in `docs/CLOSED-SETS.md`), `ExecutionOutcomeConflictError`, and the shared backend halves `executionRecordDisposition` / `checkpointExecutionRecorded` / `sameExecutionRecord` (every in-tree backend routes through them — `gate:single-mint` rows); `checkpointStoreExecutionUndeclared` (the refusal's one mint).
+- `engine_notice` code `checkpoint.execution_outcome_unrecorded` (audience operator) — the resolver disposed the decided action and the store answered `not_resolved` / `absent`: the execution result stands as delivered, the row reads unknown, and this names it; `detail: { sessionId, runId, scope, checkpointId?, word }`. A conflict is not a notice: the throw propagates and the resumed leg fails with `checkpoint.execution_outcome_conflict` (the action, if it ran, ran; the defect is reported, not hidden).
+- `@contract checkpoint.execution_outcome` (the row field's JSDoc is the one home).
+
+### Changed
+- The pending-call resolver (`resolvePendingCall`) files the frame's record on every arm through one `settleEnd` helper, between the `tool_end` frame and the transcript append; a policy_ask decide reaching the resolver without its settlement record is refused (`checkpoint.invalid_outcome`) rather than settled unrecorded. `ResumeRun.recordExecutionOutcome` is the bound verb (required seat). The notice half lives in `runner/execution-record.ts` (layer 1).
 
-Backport patch on the 7.6.x line (two field bugs the server 7.64.0 chain found; no store-contract change — that is 7.7.0).
+### Changed (refactor — byte-invariant on the runtime)
+- **design/393 S1** — six module-level helpers leave runtask.ts for layer-1 modules (initial-run-state / steer-admission / tool-end-body / decide-continuation / clock-and-limits / git-leg-delivery; runtask 11 963 → 11 059); dist runtask.js changes by import lines and moved bodies only, the await-boundary table is all-zero, the export snapshot is unchanged by this slice.
+
+### Pins
+- `test/backlog602-execution-outcome.test.ts` (17): store-level ③④⑤⑥ over both in-process backends + file-ledger replay; engine-level ① (person's edit vetoed post-CAS ⇒ frame and row both `denied/policy`, decision cell still `allowed`, `executionVerdict` executed, reopen refused), ② (executed allow recorded), a delivered refusal, the unrecorded notice, the conflict propagation, ⑦ (undeclared store refused on both seats with the declared control). Store-contract kit +6 cases (InMemory / File / Pg via pg-mem).
 
 ### Fixed
-- **R12 (`forwardSubagentEvents`)** — a run that opted into forwarding did not wait for the frames its BACKGROUND children had already handed to the forward channel before saying `done`; the gap is one microtask ladder deep and moved when #594 split the tool gate into three async stations (a child's gated call went from 24 to 27 microtask hops between `tool_start` and `tool_end`), so a consumer that read the parent to `done` and then inspected the sink lost the child's `tool_end`. The parent now takes one macrotask turn right before its terminal push, only on opted-in runs, on both the success and the failure path. Pin: `test/forward-subagent-events-drain.test.ts`.
-- **R13 (checkpoint)** — the pre-CAS refusal of a pending approval row that carries no `origin` word (a row minted before the ask's origin was persisted on the park) now carries `reason: "origin_missing"` like its three `unsupported_version` siblings, so a host upgrading with parked cards can classify the orphaned row. Pin: `test/backlog-r13-origin-missing-reason.test.ts`.
+- **#618 (P1, B-040)** — the auto-mode classifier's request said nothing about thinking and carried no output cap, so a default-on Messages-compatible endpoint (deepseek's anthropic port in the field) spent the whole cap on reasoning and answered with zero text: every classification was a contract failure, three of them opened the session breaker, and every later ask in the session became a card for a person (3–7 s per classification on the way). The classify call now carries `reasoning:"off"` and `maxTokens: AUTO_MODE_CLASSIFIER_MAX_TOKENS` (256, derived from the engine's own `<block>…` output contract — the longest legal block verdict is ≈150 tokens; not upstream's 64 nor its 4096 critique cap), on every model whose wire can SAY off (`thinkingOffExpressible`); a model that thinks regardless (anthropic adaptive form; stock openai / Responses with no declared off spelling) keeps its own output budget — a cap sized for the answer alone would only cut its thinking. Explicit "off" is now spelled on every wire that has an off form, one rule with no absence-means-off exception: anthropic budget form `thinking:{type:"disabled"}` (adaptive form: field omitted — those models reject `disabled`); openai lane — deepseek `thinking:{type:"disabled"}`, qwen/zai `enable_thinking:false`, qwen-chat-template `chat_template_kwargs.enable_thinking:false`, openrouter/together `reasoning:{enabled:false}`; stock openai completions and the Responses lane the DEPLOYMENT-declared off spelling (`thinkingLevelMap.off`, e.g. a provider's `"none"` tier — `declaredOffSpelling`), else absence (an enabled tier is never inferred as off: it turns reasoning on). "Unset" still writes nothing on every format. A new trace frame `auto_mode.classified {toolCallId, model, ms, verdict, cause?}` reads one line per decision (breaker-open short-circuits included); `AutoModeDeciderOptions.onClassified` is the hook it rides. Repro `scripts/repro/B-040.mjs` (RED on 7.6.1, GREEN here) runs under `gate:repro`.
 
-### Changed
-- `CheckpointError.detail.reason` closed set gains `"origin_missing"` (terminal for the row's bytes; the host decides the orphaned card).
+### Changed (wire — consumers named, #618)
+- Classifier request body on the wire: `thinking:{type:"disabled"}` + `max_tokens: 256` (anthropic budget form); `reasoning:"off"` reaches every brain lane. A deployment that reads the classifier's request through a proxy sees the two new keys.
+- Explicit `"off"` on the main model's finalize turn (and any caller passing `reasoning:"off"`): anthropic budget models now receive `thinking:{type:"disabled"}` (was: no key); deepseek-format models receive `thinking:{type:"disabled"}` (was: no key); openrouter/together-format models receive `reasoning:{enabled:false}` (was: no key); stock-openai-format and Responses-lane models with a declared `thinkingLevelMap.off` receive that spelling as `reasoning_effort` / `reasoning.effort` (was: no key; without the mapping still no key). Unset requests are byte-identical to 7.6.1.
+
+### Added (#618)
+- `AUTO_MODE_CLASSIFIER_MAX_TOKENS`, `thinkingOffExpressible(model)`, `declaredOffSpelling(model)`, `type OffCapabilityModel`, `type AutoModeClassified`, `AutoModeDeciderOptions.onClassified`, trace frame kind `auto_mode.classified`.
+
+### Known limit (ticketed, not fixed here)
+- The off-capability table reads the WIRE's ability to say off; a thinking-only model served through a format that has a disable key (a Qwen thinking-only build, a mandatory-reasoning model behind openrouter/together) ignores that key, so its classifier still gets the 256-token cap and fails the verdict contract. The per-model fact the compat declaration would need (`mandatoryReasoning` / a classifier-specific budget knob) is a follow-up.
 
 ## 7.6.1 — 2026-09-07
 

package/dist/agents/peer-admission.d.ts

@@ -78,7 +78,7 @@ export interface PeerIdentity {
     ownTokens: string[];
 }
 /**
- * design/176 §4.1 — the LATE-BOUND self-identity carrier ({@link import("../core/runner/prepare-task.js").RunInternals}`.peerSelfRef`).
+ * design/176 §4.1 — the LATE-BOUND self-identity carrier ({@link import("../core/runner/contracts.js").RunInternals}`.peerSelfRef`).
  * A ref (same family as `ownOrgAdmissionRef`): revival replays a spread COPY of spawn-time
  * internals, so a plain field would freeze at its spawn value; and a root run's session axis only
  * exists once `prepareTask` acquires the session — no single assembly point can synthesize the full

package/dist/brain/anthropic.js

@@ -276,9 +276,11 @@ export function createAnthropicBrain(config = {}) {
                     body.temperature = options.temperature;
                 }
                 let builtReasoningFacts;
+                let thinkingOn = false;
                 if (reasoningRequestCarried(model, options?.reasoning)) {
                     if (anthCompat.thinkingMode === "adaptive") {
                         body.thinking = { type: "adaptive" };
+                        thinkingOn = true;
                     }
                     else {
                         const hardCap = overrides?.maxOutputTokens !== undefined || options?.maxTokens !== undefined;
@@ -292,11 +294,15 @@ export function createAnthropicBrain(config = {}) {
                             const { max, budget } = thinkingBudget(body.max_tokens, share, config.thinkingBudgetTokens, hardCap);
                             body.max_tokens = max;
                             body.thinking = { type: "enabled", budget_tokens: budget };
+                            thinkingOn = true;
                         }
                     }
-                    if (body.thinking !== undefined)
+                    if (thinkingOn)
                         delete body.temperature;
                 }
+                else if (model.reasoning && options?.reasoning === "off" && anthCompat.thinkingMode !== "adaptive") {
+                    body.thinking = { type: "disabled" };
+                }
                 const betas = [];
                 let sendEffortBeta = false;
                 const declaredEffort = declaredEffortLevels(anthCompat.effortLevels);
@@ -308,7 +314,7 @@ export function createAnthropicBrain(config = {}) {
                 }
                 if (sendEffortBeta)
                     betas.push("effort-2025-11-24");
-                if (anthCompat.contextManagement && body.thinking !== undefined) {
+                if (anthCompat.contextManagement && thinkingOn) {
                     body.context_management = { edits: [{ type: "clear_thinking_20251015", keep: "all" }] };
                     betas.push("context-management-2025-06-27");
                 }

package/dist/brain/open-responses.js

@@ -7,7 +7,7 @@ import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
 import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
-import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
+import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 const DEGENERATE_POLL_CHARS = 64;
 const MALFORMED_SAMPLE_CHARS = 160;
@@ -152,11 +152,13 @@ function toResponsesTools(ctx) {
     }));
 }
 function resolveWireEffort(model, reasoning) {
-    if (!reasoningRequestCarried(model, reasoning))
-        return undefined;
+    if (model.reasoning && reasoning === "off")
+        return declaredOffSpelling(model);
     const compat = responsesCompat(model);
     if (compat.supportsReasoningEffort === false)
         return undefined;
+    if (!reasoningRequestCarried(model, reasoning))
+        return undefined;
     return mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
 }
 function computeUsage(model, raw) {

package/dist/brain/openai.js

@@ -8,7 +8,7 @@ import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNot
 import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
 import { BrainError } from "./errors.js";
 import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
-import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
+import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function closeToolCallAccum(acc) {
     if (acc.closedTc)
@@ -78,13 +78,36 @@ function thinkingCompat(model) {
 }
 function applyThinking(body, model, reasoning) {
     if (model.reasoning && reasoning === "off") {
-        const offFormat = thinkingCompat(model).thinkingFormat ?? "openai";
-        if (offFormat === "qwen" || offFormat === "zai") {
-            body.enable_thinking = false;
-        }
-        else if (offFormat === "qwen-chat-template") {
-            const k = (typeof body.chat_template_kwargs === "object" && body.chat_template_kwargs) || {};
-            body.chat_template_kwargs = { ...k, enable_thinking: false };
+        const offCompat = thinkingCompat(model);
+        const offFormat = offCompat.thinkingFormat ?? "openai";
+        switch (offFormat) {
+            case "qwen":
+            case "zai":
+                body.enable_thinking = false;
+                break;
+            case "qwen-chat-template": {
+                const k = (typeof body.chat_template_kwargs === "object" && body.chat_template_kwargs) || {};
+                body.chat_template_kwargs = { ...k, enable_thinking: false };
+                break;
+            }
+            case "deepseek":
+                body.thinking = { type: "disabled" };
+                break;
+            case "openrouter":
+            case "together":
+                body.reasoning = { enabled: false };
+                break;
+            case "openai": {
+                const offSpelling = declaredOffSpelling(model);
+                if (offSpelling !== undefined)
+                    body.reasoning_effort = offSpelling;
+                break;
+            }
+            default: {
+                const _exhaustive = offFormat;
+                void _exhaustive;
+                break;
+            }
         }
         return;
     }

package/dist/brain/reasoning.d.ts

@@ -104,6 +104,38 @@ export declare const MIN_THINKING_TOKENS = 1024;
  * host the budget instead (`hardCap === false`).
  */
 export declare function budgetCapSkipsThinking(outputCapTokens: number, hardCap: boolean): boolean;
+/** The model slice the off-capability reads: the API family, the reasoning bit, the compat declaration and the levelmap. */
+export interface OffCapabilityModel {
+    api?: string;
+    reasoning?: boolean;
+    compat?: unknown;
+    thinkingLevelMap?: Readonly<Partial<Record<ThinkingLevel, string | null>>>;
+}
+/**
+ * The DEPLOYMENT-declared spelling of the explicit "off" tier on an effort-only wire (stock openai
+ * completions, the Responses lane): `thinkingLevelMap.off` as a non-empty string (a provider's own
+ * "none" tier), on an endpoint that takes an effort value at all (`supportsReasoningEffort` not
+ * false) — else `undefined`: there is nothing to send. The effort formats have no disable key, and an
+ * effort VALUE is never off (it enables reasoning at that tier), so off on those wires is spelled only
+ * when the deployment says how. The two appliers and {@link thinkingOffExpressible} read this ONE
+ * function, so what the wire carries and what the capability table claims cannot disagree.
+ */
+export declare function declaredOffSpelling(model: OffCapabilityModel): string | undefined;
+/**
+ * Whether this model's wire can SAY "off". A model that does not reason at all (`reasoning` falsy)
+ * never thinks, so off is trivially expressible. Otherwise, per wire: the anthropic budget form spells
+ * `{type:"disabled"}` (the ADAPTIVE form rejects it — those models think on every request); deepseek
+ * `{type:"disabled"}`, the binary enable keys at `false`, openrouter/together `reasoning:{enabled:false}`
+ * all say it; the effort-only wires (stock openai completions, the Responses lane) say it only through
+ * a deployment-declared off spelling ({@link declaredOffSpelling}).
+ *
+ * A caller that sizes an output cap for an ANSWER alone (the auto-mode classifier's block-verdict
+ * contract) applies the cap only when this is true: a model that will think regardless cannot have its
+ * cap derived from the answer's contract, and keeps its own budget. What this table cannot see is a
+ * model that IGNORES its wire's disable key (a thinking-only build served through a format that has
+ * one) — that is a per-model fact the compat declaration does not yet carry.
+ */
+export declare function thinkingOffExpressible(model: OffCapabilityModel): boolean;
 /**
  * OPTIONAL per-request facts for {@link resolveReasoning} — what the wire's budget arm knows at
  * request build that a per-leg eager resolution cannot: the resolved output cap and whether it is a

package/dist/brain/reasoning.js

@@ -23,6 +23,24 @@ export const MIN_THINKING_TOKENS = 1024;
 export function budgetCapSkipsThinking(outputCapTokens, hardCap) {
     return hardCap && outputCapTokens < MIN_THINKING_TOKENS * 2;
 }
+export function declaredOffSpelling(model) {
+    const compat = (model.compat ?? {});
+    if (compat.supportsReasoningEffort === false)
+        return undefined;
+    const mapped = model.thinkingLevelMap?.off;
+    return typeof mapped === "string" && mapped !== "" ? mapped : undefined;
+}
+export function thinkingOffExpressible(model) {
+    if (!model.reasoning)
+        return true;
+    const compat = (model.compat ?? {});
+    if (model.api === "anthropic-messages")
+        return compat.thinkingMode !== "adaptive";
+    if (model.api !== undefined && RESPONSES_APIS.has(model.api))
+        return declaredOffSpelling(model) !== undefined;
+    const format = compat.thinkingFormat ?? "openai";
+    return format === "openai" ? declaredOffSpelling(model) !== undefined : true;
+}
 export function declaredEffortLevels(v) {
     return Array.isArray(v) && v.length > 0 ? v : undefined;
 }

package/dist/core/auto-mode-defaults.d.ts

@@ -6,6 +6,22 @@ export declare const AUTO_MODE_DEFAULT_FAILURE_THRESHOLD = 3;
 export declare const AUTO_MODE_DEFAULT_WINDOW_MAX_ENTRIES = 40;
 /** Per-entry excerpt cap when `AutoModeWindowOptions.maxCharsPerEntry` is omitted. */
 export declare const AUTO_MODE_DEFAULT_WINDOW_MAX_CHARS = 2000;
+/**
+ * The classifier call's output cap (`maxTokens`), sized from the engine's OWN output contract rather
+ * than copied from upstream: the parser (`parseAutoModeResponse`) accepts exactly two shapes,
+ * `<block>no</block>` and `<block>yes</block><category>NAME</category><reason>[NAME] one short
+ * sentence</reason>`. The longest rule name in the shipped rule sets is 46 characters and the reason
+ * is one short sentence naming that rule (≈200 characters at the outside, more when several rules
+ * match and the others are named in the reason), so the longest LEGAL reply is ≈350 characters —
+ * ≈120 tokens at the conservative 3 chars/token that tag-heavy text tokenizes at, ≈150 with a
+ * second and third rule name in the reason. Doubled for margin: a truncated block verdict still
+ * parses as a block (the parser tolerates a missing tail), a truncated allow does not exist (it is
+ * seven tokens), and the cap's job is to make a model that ignores the "no preamble" instruction —
+ * or that reasons in-text — cost a bounded, quickly-detected contract failure instead of a slow one.
+ * Paired with `reasoning:"off"` at the call: the cap hosts the ANSWER, so it applies only where the
+ * wire can say off (`thinkingOffExpressible`); a model that thinks regardless keeps its own budget.
+ */
+export declare const AUTO_MODE_CLASSIFIER_MAX_TOKENS = 256;
 /** The sentinel a deployment puts INSIDE a paired rule list to splice the CC default rules back in at
  *  that position (CC `XYt = "$defaults"`). It lives here, beside the other defaults, because the #503
  *  recipe canonicalizer needs its VALUE and must not load the assembly face (and its SHA-locked assets)

package/dist/core/auto-mode-defaults.js

@@ -2,6 +2,7 @@ export const AUTO_MODE_DEFAULT_TIMEOUT_MS = 15_000;
 export const AUTO_MODE_DEFAULT_FAILURE_THRESHOLD = 3;
 export const AUTO_MODE_DEFAULT_WINDOW_MAX_ENTRIES = 40;
 export const AUTO_MODE_DEFAULT_WINDOW_MAX_CHARS = 2_000;
+export const AUTO_MODE_CLASSIFIER_MAX_TOKENS = 256;
 export const AUTO_MODE_DEFAULTS_SENTINEL = "$defaults";
 export const AUTO_MODE_DENIAL_LIMIT_DEFAULTS = Object.freeze({ maxConsecutive: 3, maxTotal: 20 });
 export const AUTO_MODE_DENIAL_AUTO_DENY_DEFAULT_MS = 120_000;

package/dist/core/auto-mode.d.ts

@@ -70,6 +70,25 @@ export interface AutoModeDeciderOptions {
         consecutiveFailures: number;
         lastCause: string;
     }) => void;
+    /**
+     * Fired once per `decide` call with the verdict the gate is about to act on and the wall time it
+     * waited (`ms`, integer ≥ 0; a timed-out round reads the deadline; a breaker-open short-circuit
+     * reads ~0 with `cause:"breaker_open"`). `cause` is present iff the verdict is `unavailable`. The
+     * engine's own wiring turns this into the `auto_mode.classified` trace frame; a hand-built decider
+     * need not implement it. Like the breaker alarm, a throwing hook never breaks the gate.
+     */
+    onClassified?: (info: AutoModeClassified) => void;
+}
+/** What {@link AutoModeDeciderOptions.onClassified} receives — one record per decision. */
+export interface AutoModeClassified {
+    /** The gated call the decision was about (`AutoModeClassifyInput.req.toolCallId`). */
+    toolCallId: string;
+    /** Wall-clock milliseconds between the decide call and its verdict. */
+    ms: number;
+    verdict: AutoModeVerdict["kind"];
+    cause?: Extract<AutoModeVerdict, {
+        kind: "unavailable";
+    }>["cause"];
 }
 export interface AutoModeDecider {
     /** Never rejects. Any internal failure surfaces as `unavailable`/`parse_error` (fail-closed). */

package/dist/core/auto-mode.js

@@ -32,67 +32,85 @@ export function createAutoModeDecider(opts) {
             }
         }
     };
-    return {
-        breakerOpen: () => open,
-        consecutiveFailures: () => consecutiveFailures,
-        async decide(input, signal) {
-            if (open)
-                return { kind: "unavailable", cause: "breaker_open" };
-            let timer;
-            const inner = new AbortController();
-            const onOuterAbort = () => inner.abort();
-            if (signal !== undefined) {
-                if (signal.aborted)
-                    inner.abort();
-                else
-                    signal.addEventListener("abort", onOuterAbort, { once: true });
-            }
+    const decide = async (input, signal) => {
+        const startedAt = performance.now();
+        const verdict = await decideUnreported(input, signal);
+        if (opts.onClassified !== undefined) {
             try {
-                const raw = await new Promise((resolve, reject) => {
-                    let settled = false;
-                    timer = setTimeout(() => {
-                        if (!settled) {
-                            settled = true;
-                            inner.abort();
-                            reject(new AutoModeTimeout());
-                        }
-                    }, timeoutMs);
-                    opts.classify(input, inner.signal).then((v) => {
-                        if (!settled) {
-                            settled = true;
-                            resolve(v);
-                        }
-                    }, (e) => {
-                        if (!settled) {
-                            settled = true;
-                            reject(e);
-                        }
-                    });
+                opts.onClassified({
+                    toolCallId: input.req.toolCallId,
+                    ms: Math.max(0, Math.round(performance.now() - startedAt)),
+                    verdict: verdict.kind,
+                    ...(verdict.kind === "unavailable" ? { cause: verdict.cause } : {}),
                 });
-                if (open)
-                    return { kind: "unavailable", cause: "breaker_open" };
-                const verdict = parseAutoModeResponse(raw);
-                if (verdict.kind === "parse_error")
-                    recordFailure("parse_error");
-                else
-                    consecutiveFailures = 0;
-                return verdict;
             }
-            catch (e) {
-                if (signal?.aborted)
-                    return { kind: "unavailable", cause: "error" };
-                const timedOut = e instanceof AutoModeTimeout;
-                recordFailure(timedOut ? "timeout" : "error");
-                return { kind: "unavailable", cause: timedOut ? "timeout" : "error" };
-            }
-            finally {
-                if (timer !== undefined)
-                    clearTimeout(timer);
-                if (signal !== undefined)
-                    signal.removeEventListener("abort", onOuterAbort);
+            catch {
             }
-        },
+        }
+        return verdict;
+    };
+    return {
+        breakerOpen: () => open,
+        consecutiveFailures: () => consecutiveFailures,
+        decide,
     };
+    async function decideUnreported(input, signal) {
+        if (open)
+            return { kind: "unavailable", cause: "breaker_open" };
+        let timer;
+        const inner = new AbortController();
+        const onOuterAbort = () => inner.abort();
+        if (signal !== undefined) {
+            if (signal.aborted)
+                inner.abort();
+            else
+                signal.addEventListener("abort", onOuterAbort, { once: true });
+        }
+        try {
+            const raw = await new Promise((resolve, reject) => {
+                let settled = false;
+                timer = setTimeout(() => {
+                    if (!settled) {
+                        settled = true;
+                        inner.abort();
+                        reject(new AutoModeTimeout());
+                    }
+                }, timeoutMs);
+                opts.classify(input, inner.signal).then((v) => {
+                    if (!settled) {
+                        settled = true;
+                        resolve(v);
+                    }
+                }, (e) => {
+                    if (!settled) {
+                        settled = true;
+                        reject(e);
+                    }
+                });
+            });
+            if (open)
+                return { kind: "unavailable", cause: "breaker_open" };
+            const verdict = parseAutoModeResponse(raw);
+            if (verdict.kind === "parse_error")
+                recordFailure("parse_error");
+            else
+                consecutiveFailures = 0;
+            return verdict;
+        }
+        catch (e) {
+            if (signal?.aborted)
+                return { kind: "unavailable", cause: "error" };
+            const timedOut = e instanceof AutoModeTimeout;
+            recordFailure(timedOut ? "timeout" : "error");
+            return { kind: "unavailable", cause: timedOut ? "timeout" : "error" };
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (signal !== undefined)
+                signal.removeEventListener("abort", onOuterAbort);
+        }
+    }
 }
 class AutoModeTimeout extends Error {
     constructor() {

package/dist/core/checkpoint-execution-record.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The execution-outcome record's vocabulary (layer 0, beside the checkpoint store it serves): the closed
+ * answer set of `CheckpointStore.recordExecutionOutcome`, its one disposition table, the conflict error,
+ * the shared write disposition and reopen predicate every backend routes through, the structural
+ * equality the idempotency arm uses, and the one read face of the column. The column itself
+ * (`CheckpointRow.executionOutcome` / `executionAtMs`) and the verb's contract are declared on the store
+ * (`checkpoint-store.ts`); this module names no store type — the row facts it reads are spelled
+ * structurally — so the store reaches DOWN for it and nothing here reaches back.
+ */
+import { type AssertAllKeysHandled } from "./ask-origin.js";
+import type { GateOutcome } from "./gate-outcome.js";
+/**
+ * The closed answer set of `CheckpointStore.recordExecutionOutcome` — what the store did with the
+ * execution record it was handed. One word per way the write can end; a caller keys on the word, never
+ * on an absence:
+ *  - `recorded` — the CAS won: the row was `resolved` with no record yet, and now carries this one.
+ *  - `already_recorded` — the row already carries a record EQUAL to the one supplied (a retry of the
+ *    same write; idempotent, nothing changed). A record that DIFFERS is not a word — it is the
+ *    {@link ExecutionOutcomeConflictError} throw.
+ *  - `not_resolved` — the row exists in this scope but is not `resolved` (still pending, or expired):
+ *    there is no decision an execution could be the outcome of, so nothing was written.
+ *  - `absent` — no row under this token in this scope (a missing row and a wrong-scope row alike — the
+ *    isolation rule every verb of the store keeps).
+ */
+export declare const EXECUTION_OUTCOME_RECORD_WORDS: readonly ["recorded", "already_recorded", "not_resolved", "absent"];
+export type ExecutionOutcomeRecordWord = (typeof EXECUTION_OUTCOME_RECORD_WORDS)[number];
+/** Membership test for {@link ExecutionOutcomeRecordWord} — a deployment store answers across a process
+ *  boundary, so the consumer validating its word must not hand-roll the set. */
+export declare function isExecutionOutcomeRecordWord(v: unknown): v is ExecutionOutcomeRecordWord;
+/**
+ * The one disposition table over {@link ExecutionOutcomeRecordWord}: does this answer mean the row now
+ * carries NO execution record — i.e. the leg's disposition of the decided action is not on file? The
+ * engine's belt reads it to decide whether to announce `checkpoint.execution_outcome_unrecorded` (the
+ * execution result itself is never changed by the answer: the record is an account of what ran, not a
+ * gate on it). A new word must take a row here (the fence below reds `tsc` otherwise).
+ */
+export declare const EXECUTION_RECORD_LEAVES_ROW_UNRECORDED: {
+    readonly recorded: false;
+    readonly already_recorded: false;
+    readonly not_resolved: true;
+    readonly absent: true;
+};
+export type ExecutionRecordTableCoversEveryWord = AssertAllKeysHandled<Exclude<ExecutionOutcomeRecordWord, keyof typeof EXECUTION_RECORD_LEAVES_ROW_UNRECORDED>>;
+/**
+ * The read face of `CheckpointRow.executionOutcome`: what a reader of a resolved row can say about how
+ * the decided action was disposed. `executed` carries the record the resumed leg filed; `unknown` is the
+ * ONE meaning of the column's absence (the leg has not reached its resolution yet, the row was consumed
+ * by a worker that could not record, or the store answered `not_resolved`/`absent` and the engine
+ * announced it). Never `allowed` by default — the pre-execution decision lives on `resolvedOutcome`.
+ */
+export type ExecutionVerdict = {
+    kind: "executed";
+    gate: GateOutcome;
+} | {
+    kind: "unknown";
+};
+/**
+ * `CheckpointStore.recordExecutionOutcome` was handed a record for a row that already carries a DIFFERENT
+ * one. The record is physically immutable (see `CheckpointRow.executionOutcome`), so this is never
+ * resolved by overwriting: two different accounts of one execution mean the engine ran, or believes it
+ * ran, the same decided action twice — an engine defect the belt must surface, not a store condition it
+ * may absorb. Carries both records so the operator can read what was on file and what tried to replace
+ * it. Code `checkpoint.execution_outcome_conflict`; a deployment store may throw any error carrying the
+ * same `code` — the code is the contract, this class is its in-tree form.
+ */
+export declare class ExecutionOutcomeConflictError extends Error {
+    readonly code: "checkpoint.execution_outcome_conflict";
+    /** The record on file — a COPY: a backend hands this constructor its live row value, and a caller that
+     *  catches the error must not be able to rewrite the row through it (the record is immutable by CAS,
+     *  not by convention). */
+    readonly recorded: GateOutcome;
+    /** The record that tried to replace it — copied for the same reason. */
+    readonly attempted: GateOutcome;
+    constructor(recorded: GateOutcome, attempted: GateOutcome);
+}
+/** The row facts the record's disposition reads — spelled structurally so a backend can hand a partial
+ *  read-back (a Pg row) as easily as a full `Checkpoint`. */
+export interface ExecutionRecordRowFacts {
+    scope: string;
+    status: "pending" | "resolved" | "expired";
+    executionOutcome?: GateOutcome;
+}
+/** `true` iff the row carries an execution record — the reopen verbs' extra predicate (a settled action
+ *  is not re-openable) and the record verb's own idempotency read. Pure; shared by every backend. */
+export declare function checkpointExecutionRecorded(cp: Pick<ExecutionRecordRowFacts, "executionOutcome">): boolean;
+/** Structural equality of two execution records as the JSON they round-trip as — key-order insensitive
+ *  (a jsonb column reorders keys) and indifferent to freezing (the engine's record is minted frozen; a
+ *  store's copy is not). A record is a plain data graph by construction, so nothing here needs the
+ *  accessor/topology defences a caller-supplied value would. */
+export declare function sameExecutionRecord(a: GateOutcome, b: GateOutcome): boolean;
+/**
+ * THE one disposition of an execution-record write, shared by every backend so the CAS predicate
+ * `status = 'resolved' AND execution_outcome IS NULL` and its two idempotency/conflict arms cannot drift
+ * between stores (the same posture as the shared row predicate `checkpointRowMatches`). Pure: it decides
+ * what the write means for THIS row and this record; the backend keeps its own commit half (an in-place
+ * assignment, an appended ledger event, an `UPDATE … WHERE` that folds the same predicate into SQL).
+ *  - `commit` — the row is `resolved` in this scope with no record: write it (the answer is `recorded`).
+ *  - `already_recorded` / `not_resolved` / `absent` — the {@link ExecutionOutcomeRecordWord} to answer.
+ *  - `conflict` — the row carries a different record: throw {@link ExecutionOutcomeConflictError}.
+ * Order is load-bearing: a record on file is judged BEFORE the status arm, so a retry against a row whose
+ * status a concurrent verb has since moved still answers by the record it carries.
+ */
+export declare function executionRecordDisposition(cp: ExecutionRecordRowFacts | undefined, scope: string, gate: GateOutcome): "commit" | "conflict" | Exclude<ExecutionOutcomeRecordWord, "recorded">;
+/**
+ * The ONE read of `CheckpointRow.executionOutcome`: `executed` with the record when the row carries one,
+ * `unknown` otherwise. A consumer rebuilding a run from its rows (an audit face, a supervisor inbox after
+ * a stream break) reads this rather than the column, so "no column" and "column not yet written" have
+ * exactly one spelling between them and no reader invents a default disposition.
+ */
+export declare function executionVerdict(cp: Pick<ExecutionRecordRowFacts, "executionOutcome">): ExecutionVerdict;

package/dist/core/checkpoint-execution-record.js

@@ -0,0 +1,49 @@
+import {} from "./ask-origin.js";
+export const EXECUTION_OUTCOME_RECORD_WORDS = ["recorded", "already_recorded", "not_resolved", "absent"];
+const EXECUTION_OUTCOME_RECORD_WORD_SET = new Set(EXECUTION_OUTCOME_RECORD_WORDS);
+export function isExecutionOutcomeRecordWord(v) {
+    return EXECUTION_OUTCOME_RECORD_WORD_SET.has(v);
+}
+export const EXECUTION_RECORD_LEAVES_ROW_UNRECORDED = {
+    recorded: false,
+    already_recorded: false,
+    not_resolved: true,
+    absent: true,
+};
+export class ExecutionOutcomeConflictError extends Error {
+    code = "checkpoint.execution_outcome_conflict";
+    recorded;
+    attempted;
+    constructor(recorded, attempted) {
+        super("the checkpoint already carries an execution outcome that differs from the one being recorded — the record is immutable, so this is an engine defect (one decided action settled twice), not a retry");
+        this.name = "ExecutionOutcomeConflictError";
+        this.recorded = structuredClone(recorded);
+        this.attempted = structuredClone(attempted);
+    }
+}
+export function checkpointExecutionRecorded(cp) {
+    return cp.executionOutcome !== undefined;
+}
+export function sameExecutionRecord(a, b) {
+    return canonicalJson(a) === canonicalJson(b);
+}
+function canonicalJson(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v) ?? "undefined";
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(",")}]`;
+    const keys = Object.keys(v).filter((k) => v[k] !== undefined).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(v[k])}`).join(",")}}`;
+}
+export function executionRecordDisposition(cp, scope, gate) {
+    if (cp === undefined || cp.scope !== scope)
+        return "absent";
+    if (cp.executionOutcome !== undefined)
+        return sameExecutionRecord(cp.executionOutcome, gate) ? "already_recorded" : "conflict";
+    if (cp.status !== "resolved")
+        return "not_resolved";
+    return "commit";
+}
+export function executionVerdict(cp) {
+    return cp.executionOutcome !== undefined ? { kind: "executed", gate: cp.executionOutcome } : { kind: "unknown" };
+}