@sema-agent/core 7.55.0 → 7.56.0

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

@@ -324,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
@@ -393,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
@@ -416,10 +434,9 @@ 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 — 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;
+     *    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`.
@@ -466,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

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

@@ -11,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";
 /**
@@ -83,12 +100,18 @@ export declare const FILE_HISTORY_ERROR_CODES: readonly ["track_failed", "snapsh
 export interface FileHistoryError {
     /** `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, a target whose
-     *  history cannot be judged) must NOT wear this
+     *  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, and `exportHistory` answers it for a history it cannot
@@ -172,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<{
@@ -192,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;
@@ -345,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;
@@ -600,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
@@ -649,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;

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

@@ -32,6 +32,7 @@ function parentDirOf(absPath) {
     const parent = cut.slice(0, i);
     return win ? parent.replace(/\//g, "\\") : parent;
 }
+export const FILE_HISTORY_REFUSAL_CLASSES = Object.freeze(["link_safety", "base_unavailable", "key_unresolvable"]);
 export function trackKeyFamilyOf(root) {
     return isWinFormPath(root) ? "win" : "posix";
 }
@@ -53,17 +54,17 @@ export function resolveTrackKey(root, key, minted) {
     const win = isWinFormPath(root);
     if (minted !== undefined && minted.family !== trackKeyFamilyOf(root)) {
         if (minted.kind === "absolute") {
-            return { ok: false, reason: `foreign-family absolute key cannot be restored here (recorded under a ${minted.family} root, this root is ${trackKeyFamilyOf(root)}): ${key}` };
+            return { ok: false, reason: `foreign-family absolute key cannot be restored here (recorded under a ${minted.family} root, this root is ${trackKeyFamilyOf(root)}): ${key}`, class: "key_unresolvable" };
         }
         if (isUnsafeRelPathLike(normSlash(key)) || key.includes("\\")) {
-            return { ok: false, reason: `foreign-family key is ambiguous across path families (recorded under a ${minted.family} root, this root is ${trackKeyFamilyOf(root)}): ${key}` };
+            return { ok: false, reason: `foreign-family key is ambiguous across path families (recorded under a ${minted.family} root, this root is ${trackKeyFamilyOf(root)}): ${key}`, class: "key_unresolvable" };
         }
     }
     const keyN = win ? normSlash(key) : key;
     if (isAbsoluteForFamily(pathFamilyOf({ root }), keyN) || (win && /^[A-Za-z]:/.test(keyN)))
         return { ok: true, abs: key };
     if (win ? isUnsafeRelPathLike(keyN) : keyN.split("/").includes(".."))
-        return { ok: false, reason: `unsafe recorded key escapes root: ${key}` };
+        return { ok: false, reason: `unsafe recorded key escapes root: ${key}`, class: "key_unresolvable" };
     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"]);
@@ -272,18 +273,24 @@ export async function captureFileBackupViaEnv(env, absPath, root, signal) {
 }
 export async function worldStillMatchesMint(env, absPath, root, baseAvailable, mintedBlobHash, signal) {
     if (!baseAvailable) {
-        return { unchanged: false, reason: "the first touch recorded a base-UNAVAILABLE marker, whose whole purpose is to refuse a fake pristine later — an ambiguous failure may not erase it" };
+        return { verdict: "kept", reason: "the first touch recorded a base-UNAVAILABLE marker, whose whole purpose is to refuse a fake pristine later — an ambiguous failure may not erase it" };
     }
     const cap = await captureFileBackupViaEnv(env, absPath, root, signal);
     if (cap.state === "absent") {
-        return mintedBlobHash === null ? { unchanged: true } : { unchanged: false, reason: "the file recorded at the first touch is gone now" };
+        return mintedBlobHash === null ? { verdict: "unchanged" } : { verdict: "kept", reason: "the file recorded at the first touch is gone now" };
     }
     if (cap.state === "file") {
         if (mintedBlobHash === null)
-            return { unchanged: false, reason: "the path was recorded as NOT EXISTING at the first touch but holds bytes now" };
-        return cap.hash === mintedBlobHash ? { unchanged: true } : { unchanged: false, reason: "the file's bytes differ from the ones recorded at the first touch" };
+            return { verdict: "kept", reason: "the path was recorded as NOT EXISTING at the first touch but holds bytes now" };
+        return cap.hash === mintedBlobHash ? { verdict: "unchanged" } : { verdict: "kept", reason: "the file's bytes differ from the ones recorded at the first touch" };
     }
-    return { unchanged: false, reason: `the path could not be re-read to prove it is unchanged (${cap.state === "aborted" ? "aborted" : cap.cause})` };
+    return { verdict: "unjudged", reason: `the path could not be re-read to prove it is unchanged (${cap.state === "aborted" ? "aborted" : cap.cause})`, aborted: cap.state === "aborted" };
+}
+export function annulProofFailure(proof, absPath) {
+    if (proof.verdict === "kept") {
+        return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} is NOT retractable: ${proof.reason} — the write this retraction compensates for may have changed the file, and deleting the only baseline of a modified file is worse than keeping a stale record` } };
+    }
+    return { ok: false, error: { code: proof.aborted ? "aborted" : "track_failed", message: `first-touch record for ${absPath} was left in place: ${proof.reason}, so whether the write this retraction compensates for changed the file was not judged` } };
 }
 export function modeProvenDifferent(recorded, current) {
     return recorded !== undefined && current !== undefined && recorded !== current;
@@ -317,7 +324,7 @@ export async function applyFileRestoreViaEnv(env, absPath, target, opts) {
     }
     const w = await writeRestoredBytes(env, absPath, target.bytes, signal);
     if (!w.ok)
-        return { outcome: w.refused ? "refused" : "failed", reason: `write: ${w.code}` };
+        return w.refused ? { outcome: "refused", reason: `write: ${w.code}`, class: "link_safety" } : { outcome: "failed", reason: `write: ${w.code}` };
     const modeAfter = await applyRecordedMode(env, absPath, opts, undefined);
     return { outcome: "applied", ...(modeAfter === "unpreserved" || modeAfter === "applied_unpreserved" ? { modeNotPreserved: true } : {}) };
 }
@@ -330,6 +337,7 @@ async function restorePreflight(env, absPath, opts) {
                 reason: info.value.kind === "symlink"
                     ? "restore target is a SYMLINK — the recorded bytes belong to the file that was edited, not to whatever the link now points at"
                     : `restore target is a ${info.value.kind}, not a regular file — the recorded bytes are not this object's`,
+                class: "link_safety",
             },
         };
     }
@@ -345,6 +353,7 @@ async function restorePreflight(env, absPath, opts) {
         refused: {
             outcome: "refused",
             reason: `restore target's parent chain changed identity since it was recorded (recorded ${JSON.stringify(opts.parentIdent)}, now ${JSON.stringify(now)}) — writing here could land outside the task root`,
+            class: "link_safety",
         },
     };
 }
@@ -542,9 +551,8 @@ export class InMemoryFileHistoryStore {
             if (before !== undefined)
                 return { ok: false, error: { code: "conflict", message: before } };
             const proof = verify === undefined ? undefined : await worldStillMatchesMint(verify.env, absPath, root, t.baseAvailable, t.versions[0]?.blobHash ?? null, verify.signal);
-            if (proof !== undefined && !proof.unchanged) {
-                return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} is NOT retractable: ${proof.reason} — the write this retraction compensates for may have changed the file, and deleting the only baseline of a modified file is worse than keeping a stale record` } };
-            }
+            if (proof !== undefined && proof.verdict !== "unchanged")
+                return annulProofFailure(proof, absPath);
             const after = ineligible();
             if (after !== undefined)
                 return { ok: false, error: { code: "conflict", message: after } };
@@ -655,7 +663,7 @@ export class InMemoryFileHistoryStore {
                 let targetVersion = boundary.get(key);
                 if (targetVersion === undefined) {
                     if (!t.baseAvailable) {
-                        ledger.refused.push({ path: key, reason: "base_unavailable" });
+                        ledger.refused.push({ path: key, reason: "base_unavailable", class: "base_unavailable" });
                         continue;
                     }
                     targetVersion = 1;
@@ -667,7 +675,7 @@ export class InMemoryFileHistoryStore {
                 }
                 const resolved = resolveTrackKey(root, key, t.keyDesc);
                 if (!resolved.ok) {
-                    ledger.refused.push({ path: key, reason: resolved.reason });
+                    ledger.refused.push({ path: key, reason: resolved.reason, class: resolved.class });
                     continue;
                 }
                 let target;
@@ -698,7 +706,7 @@ export class InMemoryFileHistoryStore {
                 else if (applied.outcome === "identical")
                     ledger.identicalSkipped.push(key);
                 else if (applied.outcome === "refused")
-                    ledger.refused.push({ path: key, reason: applied.reason });
+                    ledger.refused.push({ path: key, reason: applied.reason, class: applied.class });
                 else
                     ledger.failed.push({ path: key, reason: applied.reason });
                 if ((applied.outcome === "applied" || applied.outcome === "identical") && applied.modeNotPreserved === true)

package/dist/core/gate-fold.d.ts

@@ -1,4 +1,4 @@
-import type { GatePass } from "./runner/gate-exit.js";
+import { type GatePass } from "./runner/gate-exit.js";
 import type { ToolGateResult } from "./hooks.js";
 /**
  * Run the fold over the pass: adjudicate, fold the hook-ask, tighten. Writes `req` (re-minted over the FINAL