@sema-agent/core 7.55.0 → 7.57.0

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,19 +100,27 @@ 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
-     *  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. */
+     *  same code for the same non-conflict failures — a source that cannot supply a referenced blob (it is
+     *  absent, its read throws, or its bytes do not hash to their address), a target whose history cannot
+     *  be judged, a fault in staging or publishing a good graph (the disk refusing it) — and `exportHistory`
+     *  answers it for a history it cannot read whole. `unsupported_format` is the import DOOR's refusal and
+     *  nothing else: a foreign-epoch or wrong-version envelope, or an envelope whose content the closed sets
+     *  (or the backend's own record-naming rules) cannot hold, refused before any blob is fetched; 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}
@@ -172,10 +197,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 +219,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;
@@ -277,8 +332,9 @@ export declare function fileHistoryExportDigest(data: FileHistoryExport): string
  * The import DOOR's structural judgment, shared by every backend (a second implementation is a second
  * opinion about what is safe to accept): the envelope must carry THIS format version and every row
  * must be shaped and self-described from the closed sets — `unsupported_format` otherwise, never a
- * coercion. Backends call this BEFORE fetching a single blob, so a foreign-epoch payload costs
- * nothing and changes nothing.
+ * coercion and never a throw (a payload that cannot be read is refused in the same word). Backends call
+ * this BEFORE fetching a single blob, so a foreign-epoch payload costs nothing and changes nothing, and
+ * `unsupported_format` is a word only this door (and a backend's own record-naming rule) says.
  */
 export declare function validateFileHistoryExport(data: FileHistoryExport): FileHistoryResult;
 /**
@@ -345,7 +401,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;
@@ -513,7 +571,10 @@ export interface FileHistoryStore {
      * 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. 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
+     * fetched; a source that cannot supply a referenced blob — absent, its read throws, or bytes that fail
+     * their content address — ⇒ `adopt_failed`, and so is a fault in staging or publishing the graph.
+     * `unsupported_format` is the door's refusal alone ({@link validateFileHistoryExport}, before any blob
+     * is fetched). `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.
@@ -600,13 +661,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 +727,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"]);
@@ -157,6 +158,14 @@ export function fileHistoryExportDigest(data) {
     return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
 }
 export function validateFileHistoryExport(data) {
+    try {
+        return judgeFileHistoryEnvelope(data);
+    }
+    catch (err) {
+        return { ok: false, error: { code: "unsupported_format", message: `file-history import payload cannot be read: ${thrownText(err)}` } };
+    }
+}
+function judgeFileHistoryEnvelope(data) {
     const bad = (message) => ({ ok: false, error: { code: "unsupported_format", message } });
     if (data === null || typeof data !== "object")
         return bad("file-history import payload is not an envelope");
@@ -181,6 +190,8 @@ export function validateFileHistoryExport(data) {
         if (typeof t.baseAvailable !== "boolean" || !Array.isArray(t.versions))
             return bad(`tracked row ${t.relOrAbsPath} is missing its base-availability state or version chain`);
         for (const v of t.versions) {
+            void v?.backupTime;
+            void v?.parentIdent;
             if (typeof v?.version !== "number" || !Number.isInteger(v.version) || v.version < 1)
                 return bad(`tracked row ${t.relOrAbsPath} carries a non-integer version number`);
             if (v.blobHash !== null && (typeof v.blobHash !== "string" || !/^[0-9a-f]{64}$/.test(v.blobHash)))
@@ -272,18 +283,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 +334,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 +347,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 +363,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 +561,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 +673,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 +685,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 +716,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)
@@ -866,7 +884,7 @@ export class InMemoryFileHistoryStore {
             }
         }
         catch (err) {
-            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
+            return { ok: false, error: { code: "adopt_failed", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async importStaged(scope, data, srcGetBlob, needed) {
@@ -880,12 +898,12 @@ export class InMemoryFileHistoryStore {
                     bytes = await srcGetBlob(hash);
                 }
                 catch (err) {
-                    return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fetch failed: ${thrownText(err)}`, ...caughtFault(err) } };
+                    return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${thrownText(err)}`, ...caughtFault(err) } };
                 }
                 if (bytes === undefined)
                     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` } };
+                    return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fails content-address integrity — refused, nothing published` } };
                 }
                 staged.set(hash, bytes);
             }
@@ -912,7 +930,7 @@ export class InMemoryFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
+            return { ok: false, error: { code: "adopt_failed", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
 }

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

package/dist/core/gate-fold.js

@@ -2,6 +2,8 @@ import { inlineUntrusted } from "./untrusted-text.js";
 import { markTightenMessage } from "./safety-axis-vocab.js";
 import { PROBE_REASON_MAX, normalizeProbeCause } from "./checkpoint-store.js";
 import { normalizeReadRootCandidate } from "./read-root-candidate.js";
+import { engineFailClosedExit, hookDenyExit } from "./runner/gate-exit.js";
+import { readRejudge, screenRewrite } from "./rewrite-rejudge.js";
 import { traceHookCrash } from "./gate-crash-trace.js";
 import { writeProtectionMandated, writeProtectionTightenDecision } from "./write-protect.js";
 import { createGateDeadline, awaitWriteProtectionJudgment, gateWaitFailureOf, withGateTimeout } from "./gate-bounded-await.js";
@@ -26,7 +28,7 @@ export async function runGateFold(pass) {
     catch (error) {
         unread = { error };
     }
-    pass.decision = unread !== undefined ? failedJudgmentDeny(unread.error, callSignal ?? input.abortSignal, (e) => traceHookCrash(input, e, notifier), "the call's target reading", { toolName, toolCallId }) : adjudicate ? refuseOutOfContractDecision(await (callSignal !== undefined ? adjudicate(pass.req, callSignal) : adjudicate(pass.req))) : { action: "allow" };
+    pass.decision = unread !== undefined ? failedJudgmentDeny(unread.error, callSignal ?? input.abortSignal, (e) => traceHookCrash(input, e, notifier), "the call's target reading", { toolName, toolCallId }) : adjudicate ? refuseOutOfContractDecision(await (callSignal !== undefined ? adjudicate(pass.req, callSignal) : adjudicate(pass.req)), { call: pass.req }) : { action: "allow" };
     {
         const read = ledger.fromDecision(pass.decision);
         pass.decision = read.decision;
@@ -38,6 +40,18 @@ export async function runGateFold(pass) {
         if (attributed !== undefined)
             pass.classifierRound = attributed;
     }
+    const rewritten = pass.screening !== undefined && pass.decision.action !== "deny" ? readRejudge(pass.req, pass.currentInput, pass.decision) : undefined;
+    if (pass.screening !== undefined && rewritten?.kind === "rewritten") {
+        const second = await screenRewrite(pass.screening, pass.req, rewritten.form, `the rewritten call to "${toolName}"`);
+        if (second.kind === "refused") {
+            pass.currentInput = rewritten.form;
+            return second.by === "hook" ? hookDenyExit(pass, second.reason) : await engineFailClosedExit(pass, second.reason);
+        }
+        if (second.answer?.additionalContext)
+            pass.preToolContext.push(second.answer.additionalContext);
+        pass.hookAsk = second.answer?.action === "ask" ? second.answer : undefined;
+        pass.hookAllowedBy = second.answer?.action === "allow" ? (second.answeredBy !== undefined ? [second.answeredBy] : []) : undefined;
+    }
     if ((pass.decision.action === "allow" || pass.decision.action === "ask") && pass.decision.updatedInput !== undefined) {
         pass.policyRewrite = argsAsTheToolReads(pass.req, pass.decision.updatedInput);
     }
@@ -124,7 +138,7 @@ export async function runGateFold(pass) {
         if (tighten) {
             pass.decision = {
                 action: "ask",
-                message: markTightenMessage(toolName, "irreversible"),
+                message: markTightenMessage(toolName, input.irreversibility === "always" ? "irreversible" : "unproven"),
                 decisionReason: "safety",
                 ...(probeReason !== undefined ? { probeReason } : {}),
                 ...(probeCause !== undefined ? { probeCause } : {}),
@@ -219,19 +233,18 @@ function applyShellReadVerdict(pass, answer, toolName, shellGated) {
                 pass.shellReadDetails = verdict.details;
             if (pass.decision.action !== "allow") {
                 if (pass.decision.action === "ask")
-                    pass.decision = { ...withProbeMandate(pass.decision, account), ...silencedBy(verdict, pass.decision) };
+                    pass.decision = silencedBy(withProbeMandate(pass.decision, account), verdict, pass.req);
                 return;
             }
             const candidate = normalizeReadRootCandidate(verdict.readRootCandidate);
-            pass.decision = {
+            pass.decision = silencedBy({
                 action: "ask",
                 message: shellReadAskMessage(toolName, verdict),
                 decisionReason: "safety",
                 probeMandated: true,
-                ...silencedBy(verdict, {}),
                 ...(account !== undefined ? { probeReason: account } : {}),
                 ...(candidate !== undefined ? { probeReadRootCandidate: candidate } : {}),
-            };
+            }, verdict, pass.req);
             if (candidate !== undefined)
                 pass.shellReadOffer = true;
             pass.tightenedBy = shellGated ? "shell_gate" : "safety";
@@ -242,17 +255,16 @@ function applyShellReadVerdict(pass, answer, toolName, shellGated) {
             if (verdict.details !== undefined)
                 pass.shellReadDetails = verdict.details;
             if (pass.decision.action === "ask")
-                pass.decision = { ...pass.decision, ...silencedBy(verdict, pass.decision) };
+                pass.decision = silencedBy(pass.decision, verdict, pass.req);
             if (pass.decision.action === "allow") {
                 const candidate = normalizeReadRootCandidate(verdict.readRootCandidate);
-                pass.decision = {
+                pass.decision = silencedBy({
                     action: "ask",
                     message: shellReadAskMessage(toolName, verdict),
                     decisionReason: "safety",
-                    ...silencedBy(verdict, {}),
                     ...(account !== undefined ? { probeReason: account } : {}),
                     ...(candidate !== undefined ? { probeReadRootCandidate: candidate } : {}),
-                };
+                }, verdict, pass.req);
                 if (candidate !== undefined)
                     pass.shellReadOffer = true;
                 pass.tightenedBy = shellGated ? "shell_gate" : "safety";