@sema-agent/core 7.52.0 → 7.53.0

package/dist/brain/model-presets.js

@@ -1,4 +1,5 @@
 import { catalogText } from "../prompt-assembly/catalog/index.js";
+import { ANTHROPIC_DEFAULT_BASE_URL } from "./anthropic.js";
 export const FABLE_5_COMPAT = {
     thinkingMode: "adaptive",
     effortLevels: ["low", "medium", "high", "xhigh", "max"],
@@ -15,7 +16,7 @@ export function fable5Model(overrides = {}) {
         name: "Claude Fable 5",
         api: "anthropic-messages",
         provider: "anthropic",
-        baseUrl: "https://api.anthropic.com",
+        baseUrl: ANTHROPIC_DEFAULT_BASE_URL,
         reasoning: true,
         defaultThinking: "high",
         input: ["text", "image"],

package/dist/brain/route-adjudicator.d.ts

@@ -218,6 +218,12 @@ export declare function routeRefusalError(verdict: Extract<RouteAdjudication, {
  * nothing. A credential is bound to the origin it was first SENT to, never to one it was only judged for. The request's
  * halves (the entry's id and root, the brain's root and lane default) are read ONCE, here: both judgments and the binding
  * are of the request this build is sending, whatever the caller's objects say by the time it is committed.
+ *
+ * Exported from the package root for a HOST that sends a request itself (its own `fetch`, outside a first-party brain): it
+ * passes this same gate, so the binding does not depend on who sends first. Resolve the credential with
+ * {@link resolveRouteCredential} (a credential built by hand carries no identity: it is judged and binds nothing), call this
+ * before building, and run the admission it returns immediately before the request goes out; a refusal is the very error a
+ * first-party brain throws for the same request. {@link adjudicateModelRoute} stays the read: it judges and binds nothing.
  */
 export declare function admitRouteRequest(model: Pick<Model, "id" | "baseUrl">, credential: RouteCredential, config: RoutePairingConfig): () => void;
 /**

package/dist/brain/routing.d.ts

@@ -5,9 +5,31 @@ export interface RoutingBrainOptions {
     /** Brain used when no route matches. If omitted, an unmatched model yields an error. */
     fallback?: Brain;
 }
+/** The two `Model` fields a route can be named by — a catalog entry that carries only a provider word is as good a subject as a whole `Model`. */
+type RouteWords = {
+    readonly provider?: string | undefined;
+    readonly api?: string | undefined;
+};
+/**
+ * THE judge of which line serves a model: the model's route word (`provider`, or `api` when `by` says so) IF the route table
+ * has an OWN route under that word, else `undefined` — the fallback (the deployment's gateway) serves it. A word the model
+ * carries without a route, and a model with no string word at all, both answer `undefined`: a route that is not mounted is
+ * not a line, whatever the model says.
+ *
+ * `routes` is the route TABLE itself — the very object a host hands {@link createRoutingBrain}, which asks this function for
+ * every request — so the judge and the router answer from one reading of one table, whatever its shape. The question is
+ * `Object.hasOwn(routes, word)`: it evaluates no entry and lists no keys, so a non-enumerable own route is a route, a lazily
+ * keyed table is asked about the one name it is asked about, and a name the table only inherits (`constructor`, `__proto__`)
+ * is not a route. The judge never reads a route's value: a route mounted under the word IS the line, and when its value is not
+ * a brain the router fails that request on that line (an error terminal naming the route) rather than moving it to the
+ * fallback — so the line this answers is the line the request was sent to, either way. A table that cannot answer the question
+ * (it is not an object, or its trap throws) throws here, and the router fails the request with an error terminal.
+ */
+export declare function brainLaneOf(model: RouteWords, routes: Readonly<Record<string, unknown>>, by?: NonNullable<RoutingBrainOptions["by"]>): string | undefined;
 /**
  * Route to different brains by a Model field (default `model.provider`). Lets one Runner serve
- * multiple providers/gateways; compose with `createFailoverBrain` for per-route failover.
+ * multiple providers/gateways; compose with `createFailoverBrain` for per-route failover. Which route serves a
+ * model is {@link brainLaneOf}'s answer.
  *
  * @example
  * createRoutingBrain({
@@ -16,3 +38,4 @@ export interface RoutingBrainOptions {
  * }, { fallback: createOpenAIBrain({ baseUrl: VLLM }) });
  */
 export declare function createRoutingBrain(routes: Record<string, Brain>, opts?: RoutingBrainOptions): Brain;
+export {};

package/dist/brain/routing.js

@@ -1,42 +1,77 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { ZERO_USAGE } from "./errors.js";
-function errorMessage(model, text) {
+function errorMessage(who, text) {
     return {
         role: "assistant",
         content: [{ type: "text", text: "" }],
-        api: model.api,
-        provider: model.provider,
-        model: model.id,
+        api: who.api,
+        provider: who.provider,
+        model: who.id,
         stopReason: "error",
         errorMessage: text,
         usage: ZERO_USAGE,
         timestamp: Date.now(),
     };
 }
+const BLANK_IDENTITY = { api: "", provider: "", id: "" };
+function spelled(word) {
+    return (typeof word === "object" && word !== null) || typeof word === "function" ? `[${typeof word}]` : String(word);
+}
+function routeKeyOf(model, by) {
+    return by === "api" ? model.api : model.provider;
+}
+function isBrain(value) {
+    return value !== null && typeof value === "object" && typeof value.stream === "function";
+}
+export function brainLaneOf(model, routes, by = "provider") {
+    const word = routeKeyOf(model, by);
+    return typeof word === "string" && Object.hasOwn(routes, word) ? word : undefined;
+}
 export function createRoutingBrain(routes, opts = {}) {
     const by = opts.by ?? "provider";
     const resolveTarget = (model) => {
-        const key = by === "api" ? model.api : model.provider;
-        const routed = Object.hasOwn(routes, key) ? routes[key] : undefined;
-        const matched = routed !== null && typeof routed === "object" && typeof routed.stream === "function"
-            ? routed
-            : undefined;
-        return matched ?? opts.fallback;
+        const lane = brainLaneOf(model, routes, by);
+        if (lane === undefined)
+            return { target: opts.fallback };
+        const routed = routes[lane];
+        return isBrain(routed) ? { target: routed } : { broken: `route ${by}="${lane}" is mounted but its value is not a brain` };
     };
     const stream = (model, context, options) => {
-        const key = by === "api" ? model.api : model.provider;
-        const target = resolveTarget(model);
-        if (!target) {
+        const reject = (text, named) => {
             const out = createAssistantMessageEventStream();
-            out.push({
-                type: "error",
-                reason: "error",
-                error: errorMessage(model, `createRoutingBrain: no brain for ${by}="${key}"`),
-            });
+            try {
+                const wordOf = (field) => (field === by && named !== undefined ? named.value : model[field]);
+                out.push({ type: "error", reason: "error", error: errorMessage({ api: wordOf("api"), provider: wordOf("provider"), id: wordOf("id") }, text) });
+            }
+            catch {
+                out.push({ type: "error", reason: "error", error: errorMessage(BLANK_IDENTITY, `${text} (the model's own words could not be read either)`) });
+            }
             return out;
+        };
+        let word;
+        try {
+            word = { value: routeKeyOf(model, by) };
         }
+        catch {
+            return reject(`createRoutingBrain: the model's ${by} could not be read`);
+        }
+        const named = word.value;
+        const asked = { api: named, provider: named };
+        let resolved;
+        try {
+            resolved = resolveTarget(asked);
+        }
+        catch {
+            return reject(`createRoutingBrain: the route table threw while ${by}="${spelled(named)}" was looked up`, word);
+        }
+        const target = "target" in resolved ? resolved.target : undefined;
+        if (!target)
+            return reject("broken" in resolved ? `createRoutingBrain: ${resolved.broken}` : `createRoutingBrain: no brain for ${by}="${spelled(named)}"`, word);
         return target.stream(model, context, options);
     };
-    const adjudicateRoute = (model, perModelAuth) => resolveTarget(model)?.adjudicateRoute?.(model, perModelAuth);
+    const adjudicateRoute = (model, perModelAuth) => {
+        const resolved = resolveTarget(model);
+        return "target" in resolved ? resolved.target?.adjudicateRoute?.(model, perModelAuth) : undefined;
+    };
     return { stream, adjudicateRoute };
 }

package/dist/brain/timeout.js

@@ -1,14 +1,15 @@
+import { describeRejectedValue } from "../core/tool-search-setting.js";
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export function resolveStallTimeoutMs(value, knob) {
     if (value === undefined)
         return undefined;
     if (!Number.isFinite(value) || value < 0) {
-        const e = new Error(`${knob} must be a non-negative finite number of milliseconds (got ${String(value)})`);
+        const e = new Error(`${knob} must be a non-negative finite number of milliseconds (got ${describeRejectedValue(value)})`);
         e.code = "config.stall_timeout_invalid";
         throw e;
     }
     if (value > MAX_TIMER_DELAY_MS) {
-        const e = new Error(`${knob} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so this watchdog would abort every call instead of tolerating a long one (got ${String(value)}). Pass 0 to disable it.`);
+        const e = new Error(`${knob} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so this watchdog would abort every call instead of tolerating a long one (got ${describeRejectedValue(value)}). Pass 0 to disable it.`);
         e.code = "config.stall_timeout_invalid";
         throw e;
     }
@@ -112,12 +113,12 @@ export function resolveBrainCallGuardrailMs(knob) {
     if (knob === false || knob === 0)
         return undefined;
     if (typeof knob !== "number" || !Number.isFinite(knob) || knob < 0) {
-        const e = new Error(`brainCallGuardrailMs must be a positive number of milliseconds, 0, or false (got ${String(knob)})`);
+        const e = new Error(`brainCallGuardrailMs must be a positive number of milliseconds, 0, or false (got ${describeRejectedValue(knob)})`);
         e.code = "config.brain_call_guardrail_invalid";
         throw e;
     }
     if (knob > MAX_TIMER_DELAY_MS) {
-        const e = new Error(`brainCallGuardrailMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so the backstop would abort every model call (got ${String(knob)}). Pass false or 0 to turn the backstop off.`);
+        const e = new Error(`brainCallGuardrailMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so the backstop would abort every model call (got ${describeRejectedValue(knob)}). Pass false or 0 to turn the backstop off.`);
         e.code = "config.brain_call_guardrail_invalid";
         throw e;
     }

package/dist/core/a2a.d.ts

@@ -69,8 +69,11 @@ export interface MaterializedA2a {
     /** One entry per DECLARED peer, in declaration order, ready or failed — the declaration as this materialization read it once. */
     statuses: A2aPeerStatus[];
     /** Re-read one peer's card (or every declared peer) and re-derive its tools. Unlike the MCP refresh
-     *  this dials nothing new — every A2A call is a fresh request anyway — so a peer that failed at
-     *  prepare time can genuinely recover here. */
+     *  this dials nothing new — every A2A call is a fresh request anyway — so a peer whose card or network
+     *  failed at prepare time can genuinely recover here. The DECLARATION is not re-read: a refresh works
+     *  from the copy this materialization took and judged — the members too (`headers`, `allowSkills`,
+     *  `toolAxes` are copied, not shared) — so a declaration refused then is refused again and a caller
+     *  rewriting its object afterwards, by replacing a member or by editing one in place, changes nothing. */
     refresh: (peer?: string) => Promise<A2aRefreshResult[]>;
     /**
      * Task teardown. There is no socket to close (every call is its own request), so what this owns is the

package/dist/core/a2a.js

@@ -5,6 +5,7 @@ import { assertEndpointBound, redirectPolicy, resolveProtocolHttpHeaders, underD
 import { describeHttpTransportFailure } from "./mcp-failure.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
 import { A2A_NAMESPACE } from "./protocol-table.js";
+import { judgeEntryToolAxes, refusedDeclarer, snapshotDeclaredEntry } from "./locked-config.js";
 import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
 import { thrownText } from "./thrown-value.js";
 const A2A_REQUEST_TIMEOUT_MS = 30_000;
@@ -540,25 +541,39 @@ function buildSkillTool(spec, t, skill, lifecycle) {
         },
     };
 }
-async function materializePeer(declaredSpec, principal, lifecycle, signal) {
-    const spec = Object.freeze({ ...declaredSpec });
+function declaredPeerOf(declared, index) {
+    let snapshot;
+    try {
+        snapshot = snapshotDeclaredEntry(declared, "a2a");
+    }
+    catch (err) {
+        return { spec: { name: refusedDeclarer(err) ?? `(peer #${index + 1}, name unreadable)` }, refusal: err };
+    }
+    const judged = judgeEntryToolAxes(snapshot, "a2a");
+    return judged.ok ? { spec: judged.entry } : { spec: snapshot, refusal: judged.error };
+}
+async function materializePeer(peer, principal, lifecycle, signal) {
+    if ("refusal" in peer)
+        throw peer.refusal;
+    const { spec } = peer;
+    const declaredAxes = spec.toolAxes;
     const headers = resolveProtocolHttpHeaders(A2A_NAMESPACE.id, spec, principal);
     const discovery = { peer: spec.name, endpoint: spec.url, headers };
     const card = readCard(spec.name, await discoverCardBody(spec, discovery, signal), spec.url);
     assertEndpointBound(A2A_NAMESPACE.id, spec.name, card.endpoint, spec.cardUrl === undefined ? [spec.url] : [spec.url, spec.cardUrl], headers);
     const transport = { peer: spec.name, endpoint: card.endpoint, headers };
     const tools = [];
-    const axes = [];
+    const skillAxes = [];
     for (const skill of card.skills) {
         if (spec.allowSkills !== undefined && !spec.allowSkills.includes(skill.id))
             continue;
         const tool = buildSkillTool(spec, transport, skill, lifecycle);
         tools.push(tool);
-        axes.push(a2aAxisFor(tool.name, spec.toolAxes?.[skill.id]));
+        skillAxes.push(a2aAxisFor(tool.name, declaredAxes?.[skill.id]));
     }
     return {
         tools,
-        axes,
+        axes: skillAxes,
         status: {
             name: spec.name,
             status: "ready",
@@ -576,8 +591,9 @@ function asPeerWarning(spec, err) {
     return warning;
 }
 export async function materializeA2aTools(specs, principal, signal) {
-    if (specs.length > 0) {
-        const collision = findNamespacePrefixCollision(A2A_NAMESPACE, specs.map((s) => s.name));
+    const peers = specs.map((spec, index) => declaredPeerOf(spec, index));
+    if (peers.length > 0) {
+        const collision = findNamespacePrefixCollision(A2A_NAMESPACE, peers.map((p) => p.spec.name));
         if (collision) {
             const [a, b] = collision.peers;
             const e = new Error(a === b
@@ -592,9 +608,9 @@ export async function materializeA2aTools(specs, principal, signal) {
     const toolAxes = [];
     const warnings = [];
     const statuses = [];
-    const settled = await Promise.allSettled(specs.map((spec) => materializePeer(spec, principal, lifecycle, signal)));
-    for (let i = 0; i < specs.length; i++) {
-        const spec = specs[i];
+    const settled = await Promise.allSettled(peers.map((peer) => materializePeer(peer, principal, lifecycle, signal)));
+    for (let i = 0; i < peers.length; i++) {
+        const spec = peers[i].spec;
         const outcome = settled[i];
         if (outcome.status === "fulfilled") {
             tools.push(...outcome.value.tools);
@@ -613,12 +629,13 @@ export async function materializeA2aTools(specs, principal, signal) {
         statuses,
         refresh: async (peer) => {
             const prefixOf = (name) => mintNamespacePrefix(A2A_NAMESPACE, name);
-            const targets = peer !== undefined ? specs.filter((s) => s.name === peer) : specs;
+            const targets = peer !== undefined ? peers.filter((p) => p.spec.name === peer) : peers;
             if (peer !== undefined && targets.length === 0) {
                 return [{ peer, prefix: prefixOf(peer), status: "failed", toolCount: 0, added: [], removed: [], error: "no peer of that name is declared for this task" }];
             }
             const results = [];
-            for (const spec of targets) {
+            for (const target of targets) {
+                const { spec } = target;
                 const prefix = prefixOf(spec.name);
                 if (lifecycle.disposed) {
                     results.push({ peer: spec.name, prefix, status: "disposed", toolCount: 0, added: [], removed: [] });
@@ -626,7 +643,7 @@ export async function materializeA2aTools(specs, principal, signal) {
                 }
                 const previous = statuses.find((s) => s.name === spec.name)?.toolNames ?? [];
                 try {
-                    const fresh = await materializePeer(spec, principal, lifecycle, signal);
+                    const fresh = await materializePeer(target, principal, lifecycle, signal);
                     const names = fresh.tools.map((t) => t.name);
                     results.push({
                         peer: spec.name,

package/dist/core/allow-entry.d.ts

@@ -163,7 +163,8 @@ export declare function uncoveredCommandSegment(rows: readonly AllowEntryRow[],
  * segment covered by a row — or, for a `grant` list, read-only by itself); deny: a row whose program run the call performs (the
  * wide tightening reading; a call that cannot be read against the row is refused too). PATH — the persisted path adjudication
  * (allow: the narrow reading, every view of the target inside what the row names; deny: any view reaching it). NAME / DOMAIN —
- * the one predicate of each (the name the call names, the host it fetches).
+ * the one predicate of each (the name the call names, the host it fetches); a keyed tool's call naming no value for its key is
+ * refused by a deny list's row of the key and granted by no allow row (the persisted walk's reading, `keyedValueAbsentReason`).
  */
 export declare function judgeAllowEntries<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, behavior: "allow" | "deny", ctx: AllowEntryJudgeContext, posture?: AdmissionPosture): readonly R[] | undefined;
 /** The allow rows of a list, as the allow layer reads them in `mode`: the strip applied BEFORE the match (in `auto`). */

package/dist/core/allow-entry.js

@@ -4,7 +4,7 @@ import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js
 import { judgeRuleToolName, splitNamespacedName } from "./tool-name-aliases.js";
 import { catalogToolNames, isShellFaceToolName } from "./tool-registry.js";
 import { ALLOW_RULE_MEMBERS } from "./allow-rule-shadow.js";
-import { COMMAND_RULE_TOOL, adjudicatePersistedDomainRules, adjudicatePersistedNameRules, commandCoverageOf, domainRuleSubjectOf, laneToolNamesOf, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleToolGrammarOf } from "./permission-rule-model.js";
+import { COMMAND_RULE_TOOL, adjudicatePersistedDomainRules, adjudicatePersistedNameRules, commandCoverageOf, domainRuleSubjectOf, laneToolNamesOf, nameRuleSubjectOf, noticeRuleText, parseRuleText, programRunReachOf, ruleToolGrammarOf } from "./permission-rule-model.js";
 import { pathRuleLaneAnswer } from "./runner/permission-rule-lanes.js";
 import { callTargetReadingOf } from "./effective-path-target.js";
 import { splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
@@ -462,6 +462,6 @@ export function allowedToolsNotGrantedNotice(inert, sessionId) {
         message: `${inert.length} allowed-tools entr${inert.length === 1 ? "y grants" : "ies grant"} or refuse${inert.length === 1 ? "s" : ""} nothing — ${shown.join("; ")}${rest > 0 ? `; and ${rest} more` : ""}. ` +
             "A list holding `*` voids the list, `mcp__*` names no server, a rule the grammar refuses (`grammar`) or one on a tool with no such rule form (`content_unsupported`: an allow by path is an `Edit(…)` or `Read(…)` rule) grants nothing, and a tool name must be spelled as the tool is mounted; name the tools (or `mcp__<server>`) instead." +
             (refusing ? " Such an entry in a disallowed-tools list keeps its Skill from activating: a refusal that reads as nothing is not dropped." : ""),
-        detail: { ...(sessionId !== undefined ? { sessionId } : {}), entries: inert.map((e) => ({ ...e })) },
+        detail: { ...(sessionId !== undefined ? { sessionId } : {}), entries: inert.map((e) => ({ ...e, entry: noticeRuleText(e.entry) })) },
     };
 }

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

@@ -101,6 +101,18 @@ export interface CompactionForkContext {
      *  eligibility gate refuses a snapshot from a different model (see the engine-side twin's doc). */
     modelId?: string;
 }
+/**
+ * What a compaction pass reports at the moment it commits ({@link MaybeCompactOptions.onStarted}) — and the
+ * whole content of its `compaction_started` wire frame. `pass` is minted HERE, by the one function every lane
+ * runs, so no lane can number its own passes; the frame that ends the pass carries the same value.
+ */
+export interface CompactionPassStart {
+    readonly pass: string;
+    /** The trigger this pass runs under — the value it hands the `preCompact` hook. */
+    readonly trigger: "auto" | "manual" | "forced";
+    /** Engine clock, epoch ms, at the commit. */
+    readonly startedAt: number;
+}
 export interface MaybeCompactOptions {
     /** Disclosure channel for CONTAINED host-callback failures in this scope (the RB-463
      *  isolation primitive's bounded first-failure per site). Absent ⇒ failures are counted only. */
@@ -482,6 +494,17 @@ export interface MaybeCompactOptions {
      * not optional there, so a preCompact `block` is IGNORED on "forced").
      */
     trigger?: "auto" | "manual" | "forced";
+    /**
+     * The pass has COMMITTED: the trigger gate passed, a valid cut point exists and no `preCompact` handler
+     * blocked it, and nothing has yet consulted the summary provider or called the model. Fired exactly once per
+     * pass — a retry inside the summary call is the same pass — and never for a pass that ends before this point
+     * (under threshold, held under the floor, disabled, nothing to compact, blocked, or cut by its own signal while
+     * the `preCompact` hook ran). A pass that fired it ends
+     * in `compacted: true` or a throw, so the caller that put a frame on the wire here owes the matching end.
+     * Observe-only: a throw — or the rejection of an `async` callback, which this seat does not await — is
+     * contained and never reaches the pass.
+     */
+    onStarted?: (start: CompactionPassStart) => void;
     /**
      * design/134 (CC PreCompact parity) — fired AFTER the trigger gate and a CONFIRMED valid cut point
      * (so every invocation corresponds to a compaction that would actually happen), BEFORE the
@@ -553,6 +576,10 @@ export declare function maybeCompact(opts: MaybeCompactOptions): Promise<{
      *  nothing to do looked identical to one that never wanted to run; the caller's outcome event
      *  (`compaction_outcome{outcome:"noop"}`) reads this flag. */
     noop?: true;
+    /** The id of the pass this result concludes — the value {@link MaybeCompactOptions.onStarted} was handed.
+     *  Set exactly when `compacted` is true: every other return of this function ends before the pass commits,
+     *  and a pass that commits and does not land THROWS (the caller learned the id from the start callback). */
+    pass?: string;
     tokensBefore?: number;
     /** The §25.2 STRUCTURAL pre/post delta in ONE coordinate — the only subtractable quantity here.
      *  Absent ⇒ the post measurement failed and no delta was taken. */
@@ -669,6 +696,8 @@ export declare function maybeCompact(opts: MaybeCompactOptions): Promise<{
 /** What a landed compaction hands the wire frame. Structural, so both the full `maybeCompact` result
  *  and the settle lane's narrower `EndOfTaskCompaction` satisfy it without either importing the other. */
 export interface CompactedFrameSource {
+    /** The pass this landing concludes (see {@link MaybeCompactOptions.onStarted}). */
+    pass?: string;
     tokensBefore?: number;
     freedTokens?: number;
     postTriggerTokens?: number;
@@ -703,6 +732,34 @@ export interface CompactedFrameSource {
 export declare function mintCompactedEvent(comp: CompactedFrameSource, trigger: "auto" | "manual" | "forced", identity: TaskEventIdentity): Extract<TaskEvent, {
     type: "compacted";
 }>;
+/**
+ * THE mint of the `compaction_started` wire frame — the opening half of the pair whose closing half is the
+ * `compacted` frame above (or a `compaction_outcome` that carries the same `pass`). One function, three
+ * lanes, as the landing's: the frame is the start report itself plus the identity envelope, so a lane that
+ * wants to announce a pass can only announce the one `maybeCompact` committed.
+ */
+export declare function mintCompactionStartedEvent(start: CompactionPassStart, identity: TaskEventIdentity): Extract<TaskEvent, {
+    type: "compaction_started";
+}>;
+/**
+ * One compaction pass's account on the wire: the `onStarted` seat to hand `maybeCompact`, and the id the frame
+ * that ENDS the pass must carry. A lane makes one per pass, hands `onStarted` to the pass, and spreads
+ * {@link CompactionPassReport.end} into every `compaction_outcome` the pass can end with after it committed — a
+ * pass that threw before it committed leaves it empty, which is exactly "no start was announced, so no `pass`
+ * names it". The landing needs no spread: `maybeCompact` returns the id and `mintCompactedEvent` reads it.
+ */
+export interface CompactionPassReport {
+    readonly onStarted: (start: CompactionPassStart) => void;
+    /** The announced pass's id; `undefined` until a start went on the wire. */
+    readonly pass: string | undefined;
+    /** `{ pass }` once a start was announced, `{}` before — for the frame that ends the pass. */
+    readonly end: {
+        pass?: string;
+    };
+}
+export declare function compactionPassReport(sink: {
+    push(event: TaskEvent): void;
+}, ident: () => TaskEventIdentity): CompactionPassReport;
 /**
  * How many cross-session message frames the summarized prefix held: the engine-note user messages
  * whose text is the drain's `<cross-session-message …>` envelope, before the kept tail begins. The

package/dist/core/auto-compaction.js

@@ -1,11 +1,11 @@
 import { CROSS_SESSION_MESSAGE_TAG } from "../agents/cross-session-envelope.js";
-import { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, CompactionError, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, formatFileOperations, formatPersistedOutputRefs, prepareCompaction, shouldCompact, } from "../internal/harness.js";
+import { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, CompactionError, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, formatFileOperations, formatPersistedOutputRefs, prepareCompaction, shouldCompact, uuidv7, } from "../internal/harness.js";
 import { fileArgPath } from "./tool-registry.js";
 import { contextEditFrontier, resolveTriggerWindow } from "./context-edit.js";
 import { selectCompactionEpoch } from "../prompt-assembly/epoch.js";
 import { brainToRuntime } from "./runtime.js";
 import { defuseFenceMarkers, sanitizeUntrustedText } from "./untrusted-text.js";
-import { createSafeNotifier } from "./safe-notify.js";
+import { createSafeNotifier, observeThenableRejection } from "./safe-notify.js";
 export const DEFAULT_COMPACTION_INSTRUCTIONS = "Preserve verbatim every code, identifier, name, number, file path, error message, credential " +
     "reference, and explicit user instruction or decision mentioned anywhere in the conversation. " +
     "When in doubt, keep the specific detail rather than generalizing it.";
@@ -152,6 +152,12 @@ export async function maybeCompact(opts) {
             ? `${specInstructions}\n\n${hookSanitized}`
             : hookSanitized
         : specInstructions;
+    const signalAtCommit = opts.signal;
+    if (signalAtCommit?.aborted === true) {
+        throw Object.assign(new CompactionError("aborted", "compaction cancelled before the pass committed — nothing was summarized or persisted"), opts.manualCancelSignal?.aborted === true ? { [COMPACTION_MANUAL_CANCEL_FLAG]: true } : {});
+    }
+    const pass = uuidv7();
+    notifier.notify(() => observeThenableRejection(opts.onStarted?.({ pass, trigger, startedAt: Date.now() }), notifier, "compaction.onStarted"), "compaction.onStarted");
     const maxReuse = opts.maxConsecutiveProviderReuse ?? 3;
     const forceRealSummary = maxReuse > 0 && (opts.consecutiveProviderReuse ?? 0) >= maxReuse;
     let providerSummary;
@@ -555,6 +561,7 @@ export async function maybeCompact(opts) {
     return {
         contextUsage,
         compacted: true,
+        pass,
         tokensBefore: summaryTokensBefore,
         freedTokens,
         triggerTokens: tokens,
@@ -585,6 +592,7 @@ export function mintCompactedEvent(comp, trigger, identity) {
     return {
         type: "compacted",
         trigger,
+        ...(comp.pass !== undefined ? { pass: comp.pass } : {}),
         tokensBefore: comp.tokensBefore ?? 0,
         ...(comp.freedTokens !== undefined ? { freedTokens: comp.freedTokens } : {}),
         ...(comp.postTriggerTokens !== undefined ? { tokensAfter: comp.postTriggerTokens } : {}),
@@ -601,6 +609,24 @@ export function mintCompactedEvent(comp, trigger, identity) {
         ...identity,
     };
 }
+export function mintCompactionStartedEvent(start, identity) {
+    return { type: "compaction_started", trigger: start.trigger, pass: start.pass, startedAt: start.startedAt, ...identity };
+}
+export function compactionPassReport(sink, ident) {
+    let pass;
+    return {
+        onStarted: (start) => {
+            sink.push(mintCompactionStartedEvent(start, ident()));
+            pass = start.pass;
+        },
+        get pass() {
+            return pass;
+        },
+        get end() {
+            return pass !== undefined ? { pass } : {};
+        },
+    };
+}
 export function countSummarizedCrossSessionMessages(branch, firstKeptEntryId) {
     const firstKeptIdx = branch.findIndex((e) => e.id === firstKeptEntryId);
     const summarized = firstKeptIdx >= 0 ? branch.slice(0, firstKeptIdx) : branch;

package/dist/core/checkpoint-store.d.ts

@@ -2099,24 +2099,33 @@ export type CheckpointErrorReason = "version_newer" | "env_factory_missing" | "g
  | "installation_record_absent" | "installation_record_misaligned" | "installation_record_invalid"
 /** On `checkpoint.config_refused` with `detail.code` `config.tool_face_control` — the arm prepare's own refusal carries as its `detail.reason`:
  *  a tool-name list the row recorded is not a list / has a member that is not a string / has a spelling no tool name can have / is not in
- *  the one spelling a row records (`"not_a_list"`, `"not_a_string"`, `"unknown_name"`, `"unsupported_pattern"`); the record of the delegation tool that
+ *  the one spelling a row records (`"not_a_list"`, `"not_a_string"`, `"unknown_name"`, `"unsupported_pattern"`; the re-supplied config's own four lists —
+ *  `allowTools`, `excludeTools`, `deferTools`, `alwaysLoadTools` — are refused as `"not_a_list"` / `"not_a_string"`); the record of the delegation tool that
  *  wrote the leg's lists is not one (`"invalid_record"`); the roster the resume hands mounts a delegation tool under another name than it declares
  *  (`"renamed_mount"`); the process-wide table of declared names is occupied by a value that is not the engine's (`"registry_occupied"`). */
- | "not_a_list" | "not_a_string" | "unknown_name" | "unsupported_pattern" | "invalid_record" | "renamed_mount" | "registry_occupied";
+ | "not_a_list" | "not_a_string" | "unknown_name" | "unsupported_pattern" | "invalid_record" | "renamed_mount" | "registry_occupied"
+/** On `checkpoint.config_refused` with `detail.code` `config.unknown_role` — a role seat or a tier binding the deployment wrote that the engine cannot read:
+ *  a word the model catalog does not hold (`"unknown_model_ref"`), or a value that is no model reference at all — a number, a boolean, a list
+ *  (`"not_a_model_ref"`). The sentence names the seat (`roles.consolidate`, `tiers.pro`). */
+ | "unknown_model_ref" | "not_a_model_ref";
 /**
- * The codes a RESUME's pre-claim configuration screen carries as `detail.code` of a `checkpoint.config_refused` — the nine
- * words prepare's mode, output-style, approval-reach, invoked-skill, attachment, recorded-mode and tool-face doors throw, held unchanged so one refusal
- * reads the same on a fresh run (`TaskResult.errorCode`) and on a resume. `config.spec_retired_key`: a retired spec key;
- * `config.output_style_invalid`: a malformed output-style seat; `config.permission_mode_invalid`: a mode word outside the closed
- * set (the config's `permissionMode`, or one the row recorded); `config.shell_gate_value_retired`: a retired shell-floor word;
- * `config.approval_reach_invalid`: an `approvalReach` outside its set; `config.user_invoked_skill_unknown` / `skill_deny_unreadable`:
- * `userInvokedSkills` names a skill the config does not carry / one whose `disallowed-tools` entry the grammar reads as nothing;
- * `config.user_attachment_invalid`: the config declares `userAttachments` (a resume sends no new human message) or a malformed
- * value there; `config.tool_face_control`: the tool names the row recorded (its ceiling, its frozen policy chain, the record of who wrote
- * its lists) are not readable as written, or the roster the resume hands mounts a delegation tool under another name than it declares
- * (`detail.reason` names which: {@link CheckpointErrorReason}).
+ * The codes a RESUME's pre-claim configuration screen carries as `detail.code` of a `checkpoint.config_refused` — the words prepare's
+ * doors throw, held unchanged so one refusal reads the same on a fresh run (`TaskResult.errorCode`) and on a resume: the mode, output-style,
+ * approval-reach, invoked-skill, attachment, recorded-mode and tool-face doors (`config.spec_retired_key` … `config.tool_face_control`, the first
+ * nine — `detail.reason` names the tool-face arm: {@link CheckpointErrorReason}), and every value door of the config-door phase over the
+ * re-supplied config and the deployment's deps (`configValueDoors`, the rest): the retired deps seats and caller-policy members
+ * (`config.deps_retired_key`), the peer presence, the restore selector, the microCompact knob, the prompt selectors, `resumeAt` on a resume
+ * (`resume_at.conflicts_resume`, `resume_at.mode_without_target` — a resume carrying `resumeAt` is refused as a conflict before its mode is
+ * read, so `resume_at.invalid_mode` is a fresh run's word only), the containment faces, the add-only seats and the MCP / A2A `toolAxes` (`config.invalid_argument`), the three memory seats,
+ * the auto-consolidation arming (its role key too, and the role seats and tier bindings it reads: `config.unknown_role`, `detail.reason` naming the arm), the materialize strategy and persistence flag, the lock layer (`config.locked_registry`,
+ * `config.locked_key`), an MCP server's content class, the skills-listing seats (`config.skill_listing_budget_invalid`), the limits and the
+ * resource-suspend knobs, the attachment modes, the governance windows, the brain-call guardrail and the retention declaration over the stores the leg
+ * would run on (`config.retention_policy`, `config.retention_capability`), and the checkpoint store seat itself (`config.invalid_checkpoint_store`: the
+ * retired `null` spelling, a store that declares no execution outcome), and the skills seat and the hands band (`config.invalid_argument`;
+ * a skill's `baseDir` by its own reader, `config.skill_base_dir_invalid`). A door not entered here (the leg's model, its rebuilt
+ * roster, its answer face, the approval seat's value) still refuses after the claim, each for a stated reason (INTEGRATION-CORE, "A resume's two doors").
  */
-export declare const CHECKPOINT_CONFIG_REFUSAL_CODES: readonly ["config.spec_retired_key", "config.output_style_invalid", "config.permission_mode_invalid", "config.shell_gate_value_retired", "config.approval_reach_invalid", "config.user_invoked_skill_unknown", "config.skill_deny_unreadable", "config.user_attachment_invalid", "config.tool_face_control"];
+export declare const CHECKPOINT_CONFIG_REFUSAL_CODES: readonly ["config.spec_retired_key", "config.output_style_invalid", "config.permission_mode_invalid", "config.shell_gate_value_retired", "config.approval_reach_invalid", "config.user_invoked_skill_unknown", "config.skill_deny_unreadable", "config.user_attachment_invalid", "config.tool_face_control", "config.deps_retired_key", "config.peer_presence_invalid", "config.tool_model_gate_invalid", "config.microcompact_invalid", "config.prompt_selector_invalid", "resume_at.conflicts_resume", "resume_at.mode_without_target", "config.read_face_invalid", "config.write_face_invalid", "config.invalid_argument", "config.memory_delegation_evidence", "config.memory_provenance", "config.memory_capture_policy", "config.auto_consolidation", "config.unknown_role", "config.tool_materialize_invalid", "config.memory_persistence_invalid", "config.tool_materialize_unreachable", "config.locked_registry", "config.locked_key", "config.mcp_content_class", "config.skill_listing_budget_invalid", "config.limit_unknown_key", "config.limit_invalid", "config.attachment_invalid", "config.usage_window_invalid", "config.brain_call_guardrail_invalid", "config.retention_policy", "config.retention_capability", "config.invalid_checkpoint_store", "config.skill_base_dir_invalid"];
 export type CheckpointConfigRefusalCode = (typeof CHECKPOINT_CONFIG_REFUSAL_CODES)[number];
 export declare const isCheckpointConfigRefusalCode: (word: unknown) => word is CheckpointConfigRefusalCode;
 /** A typed checkpoint-store error so callers branch on `code` (mirrors `SessionError`). */
@@ -2295,13 +2304,13 @@ export declare class CheckpointError extends Error {
      *  resolve, or try to supply the minted record), or — design/252 G-7 — `"approver"` (the attribution is not a
      *  well-formed identifier: re-decide with a plain, bounded, control-character-free string, or omit
      *  it). On a `checkpoint.config_refused` `field` names which INPUT carries the refusal — `"taskConfig"`
-     *  (the re-supplied config: correct it and resume the same token) or `"inheritedGate"` (the mode the row
-     *  recorded: no config reaches it; expire the row). The throw
+     *  (the re-supplied config: correct it and resume the same token), `"deps"` (the deployment's own seat — and the policies the
+     *  caller re-supplies as inherited constraints: correct them and resume the same token) or `"inheritedGate"` (the row's record: no config reaches it; expire the row). The throw
      *  sites always knew which arm fired; this carries that fact instead of dropping it (ruled
      *  2026-08-03, cross-repo HITL discussion). Additive and optional — `code` remains the only REQUIRED
      *  discriminant. */
     readonly detail?: {
-        field?: "boundCallId" | "boundInputHash" | "boundGrantDigest" | "answer" | "hostDecision" | "approver" | "taskConfig" | "inheritedGate";
+        field?: "boundCallId" | "boundInputHash" | "boundGrantDigest" | "answer" | "hostDecision" | "approver" | "taskConfig" | "deps" | "inheritedGate";
         /** On `checkpoint.config_refused` — prepare's own code for the refusal ({@link CheckpointConfigRefusalCode}), the
          *  word a fresh run of the same bad config reports as its `errorCode`. Absent on every other code. */
         code?: CheckpointConfigRefusalCode;
@@ -2498,13 +2507,13 @@ export declare class CheckpointError extends Error {
      *  resolve, or try to supply the minted record), or — design/252 G-7 — `"approver"` (the attribution is not a
      *  well-formed identifier: re-decide with a plain, bounded, control-character-free string, or omit
      *  it). On a `checkpoint.config_refused` `field` names which INPUT carries the refusal — `"taskConfig"`
-     *  (the re-supplied config: correct it and resume the same token) or `"inheritedGate"` (the mode the row
-     *  recorded: no config reaches it; expire the row). The throw
+     *  (the re-supplied config: correct it and resume the same token), `"deps"` (the deployment's own seat — and the policies the
+     *  caller re-supplies as inherited constraints: correct them and resume the same token) or `"inheritedGate"` (the row's record: no config reaches it; expire the row). The throw
      *  sites always knew which arm fired; this carries that fact instead of dropping it (ruled
      *  2026-08-03, cross-repo HITL discussion). Additive and optional — `code` remains the only REQUIRED
      *  discriminant. */
     detail?: {
-        field?: "boundCallId" | "boundInputHash" | "boundGrantDigest" | "answer" | "hostDecision" | "approver" | "taskConfig" | "inheritedGate";
+        field?: "boundCallId" | "boundInputHash" | "boundGrantDigest" | "answer" | "hostDecision" | "approver" | "taskConfig" | "deps" | "inheritedGate";
         /** On `checkpoint.config_refused` — prepare's own code for the refusal ({@link CheckpointConfigRefusalCode}), the
          *  word a fresh run of the same bad config reports as its `errorCode`. Absent on every other code. */
         code?: CheckpointConfigRefusalCode;