@sema-agent/core 7.54.1 → 7.55.0

package/dist/core/compliance.d.ts

@@ -1,4 +1,4 @@
-/** Closed compliance profile set (CC 2.1.221 policy-limits profiles). */
+/** Closed compliance profile set (policy-limits profiles). */
 export type ComplianceProfile = "hipaa" | "zdr";
 /** Closed capability set the ENGINE can veto end-to-end (see the module header for the entry-point
  *  map — a capability is admitted here only with its full interception story). */
@@ -17,7 +17,7 @@ export interface CompliancePosture {
     additionalDenies?: readonly ComplianceCapability[];
 }
 /**
- * Builtin per-profile deny floors, mapped from the CC 2.1.221 policy-limits pair table onto the
+ * Builtin per-profile deny floors, mapped from the policy-limits pair table onto the
  * capabilities this engine manages: hipaa denies `allow_web_fetch` ⇒ `web_fetch`. (CC's
  * `allow_memory_sync` row maps onto the org-memory plane and joins this table together with the
  * memory-admission seam; CC has no MCP/workflow rows — those stay reachable via `additionalDenies`.)

package/dist/core/context-edit.d.ts

@@ -10,7 +10,7 @@ import { type ContextWindowOverlay } from "./context-settings.js";
  */
 export declare const EDIT_FRACTION = 0.7;
 /**
- * CC-parity trigger geometry (verified against CC 2.1.207): the reactive autocompact trigger sits a
+ * Trigger geometry: the reactive autocompact trigger sits a
  * FIXED DISTANCE below the window, not at a fixed fraction —
  *   effectiveWindow = autocompactWindow − min(maxOutputTokens, 20000)   (CC `Nye`, cap `uMd`)
  *   trigger         = effectiveWindow − 13000                           (CC `dSo`, buffer `rMd`)
@@ -18,7 +18,7 @@ export declare const EDIT_FRACTION = 0.7;
  * 167000 (83.5% of nominal), a 1M window at 967000.
  *
  * 1M DIVERGENCE, stated as fact rather than as an equivalence (anchoring re-check 2026-08-23): CC
- * carries a MODEL-DEFAULT autocompact-window table (2.1.223 `j3u` :242918 — `claude-sonnet-5`
+ * carries a MODEL-DEFAULT autocompact-window table (`claude-sonnet-5`
  * default 967000, and since 223 a surface dimension: `remote_cowork` / `local-agent` 500000), so a
  * 1M sonnet-5 gets 967000 as its window and 934000 as its trigger WITHOUT anyone configuring
  * anything. We ship no such table: a model declaring only `contextWindow: 1e6` triggers at 967000
@@ -52,14 +52,14 @@ export declare function contextEditFrontier(window: number): number;
 /**
  * The `RunnerDeps.microCompact.machine` vocabulary — ONE clearing machine, switchable:
  *
- *  - `"cc"` (default): the CC 2.1.223 `yId` machine — keep 5, a ≥20000-token minimum-savings gate
+ *  - `"cc"` (default): the reference's machine — keep 5, a ≥20000-token minimum-savings gate
  *    (below it the pass is a byte-identical no-op), ONE deep clear of everything beyond the keep
  *    window, the window base counts already-cleared/offloaded occurrences (they hold their keep
  *    slots), and CC's plain marker bytes.
  *  - `"off"`: no proactive frontier clearing; the machine gets its one shot at the blocking point
  *    of the guard chain instead (trace trigger `"blocking"`).
  *
- * WHOLE-MACHINE CROSS-CHECK against the 2.1.250 corpus (design/374 slice 4 — the "the knob number
+ * WHOLE-MACHINE CROSS-CHECK against the reference corpus (design/374 slice 4 — the "the knob number
  * was copied, the machine was not" disease is checked by naming the machine's parts, not the one
  * number). CC's four load-bearing parts, each against its 250 coordinate, all verified present here:
  *   ① the ≥20000-token minimum-savings gate — {@link MIN_CLEAR_SAVINGS_TOKENS} vs `Mnn`
@@ -70,7 +70,7 @@ export declare function contextEditFrontier(window: number): number;
  *      re-resolved member-by-member off the 250 corpus, byte-identical (see that constant).
  *   ③ cleared-but-recoverable — CC replaces the content with a POINTER, not a void
  *      (`<persisted-output>Tool result saved to: {path}\n\nUse Read to view</persisted-output>`,
- *      cli250.js:40044), which is what makes a keep window of 5 survivable at all. Ours is the same
+ *      cli296.js:219492: "Tool result saved to: "), which is what makes a keep window of 5 survivable at all. Ours is the same
  *      construction in this engine's carrier: the full text is offloaded first and the marker
  *      carries the store ref ({@link ContextEditOptions.offload} → {@link clearOneResult}), read
  *      back through ReadToolResult instead of a filesystem path (registered divergence D-9). The
@@ -92,8 +92,7 @@ export declare const MICRO_COMPACT_MACHINES: readonly ["off", "cc"];
 export type MicroCompactMachine = (typeof MICRO_COMPACT_MACHINES)[number];
 /**
  * How many most-recent CANDIDATE tool results keep their content when the stale-result pass runs:
- * 5 (CC 2.1.223 `uAp`; 2.1.250 `var k=5` beside the call site, cli250.js:58373, and 2.1.245 carries
- * the same value — zero drift across 245→250; same value again on CC 88's `timeBasedMCConfig`, i.e.
+ * 5 (the reference's hard-coded constant beside its call site; the same value in every corpus generation checked, i.e.
  * stable across all three corpus generations, and it is a hard-coded constant upstream, not a
  * setting). The #384 adjudication adopted 5 CONDITIONAL on the whole machine coming with it (20k
  * gate + deep clear + re-ordered backstops); the machine carries that condition (§3.5: the gate

package/dist/core/cross-boundary-taint.d.ts

@@ -88,7 +88,8 @@ export interface CrossBoundaryCheck {
     /** This call's obligation under the tree's state at this moment (the station reads it on the final arguments). */
     obligation(call: CrossBoundaryCall): CrossBoundaryObligation;
     /** The allow exit's rule, on the bytes that run and the party that decided: re-reads the obligation; a mandate the decider cannot
-     *  answer refuses; otherwise the off-target-read bit the call owes is joined and the session record is written before it runs. */
+     *  answer refuses; otherwise the session record carrying the off-target-read bit the call owes is written, and the bit joins the
+     *  tree, before it runs — a call the exit refuses joins nothing. */
     exit(call: CrossBoundaryCall, decidedBy: HostDecider): Promise<CrossBoundaryExitRefusal | undefined>;
 }
 /** The gate input's seat for {@link CrossBoundaryCheck}: present on a leg whose station is ENGAGED (a posture is declared, the leg runs
@@ -183,14 +184,19 @@ export declare function crossBoundaryPostureUndeclaredNotice(at: {
     readonly tree: CrossBoundaryTree;
 }): EngineNotice;
 /** Where a session record's write was owed: a leg's prepare, an exit before its call runs, a suspend before its row, a settle. */
-export type CrossBoundaryRecordPhase = "prepare" | "exit" | "suspend" | "settle"; /** The one mint of `config.cross_boundary_record_unwritten`: a session record that could not be written and refused nothing — on a tree
+export type CrossBoundaryRecordPhase = "prepare" | "exit" | "suspend" | "settle";
+/** The one mint of `config.cross_boundary_record_unwritten`: a session record that could not be written and refused nothing — on a tree
  *  that is not governed (no judgment reads the record), or at a governed leg's prepare / settle (no call to refuse; the next leg then
- *  reads the content after the newest record as off-target). A governed exit refuses its call and a governed suspend its row instead. */
+ *  reads the content after the newest record as off-target). A governed exit refuses its call and a governed suspend its row instead.
+ *  `catchUp`: an earlier record of the same write landed and the one that carries the tree's newer bits did not — on a governed tree
+ *  that earlier record covers the content before it, so the sentence says the next leg may not route its device calls to a person.
+ *  Minted once per state a leg could not write. */
 export declare function crossBoundaryRecordUnwrittenNotice(at: {
     readonly sessionId: string;
     readonly runId: string;
     readonly phase: CrossBoundaryRecordPhase;
     readonly governed: boolean;
+    readonly catchUp: boolean;
     readonly cause: string;
 }): EngineNotice;
 /** The face a protocol tool (an MCP tool, an A2A skill) carries for its JUDGED `toolAxes` entry (`readToolAxes`' copy): the empty leg

package/dist/core/cross-boundary-taint.js

@@ -155,9 +155,11 @@ export function crossBoundaryRecordUnwrittenNotice(at) {
     return {
         code: "config.cross_boundary_record_unwritten",
         message: `The session's cross-boundary record could not be written at ${at.phase} (${at.cause.slice(0, 300)}) — ` +
-            (at.governed
-                ? "the tree is governed: the next leg on this session reads the content after its newest record as off-target, so its device calls are put to a person."
-                : "the tree is not governed: no judgment reads the record, so its failure refused nothing; the tree's growth, or the leg's end, writes next."),
+            (!at.governed
+                ? "the tree is not governed: no judgment reads the record, so its failure refused nothing; the tree's growth, or the leg's end, writes next, and a failure of this same state is not reported again."
+                : at.catchUp
+                    ? "the tree is governed, and an earlier record of this write landed: the catch-up record that carries the tree's newer bits has not been written. Until #2160 lands, the next leg on this session may read the content before that earlier record as covered and may not route its device calls to a person (KNOWN-LIMITS KL-469-c); the terminal shape is fail-closed."
+                    : "the tree is governed: the next leg on this session reads the content after its newest record as off-target, so its device calls are put to a person."),
         detail: { sessionId: at.sessionId, runId: at.runId, phase: at.phase, governed: at.governed, cause: at.cause.slice(0, 300) },
     };
 }

package/dist/core/decision-receipt.js

@@ -1,6 +1,6 @@
 import { types } from "node:util";
 import { ASK_CLASSES, ASK_ORIGINS, isAskClass, isAskOrigin, isPersistedRuleMandate, PERSISTED_RULE_MANDATES } from "./ask-origin.js";
-import { AUTO_MODE_FALLBACK_CAUSES, isAutoModeFallbackCause } from "./auto-mode.js";
+import { AUTO_MODE_FALLBACK_CAUSES, isAutoModeFallbackCause, isDenialLimitBound } from "./auto-mode.js";
 import { thrownText } from "./thrown-value.js";
 const ENGINE_REFUSALS = new WeakSet();
 export const refusedOutOfContract = (message) => {
@@ -62,7 +62,7 @@ const NESTED_CONTRACTS = [
 ];
 const nonNegativeInteger = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
 const NESTED_VALUE_FENCES = {
-    denialLimitFallback: { consecutive: nonNegativeInteger, total: nonNegativeInteger, limit: (v) => v === "consecutive" || v === "total" },
+    denialLimitFallback: { consecutive: nonNegativeInteger, total: nonNegativeInteger, limit: isDenialLimitBound },
     probeCause: { code: (v) => typeof v === "string" && v.length > 0 },
     "probeCause.roots": { total: nonNegativeInteger },
     "probeCause.further": { total: nonNegativeInteger },

package/dist/core/effective-path-target.d.ts

@@ -65,7 +65,7 @@ export interface ToolPathBases {
  */
 export declare function pathTargetBaseOf(pt: Pick<ToolCallPathTarget, "base"> | undefined, bases: ToolPathBases): string | undefined;
 /**
- * design/116 批④ #8 (CC 2.1.198 RWp, bundle :332987) — decompose an ABSOLUTE glob pattern into a base
+ * design/116 批④ #8 — decompose an ABSOLUTE glob pattern into a base
  * directory + relative pattern: cut at the last separator before the first glob metachar (`* ? [ {`); a
  * pattern with no metachar splits dirname/basename. `undefined` for a relative pattern (the caller keeps it
  * as-is) or when no usable base can be derived; a namespace refusal ({@link win32NamespaceScreen}, run

package/dist/core/engine-notice.d.ts

@@ -62,8 +62,8 @@ export interface EngineNotice {
      *    firing rule as its skills sibling below (once per delivered frame, on the carrying message's receipt).
      *  - `"permission.allowed_tool_not_granted"` — an allow list holds entries that grant (or refuse) nothing: a loaded skill's
      *    `allowed-tools` / `disallowed-tools`, the request's `TaskSpec.allowedTools`, the deployment's `RunnerDeps.allowedTools`.
-     *    `*` (it voids an allow list; on a deny list it reads as nothing and the rest still refuses), `mcp__*` (no server
-     *    named), a rule on a tool with no such rule form (an allow by path on a tool other than `Read` / `Edit`, a deny by host),
+     *    `*` (it voids an allow list; on a deny list it reads as nothing and the rest still refuses), `mcp__*` / `mcp__*__*` (no server
+     *    named), a rule on a tool with no such rule form (an allow by path on a tool other than `Read` / `Edit`),
      *    a shape the rule grammar refuses, a tool name stale against the run's roster. The run goes on and asks for those tools
      *    as usual. Audience `user`; once per prepared task for the skill and request lists (`detail.sessionId` present), once
      *    per Runner for the deployment's (at construction, no session). `detail: { sessionId?, entries: [{ source, entry,
@@ -231,6 +231,16 @@ export interface EngineNotice {
      *    above's keys MINUS `to` (nothing moved, and a `to` naming a model that was not used is the one lie a
      *    consumer cannot detect); `action` is the discriminator, so a reader never infers the posture from that
      *    absence. Audience `operator`, same entitlement reading as its twin. Dedup key: (code, seat) per run.
+     *  - `"route.seat_detached"` (same pre-flight, the third POSTURE) — a derived seat no primary model can stand in for
+     *    (the advisor tool: advising the agent with its own model is no advice) failed the pairing pre-flight, so the seat
+     *    is taken off THIS run: the advisor tool is not mounted (the leg's manifest says `advisor.reason: "route_refused"`).
+     *    `detail: { seat, from, cause, fixHint, action: "detached", sessionId?, runId? }` — `route.classifier_unroutable`'s
+     *    keys, `action` the discriminator. Audience `operator`. Dedup key: (code, seat) per run.
+     *  - `"advisor.not_attached"` (`src/core/advisor-verdict.ts`) — a task's `advisorModel` did not attach for a reason the
+     *    person is told: `unknown_model`, `advisor_unranked`, `weakest_tier`, `main_unranked`, `pairing` (the advisor is on a
+     *    weaker tier than the main model) or `hold_unknown` (whether the conversation switched it off could not be read).
+     *    `detail: { advisorModel, mainModel, reason, sessionId, runId? }`. Root legs only (a delegated child tells nobody).
+     *    Audience `user`. Dedup key: (code, reason, advisorModel, mainModel) per SESSION (the once-per-session record).
      *  - `"classifier.fallback"` (the classifier's candidate ladder, `src/core/runner/classifier-ladder.ts`)
      *    — a gated call's classification did NOT rule on the classifier seat and was re-asked on the model
      *    behind it. Sibling of `route.fallback_to_primary` one layer later: that one fires when the derived
@@ -406,8 +416,12 @@ export interface EngineNotice {
      *    {@link import("./cross-boundary-taint.js").crossBoundaryPostureUndeclaredNotice}. Audience `operator`.
      *  - `"config.cross_boundary_record_unwritten"` — a session's cross-boundary record the engine owed could not be written (the
      *    store threw, or answered with no entry id) and refused nothing: on a tree that is not governed no judgment reads the record;
-     *    at a governed leg's prepare or settle the next leg reads the content after the newest record as off-target. Per failed write;
-     *    `detail: { sessionId, runId, phase, governed, cause }` (`phase`: `prepare` / `exit` / `suspend` / `settle`). Minted by
+     *    at a governed leg's prepare or settle the next leg reads the content after the newest record as off-target — except where an
+     *    earlier record of the same write landed and its catch-up did not: that catch-up record has not been written, and until #2160
+     *    lands the next leg may read the content before the earlier record as covered and may not route its device calls to a person
+     *    (KNOWN-LIMITS KL-469-c; the terminal shape is fail-closed), which the sentence says. Once per state a leg could not write;
+     *    `detail: { sessionId, runId, phase, governed, cause }` (`phase`: `prepare` / `exit` / `suspend` / `settle`, where that state
+     *    first failed). Minted by
      *    {@link import("./cross-boundary-taint.js").crossBoundaryRecordUnwrittenNotice}. Audience `operator`.
      *  - `"config.permission_mode_unavailable"` — the permission mode a task requested is not the mode the leg runs
      *    under: the deployment denies it (`by: "operator_deny"` — `RuntimeCaps.bypassPermissions` / `autoMode` is
@@ -619,7 +633,7 @@ export interface EngineNotice {
      *    secret token never rides a notice). A DIFFERENT record already on file is not this notice — it
      *    is the `checkpoint.execution_outcome_conflict` throw (an engine defect, propagated).
      *
-     *  - `"classifier.denial_limit"` (#548, CC 2.1.250 `FO`/"too many classifier denials in headless
+     *  - `"classifier.denial_limit"` (#548, "too many classifier denials in headless
      *    mode") — the auto-mode classifier's DENIAL LIMIT was reached (3 consecutive blocks, or 20 in the
      *    run; `RunnerDeps.autoMode.denialLimit`) and the fallback ask it turns into was never JUDGED by
      *    anyone. Two lanes reach it. SYNCHRONOUS: no approver to go to — none wired, a blanket

package/dist/core/exec-output-tail.d.ts

@@ -58,7 +58,7 @@ export interface StreamCursorState {
     acceptedBytes: number;
     /** `tail.sourceSkippedBytes()` as of the last slice — the delta is disclosed exactly once. */
     disclosedSkippedBytes: number;
-    /** Incremental UTF-8 decoder (CC 2.1.220 shape: StringDecoder holds a split multi-byte char across
+    /** Incremental UTF-8 decoder (StringDecoder holds a split multi-byte char across
      *  reads instead of emitting replacement chars at every read boundary). */
     decoder: StringDecoder;
 }

package/dist/core/file-history-retention.d.ts

@@ -13,7 +13,7 @@
  *
  * PROVENANCE OF THE DEFAULT (not a taste call, and not a JSDoc-only constraint): the reference
  * implementation caps its own file-history at the newest 100 snapshots and evicts the rest — CC
- * 2.1.250 holds the cap as a module constant (`R1e = 100`) and applies it in the snapshot reducer
+ * holds the cap as a module constant and applies it in the snapshot reducer
  * (`if (E.length > R1e) R = E.slice(-R1e), <evict>(E.slice(0, E.length - R1e), R, …).catch(…)`),
  * i.e. keep the newest N by commit order, hand the evicted ones to a best-effort eviction pass, and
  * never let that pass fail the turn that triggered it. Its eviction unlinks a backup only when no

package/dist/core/file-history-store.d.ts

@@ -1,3 +1,4 @@
+import type { GovernanceRetryClass } from "./governance-codes.js";
 import { type FileHistoryRetentionPolicy } from "./file-history-retention.js";
 import type { ExecutionEnv } from "../internal/harness-types.js";
 /** rel path of `child` under `root` in "/" form (win root) / verbatim form (posix root); null when not under.
@@ -80,21 +81,54 @@ export declare function resolveTrackKey(root: string, key: string, minted?: File
  *  value rather than keeping its own list. */
 export declare const FILE_HISTORY_ERROR_CODES: readonly ["track_failed", "snapshot_failed", "restore_failed", "adopt_failed", "not_found", "aborted", "unsupported_format", "conflict"];
 export interface FileHistoryError {
-    /** `not_found` = no boundary for that (scope, entryId); `aborted` = the signal fired (or the
+    /** `not_found` = no boundary for that (scope, entryId) — an absence, never a fault (a boundary that is there
+     *  but cannot be read is the verb's `*_failed` with the fault); `aborted` = the signal fired (or the
      *  fencing discarded a timed-out attempt); `conflict` = a non-destructive-target law refused
      *  (adopt/import onto a scope with its own history) — and ONLY that, because a caller decides
      *  whether to stay quiet on it: the engine's fork-carry seat treats `conflict` as "already carried,
      *  or grown its own" and says nothing, so an adoption that failed for any OTHER reason (a corrupt
-     *  source graph, a blob it cannot reach, a consumed-id ledger it cannot carry — including the
-     *  tombstones a publish owes for unreadable residue it is about to replace) must NOT wear this
+     *  source graph, a blob it cannot reach, a consumed-id ledger it cannot carry, a target whose
+     *  history cannot be judged) must NOT wear this
      *  code or the failure disappears into that silence — those are `adopt_failed`, which the
      *  ADOPTION FAMILY shares: `importHistory` publishes under the same target law and answers the
-     *  same code for the same non-conflict failures (its `unsupported_format` names a bad ENVELOPE or
+     *  same code for the same non-conflict failures, and `exportHistory` answers it for a history it cannot
+     *  read whole (its `unsupported_format` names a bad ENVELOPE or
      *  work its shape drove; a fault in the PUBLISH step itself — the disk refusing a good graph —
      *  answers `adopt_failed`); `unsupported_format`
      *  = a foreign-epoch or wrong-version envelope; the rest name the verb that failed. */
     code: (typeof FILE_HISTORY_ERROR_CODES)[number];
     message: string;
+    /** The backend's judgment of a FAULT — it could not do what it was asked — as a {@link GovernanceRetryClass}
+     *  word (the words are defined there, once). Stated whenever the backend knows: from a caught error's code,
+     *  or from a state it found itself (a damaged record is `terminal`). Absent when it does not know, and on an
+     *  outcome that is not a fault (an absent boundary's `not_found`, the empty-target law, an abort). Every
+     *  reader — the engine's edit refusal, the rewind disclosure, a failed rewind task's `terminal.detail`, a
+     *  host's metrics — reads this cell, never the message text. */
+    permanence?: GovernanceRetryClass;
+}
+/** A fault's judgment as the member a {@link FileHistoryError} spreads in: `{ permanence }` when judged, `{}`
+ *  when not — so an unjudged failure carries no `permanence` member at all. */
+export type FileHistoryFault = {
+    readonly permanence?: GovernanceRetryClass;
+};
+/** The bundled backends' ONE reading of a caught value — by its `code` member only, never its message. */
+export declare function caughtFault(caught: unknown): FileHistoryFault;
+/** A record the backend found damaged (unparseable, the wrong shape, failing its own digest): no retry
+ *  repairs it. */
+export declare const DAMAGED_RECORD: FileHistoryFault;
+/**
+ * The `Error` the engine hands `RunnerDeps.onError` on every `phase: "rewind"` delivery: `code` and
+ * `permanence` are the failure's own, read the same way as on a {@link FileHistoryError}; `message` is the
+ * engine's sentence about it (not the store's text). A failure the engine itself observed carries the same
+ * shape: a timed-out capture is `aborted`; a backend that threw instead of answering is the verb's own
+ * `*_failed` code with no `permanence` and the thrown value as the standard `Error.cause`.
+ */
+export declare class FileHistoryStoreError extends Error implements Pick<FileHistoryError, "code" | "permanence"> {
+    readonly code: FileHistoryError["code"];
+    readonly permanence?: FileHistoryError["permanence"];
+    constructor(failure: Pick<FileHistoryError, "code" | "permanence">, message: string, thrown?: {
+        value: unknown;
+    });
 }
 export type FileHistoryResult = {
     ok: true;
@@ -117,6 +151,15 @@ export type FileHistoryTrackResult = {
     ok: false;
     error: FileHistoryError;
 };
+/** {@link FileHistoryStore.exportHistory}'s answer: the envelope, `null` = nothing to export (the one meaning of
+ *  `null`), or a history that cannot be read whole — `adopt_failed` with the fault, naming what cannot be read. */
+export type FileHistoryExportResult = {
+    ok: true;
+    history: FileHistoryExport | null;
+} | {
+    ok: false;
+    error: FileHistoryError;
+};
 /**
  * Three-state discriminant + full per-file ledger on EVERY arm (design/381 DV-15). Refusals are
  * never folded into benign skips; `base_unavailable` (DV-14) is a refusal reason.
@@ -353,10 +396,13 @@ export interface FileHistoryStore {
      * from "the env died after k writes". Restore is per-file idempotent (identical files skip), so
      * the documented recovery for a partial outcome is: re-run the same restore; it converges. There
      * is NO all-or-nothing guarantee and none is claimed. Task-level policy on `"partial"` lives in
-     * the CALLER (prepare defaults to fail-loud; see DV-15).
+     * the CALLER (prepare defaults to fail-loud; see DV-15). A boundary never made is `not_found` and
+     * touches NOTHING — no file read or written, an empty ledger — since the engine's refusal of a
+     * rewind without a boundary is exactly this answer (the contract kit checks the bytes).
      */
     restore(scope: string, entryId: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileHistoryRestoreResult>;
-    /** Whether a boundary exists for (scope, entryId). */
+    /** Whether (scope, entryId) has a USABLE boundary: `false` both for one never made and for one that is there but
+     *  cannot be read — `restore` is the verb that says which (`not_found` / `restore_failed` with the fault). */
     canRestore(scope: string, entryId: string): Promise<boolean>;
     /**
      * Optional dry-run: per-file change stats for a prospective restore (CC diffStats; design/381
@@ -466,7 +512,11 @@ export interface FileHistoryStore {
      * empty OR already holds a graph with the exact same import identity/digest (pure idempotent
      * re-publish). A non-empty target with any other content ⇒ typed `conflict` refusal — atomic
      * visibility prevents half-graphs, this law prevents publishing the WRONG complete graph over
-     * locally-grown history.
+     * locally-grown history. A target whose history cannot be judged ⇒ `adopt_failed`, before any blob is
+     * fetched; a source that cannot supply a referenced blob ⇒ `adopt_failed`. `exportHistory` answers a
+     * {@link FileHistoryExportResult}: the whole graph, `null` for nothing to export, or `adopt_failed` with the
+     * fault for a history it cannot read whole (an unreadable tracked set, boundaries that cannot be judged) —
+     * never a partial graph, and never a `null` that hides a fault.
      */
     /**
      * NO `dispose` / lifecycle verb, and that is a decision rather than an omission (design/381 slice 3,
@@ -484,7 +534,7 @@ export interface FileHistoryStore {
      *    sibling file store in this family offers.
      * A deployment that needs cross-process exclusion takes the assembled backend, or brings its own.
      */
-    exportHistory?(scope: string): Promise<FileHistoryExport | null>;
+    exportHistory?(scope: string): Promise<FileHistoryExportResult>;
     importHistory?(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
 }
 /**
@@ -751,7 +801,7 @@ export declare class InMemoryFileHistoryStore implements FileHistoryStore {
     diffStats(scope: string, entryId: string, env: ExecutionEnv, root: string): Promise<FileHistoryDiffStats | null>;
     reap(scope: string, keepEntryIds: string[]): Promise<number>;
     adoptScope(fromScope: string, toScope: string): Promise<FileHistoryResult>;
-    exportHistory(scope: string): Promise<FileHistoryExport | null>;
+    exportHistory(scope: string): Promise<FileHistoryExportResult>;
     /** The export projection as a SYNCHRONOUS function — the import's final claim needs to compare a
      *  target's identity without yielding (see the publish step). */
     private exportOf;

package/dist/core/file-history-store.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { thrownText } from "./thrown-value.js";
+import { readMember, thrownText } from "./thrown-value.js";
 import { isAbsoluteForFamily, isWinFormPath, pathFamilyOf, relativeInEveryFamily } from "../tools/fs/safety.js";
 import { fileHistoryBoundariesToKeep, resolveFileHistoryRetention } from "./file-history-retention.js";
 const normSlash = (p) => p.replace(/\\/g, "/");
@@ -67,6 +67,26 @@ export function resolveTrackKey(root, key, minted) {
     return { ok: true, abs: joinUnder(root, keyN) };
 }
 export const FILE_HISTORY_ERROR_CODES = Object.freeze(["track_failed", "snapshot_failed", "restore_failed", "adopt_failed", "not_found", "aborted", "unsupported_format", "conflict"]);
+const CAUGHT_CODE_RETRY_CLASS = new Map([
+    ...["EACCES", "EPERM", "EROFS", "ENAMETOOLONG", "EFBIG", "ENOTDIR", "EISDIR"].map((c) => [c, "terminal"]),
+    ...["EAGAIN", "EWOULDBLOCK", "EBUSY", "EINTR", "ETIMEDOUT", "EMFILE", "ENFILE"].map((c) => [c, "transient"]),
+]);
+export function caughtFault(caught) {
+    const code = readMember(caught, "code");
+    const judged = typeof code === "string" ? CAUGHT_CODE_RETRY_CLASS.get(code) : undefined;
+    return judged === undefined ? {} : { permanence: judged };
+}
+export const DAMAGED_RECORD = Object.freeze({ permanence: "terminal" });
+export class FileHistoryStoreError extends Error {
+    code;
+    constructor(failure, message, thrown) {
+        super(message, thrown !== undefined ? { cause: thrown.value } : undefined);
+        this.name = "FileHistoryStoreError";
+        this.code = failure.code;
+        if (failure.permanence !== undefined)
+            this.permanence = failure.permanence;
+    }
+}
 export const FILE_HISTORY_DIFF_LINE_BUDGET = 2000;
 export function countRestoreLineDiff(current, target) {
     const isBinary = (b) => b !== undefined && b.includes(0);
@@ -491,7 +511,7 @@ export class InMemoryFileHistoryStore {
             return { ok: true, minted: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} could not be persisted: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} could not be persisted: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async annulTrack(scope, absPath, root, verify) {
@@ -532,7 +552,7 @@ export class InMemoryFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "track_failed", message: `annulling the first-touch record for ${absPath} failed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "track_failed", message: `annulling the first-touch record for ${absPath} failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async snapshot(scope, entryId, env, root, signal) {
@@ -601,14 +621,14 @@ export class InMemoryFileHistoryStore {
             }
             catch (err) {
                 sc.spentAttempts.add(entryId);
-                return { ok: false, error: { code: "snapshot_failed", message: `boundary for entry "${entryId}" could not be committed: ${thrownText(err)}` } };
+                return { ok: false, error: { code: "snapshot_failed", message: `boundary for entry "${entryId}" could not be committed: ${thrownText(err)}`, ...caughtFault(err) } };
             }
             this.applyBoundaryRetention(scope, entryId);
             return { ok: true };
         }
         catch (err) {
             sc.spentAttempts.add(entryId);
-            return { ok: false, error: { code: "snapshot_failed", message: thrownText(err) } };
+            return { ok: false, error: { code: "snapshot_failed", message: thrownText(err), ...caughtFault(err) } };
         }
         finally {
             sc.activeAttempts.delete(entryId);
@@ -688,7 +708,7 @@ export class InMemoryFileHistoryStore {
         }
         catch (err) {
             const touched = empty.filesChanged.length > 0 || empty.identicalSkipped.length > 0 || empty.refused.length > 0 || empty.failed.length > 0;
-            return { outcome: touched ? "partial" : "failed", ...empty, error: { code: "restore_failed", message: thrownText(err) } };
+            return { outcome: touched ? "partial" : "failed", ...empty, error: { code: "restore_failed", message: thrownText(err), ...caughtFault(err) } };
         }
     }
     async canRestore(scope, entryId) {
@@ -795,14 +815,12 @@ export class InMemoryFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "adopt_failed", message: `adoptScope failed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "adopt_failed", message: `adoptScope failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async exportHistory(scope) {
         const sc = this.scopes.get(scope);
-        if (sc === undefined || (sc.tracked.size === 0 && sc.boundaries.size === 0))
-            return null;
-        return this.exportOf(sc);
+        return { ok: true, history: sc === undefined || (sc.tracked.size === 0 && sc.boundaries.size === 0) ? null : this.exportOf(sc) };
     }
     exportOf(sc) {
         return {
@@ -826,9 +844,9 @@ export class InMemoryFileHistoryStore {
             const shaped = validateFileHistoryExport(data);
             if (!shaped.ok)
                 return shaped;
-            const existing = await this.exportHistory(scope);
-            if (existing !== null) {
-                if (fileHistoryExportDigest(existing) === fileHistoryExportDigest(data))
+            const existing = this.scopes.get(scope);
+            if (existing !== undefined && (existing.tracked.size > 0 || existing.boundaries.size > 0)) {
+                if (fileHistoryExportDigest(this.exportOf(existing)) === fileHistoryExportDigest(data))
                     return { ok: true };
                 return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" already holds a DIFFERENT history — a first import requires an empty target and a retry is legal only for the identical envelope (atomic visibility prevents half-graphs; this law prevents publishing the wrong complete graph over locally-grown history)` } };
             }
@@ -848,7 +866,7 @@ export class InMemoryFileHistoryStore {
             }
         }
         catch (err) {
-            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async importStaged(scope, data, srcGetBlob, needed) {
@@ -862,10 +880,10 @@ export class InMemoryFileHistoryStore {
                     bytes = await srcGetBlob(hash);
                 }
                 catch (err) {
-                    return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fetch failed: ${thrownText(err)}` } };
+                    return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fetch failed: ${thrownText(err)}`, ...caughtFault(err) } };
                 }
                 if (bytes === undefined)
-                    return { ok: false, error: { code: "not_found", message: `source blob ${hash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
+                    return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
                 if (createHash("sha256").update(bytes).digest("hex") !== hash) {
                     return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fails content-address integrity — refused, nothing published` } };
                 }
@@ -894,7 +912,7 @@ export class InMemoryFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
 }

package/dist/core/gate-fold.js

@@ -10,6 +10,7 @@ import { failedJudgmentDeny } from "./runner/policy-throw.js";
 import { thrownText } from "./thrown-value.js";
 import { argsAsTheToolReads } from "./effective-path-target.js";
 import { foldHookAsk, refuseOutOfContractDecision } from "./tool-policy.js";
+import { withProbeMandate } from "./ask-origin.js";
 import { applyUnansweredSilence, readStationAnswer, silencedBy } from "./shell-read-silence.js";
 import { asksUnstated, permissionSeatAt, unstatedAskMessage } from "./mode-policy.js";
 export async function runGateFold(pass) {
@@ -133,7 +134,7 @@ export async function runGateFold(pass) {
             pass.tightenedBy = input.shellGated === true ? "shell_gate" : "safety";
         }
         else if (alreadyAsking && probeMandated === true && pass.decision.action === "ask") {
-            pass.decision = { ...pass.decision, probeMandated: true };
+            pass.decision = withProbeMandate(pass.decision, probeReason);
         }
     }
     if (input.peerMessage === true && pass.decision.action === "allow" && input.autoMode !== undefined) {
@@ -218,7 +219,7 @@ function applyShellReadVerdict(pass, answer, toolName, shellGated) {
                 pass.shellReadDetails = verdict.details;
             if (pass.decision.action !== "allow") {
                 if (pass.decision.action === "ask")
-                    pass.decision = { ...pass.decision, probeMandated: true, ...silencedBy(verdict, pass.decision) };
+                    pass.decision = { ...withProbeMandate(pass.decision, account), ...silencedBy(verdict, pass.decision) };
                 return;
             }
             const candidate = normalizeReadRootCandidate(verdict.readRootCandidate);

package/dist/core/gate-lanes.js

@@ -1,18 +1,19 @@
 import { argsAsTheToolReads, withArgsReading } from "./effective-path-target.js";
 import { attest, attestationOf, bindableArgsOf, decisionText, foldHookAsk, mergeAttestation, refusalOf, refuseOutOfContractDecision, withAttestation } from "./tool-policy.js";
-import { arbitrateByMode, classifyAsk, decisionAskClassesOf, fileCommandOptionsSentence, persistedRuleMandateOf, safetyAxisOf, stampAskOrigin } from "./ask-origin.js";
+import { arbitrateByMode, classifyAsk, decisionAskClassesOf, dontAskRefusalMessage, fileCommandOptionsSentence, persistedRuleMandateOf, safetyAxisOf, stampAskOrigin } from "./ask-origin.js";
 import { classifierParseFailureDenyMessage, denialLimitFallbackMessage, rungDidNotRule, unarmedWindow } from "./auto-mode.js";
 import { classifierNoRulingArm, settleNoRulingAsk } from "./classifier-unavailable-arm.js";
 import { SETTLEMENT_NOBODY_JUDGED } from "./gate-outcome.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
+import { toolFace } from "./tool-catalog-entries.js";
 import { applyPersistedTightening, disclosedRuleSet } from "./persisted-rule-arms.js";
 import { skillAllowDecision, skillRowRefusal } from "./skill-grant.js";
 import { allowRuleShadowOf } from "./allow-entry.js";
 import { CD_GIT_COMPOUND_SENTENCE, changesDirectoryBeforeGit, readOnlyShellVerdict } from "./read-only-shell.js";
 import { readShellCommand } from "./shell-run-candidates.js";
-import { COMMAND_RULE_TOOL } from "./permission-rule-model.js";
-import { catalogRuleFaceOf } from "./tool-registry.js";
+import { COMMAND_RULE_TOOL, ruleShapeOf } from "./permission-rule-model.js";
+import { catalogRuleFaceOf, isProtectedWrite } from "./tool-registry.js";
 import { callFaceSeat } from "./tool-roster.js";
 import { heldBy, wireOf } from "./tool-name-readings.js";
 import { asksUnstated, modeAcceptsFileCommand, permissionSeatAt, unstatedAskMessage } from "./mode-policy.js";
@@ -26,6 +27,8 @@ import { agentIdOf, judgedInputOf, raiseToolCheck } from "./mods/stations.js";
 import { readToolChecks } from "./tool-check-reading.js";
 import { policyThrowLine, reportPolicyThrow } from "./runner/policy-throw.js";
 const QUESTION_TOOL_NAMES = new Set([ASK_USER_QUESTION_TOOL_NAME]);
+const CONTENT_ROUTING_CONTRACTS = new Set(["ask-user-question", "structured-output", "report-blocked"].map((id) => toolFace(id).contract.contractId));
+const routesContent = (f) => f?.engineMounted === true && CONTENT_ROUTING_CONTRACTS.has(f.contractId);
 function parkWith(suspendAsk, parkArgs, carry) {
     return suspendAsk(...parkArgs, carry);
 }
@@ -159,7 +162,7 @@ export async function runGateLanes(pass) {
     pass.decision = orgAnswer.decision;
     const readPersistedRules = (req) => readPersistedRuleLane(input.persistedRules, req, input.abortSignal);
     const laneReq = Object.freeze(pass.policyRewrite !== undefined ? await withArgsReading(pass.req, pass.policyRewrite, pass.callSignal ?? input.abortSignal) : { ...pass.req });
-    const laneAnswer = input.persistedRules !== undefined && wireOf("lanes.persistedLaneSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME ? await readPersistedRules(laneReq) : undefined;
+    const laneAnswer = input.persistedRules !== undefined && !routesContent(pass.req.face) ? await readPersistedRules(laneReq) : undefined;
     {
         const tightened = applyPersistedTightening(pass.decision, laneAnswer, laneReq);
         pass.decision = tightened.tightened === "deny" ? refusalOf(tightened.decision, laneReq.args) : tightened.decision;
@@ -272,7 +275,7 @@ export async function runGateLanes(pass) {
             ["hook", () => (pass.hookAllowedBy !== undefined && pass.policyRewrite === undefined ? { entries: pass.hookAllowedBy, clear: () => ({ action: "allow", message: "a PreToolUse hook allowed this call", decisionReason: "hook" }), afterClear: async () => undefined } : undefined)],
             ["deployment", () => {
                     const hit = input.deploymentAllows?.allowing(pass.req, mode);
-                    return hit && { entries: hit.entries, clear: () => listAllow("deployment_rule", "the deployment's", hit.entries), afterClear: () => notifier.notifyAsync(() => input.deploymentAllows?.onAllowed?.({ toolName: pass.req.toolName, toolCallId, entries: hit.entries }), "toolGate.allowedToolsResolved") };
+                    return hit && { entries: hit.entries, ...(hit.positions !== undefined ? { positions: hit.positions } : {}), clear: () => listAllow("deployment_rule", "the deployment's", hit.entries), afterClear: () => notifier.notifyAsync(() => input.deploymentAllows?.onAllowed?.({ toolName: pass.req.toolName, toolCallId, entries: hit.entries }), "toolGate.allowedToolsResolved") };
                 }],
             ["persisted", () => storedAllows && {
                     entries: storedAllows.map((r) => r.rule),
@@ -286,7 +289,7 @@ export async function runGateLanes(pass) {
                 }],
             ["request", () => {
                     const hit = input.requestAllows?.allowing(pass.req, mode);
-                    return hit && { entries: hit.entries, clear: () => listAllow("request_rule", "this run's", hit.entries), afterClear: () => notifier.notifyAsync(() => input.requestAllows?.onAllowed?.({ toolName: pass.req.toolName, toolCallId, entries: hit.entries }), "toolGate.allowedToolsResolved") };
+                    return hit && { entries: hit.entries, ...(hit.positions !== undefined ? { positions: hit.positions } : {}), clear: () => listAllow("request_rule", "this run's", hit.entries), afterClear: () => notifier.notifyAsync(() => input.requestAllows?.onAllowed?.({ toolName: pass.req.toolName, toolCallId, entries: hit.entries }), "toolGate.allowedToolsResolved") };
                 }],
         ];
         const shadows = [];
@@ -299,6 +302,7 @@ export async function runGateLanes(pass) {
                     continue;
                 if (allowMayClear()) {
                     pass.decision = hit.clear();
+                    pass.clearedBy = { ...allowRuleShadowOf(member, hit.entries), ...(hit.positions !== undefined ? { positions: hit.positions } : {}) };
                     await hit.afterClear();
                     if (member !== "hook")
                         afterRuleClear();
@@ -468,7 +472,7 @@ export async function runGateLanes(pass) {
                 pass.decision = refusalOf({
                     action: "deny",
                     message: verdict.mode === "dontAsk"
-                        ? `refused by the dontAsk permission mode: this call needed approval (${verdict.askClass}) and the mode answers no ask; run under a mode with an approver, or change the call`
+                        ? dontAskRefusalMessage({ toolName, classification: pass.askClassification, coveredWrite: isProtectedWrite(pass.req), ruleShape: ruleShapeOf(pass.req, "allow") ?? toolName })
                         : `refused by the bypassPermissions permission mode: the write-protection judge could not resolve this write's target, and with nobody to ask the mode refuses rather than releases it`,
                     decisionReason: "mode",
                 }, finalArgs);
@@ -636,7 +640,7 @@ export async function runGateLanes(pass) {
             }
             let editLane;
             const editLaneReq = Object.freeze(await withArgsReading(pass.req, editArgs, callSignal ?? input.abortSignal));
-            if (input.persistedRules !== undefined && wireOf("lanes.persistedEditSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME) {
+            if (input.persistedRules !== undefined && !routesContent(pass.req.face)) {
                 editLane = await readPersistedRules(editLaneReq);
                 const editTightened = applyPersistedTightening(recheck, editLane, editLaneReq);
                 recheck = editTightened.decision;