@sema-agent/core 7.51.2 → 7.52.0

package/dist/brain/route-adjudicator.js

@@ -1,6 +1,8 @@
-import { AUTH_CARRIER_NAMES } from "./request-params.js";
+import { createHash } from "node:crypto";
 import { BrainError } from "./errors.js";
+import { reportCredentialOriginRefusal } from "./status-sink.js";
 import { receiptRefusal, receiveOwnProperties } from "../core/own-property-receipt.js";
+import { credentialHeaderValues, holdOwnCredentialValues, isCredentialHeaderName, isSchemedCredentialHeader } from "../core/secret-env.js";
 const REDACTED_VALUE = "«redacted»";
 const REDACTED_CREDENTIALS = "[redacted-credentials]";
 function servableParse(raw) {
@@ -191,23 +193,96 @@ export function resolveRequestRootOf(modelBaseUrl, configBaseUrl, laneDefault =
 export function hasAuthCarrier(headers) {
     if (!headers)
         return false;
-    for (const k of Object.keys(headers)) {
-        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
-            return true;
+    return Object.keys(headers).some((name) => isCredentialHeaderName(name));
+}
+function routeOriginOf(rootKey) {
+    if (rootKey === "")
+        return "";
+    const u = servableParse(rootKey);
+    return u === undefined ? rootKey : `${u.protocol}//${u.host}`;
+}
+const CREDENTIAL_ORIGIN_BINDINGS_MAX = 16_384;
+const CREDENTIAL_ORIGIN_TABLE = Symbol.for("sema.core.credentialOriginTable");
+function credentialOriginTable() {
+    const held = Reflect.get(globalThis, CREDENTIAL_ORIGIN_TABLE);
+    if (held instanceof Map)
+        return held;
+    const table = new Map();
+    Reflect.set(globalThis, CREDENTIAL_ORIGIN_TABLE, table);
+    return table;
+}
+export function __resetCredentialOriginBindings() {
+    credentialOriginTable().clear();
+}
+const resolvedCredentialFacts = new WeakMap();
+const HEADER_VALUE_ENDS = /^[\t\n\r ]+|[\t\n\r ]+$/g;
+const AUTH_SCHEME_CREDENTIALS = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+[\t ]+(\S[\s\S]*)$/;
+function perModelCredential(credential, apiKey, bag, conflict) {
+    const headers = {};
+    for (const [name, value] of Object.entries(bag ?? {})) {
+        if (isCredentialHeaderName(name) && typeof value === "string")
+            headers[name] = value;
     }
-    return false;
+    const headerValues = Object.entries(headers).map(([name, value]) => {
+        const wire = value.replace(HEADER_VALUE_ENDS, "");
+        return isSchemedCredentialHeader(name) ? (AUTH_SCHEME_CREDENTIALS.exec(wire)?.[1] ?? wire) : wire;
+    });
+    const values = apiKey !== undefined ? [apiKey, ...headerValues] : headerValues;
+    const secrets = [...new Set(values.map((v) => v.replace(HEADER_VALUE_ENDS, "")).filter((v) => v !== ""))];
+    if (secrets.length === 0 && Object.keys(headers).length === 0 && conflict === undefined)
+        return credential;
+    const proof = Object.freeze(credential);
+    resolvedCredentialFacts.set(proof, Object.freeze({
+        identities: Object.freeze(secrets.map((s) => createHash("sha256").update(s).digest("base64url"))),
+        headers: Object.freeze(headers),
+        ...(conflict !== undefined ? { keyHeaderConflict: Object.freeze(conflict) } : {}),
+    }));
+    return proof;
+}
+function boundElsewhere(identities, requestOrigin) {
+    const table = credentialOriginTable();
+    return identities.map((id) => table.get(id)).find((bound) => bound !== undefined && bound !== requestOrigin);
+}
+function bindCredentialOrigin(identities, requestOrigin) {
+    const table = credentialOriginTable();
+    for (const id of identities) {
+        table.delete(id);
+        if (table.size >= CREDENTIAL_ORIGIN_BINDINGS_MAX) {
+            const oldest = table.keys().next();
+            if (oldest.done !== true)
+                table.delete(oldest.value);
+        }
+        table.set(id, requestOrigin);
+    }
+}
+function routeHalves(model, config) {
+    const entry = routeKeyOf(model.baseUrl);
+    const declared = routeKeyOf(config.baseUrl);
+    const deploymentRoot = declared || routeKeyOf(config.laneDefault);
+    return { entry, declared, deploymentRoot, request: entry || deploymentRoot };
+}
+function keyHeaderConflict(apiKey, headers, keyHeader) {
+    if (apiKey === undefined || apiKey === "" || keyHeader === undefined || headers === undefined)
+        return undefined;
+    const fold = keyHeader.toLowerCase();
+    const written = Object.keys(headers).find((name) => name.toLowerCase() === fold);
+    return written === undefined ? undefined : { header: written, keyHeader };
 }
 export function resolveRouteCredential(input) {
-    const { optionsApiKey, optionsHeaders, modelHeaders, configApiKey, configHeaders } = input;
-    if (optionsApiKey !== undefined) {
-        if (typeof optionsApiKey !== "string")
+    const { optionsApiKey, optionsHeaders, modelHeaders, configApiKey, configHeaders, keyHeader } = input;
+    holdOwnCredentialValues(credentialHeaderValues(modelHeaders));
+    const answerHeadersBorne = hasAuthCarrier(optionsHeaders);
+    if (optionsApiKey !== undefined || answerHeadersBorne) {
+        if (optionsApiKey !== undefined && typeof optionsApiKey !== "string")
             throw new TypeError(`route pairing: apiKey must be a string (got ${typeof optionsApiKey})`);
-        return { source: "per-model", apiKey: optionsApiKey };
+        return perModelCredential({
+            source: "per-model",
+            ...(optionsApiKey !== undefined ? { apiKey: optionsApiKey } : {}),
+            ...(answerHeadersBorne ? { headersBorne: true, carrierBag: "options" } : {}),
+        }, optionsApiKey, answerHeadersBorne ? optionsHeaders : undefined, keyHeaderConflict(optionsApiKey, optionsHeaders, keyHeader));
     }
-    if (hasAuthCarrier(optionsHeaders))
-        return { source: "per-model", headersBorne: true, carrierBag: "options" };
     if (hasAuthCarrier(modelHeaders))
-        return { source: "per-model", headersBorne: true, carrierBag: "model" };
+        return perModelCredential({ source: "per-model", headersBorne: true, carrierBag: "model" }, undefined, modelHeaders);
     const configHeadersBorne = hasAuthCarrier(configHeaders);
     if (configApiKey !== undefined || configHeadersBorne) {
         if (configApiKey !== undefined && typeof configApiKey !== "string") {
@@ -222,15 +297,53 @@ export function resolveRouteCredential(input) {
     return { source: "absent" };
 }
 export function adjudicateModelRoute(model, credential, config) {
-    const entry = routeKeyOf(model.baseUrl);
-    const declared = routeKeyOf(config.baseUrl);
-    const deploymentRoot = declared || routeKeyOf(config.laneDefault);
-    const request = entry || deploymentRoot;
+    const { entry, declared, deploymentRoot, request } = routeHalves(model, config);
     const entryShown = displayUrlOf(entry);
     const declaredShown = displayUrlOf(declared);
     const requestShown = displayUrlOf(request);
-    if (credential.source === "per-model")
-        return { ok: true, posture: "per-model" };
+    if (credential.source === "per-model") {
+        const facts = resolvedCredentialFacts.get(credential);
+        const conflict = facts?.keyHeaderConflict;
+        if (conflict !== undefined) {
+            return {
+                ok: false,
+                code: "route.credential_answer_conflict",
+                detail: {
+                    modelId: model.id,
+                    entryBaseUrl: entryShown,
+                    requestBaseUrl: requestShown,
+                    configBaseUrl: declaredShown,
+                    fixHint: `model "${model.id}": the request carries both an apiKey and a "${conflict.header}" header, and this lane writes the apiKey in ` +
+                        `"${conflict.keyHeader}" — one header cannot hold two credentials; hand the key as apiKey or as the header, not both`,
+                },
+            };
+        }
+        const identities = facts?.identities;
+        const requestOrigin = routeOriginOf(request);
+        if (identities === undefined || requestOrigin === "")
+            return { ok: true, posture: "per-model" };
+        const boundOrigin = boundElsewhere(identities, requestOrigin);
+        if (boundOrigin === undefined)
+            return { ok: true, posture: "per-model" };
+        const boundShown = displayUrlOf(boundOrigin);
+        const requestOriginShown = displayUrlOf(requestOrigin);
+        return {
+            ok: false,
+            code: "route.credential_origin_mismatch",
+            detail: {
+                modelId: model.id,
+                entryBaseUrl: entryShown,
+                requestBaseUrl: requestShown,
+                configBaseUrl: declaredShown,
+                boundOrigin: boundShown,
+                requestOrigin: requestOriginShown,
+                fixHint: `model "${model.id}" targets ${requestShown} (origin ${requestOriginShown}) but its own credential is bound to ${boundShown}, ` +
+                    `the origin it was first sent to — a credential does not follow its entry to another host: change the entry's credential ` +
+                    `reference in the same step as its baseUrl (a new credential is a new binding), or point the entry back at ${boundShown}; ` +
+                    `a binding lasts as long as the engine process, so a provider that only moved domains and accepts the same credential there needs a restart`,
+            },
+        };
+    }
     if (credential.source === "deployment-config") {
         if (request !== "" && request === deploymentRoot)
             return { ok: true, posture: "paired" };
@@ -273,22 +386,40 @@ export function adjudicateModelRoute(model, credential, config) {
 export function routeRefusalText(verdict) {
     return `${verdict.code}: ${verdict.detail.fixHint}`;
 }
-export function applyRouteCredentialHeaders(merged, credential, bags) {
+export function routeRefusalError(verdict) {
+    const { modelId, boundOrigin, requestOrigin } = verdict.detail;
+    if (verdict.code === "route.credential_origin_mismatch" && boundOrigin !== undefined && requestOrigin !== undefined) {
+        reportCredentialOriginRefusal({ modelId, boundOrigin, requestOrigin });
+    }
+    return new BrainError("invalid_request", routeRefusalText(verdict));
+}
+export function admitRouteRequest(model, credential, config) {
+    const judged = { id: model.id, baseUrl: model.baseUrl };
+    const { baseUrl, laneDefault } = config;
+    const pairing = { ...(baseUrl !== undefined ? { baseUrl } : {}), ...(laneDefault !== undefined ? { laneDefault } : {}) };
+    const judgeOrRefuse = () => {
+        const verdict = adjudicateModelRoute(judged, credential, pairing);
+        if (!verdict.ok)
+            throw routeRefusalError(verdict);
+    };
+    judgeOrRefuse();
+    const identities = credential.source === "per-model" ? resolvedCredentialFacts.get(credential)?.identities : undefined;
+    const requestOrigin = routeOriginOf(routeHalves(judged, pairing).request);
+    if (identities === undefined || identities.length === 0 || requestOrigin === "")
+        return () => { };
+    return () => {
+        judgeOrRefuse();
+        bindCredentialOrigin(identities, requestOrigin);
+    };
+}
+export function applyRouteCredentialHeaders(merged, credential) {
     if (credential.source !== "per-model")
         return;
     for (const k of Object.keys(merged)) {
-        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
+        if (isCredentialHeaderName(k))
             delete merged[k];
     }
-    if (credential.headersBorne !== true)
-        return;
-    const winner = credential.carrierBag === "options" ? bags.options : bags.model;
-    if (!winner)
-        return;
-    for (const [k, v] of Object.entries(winner)) {
-        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
-            merged[k] = v;
-    }
+    Object.assign(merged, resolvedCredentialFacts.get(credential)?.headers);
 }
 export function brainConfigSnapshot(given, subject) {
     const words = { subject, unit: "member", moment: "at construction" };
@@ -299,7 +430,9 @@ export function brainConfigSnapshot(given, subject) {
             throw receiptRefusal(`${subject}.headers must be an object of header names to values`);
         Object.defineProperty(received, "headers", { value: Object.freeze(receiveOwnProperties(headers, { ...words, subject: `${subject}.headers`, unit: "header" })), enumerable: true });
     }
-    return Object.freeze(received);
+    const snapshot = Object.freeze(received);
+    holdOwnCredentialValues([snapshot.apiKey, ...credentialHeaderValues(snapshot.headers)]);
+    return snapshot;
 }
 export function createBrainRouteJudge(config) {
     return (model, perModelAuth) => {
@@ -309,17 +442,24 @@ export function createBrainRouteJudge(config) {
             modelHeaders: model.headers,
             configApiKey: config.apiKey,
             configHeaders: config.headers,
+            keyHeader: config.keyHeader,
         });
         return adjudicateModelRoute(model, credential, { baseUrl: config.baseUrl, laneDefault: config.laneDefault });
     };
 }
+const BROKEN_PAIRING_STATUS = {
+    "route.credential_mismatch": "broken:credential_mismatch",
+    "route.credential_missing": "broken:credential_missing",
+    "route.credential_origin_mismatch": "broken:credential_origin_mismatch",
+    "route.credential_answer_conflict": "broken:credential_answer_conflict",
+};
 export function routePairingStatus(brain, model, perModelAuth) {
     const verdict = brain.adjudicateRoute?.(model, perModelAuth);
     if (verdict === undefined)
         return "unknown";
     if (verdict.ok)
         return `ok:${verdict.posture}`;
-    return verdict.code === "route.credential_mismatch" ? "broken:credential_mismatch" : "broken:credential_missing";
+    return BROKEN_PAIRING_STATUS[verdict.code];
 }
 export const DERIVED_ROUTE_PREFLIGHT_HOOK_BOUND_MS = 5_000;
 export async function adjudicateDerivedRoute(args) {
@@ -391,14 +531,3 @@ export function unroutableSeatNotice(args) {
         },
     };
 }
-export function authCarrierFingerprint(headers) {
-    if (!headers)
-        return "";
-    const rows = [];
-    for (const [k, v] of Object.entries(headers)) {
-        const fold = k.toLowerCase();
-        if (AUTH_CARRIER_NAMES.has(fold))
-            rows.push(`${fold}=${v}`);
-    }
-    return rows.sort().join("\n");
-}

package/dist/brain/route-conformance.js

@@ -1,7 +1,7 @@
 export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
     {
         name: "per-model-on-root",
-        intent: "a per-model credential is paired by construction, on the deployment root",
+        intent: "a per-model credential not bound yet is servable, on the deployment root",
         model: { id: "m-main", baseUrl: "https://gw.example.com" },
         credential: { source: "per-model", apiKey: "k-main" },
         config: { baseUrl: "https://gw.example.com" },
@@ -9,7 +9,7 @@ export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
     },
     {
         name: "per-model-off-root",
-        intent: "a per-model credential is paired by construction even off the deployment root (the resolver was asked about THIS entry)",
+        intent: "a per-model credential not bound yet is servable off the deployment root too (the resolver was asked about THIS entry)",
         model: { id: "m-third", baseUrl: "https://third-party.example.net/v1" },
         credential: { source: "per-model", apiKey: "k-third" },
         config: { baseUrl: "https://gw.example.com" },

package/dist/brain/status-sink.d.ts

@@ -150,3 +150,21 @@ export declare function runWithExtraBodyDropped<T>(observe: (r: ExtraBodyDropped
 /** Report the strip of the request the engine has SELECTED to send, to the active per-run sink, if any (called at the
  *  engine's commit points, never from `buildRequest`, which is also built speculatively). */
 export declare function reportExtraBodyDropped(report: ExtraBodyDroppedReport): void;
+/** A request refused because the per-model credential it would carry is bound to another origin: the catalog id it was
+ *  for and the two origins, each in its DISPLAY spelling. Never a value, never a digest of one. */
+export interface CredentialOriginRefusalReport {
+    modelId: string;
+    boundOrigin: string;
+    requestOrigin: string;
+}
+/**
+ * Run `fn` with a per-run credential-origin refusal sink in scope — the FIFTH brain→runner ALS channel, with the fourth's
+ * shape and for its reasons: the WHOLE leg (a refused compaction summary, side query or classifier call is refused for the
+ * same reason as a turn), not shielded around the leg's internal calls, not revoked on settlement, no-op outside the scope.
+ * The refusal is already decided when it is reported.
+ */
+export declare function runWithCredentialOriginRefusals<T>(observe: (r: CredentialOriginRefusalReport) => void, fn: () => Promise<T>): Promise<T>;
+/** Report a credential-origin refusal to the active per-run sink, if any (called by the request gate's refusal,
+ *  `routeRefusalError`; a judgment that only advises reports nothing). The
+ *  observer is the Runner's own seat, whose one delivery is the guarded `deliverEngineNotice` — nothing is swallowed here. */
+export declare function reportCredentialOriginRefusal(report: CredentialOriginRefusalReport): void;

package/dist/brain/status-sink.js

@@ -68,3 +68,10 @@ export function reportExtraBodyDropped(report) {
     catch {
     }
 }
+const credentialOriginRefusalSinkStore = new AsyncLocalStorage();
+export function runWithCredentialOriginRefusals(observe, fn) {
+    return credentialOriginRefusalSinkStore.run({ observe }, fn);
+}
+export function reportCredentialOriginRefusal(report) {
+    credentialOriginRefusalSinkStore.getStore()?.observe(report);
+}

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

@@ -8,8 +8,9 @@ import { type EngineNotice } from "./engine-notice.js";
 /** Why an entry grants (or refuses) nothing — the closed set the start-of-run notice names, for every list. `tool_name`: the
  *  entry's tool name is one the name judgment reads as stale against the run's roster (`verdict` says which); `near_miss`: the
  *  run mounts no tool of that exact name but mounts one that differs only by case (`currentName` is its spelling);
- *  `earlier_grammar`: a session's stored rules are written in an earlier rule grammar, in which the entry named no tool (the
- *  session store's list reading, `compileSessionRuleBucket` — this reader never answers it). */
+ *  `earlier_grammar`: a session's stored rules are written in an earlier rule grammar, in which the entry named no tool, or which
+ *  read an entry this grammar reads as no rule (the session store's list reading, `compileSessionRuleBucket` — this reader never
+ *  answers it). */
 export declare const ALLOW_ENTRY_INERT_REASONS: readonly ["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss", "earlier_grammar"];
 export type AllowEntryInertReason = (typeof ALLOW_ENTRY_INERT_REASONS)[number];
 /** The facts beside a reason: for `tool_name` / `near_miss` the judgment's word, the judgment's own one-line sentence when it has
@@ -21,7 +22,13 @@ export interface AllowEntryInertDetail {
     readonly guidance?: string;
     readonly currentName?: string;
     readonly valueType?: string;
+    /** Where the spelling of a `near_miss` comes from, when the station that read it reads more than the run's roster
+     *  ({@link NearMissCarrier}); absent ⇒ the roster the run mounts. A sentence only — never a field of a wire detail. */
+    readonly carriedBy?: NearMissCarrier;
 }
+/** Who carries the spelling a near miss reads as another spelling of: the roster the run mounts, a delegation tool's pool, or
+ *  only the engine's tool catalog (a tool the engine may mount, which this run's roster does not carry). */
+export type NearMissCarrier = "run" | "pool" | "catalog";
 /**
  * How a list member that is not a string is named wherever a list's entries are named (the inert record's `entry`, the Skill
  * card's binding): its TYPE, in a spelling no readable entry can have — a readable entry's name holds no whitespace and a
@@ -64,6 +71,25 @@ export type CompiledAllowEntry = {
     readonly kind: "domain";
     readonly rule: PersistedRule;
 };
+/**
+ * THE near-miss reading of a tool name the judgment calls current: the spelling the run mounts when the run mounts no tool of this
+ * exact name but one that differs from it only by case (`BASH` beside `Bash`), else `undefined`. Two kinds of name are never a near
+ * miss, because the roster they would be read against is not the final one: an engine tool's (the engine mounts some of its tools
+ * after a list is read) and a protocol tool's (a refresh mounts and unmounts them while the run goes on) — in both the exact
+ * spelling can be the right one by the time it matters. Every station that asks "is this name a case twin of a mounted tool" reads
+ * this answer: an entry list ({@link readRuleEntry}), a tool policy's name lists (the prepare-time policy-name audit).
+ */
+export declare function nearMissSpellingOf(name: string, roster: ReadonlySet<string>): string | undefined;
+/**
+ * THE universe a ROOT-facing tool-name list is read against: every name the engine's catalog carries, and the names the reader knows
+ * are carried (`carried`). A list is root-facing when it bounds the tools of the run that holds it — the run's own `allowTools` /
+ * `excludeTools` (also the ceiling of its children), a tool policy's name lists, a session's stored rules — and its reader is that
+ * run (`carried`: its roster, the caller's own tools, and the exact names of the pools its reachable delegation tools declare and can
+ * list) or the store that writes the rules (`carried`: the tools its deployment declared). Another spelling of a carried name is
+ * always refused there, whatever a delegation tool injects per spawn: the run's own tools are known, and an entry that is a case
+ * twin of one of them names the other tool by mistake. A delegation tool's pool that cannot be listed carries nothing here.
+ */
+export declare function rootFacingToolNames(carried: Iterable<string>): Set<string>;
 /** What one rule entry means under one direction ({@link readRuleEntry}): the row the grammar compiles it to, or the reason it
  *  reads as nothing with the facts a sentence about it names. */
 export type RuleEntryReading = {
@@ -87,9 +113,10 @@ export declare function compiledEntryName(compiled: CompiledAllowEntry): string;
 /**
  * Compile one list WHOLE through {@link readRuleEntry}: the entries it reads and the ones it reads as nothing (each with its
  * reason and, for a name the roster refuses, the judgment's word and the spelling to write). An allow list holding `*` voids
- * the list (every other entry on it reads as nothing too: the list grants nothing — the safe direction). A `*` on a deny list
- * reads as nothing by itself and the rest of that list still refuses: a deny list never loses an entry to a wildcard beside
- * it. `roster` as in {@link readRuleEntry}.
+ * the list (every other entry on it reads as nothing too: the list grants nothing — the safe direction) — `*` as the lenient
+ * rule parser names it ({@link namesWholeRoster}), so an entry the stricter entry grammar refuses (`* (*)`) still voids. A
+ * `*` on a deny list reads as nothing by itself and the rest of that list still refuses: a deny list never loses an entry to
+ * a wildcard beside it. `roster` as in {@link readRuleEntry}.
  */
 export declare function compileAllowList(entries: readonly string[], behavior: "allow" | "deny", roster?: ReadonlySet<string>): {
     rows: Array<{
@@ -294,11 +321,16 @@ export type AllowEntryInertNote = ({
 } & AllowEntryInert) | ({
     readonly source: AllowEntrySource;
 } & AllowEntryInert);
+/**
+ * A list entry spelled so a person reads what the engine read: the entry as a JSON string — quotes, backslashes and the usual
+ * escapes — with every character that prints as nothing, or as a space, written as `\uXXXX` (`\u{…}` beyond the BMP) and a
+ * run of spaces kept space by space. Uncapped and one-to-one (two entries never share a spelling), so a value that BINDS an
+ * entry may hold it ({@link renderListEntry} is this, capped for a sentence).
+ */
+export declare function spelledListEntry(entry: string): string;
 /**
  * THE ONE WRITER of a list entry into a sentence (the start-of-run notice, a skill's refusal and its decisions, a sub-agent
- * list's refusals and advisories): the entry as a JSON string — quotes, backslashes and the usual escapes — with every
- * character that prints as nothing, or as a space, written as `\uXXXX` (`\u{…}` beyond the BMP) and a run of spaces kept
- * space by space, so what a person reads is what the engine read. Capped on what is printed.
+ * list's refusals and advisories): {@link spelledListEntry}, capped on what is printed.
  */
 export declare function renderListEntry(entry: string): string;
 /**

package/dist/core/allow-entry.js

@@ -1,5 +1,6 @@
 import { heldBy } from "./tool-name-readings.js";
-import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
+import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "./permission-rules.js";
+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";
@@ -12,6 +13,7 @@ import { inlineUntrusted } from "./untrusted-text.js";
 import { valueTypeLabel } from "./tool-name-list.js";
 import { deliverEngineNotice } from "./engine-notice.js";
 export const ALLOW_ENTRY_INERT_REASONS = Object.freeze(["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss", "earlier_grammar"]);
+const NEAR_MISS_CARRIER = { run: "the mounted spelling is", pool: "a delegation pool carries", catalog: "the engine's tool catalog names" };
 export function nonStringMemberLabel(value) {
     return `<not a string: ${valueTypeLabel(value)}>`;
 }
@@ -21,7 +23,6 @@ export function nonListValueLabel(read) {
 function ruleRowOf(parsed) {
     return { ...parsed, scope: { kind: "global" }, adds: [{ dot: { actor: "list", counter: 1 }, origin: "user", createdAt: "" }] };
 }
-const TOOL_NAME_SPELLING = /^[^\s()\p{Cc}\p{Cf}]+$/u;
 function mountedSpellingOf(name, roster) {
     const folded = name.toLowerCase();
     for (const mounted of roster)
@@ -29,6 +30,14 @@ function mountedSpellingOf(name, roster) {
             return mounted;
     return undefined;
 }
+export function nearMissSpellingOf(name, roster) {
+    if (roster.has(name) || catalogToolNames().has(name) || splitNamespacedName(name) !== undefined)
+        return undefined;
+    return mountedSpellingOf(name, roster);
+}
+export function rootFacingToolNames(carried) {
+    return new Set([...catalogToolNames(), ...carried]);
+}
 function toolNameReading(name, roster) {
     const verdict = judgeRuleToolName(name, roster);
     if (verdict.kind === "unprefixed_namespace")
@@ -36,9 +45,7 @@ function toolNameReading(name, roster) {
     if (verdict.kind !== "current") {
         return { kind: "inert", reason: "tool_name", verdict: verdict.kind, guidance: verdict.guidance, ...(verdict.currentName !== undefined ? { currentName: verdict.currentName } : {}) };
     }
-    if (roster.has(name) || catalogToolNames().has(name) || splitNamespacedName(name) !== undefined)
-        return undefined;
-    const mounted = mountedSpellingOf(name, roster);
+    const mounted = nearMissSpellingOf(name, roster);
     return mounted === undefined ? undefined : { kind: "inert", reason: "near_miss", currentName: mounted };
 }
 export function readRuleEntry(raw, behavior, roster) {
@@ -46,12 +53,10 @@ export function readRuleEntry(raw, behavior, roster) {
     const row = (compiled) => ({ kind: "row", compiled });
     if (typeof raw !== "string")
         return { kind: "inert", reason: "grammar", valueType: valueTypeLabel(raw) };
-    if (raw !== raw.trim())
+    const parsed = ruleSpellingOf(raw);
+    if (parsed === undefined)
         return inert("grammar");
-    const parsed = parsePermissionRule(raw);
     const name = parsed.toolName;
-    if (!TOOL_NAME_SPELLING.test(name))
-        return inert("grammar");
     if (name === "*")
         return inert("wildcard_all");
     if (roster !== undefined) {
@@ -98,7 +103,7 @@ function inertReasonOf(code) {
     return code === "unsupported.tool" ? "content_unsupported" : "grammar";
 }
 export function compileAllowList(entries, behavior, roster) {
-    const voided = behavior === "allow" && entries.some((e) => isWildcardAll(readRuleEntry(e, behavior)));
+    const voided = behavior === "allow" && entries.some(namesWholeRoster);
     const rows = [];
     const inert = [];
     for (const entry of entries) {
@@ -113,8 +118,8 @@ export function compileAllowList(entries, behavior, roster) {
     }
     return { rows, inert };
 }
-function isWildcardAll(read) {
-    return read.kind === "inert" && read.reason === "wildcard_all";
+function namesWholeRoster(entry) {
+    return typeof entry === "string" && entry === entry.trim() && parsePermissionRule(entry).toolName === "*";
 }
 function answersTo(req, has) {
     return heldBy("allowEntry.names", { has }, req);
@@ -415,11 +420,13 @@ function escapedCodePoint(ch) {
     const hex = cp.toString(16).padStart(4, "0");
     return cp > 0xffff ? `\\u{${hex}}` : `\\u${hex}`;
 }
-export function renderListEntry(entry) {
-    const quoted = JSON.stringify(entry)
+export function spelledListEntry(entry) {
+    return JSON.stringify(entry)
         .replace(/ {2,}/g, (run) => "\\u0020".repeat(run.length))
         .replace(UNSEEN_IN_ENTRY, (ch) => (ch === " " ? ch : escapedCodePoint(ch)));
-    return inlineUntrusted(quoted, ENTRY_RENDER_MAX);
+}
+export function renderListEntry(entry) {
+    return inlineUntrusted(spelledListEntry(entry), ENTRY_RENDER_MAX);
 }
 export function inertEntryPhrase(e) {
     if (e.valueType !== undefined)
@@ -427,7 +434,7 @@ export function inertEntryPhrase(e) {
     const spelling = e.currentName !== undefined ? inlineUntrusted(e.currentName, 120) : undefined;
     const why = (() => {
         if (e.reason === "near_miss")
-            return `near_miss: the mounted spelling is "${spelling}"`;
+            return `near_miss: ${NEAR_MISS_CARRIER[e.carriedBy ?? "run"]} "${spelling}"`;
         if (e.reason !== "tool_name" || e.verdict === undefined)
             return e.reason;
         switch (e.verdict) {

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

@@ -1,7 +1,7 @@
 import { type AgentMessage, type CompactionSettings, type Session, type ThinkingLevel } from "../internal/harness.js";
 import type { Message, Model, Tool } from "../internal/llm.js";
 import type { ContextWindowOverlay } from "./context-settings.js";
-import type { Hooks } from "./hooks.js";
+import type { PostCompactContext, PreCompactContext, PreCompactResult } from "./hooks.js";
 import type { TraceEvent } from "./trace.js";
 import type { Brain } from "./types.js";
 import type { TaskEvent, TaskEventIdentity } from "./task-event.js";
@@ -108,25 +108,27 @@ export interface MaybeCompactOptions {
     /** The session to compact. Typed on the INTERFACE face (typecheck 车 2026-07-24): every member this
      *  module touches lives on `Session` (the optional `getPromptEpoch` degrades honestly via `?.()`). */
     session: Session;
-    /** This run's provider-declared prompt sections (the epoch declaration axis):
-     *  the compaction-boundary epoch restatement/advance must hash the SAME artifact identity as the
-     *  prepare-time pin, or every compaction under a declaration-carrying run would flap the pin. */
-    epochDeclaredSections?: import("../prompt-assembly/epoch.js").EpochDeclaredSections;
-    /** A compaction-boundary CENTER CANDIDATE ADOPTION, pre-assembled by the
-     *  caller (prepare's seam): the descriptor advances with the candidate's declarations + provenance
-     *  in the SAME CAS append as the new baseline, and `apply()` (the live prefix/fingerprint swap)
-     *  runs ONLY after that append succeeded — a failed/blocked compaction must swap nothing. */
+    /** This run's prompt identity inputs (and the pinned center layer's provenance): the compaction restates the
+     *  session's epoch when the identity is unchanged and advances it otherwise — the same identity the prepare-time
+     *  record names, so a compaction never flaps the record. Absent ⇒ no restatement (a host compacting outside a run). */
+    promptIdentity?: {
+        readonly layers: import("../prompt-assembly/epoch.js").PromptIdentityLayers;
+        readonly sourceRevision?: string;
+    };
+    /** A compaction-boundary CENTER LAYER CHANGE, pre-assembled by the caller (prepare's seam): an adopted candidate,
+     *  or an emptied center layer after an explicit revocation. The epoch advances to the identity after the change in
+     *  the SAME CAS append as the new baseline, and `apply()` (the live prefix / fingerprint swap) runs ONLY after that
+     *  append succeeded — a failed or blocked compaction swaps nothing. */
     centerAdoption?: {
-        /** Absent together with `clear` ⇒ never happens; adoption carries the new digest, ROLLBACK
-         *  (explicit center disable) carries `clear:true` and no digest. */
-        centerArtifactDigest?: string;
-        sourceRevision?: string;
-        clear?: true;
-        declaredSections: import("../prompt-assembly/epoch.js").EpochDeclaredSections;
+        /** The run's identity inputs after the change (`layers.center` absent ⇒ the center layer is emptied). */
+        promptIdentity: {
+            readonly layers: import("../prompt-assembly/epoch.js").PromptIdentityLayers;
+            readonly sourceRevision?: string;
+        };
         /** the post-swap prompt overhead in the trigger estimate's coordinate: used for THIS
          *  compaction's post-measurement so PTL recovery/anti-thrash see the swapped prefix size. */
         overheadTokensAfter: number;
-        apply: (committedArtifactDigest?: string) => void;
+        apply: (committedIdentity: string) => void;
     };
     /** Model whose context window bounds the budget (the model that runs the next turn). */
     model: Model;
@@ -196,8 +198,9 @@ export interface MaybeCompactOptions {
     contextInstructionFiles?: string;
     signal?: AbortSignal;
     /**
-     * Manual compact() withdrawal signal — the composed cancel signals of the manual callers THIS
-     * pass claimed (a strict SUBSET of `signal`, which additionally carries the task's own abort).
+     * The pass's WITHDRAWAL signal — the run's caller-stop gate (the stop verbs and the task's own
+     * `signal`), composed with the cancel signals of the manual callers THIS pass claimed (a SUBSET
+     * of `signal`, which may additionally carry the leg's own abort).
      * Used only for failure ATTRIBUTION: when the summary call's failure is its abort outcome and
      * this signal has fired, the thrown error is stamped so {@link isCompactionManualCancel} holds —
      * the caller then treats the pass as withdrawn ("mooted") instead of summarizer evidence. It
@@ -488,13 +491,13 @@ export interface MaybeCompactOptions {
      * no-block/no-instructions (the caller's wrapper owns tracing; an observer bug must never feed the
      * caller's breaker or kill PTL recovery).
      */
-    preCompact?: Hooks["preCompact"];
+    preCompact?: (ctx: PreCompactContext) => PreCompactResult | undefined | Promise<PreCompactResult | undefined>;
     /**
      * design/134 (CC PostCompact parity) — observe-only, fired after the compaction LANDED
      * (appendCompaction done, post measurement taken). A throw is swallowed (same isolation contract
      * as {@link onCompaction}: the compaction already succeeded).
      */
-    postCompact?: Hooks["postCompact"];
+    postCompact?: (ctx: PostCompactContext) => void | Promise<void>;
     /**
      * MF-18 修② — observe-only: fired when a summary call's serialized conversation INPUT was
      * truncated to fit the compaction model's context window (the ~300K-session shape that previously