@sema-agent/core 7.54.1 → 7.56.0

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-attestation.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The engine's ATTESTATION record — the one carrier of what an engine station knows about a decision and a policy cannot
+ * state: WHO settled the call's wait and WHICH question that answered (the settlement, the ask's origin word and class set,
+ * the digest of the arguments the answer licenses), and the facts the classifier stations, the in-fold unresolvable arms,
+ * the integrity guards and the policy fold record. It rides the decision as its `attestation` member and is read through
+ * {@link attestationOf} alone; the decision object's identity carries nothing.
+ *
+ * Minted only by {@link mintAttestation} and combined only by {@link mergeAttestation}: both freeze the record and enter it
+ * in a module-private brand set, so a value a caller composed — a literal, a copy, a structured clone — is not a record, and
+ * the decision receipt refuses a decision carrying one. A record is bound to the call it was minted for (`toolCallId` +
+ * `toolName`): handed back for another call it reads as absent. A spread of a decision keeps its record, and the record still
+ * says only what the engine minted — a refusal record on an allow is a contradiction the gate's exit refuses, and a
+ * resolution's answer binds the arguments it licensed (`inputDigest`).
+ *
+ * A leaf (type-only imports): the decision module that receives a record and the class derivation that reads one for its call
+ * both depend on it, and neither depends on the other through it.
+ */
+import type { AskClass, AskOrigin } from "./ask-origin.js";
+import type { ClassifierDenyCause, Settlement } from "./gate-outcome.js";
+import type { AutoModeClassifierRound } from "./auto-mode.js";
+import type { AskUnresolvableCause } from "./ask-unresolvable-notice.js";
+import type { PathDenialEvidence } from "../tools/fs/safety.js";
+import type { AskGuard } from "./tool-policy.js";
+export interface EngineAttestation {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    /** What ended the call's wait. The answer group — `settlement`, `origin`, `classes`, `inputDigest` — travels as one. */
+    readonly settlement?: Settlement;
+    /** The settled ask's origin word. */
+    readonly origin?: AskOrigin;
+    /** The settled ask's class set (`ASK_CLASSES` order), when the minting station held one. */
+    readonly classes?: readonly AskClass[];
+    /** `exactBoundInputHashOf` of the arguments the settlement licenses (an approver's edit, the snapshot shown, or the asked
+     *  args); absent when they have none (outside the bindable domain) — such a record licenses no bytes. */
+    readonly inputDigest?: string;
+    /** The FORM of a classifier round that did not rule (a classifier deny's cause). */
+    readonly classifierCause?: ClassifierDenyCause;
+    /** WHICH model answered a classification, on either arm. */
+    readonly classifierRound?: AutoModeClassifierRound;
+    /** Why an in-fold deny refused an ask nobody could resolve. */
+    readonly unresolvableCause?: AskUnresolvableCause;
+    /** The classes of the OTHER asks a policy fold collapsed into this one (each contributor's classes, unioned) — so a fact the
+     *  fold does not copy (a guard, an unreadable-rule fact, a bare real-approval bit) is not lost behind the ask that won the
+     *  slot. Written by the policy fold and by the gate's own writers of a standing ask's carried classes; the one carrier of
+     *  those classes. */
+    readonly foldedClasses?: readonly AskClass[];
+    /** WHICH integrity guards stand behind this ask — a removal of a protected location, an unverifiable recursive delete, shell
+     *  text the engine cannot read (or an environment that did not answer the read station), the session-transcript write,
+     *  another person's shared artifact. Engine findings (the guard policies, the read station's silence, the artifact tool's
+     *  consent): the class derivation reads them as classes and as explainers of the real-approval bit, so only a record carries
+     *  them. Never copied onto the approval request or the park row. */
+    readonly guards?: readonly AskGuard[];
+    /** Where a path deny row refused the call — the row, the view of the target it met, the face the call is on. The gate's
+     *  exit mints the refusal's card from it; the judge that found the row is its only writer. */
+    readonly pathDenial?: PathDenialEvidence;
+    /** A seat refused the call's arguments because no approval can be bound to them: the refusal's sentence, carried by the
+     *  refusal itself — the gate's deny exit reads it (the remedy it gives) instead of judging again. */
+    readonly bindingRefusal?: string;
+}
+/** The members a station attests — everything but the call binding. */
+export type AttestationMembers = Omit<EngineAttestation, "toolCallId" | "toolName">;
+/** Mint a record for `call`. Engine stations only: not re-exported from `src/index.ts`. The values are DETACHED snapshots, so a
+ *  caller that later mutates the settlement object it was handed cannot rewrite what the engine attests. */
+export declare function mintAttestation(call: {
+    toolCallId: string;
+    toolName: string;
+}, members: AttestationMembers): EngineAttestation;
+/** Is `v` a record the engine minted (the brand alone — no binding)? The receipt's test. */
+export declare function isEngineAttestation(v: unknown): v is EngineAttestation;
+/** THE read: the record `d` carries FOR `call` — a branded record bound to that call, else `undefined` (a record bound to
+ *  another call is a replayed one and reads as absent). Read off the own data member, never through an accessor. */
+export declare function attestationOf(d: unknown, call: {
+    toolCallId: string;
+    toolName: string;
+}): EngineAttestation | undefined;
+/**
+ * Combine two records for `call`, member GROUP by group: the later record's group stands where it has one, the earlier's
+ * fills a group the later lacks. A record not bound to `call` contributes nothing. `answer` scope is the veto's merge: the
+ * earlier record contributes ONLY its answer, and only when the later carries none — a person's yes rides a later layer's
+ * deny (invariant I3) while the refusing station's own facts stay its own.
+ */
+export declare function mergeAttestation(call: {
+    toolCallId: string;
+    toolName: string;
+}, earlier: EngineAttestation | undefined, later: EngineAttestation | undefined, scope?: "all" | "answer"): EngineAttestation | undefined;
+/** `d` with `members` attested for `call`, merged over the record it already carries for that call (the new members' groups
+ *  win). Always a fresh object — the receipt hands out frozen ones. */
+export declare function attest<T extends object>(d: T, call: {
+    toolCallId: string;
+    toolName: string;
+}, members: AttestationMembers): T;
+/** `d` carrying `record` (a fresh object), or `d` itself when there is no record to put on it. */
+export declare function withAttestation<T extends object>(d: T, record: EngineAttestation | undefined): T;

package/dist/core/engine-attestation.js

@@ -0,0 +1,70 @@
+const ATTESTATION_GROUP_OF = {
+    settlement: "answer",
+    origin: "answer",
+    classes: "answer",
+    inputDigest: "answer",
+    classifierCause: "classifierCause",
+    classifierRound: "classifierRound",
+    unresolvableCause: "unresolvableCause",
+    foldedClasses: "foldedClasses",
+    guards: "guards",
+    pathDenial: "pathDenial",
+    bindingRefusal: "bindingRefusal",
+};
+const ATTESTATION_MEMBERS = Object.keys(ATTESTATION_GROUP_OF);
+const groupLead = (g) => ATTESTATION_MEMBERS.find((k) => ATTESTATION_GROUP_OF[k] === g);
+const ENGINE_ATTESTATIONS = new WeakSet();
+function detachedMember(v) {
+    if (Array.isArray(v))
+        return Object.freeze([...v]);
+    if (typeof v !== "object" || v === null)
+        return v;
+    return Object.freeze(Object.fromEntries(Object.entries(v).map(([k, x]) => [k, typeof x === "object" && x !== null ? Object.freeze(Array.isArray(x) ? [...x] : { ...x }) : x])));
+}
+export function mintAttestation(call, members) {
+    const record = { toolCallId: call.toolCallId, toolName: call.toolName };
+    for (const k of ATTESTATION_MEMBERS)
+        if (members[k] !== undefined)
+            record[k] = detachedMember(members[k]);
+    const minted = Object.freeze(record);
+    ENGINE_ATTESTATIONS.add(minted);
+    return minted;
+}
+export function isEngineAttestation(v) {
+    return typeof v === "object" && v !== null && ENGINE_ATTESTATIONS.has(v);
+}
+const boundTo = (r, call) => isEngineAttestation(r) && r.toolCallId === call.toolCallId && r.toolName === call.toolName ? r : undefined;
+export function attestationOf(d, call) {
+    if (typeof d !== "object" || d === null)
+        return undefined;
+    return boundTo(Object.getOwnPropertyDescriptor(d, "attestation")?.value, call);
+}
+export function mergeAttestation(call, earlier, later, scope = "all") {
+    const a = boundTo(earlier, call);
+    const b = boundTo(later, call);
+    if (a === undefined)
+        return b;
+    const members = {};
+    if (b !== undefined)
+        for (const k of ATTESTATION_MEMBERS)
+            if (b[k] !== undefined)
+                members[k] = b[k];
+    let filled = false;
+    for (const g of new Set(Object.values(ATTESTATION_GROUP_OF))) {
+        if ((scope === "answer" && g !== "answer") || members[groupLead(g)] !== undefined || a[groupLead(g)] === undefined)
+            continue;
+        for (const k of ATTESTATION_MEMBERS)
+            if (ATTESTATION_GROUP_OF[k] === g && a[k] !== undefined)
+                members[k] = a[k];
+        filled = true;
+    }
+    if (!filled)
+        return b;
+    return mintAttestation(call, members);
+}
+export function attest(d, call, members) {
+    return withAttestation(d, mergeAttestation(call, attestationOf(d, call), mintAttestation(call, members)));
+}
+export function withAttestation(d, record) {
+    return record === undefined ? d : { ...d, attestation: record };
+}

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

@@ -16,7 +16,10 @@
  *    memory distiller's chat seat key), and `inheritedHostEnv` subtracts every entry whose value is one,
  *    compared whole, under every policy. A credential resolved per request (a per-model auth hook's answer) is not in
  *    it: the host that resolves it declares it. The same inheritance-only reading as the word above.
+ *  - `mods.skill_seat` — a skill carries its own hooks: `SkillSpec.mods` registrations are admitted on every leg that loads
+ *    the skill and take part only while the skill is active there (from its activation to the run's end, a park and its
+ *    resume included); they are the leg's own (no delegated child dispatches them or is screened by them).
  */
-export declare const ENGINE_CAPABILITIES: readonly ["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld"];
+export declare const ENGINE_CAPABILITIES: readonly ["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat"];
 /** One word of {@link ENGINE_CAPABILITIES}. */
 export type EngineCapability = (typeof ENGINE_CAPABILITIES)[number];

package/dist/core/engine-capabilities.js

@@ -1 +1 @@
-export const ENGINE_CAPABILITIES = Object.freeze(["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld"]);
+export const ENGINE_CAPABILITIES = Object.freeze(["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat"]);

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
@@ -314,6 +324,14 @@ export interface EngineNotice {
      *    runs. ONCE PER LEG PER (api, key set) — a deployment fact, not a request fact. Audience `operator`;
      *    `detail: { keys, api, modelId, sessionId, runId }` — `keys` the key NAMES in `extraBody`'s order (never a
      *    value), `api` the wire the adapter speaks, `modelId` the catalog id the request was sent as.
+     *  - `"model.capability_downgraded"` (#1830) — a capability the session's requests used was withheld from the model
+     *    they were sent to: today, images replaced by a one-line placeholder because the model's entry declares no image
+     *    input (`Model.input` without `"image"`; `capabilityOf` in `brain/model-capability.ts` is the one reading, and an
+     *    entry that does not declare `input` keeps its images). The message names the model and the way out (declare the
+     *    image input, or switch models). Never minted for reasoning a model declares off — the reasoning resolution's
+     *    drop arm (`TaskResult.effectiveReasoning.dropped`) is that fact's face. ONCE PER SESSION PER (model, capability)
+     *    (the session's announced record); one report per request also becomes the operator trace `vision.placeholder`.
+     *    Audience `user`; `detail: { model, capability: "image", status: "declared_off", sessionId, runId }`.
      *  - `"context.tool_turn_repaired"` (#1224) — a provider request was built from a transcript that breaks the
      *    tool-turn law, and the request view restored it (`engine/llm/tool-turns.ts`; the transcript is never
      *    rewritten): a block after an assistant's tool calls moved ahead of them (`trailing_text`), a result recorded
@@ -383,15 +401,25 @@ export interface EngineNotice {
      *    `detail: { problem, sessionId, runId }`.
      *  - `"config.execution_env_capability_invalid"` — a remote env DECLARES a boolean capability key
      *    (`isolation`, `suspendable`, `canonicalPathAuthoritative`) with a non-boolean value; ABSENCE is a
-     *    supported reading of each and stays silent. Once per key per run; `detail: { key, valueType }`.
+     *    supported reading of each and stays silent. Once per key per run; `detail: { key, valueType }`. Also minted for
+     *    `withheldEnv` (key `"withheldEnv"`) when it is neither a list of findings nor `"unknown"`, read at a shell call of
+     *    a root leg (once per run).
      *  - `"config.secret_env_scrubbed"` (#1081) — the D1 fail-closed `scrub` policy, or the deployment's
      *    own credentials (`declareWithheldEnv`: a declared name, or a value equal to a declared or engine-held
      *    credential value), withheld one or more keys from a spawned child's environment (a tool's shell, an
      *    oracle gate, or a language server).
      *    Once per PROCESS, shared by every scrub site ({@link import("./secret-env.js").announceSecretEnvScrub});
      *    `detail: { names, ownCredentials? }` — every withheld key's name, never a value; `ownCredentials`, present
-     *    only when one was withheld, the subset withheld as own credentials, by name or by value (under any policy,
-     *    `"all"` included).
+     *    only when one was withheld, the subset that is the deployment's own credential, by name or by value, whichever
+     *    rule withheld it (withheld under any policy, `"all"` included).
+     *  - `"inherit_env.names_withheld"` (#1963) — the same fact for the person whose run drives a tool shell: the variables
+     *    of the engine's environment that shell does not receive (`ExecutionEnv.withheldEnv`), the scrub's half (the run's
+     *    `inheritEnv` hands them on) and the deployment's own credentials (no policy does). Audience `user`. Read as each
+     *    call to the engine's own shell tool starts on a root leg (the answer can grow during a run: a credential the engine
+     *    takes in when it first routes a model is withheld from the next child); once per SESSION per name set (the
+     *    session's announced record). `detail: { state, names?, ownCredentials?, sessionId, runId? }` — `state` `"withheld"`
+     *    carries the operator row's split (names only, never a value); `"unknown"` (the environment answered `"unknown"`)
+     *    carries no names and says the engine could not determine them.
      *  - `"config.credential_not_withheld"` (#1816) — a credential value the engine was handed (a brain's key or credential
      *    header, a model entry's or a peer's credential header, a consolidation seat's key) is no credential (a placeholder
      *    such as `EMPTY`, fewer than eight characters, one character repeated): it is used as given, but a variable holding
@@ -406,8 +434,11 @@ 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
+     *    on a governed tree it stays owed — a prepare's by the leg's next write — and once none lands (a settle's failure is the leg's
+     *    last write; a parked leg's suspend record landed before it) the next leg reads the content after the newest record as off-target,
+     *    which the sentence says for the phase that failed. 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
@@ -452,14 +483,16 @@ export interface EngineNotice {
      *    the first eight `{ rule, scopeRoot }`, `count` all of them; `rule` is the rule text as the store served it, through the same reading
      *    as `permission.allowed_tool_not_granted`'s `entries[].entry` (the original, not a spelling of it, when it is at most 1 024 code points;
      *    a longer one is cut to 1 024 plus the truncation mark, 1 025 in all), `scopeRoot` neutralized and bounded. Audience `user`.
-     *  - `"config.session_rules_earlier_grammar"` — a session's stored permission rules (`RunnerDeps.sessionPolicyStore`) hold
-     *    entries the rule grammar they were written in reads as nothing: an allow entry admits nothing, and a `toolDeny` entry
-     *    this engine's grammar reads as no rule makes those rules refuse every call until they are rewritten. The message names
+     *  - `"config.session_rules_earlier_grammar"` — a session's stored permission rules (`RunnerDeps.sessionPolicyStore`) were
+     *    written in an earlier rule grammar and hold entries it reads otherwise than this engine's would: an entry that grammar
+     *    reads as nothing (an allow admits nothing; a `toolDeny` entry this engine's grammar reads as no rule makes those rules
+     *    refuse every call until they are rewritten), or one whose meaning a later grammar revised — the entry keeps its writer's
+     *    meaning, or takes this grammar's when its writer's could not read it, and the message says which, with both. The message names
      *    the session, the bucket, the entries (the first five, the rest counted), the reader's word and the way out. Audience
      *    `user`. Once per distinct entry set per bucket per rule layer (the run's own rules, each ancestor's inherited ones).
      *    `detail: { bucket, storedGrammar, entries: [{ entry, reader }], rewrite: { by, stampsGrammar }, rulesSessionId,
      *    sessionId }` — `entries` every one, `entry` through the same reading as `permission.allowed_tool_not_granted`'s;
-     *    `reader` ∈ `no_rule` / `named_no_tool`; `rewrite.by` = `operator_write_without_rev`; `rulesSessionId` the session
+     *    `reader` ∈ `no_rule` / `named_no_tool` / `grammar_revised`; `rewrite.by` = `operator_write_without_rev`; `rulesSessionId` the session
      *    whose rules they are (an ancestor's on a delegated child), `sessionId` the run that read them.
      *  - `"config.durable_gate_unavailable"` — a durable-approval MANDATE is in force on a leg with NO
      *    checkpoint store: the per-principal `forceDurableGate` entitlement, or the task's own
@@ -619,7 +652,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.
@@ -10,14 +11,31 @@ declare function joinUnder(root: string, rel: string): string;
 declare function parentDirOf(absPath: string): string | undefined;
 /** The re-join verdict of {@link resolveTrackKey}: an absolute path to operate on, or a NAMED
  *  refusal (the fail-closed arm — a recorded key that would escape `root` is never coerced into
- *  something writable). A-082 idx5: named so the fence can be part of the public surface. */
+ *  something writable) carrying the restore ledger's class for it. A-082 idx5: named so the fence can be part of the public surface. */
 export type FileHistoryTrackKeyResolution = {
     ok: true;
     abs: string;
 } | {
     ok: false;
     reason: string;
+    class: "key_unresolvable";
 };
+/**
+ * Why a restore declined a file it could reach — the `class` of every {@link FileHistoryRestoreResult.refused}
+ * row, named by the arm that decided the refusal (the shared env half and key resolver below, or a backend's
+ * own base-unavailable arm) and copied by the backend, never re-derived from the reason text:
+ *  · `link_safety` — the object at the path is not the regular file the record describes (a symlink, a
+ *    directory or other kind), its parent chain no longer resolves to the recorded identity, or a guarded
+ *    write found the path changed under it;
+ *  · `base_unavailable` — the first touch recorded that the path's pre-edit bytes could not be read (DV-14),
+ *    so there is no pristine version to write;
+ *  · `key_unresolvable` — the recorded key cannot be re-joined against this root (it would escape it, or it
+ *    came from another path family and is absolute or ambiguous here).
+ * Damage to the store's own records (a missing version record, a missing or corrupt blob) is not a refusal
+ * in any backend: it is a `failed` row.
+ */
+export declare const FILE_HISTORY_REFUSAL_CLASSES: readonly ["link_safety", "base_unavailable", "key_unresolvable"];
+export type FileHistoryRefusalClass = (typeof FILE_HISTORY_REFUSAL_CLASSES)[number];
 /** The path family a track key was MINTED under — the half a bare key string cannot carry. */
 export type FileHistoryKeyFamily = "posix" | "win";
 /**
@@ -80,21 +98,60 @@ 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
-     *  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
+    /** `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 HISTORY-PRESERVATION law refused the call:
+     *  doing it would discard or overwrite history that is not the caller's — `adoptScope` / `importHistory`
+     *  onto a target that holds history of its own (the non-destructive-target law), or `annulTrack` of a
+     *  record that is no longer just the caller's own mint (a boundary froze it, it grew past its first
+     *  version, another edit was served it, or the proof read found the file moved or the base-unavailable
+     *  marker standing). It is never a fault, and it is never "could not judge": a verb that cannot JUDGE its
+     *  law (an unreadable graph, a listing that fails, a proof read that cannot re-read the path) answers its
+     *  own `*_failed` (or `aborted`) with the fault. A caller reads `conflict` as "the law answered; the history
+     *  stands" — the engine's fork-carry seat says nothing on it because the only verb that seat calls is
+     *  `adoptScope`, whose `conflict` is the target law alone, 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, 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 +174,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.
@@ -129,10 +195,12 @@ export type FileHistoryRestoreResult = {
     filesChanged: string[];
     /** Track keys already equal to the target (untouched — content-hash proven, never mtime). */
     identicalSkipped: string[];
-    /** Per-file security/consistency refusals (skipped, counted, never failing the whole restore). */
+    /** Per-file security/consistency refusals (skipped, counted, never failing the whole restore); `class` is
+     *  the closed reading of why ({@link FileHistoryRefusalClass}), `reason` the sentence for a person. */
     refused: Array<{
         path: string;
         reason: string;
+        class: FileHistoryRefusalClass;
     }>;
     /** Per-file operational failures (env write/remove errors, aborts after k writes). */
     failed: Array<{
@@ -149,6 +217,34 @@ export interface FileHistoryDiffStats {
     insertions: number;
     deletions: number;
 }
+/** `Runner.rewindFiles`' request — the out-of-run code-only rewind (the reference's `rewind_files` control request). */
+export interface RewindFilesRequest {
+    /** The session whose history is converged. It must exist. */
+    sessionId: string;
+    /** The boundary key: the entry id of a turn's FIRST user entry — the id space `TaskSpec.rewindFilesTo`
+     *  addresses ("the files as they were when that turn began"). An entry with no boundary of its own refuses. */
+    to: string;
+    /** Preview only: the working tree is not written (a fork whose history was never carried may have its carry
+     *  completed — the same carry the session's next run performs). */
+    dryRun?: boolean;
+    /** Caller cancel for the restore. */
+    signal?: AbortSignal;
+}
+/** `Runner.rewindFiles`' answer. A refusal is a thrown `Error` carrying a `code`. */
+export type RewindFilesResult = 
+/** `preview: null` = no preview for this request (the backend implements no `diffStats`, or answered none);
+ *  an empty `filesChanged` with zero counts = a real "nothing would change". */
+{
+    dryRun: true;
+    preview: FileHistoryDiffStats | null;
+}
+/** The store's ledger as it answered: `complete`, or `partial` with every refused / failed file on it. */
+ | {
+    dryRun: false;
+    restore: FileHistoryRestoreResult & {
+        outcome: "complete" | "partial";
+    };
+};
 /** The line-diff bound (see {@link countRestoreLineDiff}): a pair whose edit distance exceeds this
  *  is counted as a whole-file replacement. Public so a preview UI can state what it is showing. */
 export declare const FILE_HISTORY_DIFF_LINE_BUDGET = 2000;
@@ -302,7 +398,9 @@ export interface FileHistoryStore {
      * still matches what the mint recorded (bytes still absent for an existed-not mint, still the same
      * hash for a captured one). A file that changed keeps its record, because the alternative is
      * deleting the only baseline of a file the agent really did modify — damage rewind could no longer
-     * reach, which is strictly worse than a stale record.
+     * reach, which is strictly worse than a stale record. Every refusal above is the history-preservation
+     * law (`conflict`, see {@link FileHistoryError.code}); a proof read that cannot re-read the path at all
+     * judged nothing, and keeps the record with `track_failed` (`aborted` when the signal fired) instead.
      */
     annulTrack(scope: string, absPath: string, root: string, verify?: {
         env: ExecutionEnv;
@@ -353,10 +451,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 +567,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 +589,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>;
 }
 /**
@@ -550,13 +655,30 @@ export declare function captureFileBackupViaEnv(env: ExecutionEnv, absPath: stri
  * refusal state that stops a later touch from minting already-modified bytes as pristine — erasing
  * it on an ambiguous failure re-opens exactly the DV-14 hole it exists to close. It stays
  * retractable through the `"proven"` path, which needs no evidence read at all.
+ *
+ * THREE verdicts, because a backend answers them three ways: `unchanged` retracts; `kept` is the
+ * history-preservation law keeping the record (`conflict`); `unjudged` is a read that never happened —
+ * the path could not be re-read, or the signal fired — so nothing was judged and the record stays with
+ * the verb's own failure (`track_failed`, or `aborted` when `aborted` is true), never with the law's word.
  */
-export declare function worldStillMatchesMint(env: ExecutionEnv, absPath: string, root: string, baseAvailable: boolean, mintedBlobHash: string | null, signal?: AbortSignal): Promise<{
-    unchanged: true;
+export type FileHistoryMintProof = {
+    verdict: "unchanged";
 } | {
-    unchanged: false;
+    verdict: "kept";
     reason: string;
-}>;
+} | {
+    verdict: "unjudged";
+    reason: string;
+    aborted: boolean;
+};
+export declare function worldStillMatchesMint(env: ExecutionEnv, absPath: string, root: string, baseAvailable: boolean, mintedBlobHash: string | null, signal?: AbortSignal): Promise<FileHistoryMintProof>;
+/** A backend's ONE mapping of a proof that did not say `unchanged` onto the annul verb's failure — the two
+ *  bundled backends call it, and an out-of-tree backend reuses it with the proof read itself. */
+export declare function annulProofFailure(proof: Exclude<FileHistoryMintProof, {
+    verdict: "unchanged";
+}>, absPath: string): FileHistoryResult & {
+    ok: false;
+};
 /**
  * DV-13's metadata rule applied to the MODE axis (design/381 slice 3), and it is a rule about
  * EVIDENCE rather than about equality: metadata may prove two states DIFFERENT, never the same. Two
@@ -599,9 +721,13 @@ export type FileRestoreApplyOutcome =
 } | {
     outcome: "identical";
     modeNotPreserved?: true;
-} | {
+}
+/** Every refusal this half decides is about the object at the path (its kind, its parent chain, a guarded
+ *  write's precondition), so its class is `link_safety`; a backend copies it into the ledger row. */
+ | {
     outcome: "refused";
     reason: string;
+    class: "link_safety";
 } | {
     outcome: "failed";
     reason: string;
@@ -751,7 +877,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;