@sema-agent/core 5.65.0 → 6.0.0

package/dist/stores/file/index.d.ts

@@ -4,12 +4,13 @@ import type { ToolResultStore } from "../../core/tool-result-store.js";
 import { type EvictPolicy } from "../../core/session-store.js";
 import type { SessionStore } from "../../core/session.js";
 import { type FileCheckpointStoreOptions } from "./checkpoint-store.js";
+import { type FileFileHistoryStoreOptions } from "./file-history-store.js";
+import type { FileHistoryStore } from "../../core/file-history-store.js";
 import type { StrategyStore } from "../../core/strategy-store.js";
 import type { BackgroundAgentStore } from "../../core/background-agent-store.js";
 import type { MailboxStore } from "../../core/mailbox-store.js";
 import type { RosterStore } from "../../agents/roster-store.js";
 import type { SessionPolicyStore } from "../../core/session-policy-store.js";
-import type { FileSnapshotStore } from "../../core/file-snapshot-store.js";
 import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
 import type { UsageWindowStore } from "../../core/usage-window-store.js";
 export { FileCheckpointStore, type FileCheckpointStoreOptions } from "./checkpoint-store.js";
@@ -17,7 +18,7 @@ export { FileMemoryStore } from "./memory-store.js";
 export { FileSessionRepo, type FileSessionRepoOptions } from "./session-store.js";
 export { FileToolResultStore } from "./tool-result-store.js";
 export { FileSessionPolicyStore, type FileSessionPolicyStoreOptions, type SessionPolicyCorruptReadInfo } from "./session-policy-store.js";
-export { FileFileSnapshotStore, type FileFileSnapshotStoreOptions } from "./file-snapshot-store.js";
+export { FileFileHistoryStore, type FileFileHistoryStoreOptions } from "./file-history-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
 export { FileUsageWindowStore } from "./usage-window-store.js";
 export { FileStrategyStore, type FileStrategyStoreOptions } from "./strategy-store.js";
@@ -64,9 +65,13 @@ export interface FileStorageBackendOptions {
     evict?: EvictPolicy;
     /** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold). */
     checkpoint?: FileCheckpointStoreOptions;
-    /** design/101 §E19 — file-snapshot enumerator bounds (maxFiles/maxBytes/ignoreDirs). Default
-     *  {@link DEFAULT_SNAPSHOT_BOUNDS}. */
-    snapshotBounds?: Partial<import("../../core/file-snapshot-store.js").FileSnapshotBounds>;
+    /**
+     * design/381 §片2 — file-history tuning, today just the boundary RETENTION bound (omitted ⇒ the
+     * engine default; `{ retention: { keep: "unbounded" } }` hands the GC schedule to the deployment).
+     * The corrupt-read sink is deliberately NOT accepted here: it is wired from {@link
+     * FileStorageBackendOptions.onCorruptRead} above, because one failure grammar takes one sink.
+     */
+    fileHistory?: Omit<FileFileHistoryStoreOptions, "onCorruptRead">;
     /** design/81 Slice 5 — an optional {@link import("../../core/memory.js").Embedder}. Injected ⇒ the memory
      *  store does portable (in-process) vector recall over a rebuildable sidecar index (`vectorMode:"portable"`);
      *  absent ⇒ the lexical floor, byte-identical to before. Config-driven (the deployment injects it); OFF by
@@ -84,10 +89,9 @@ export interface FileStorageBackendOptions {
      * nowhere for the deployments that need it most.
      *
      * Reach TODAY: {@link FileStorageBackend.sessionPolicyStore} (rules read as ABSENT ⇒ an unconstrained
-     * task), {@link FileStorageBackend.sessionStore}'s repo (a session listing that silently omits what it
-     * could not read) and {@link FileStorageBackend.fileSnapshotStore} (a snapshot/scope read as missing,
-     * and a blob GC that aborted). The aggregated roster and mailbox stores receive the same sink. A
-     * store that grows the seat later is wired here in the same constructor.
+     * task) and {@link FileStorageBackend.sessionStore}'s repo (a session listing that silently omits what
+     * it could not read). The aggregated roster and mailbox stores receive the same sink. A store that
+     * grows the seat later is wired here in the same constructor.
      *
      * The payload is the UNION shape ({@link FileStorageCorruptReadInfo}): `path` + `reason` always,
      * with the session-policy face's `sessionId`/`principal` present only when the reading store keys by
@@ -123,10 +127,6 @@ export declare class FileStorageBackend {
     /** design/99 §E6 — file-backed per-session permission rules (E6). Wire into `RunnerDeps.sessionPolicyStore`
      *  for a local deployment that needs session rules to survive a restart. */
     readonly sessionPolicyStore: SessionPolicyStore;
-    /** design/101 §E19 — file-backed working-tree snapshots (rewind-files). Wire into
-     *  `RunnerDeps.fileSnapshotStore`. Content-addressed blobs persist across restarts (local-only; a remote env
-     *  defers rewind to its own VM-snapshot backend). */
-    readonly fileSnapshotStore: FileSnapshotStore;
     /** SVC-2 (onboarded per) — file-backed durable workflow resume journal. Wire into
      *  `RunnerDeps.workflowJournalStore` so `resumeFromRunId` survives a process restart on a TOC box. */
     readonly workflowJournalStore: WorkflowJournalStore;
@@ -152,6 +152,15 @@ export declare class FileStorageBackend {
     /** design/147 S1c — the durable name→agent roster (layer 0.5 resolution), `root/roster.json`.
      *  Wire into `RunnerDeps.rosterStore` so name-addressing survives a restart alongside the rows. */
     readonly rosterStore: RosterStore;
+    /**
+     * design/381 slice 2 — the durable per-edited-file rewind history over the same data root
+     * (`root/file-history/`). Wire into `RunnerDeps.fileHistoryStore` so `/rewind` survives a restart:
+     * WIRING IS THE OPT-IN (DV-9), so a deployment that omits it runs with rewind off, exactly as
+     * before this member existed. It replaces the retired whole-tree `fileSnapshotStore` member —
+     * per-edited-file means no size gate, no exclusion table, no tree traversal, and files the agent
+     * never edited are structurally out of reach of a restore.
+     */
+    readonly fileHistoryStore: FileHistoryStore;
     /**
      * design/84 Seam B (TOC) — the per-scope consolidation lock for `consolidateScope`'s `acquire` injection
      * point: `consolidateScope(scope, { store: backend.memoryStore, llm, acquire: backend.consolidationLock })`.

package/dist/stores/file/index.js

@@ -8,19 +8,19 @@ import { FileMemoryStore } from "./memory-store.js";
 import { FileSessionRepo } from "./session-store.js";
 import { FileToolResultStore } from "./tool-result-store.js";
 import { FileSessionPolicyStore } from "./session-policy-store.js";
-import { FileFileSnapshotStore } from "./file-snapshot-store.js";
 import { FileWorkflowJournalStore } from "./workflow-journal-store.js";
 import { FileUsageWindowStore } from "./usage-window-store.js";
 import { FileBackgroundAgentStore } from "./background-agent-store.js";
 import { FileMailboxStore } from "./mailbox-store.js";
 import { FileRosterStore } from "../../agents/roster-store.js";
 import { FileStrategyStore } from "./strategy-store.js";
+import { FileFileHistoryStore } from "./file-history-store.js";
 export { FileCheckpointStore } from "./checkpoint-store.js";
 export { FileMemoryStore } from "./memory-store.js";
 export { FileSessionRepo } from "./session-store.js";
 export { FileToolResultStore } from "./tool-result-store.js";
 export { FileSessionPolicyStore } from "./session-policy-store.js";
-export { FileFileSnapshotStore } from "./file-snapshot-store.js";
+export { FileFileHistoryStore } from "./file-history-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
 export { FileUsageWindowStore } from "./usage-window-store.js";
 export { FileStrategyStore } from "./strategy-store.js";
@@ -36,13 +36,13 @@ export class FileStorageBackend {
     memoryStore;
     toolResultStore;
     sessionPolicyStore;
-    fileSnapshotStore;
     workflowJournalStore;
     usageWindowStore;
     backgroundAgentStore;
     mailboxStore;
     strategyStore;
     rosterStore;
+    fileHistoryStore;
     consolidationLock;
     lock;
     fileAgentRows;
@@ -72,7 +72,6 @@ export class FileStorageBackend {
             this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
             this.toolResultStore = new FileToolResultStore(this.root);
             this.sessionPolicyStore = new FileSessionPolicyStore(this.root, corruptRead);
-            this.fileSnapshotStore = new FileFileSnapshotStore(this.root, opts.snapshotBounds, corruptRead);
             this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root);
             built.push(() => this.fileWorkflowJournal.dispose());
             this.workflowJournalStore = this.fileWorkflowJournal;
@@ -93,6 +92,7 @@ export class FileStorageBackend {
                     }
                     : {}),
             });
+            this.fileHistoryStore = new FileFileHistoryStore(this.root, { ...(opts.fileHistory ?? {}), ...(corruptRead ?? {}) });
             this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
         }
         catch (err) {

package/dist/stores/file/permission-rule-store.js

@@ -256,6 +256,7 @@ class FilePermissionRuleStore {
             };
         }),
         apply: async (delta, opts) => this.serialize(() => {
+            delta = structuredClone(delta);
             const cur = this.current();
             if (cur.rev !== opts.expectedRev)
                 return { conflict: true, rev: cur.rev };

package/dist/stores/file/strategy-store.d.ts

@@ -15,7 +15,7 @@ import { type StoredStrategy, type StrategyStore, type StrategyStoreIncident } f
  * Layout: `<root>/<scopeDir>/<id>.json`, one strategy per file, whole-file atomic replace on write.
  * `scopeDir = slug(scope) + "-" + sha256(scope).slice(0,24)` — the slug is a strict `[a-z0-9-]`
  * whitelist purely for readability; IDENTITY lives in the 96-bit hash, so no scope value, however
- * hostile, can traverse out of the root or collide another scope's directory. Ids are gated to
+ * adversarial, can traverse out of the root or collide another scope's directory. Ids are gated to
  * `[A-Za-z0-9_-]{1,64}` at save (the escalation loop mints UUIDs; the interface is public, so a
  * hand-rolled id must not be able to name a path).
  *
@@ -52,8 +52,8 @@ export declare class FileStrategyStore implements StrategyStore {
     private scopeDirPath;
     /** The scope dir must be a REAL directory — a symlink here means the store's namespace was tampered
      *  with (a link could point retrieval at another scope's data, or writes out of the root). The
-     *  check-then-use window against a same-uid local attacker is out of the threat model: such an
-     *  attacker already holds the same rights as the store itself. */
+     *  check-then-use window against a same-uid untrusted local process is out of the threat model: such a
+     *  process already holds the same rights as the store itself. */
     private assertScopeDirSafe;
     private incident;
     /** Sweep crashed writers' stale temps (once per scope per instance). Fresh temps are left alone —

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -126,6 +126,18 @@ export declare function parseLeadingCommandName(command: string, options?: Leadi
  *  design/154: this `effect:"read"` DECLARATION face deliberately stays strict-single-command; only the
  *  classify face ({@link classifyCompoundReadonly} via {@link import("./fs-bash.js").bashReversibilityProbe}) segments compounds. */
 export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>, options?: LeadingCommandNameOptions): string | undefined;
+/**
+ * Does this text carry a bare redirection operator — the ONE metacharacter family
+ * {@link splitShellCompoundSegments} can be asked to tolerate at its whole-string gate (#490 修①,
+ * `redirection: "tolerate"`)?
+ *
+ * Exported because the tolerating caller owes a PER-SEGMENT judgement in its place, and that judgement
+ * must read the same character class this module tolerated — two hand-kept lists would drift, and a
+ * drift here is a segment nobody judged. Says nothing about what a caller should DO about a hit: the
+ * rule lane's offer face contributes no member for such a segment; the read-only classify face removes
+ * its exempt spellings before splitting at all.
+ */
+export declare function carriesShellRedirection(text: string): boolean;
 /** What {@link splitShellCompoundSegments} produces: the connector-delimited segments, plus which of
  *  them a PIPE fed (the read-only classifier's stdin arm needs that distinction; a rule lane does not). */
 export interface ShellCompoundSegments {
@@ -149,7 +161,10 @@ export interface ShellCompoundSegments {
  *     characters gone, `'`/`"` pairing is the entirety of quoting, so the mask's regions are exactly
  *     bash's quoted regions and the unquoted connectors are exactly bash's command boundaries. Callers
  *     that tolerate a narrow redirection subset (the read-only classify face and its two data-free
- *     spellings) remove those words BEFORE calling; nothing here restores them.
+ *     spellings) remove those words BEFORE calling; nothing here restores them. `redirection:
+ *     "tolerate"` (#490 修①) narrows this step to {@link rejectedSansRedirection} — the mask argument
+ *     is untouched (`<`/`>` neither quote nor bound) and the refusal moves to the caller's per-segment
+ *     vetting via {@link carriesShellRedirection}. The default refuses the whole string as it always did.
  *  2. one trailing `;` is stripped — a no-op terminator, not an empty command. OPTIONAL, because it is
  *     the one step whose answer depends on what the caller is asking. A face that asks "which programs
  *     does this run" wants it stripped (`ls;` runs `ls`, nothing else). A face that asks "is this ONE
@@ -169,6 +184,7 @@ export interface ShellCompoundSegments {
  */
 export declare function splitShellCompoundSegments(source: string, options?: {
     trailingTerminator?: "strip" | "keep";
+    redirection?: "reject" | "tolerate";
 }): ShellCompoundSegments | {
     reject: string;
 };
@@ -179,7 +195,7 @@ export declare function splitShellCompoundSegments(source: string, options?: {
  * path: `ls /etc` and `cat /etc/passwd` classified read-only, and a deployment whose manual-mode shell
  * gate auto-allows the read-only verdict served the whole filesystem with no approval prompt. CC 2.1.220
  * demotes exactly these shapes (its per-command path extractor + working-directory containment check,
- * pretty220 @457568) and renders an approval option naming the directory (@905642).
+ * pretty220 @457568) and renders an approval option naming the directory (@905642 (cli250.js:66007)).
  *
  * Supplying this object turns the check ON; omitting it leaves the classifier byte-identical to its
  * pre-RB-412 behaviour, so a consumer pinned to an older calling convention is unaffected.
@@ -313,7 +329,7 @@ export interface CompoundReadonlyVerdict {
 }
 /**
  * RB-412 — the single minting point for the out-of-root-read approval option text, so a gate rendering
- * the prompt and any other consumer cannot drift apart. Shape follows CC 2.1.220 (@905642): the option
+ * the prompt and any other consumer cannot drift apart. Shape follows CC 2.1.220 (@905642 (cli250.js:66007)): the option
  * shows the LAST segment of the grantable directory followed by a separator, not the full path.
  *
  * `directory` is the directory to be granted — a caller holding a filesystem (this classifier does not)
@@ -366,6 +382,74 @@ opts?: {
  * `createBashReadonlyTool` is that caller for the `bash_readonly` leg and does it on a local env.
  */
 export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+/**
+ * #502 — what {@link classifyOutOfRootReadGate} answers. Two members and one rule between them:
+ * `paths` is EVIDENCE for a `gated` answer, never the answer itself. A caller decides on `gated`.
+ */
+export interface OutOfRootReadGateVerdict {
+    /** True ⇔ this command is structurally gated on the read boundary. */
+    readonly gated: boolean;
+    /** The RESOLVED out-of-root paths behind a `gated` answer. EMPTY when the gate fired for a reason
+     *  that resolves none — a working-directory move this walk cannot follow, after which every relative
+     *  operand is placed against a base bash has already left, so no path can be named honestly. Read it
+     *  as display/triage evidence; emptiness is not "not gated". */
+    readonly paths: readonly string[];
+}
+/** Test seam for the lockstep pin that this mirror stays a SUBSET of the rule lane's curated table.
+ *  Exported for that one assertion — production code reads the constant directly. */
+export declare const COMMAND_LAUNCHERS_FOR_TEST: ReadonlySet<string>;
+/**
+ * #502 — the OUT-OF-ROOT READ GATE asked as its OWN question: does any listed reader in this command
+ * name a path outside the allowed directories?
+ *
+ * {@link classifyCompoundReadonlyDetailed} answers a different question — "is this whole command
+ * auto-allowable?" — and it stops at the FIRST obstacle. That makes its `outOfRootRead` signal precise
+ * for the shape it was built for and silent for three shapes where the containment fact is just as
+ * true: a compound whose OTHER segment is not a listed reader (`cat <outside> | curl …` refuses on the
+ * unlisted name and never reaches the boundary walk at all), an operand that ALSO matches the
+ * sensitive-path deny judge (whose more-specific reason short-circuits the walk), and a recursive form
+ * whose traversal root sits outside. This face answers the containment question in all of them, so a
+ * consumer that must treat "reads outside the roots" as a STRUCTURAL gate rather than as one possible
+ * reason for a demotion has one predicate to read.
+ *
+ * What it judges and what it does not:
+ *  · SEGMENTS whose PROGRAM is in `allow` — the deployment's own read-command table, the analogue of
+ *    the reference implementation's path-restricted command list. The program is read after the two
+ *    decorations the shell itself strips before choosing it (leading `NAME=value` assignments, a path
+ *    prefix), so `/bin/cat` is judged as `cat`: recognizing readers by their literal spelling alone let
+ *    a rule the persisted grammar admits (`Bash(/bin/cat:*)`) carry the exact read this gate exists for.
+ *    Every other segment is skipped, so this face never invents a path judgement for a verb the
+ *    deployment never declared readable.
+ *  · `cd` is judged whether or not the deployment listed it, because the walk MODELS it (it threads the
+ *    base across segments) and dropping it would place every later relative operand against a base bash
+ *    has already left. A move the walk cannot model (`pushd`/`popd`) is not silently tolerated either —
+ *    see the `paths`-less gated answer below.
+ *  · The CONTAINMENT half only: {@link BashReadonlyRootBoundary.denyMatch} is deliberately NOT passed
+ *    on. The deny judge outranks containment inside the walk and returns early, which would let a
+ *    deny-listed operand HIDE the fact that it also sits outside the roots — the deny demotion is
+ *    unchanged on the full face, and this one keeps answering its own question underneath it.
+ *  · `face: "open"` is honoured: under the open read face containment is structurally satisfied, an
+ *    out-of-roots operand is not a finding, and this gate is silent — a full-read deployment sees no
+ *    gate here, by the same one mechanism §2.0 already defines.
+ *
+ * Answers `gated` with the resolved paths behind it, and NOT gated for every whole-string refusal (an
+ * unparseable grammar, a substitution, a redirection) and for an operand that cannot be resolved
+ * statically. That silence is the honest answer, not a miss: those shapes name no concrete directory,
+ * so there is nothing for a path gate to be about.
+ *
+ * It deliberately does NOT reuse {@link CompoundReadonlyVerdict}: one arm of this face is gated while
+ * resolving no path at all (the unmodelled working-directory move), and that arm cannot fill an
+ * `outOfRootPaths` whose contract says the entries ARE resolved out-of-root paths. A result type that
+ * can say "gated, and here is nothing" is the one that lets the arm exist without lying.
+ *
+ * The bounded poll-loop grammar is judged through its BODY, the same text that face re-classifies —
+ * without it, the one control structure this file auto-allows would be the one shape whose reads no
+ * gate looks at. The body is judged in a single pass (the per-iteration `cd` accumulation the
+ * auto-allow face models is not replicated here): a loop that climbs out of the roots over its beats
+ * is refused by that face on its own terms, and under-reporting here can only cost a gate, never grant
+ * one.
+ */
+export declare function classifyOutOfRootReadGate(command: string, allow: ReadonlySet<string>, boundary: BashReadonlyRootBoundary): OutOfRootReadGateVerdict;
 /**
  * design/154 — compound read-only classification, reason-only face. Returns the demotion reason, or
  * undefined when the command classifies read-only. ⚠️ `undefined` is NOT "safe to auto-execute":

package/dist/tools/fs/bash-readonly-classifier.js

@@ -66,8 +66,45 @@ export function coarseReadonlyCheck(command, allow, options) {
     return undefined;
 }
 const SHELL_SEGMENT_HARD_REJECT = /[<>$()`\n\r\\]/;
+export function carriesShellRedirection(text) {
+    return SHELL_REDIRECTION_OPERATORS.test(text);
+}
+const SHELL_REDIRECTION_OPERATORS = /[<>]/;
+const SHELL_CONNECTOR_CHARS = /[|&;]/;
+function redirectionPrecedesConnector(source) {
+    const mask = quoteMask(source);
+    const quoted = (i) => mask.balanced && mask.quoted[i] === true;
+    const isSpace = (c) => c === " " || c === "\t";
+    for (let i = 0; i < source.length; i++) {
+        if (quoted(i) || !SHELL_REDIRECTION_OPERATORS.test(source[i]))
+            continue;
+        let j = i + 1;
+        while (j < source.length && !quoted(j) && (SHELL_REDIRECTION_OPERATORS.test(source[j]) || isSpace(source[j])))
+            j++;
+        if (j < source.length && !quoted(j) && SHELL_CONNECTOR_CHARS.test(source[j]))
+            return true;
+        i = j - 1;
+    }
+    return false;
+}
+function rejectedSansRedirection(source) {
+    if (redirectionPrecedesConnector(source)) {
+        return "a redirection followed by `|`, `&` or `;` is not allowed — the operator's own characters cannot be told apart from a command boundary";
+    }
+    for (const ch of source) {
+        if (SHELL_SEGMENT_HARD_REJECT.test(ch) && !SHELL_REDIRECTION_OPERATORS.test(ch)) {
+            return "command/variable substitution, subshells, escapes, and line breaks are not allowed";
+        }
+    }
+    return undefined;
+}
 export function splitShellCompoundSegments(source, options) {
-    if (SHELL_SEGMENT_HARD_REJECT.test(source)) {
+    if (options?.redirection === "tolerate") {
+        const refused = rejectedSansRedirection(source);
+        if (refused !== undefined)
+            return { reject: refused };
+    }
+    else if (SHELL_SEGMENT_HARD_REJECT.test(source)) {
         return { reject: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
     }
     const scanned = options?.trailingTerminator !== "keep" ? source.replace(/;\s*$/, "") : source;
@@ -677,15 +714,18 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     }
     return findings;
 }
-export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts) {
+function segmentCompoundForReadonly(command) {
     const trimmed = command.trim();
     if (!trimmed)
-        return { reason: "empty command" };
+        return { reject: "empty command" };
     const redirectionStripped = stripExemptRedirections(trimmed);
     const terminatorStripped = redirectionStripped.endsWith(";")
         ? redirectionStripped.slice(0, -1)
         : redirectionStripped;
-    const split = splitShellCompoundSegments(terminatorStripped, { trailingTerminator: "keep" });
+    return splitShellCompoundSegments(terminatorStripped, { trailingTerminator: "keep" });
+}
+export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts) {
+    const split = segmentCompoundForReadonly(command);
     if ("reject" in split)
         return { reason: split.reject };
     const { segments, pipeFed } = split;
@@ -884,6 +924,68 @@ export function classifySimpleCommandReadBoundary(command, boundary) {
         return {};
     return evaluateReadBoundary([toks], boundary);
 }
+const NOT_GATED = { gated: false, paths: [] };
+const ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const UNMODELLED_BASE_MOVERS = new Set(["pushd", "popd"]);
+const COMMAND_LAUNCHERS = new Set([
+    "env", "command", "builtin", "exec", "noglob", "xargs",
+    "sudo", "doas", "pkexec", "su", "runuser", "chroot", "setpriv",
+    "nohup", "nice", "ionice", "chrt", "taskset", "stdbuf", "timeout", "time", "watch",
+    "setsid", "flock", "unshare", "nsenter", "script", "numactl", "prlimit", "systemd-run", "parallel",
+    "strace", "ltrace", "valgrind", "firejail", "bwrap",
+]);
+export const COMMAND_LAUNCHERS_FOR_TEST = COMMAND_LAUNCHERS;
+const LAUNCHER_SCAN_HEAD = "cat";
+function programBasename(word) {
+    return word.includes("/") ? (word.split("/").pop() ?? word) : word;
+}
+export function classifyOutOfRootReadGate(command, allow, boundary) {
+    const containmentOnly = {
+        roots: boundary.roots,
+        ...(boundary.cwd !== undefined ? { cwd: boundary.cwd } : {}),
+        ...(boundary.homeDir !== undefined ? { homeDir: boundary.homeDir } : {}),
+        ...(boundary.face !== undefined ? { face: boundary.face } : {}),
+    };
+    const judge = (text) => {
+        const split = segmentCompoundForReadonly(text);
+        if ("reject" in split)
+            return NOT_GATED;
+        const readers = [];
+        let baseMoved = false;
+        for (const segment of split.segments) {
+            const toks = tokenizeSegment(segment);
+            if (toks.folded.length === 0)
+                continue;
+            let i = 0;
+            while (i < toks.folded.length && ASSIGNMENT_WORD.test(toks.folded[i]))
+                i++;
+            const written = toks.folded[i];
+            if (written === undefined)
+                continue;
+            const name = programBasename(written);
+            if (!allow.has(name) && COMMAND_LAUNCHERS.has(name)) {
+                readers.push({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)] });
+                continue;
+            }
+            if (UNMODELLED_BASE_MOVERS.has(name))
+                baseMoved = true;
+            if (!allow.has(name) && name !== "cd")
+                continue;
+            readers.push(i === 0 && name === written ? toks : { folded: [name, ...toks.folded.slice(i + 1)], raw: [toks.raw[i] ?? name, ...toks.raw.slice(i + 1)] });
+        }
+        if (readers.length === 0)
+            return NOT_GATED;
+        if (baseMoved)
+            return { gated: true, paths: [] };
+        const verdict = evaluateReadBoundary(readers, containmentOnly);
+        return verdict.outOfRootRead === true ? { gated: true, paths: verdict.outOfRootPaths ?? [] } : NOT_GATED;
+    };
+    const direct = judge(command);
+    if (direct.gated)
+        return direct;
+    const shape = POLL_LOOP_SHAPE.exec(command.trim());
+    return shape !== null ? judge(shape[3]) : NOT_GATED;
+}
 export function classifyCompoundReadonly(command, allow, boundary) {
     return classifyCompoundReadonlyDetailed(command, allow, boundary).reason;
 }

package/dist/tools/fs/fs-bash.js

@@ -11,7 +11,7 @@ import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
-import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
 const RECURSIVE_CAUSE_MAX_PATHS = 3;
 const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
 function operandFamily(paths) {
@@ -28,9 +28,10 @@ export function bashReversibilityProbe(allow, boundary) {
         const command = a?.command;
         if (typeof command !== "string")
             return { reversible: false };
-        if (a?.run_in_background === true)
-            return { reversible: false };
         const resolved = typeof boundary === "function" ? boundary() : boundary;
+        const outOfRootGate = () => resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
+        if (a?.run_in_background === true)
+            return { reversible: false, ...outOfRootGate() };
         const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
         if (detailed.reason === undefined) {
             if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0) {
@@ -40,6 +41,7 @@ export function bashReversibilityProbe(allow, boundary) {
                     const others = detailed.undecidedPaths.filter((p) => !recursiveSet.has(p));
                     return {
                         reversible: false,
+                        ...outOfRootGate(),
                         cause: {
                             code: RECURSIVE_READ_CAUSE_CODE,
                             roots: operandFamily(recursive),
@@ -47,11 +49,13 @@ export function bashReversibilityProbe(allow, boundary) {
                         },
                     };
                 }
-                return { reversible: false };
+                return { reversible: false, ...outOfRootGate() };
             }
             return { reversible: true };
         }
-        return { reversible: classifyBoundedReadonlyPollLoop(command, allowSet, resolved) === undefined };
+        return classifyBoundedReadonlyPollLoop(command, allowSet, resolved) === undefined
+            ? { reversible: true }
+            : { reversible: false, ...outOfRootGate() };
     };
 }
 export const FULL_SHELL_CONTRACT_ID = "core.bash@1";

package/dist/tools/fs/fs-shared.d.ts

@@ -74,6 +74,35 @@ export declare const BASH_READONLY_CONFINEMENT_NOTE = "bash_readonly is confined
  *  false-stale defect for those targets. Round-tripping the real bytes sidesteps the case analysis
  *  and stays correct if the encoding rules ever change. */
 export declare function persistedTextOf(encoded: string | Uint8Array): string;
+/**
+ * #483 — one APPLIED edit as the Edit tool's `details` card records it: the RESOLVED old/new strings
+ * (post quote/escape resolution, post deletion-newline widening) in the normalized originalFile
+ * coordinate. This is the card shape a transcript replay must re-apply, so the application step is a
+ * single source shared by the Edit tool's own apply loop and the replay — two spellings of "apply"
+ * could silently drift (e.g. one expanding `$&` and one not) and the replay's recomputed hash would
+ * refuse edits the tool actually made.
+ */
+export interface RecordedEdit {
+    oldString: string;
+    newString: string;
+    replaceAll: boolean;
+}
+/**
+ * #483 — apply ONE recorded edit mechanically (no matching layers, no validation: the recording site
+ * already resolved and validated the strings; a replay consumer that cannot prove `oldString` is
+ * present must fall back to retracting its record, never guess here).
+ *
+ * Two load-bearing details, both shared with the Edit tool's historical inline apply:
+ *  - Function-form replacement: the callback's return value is NOT interpreted as a replacement
+ *    pattern, so `$&`/`$$`/`` $` ``/`$'` in `newString` are written literally (S-1; the replaceAll
+ *    split/join path was always literal).
+ *  - `oldString === ""` is the whole-content OVERWRITE shape: the Edit tool's whitespace-only-file
+ *    overwrite lane records `{oldString: "", newString: <full new text>}` after REPLACING the file's
+ *    content wholesale (fs-write.ts, the `old_string:""` existing-file branch). The tool's own apply
+ *    loop never reaches this arm (checkEditMatch refuses an empty old_string before application), so
+ *    it exists for the replay consumer alone — a plain `replace("", ...)` would PREPEND instead.
+ */
+export declare function applyRecordedEdit(text: string, edit: RecordedEdit): string;
 /** fidelity-sweep F3 (stopgap wording): render the read-before-edit refusal, appending the slice/bash
  *  escape hatch when the target is over the Read byte cap — a bare "read it first" is un-followable
  *  there (a default whole-file Read refuses such files). Best-effort: an un-stattable file keeps the
@@ -114,7 +143,7 @@ export declare function resolveAutoDownsampler(): Promise<ImageDownsampler | und
  *  proxy — `KMu` @279761 pre-filters with a PER-EXTENSION chars-per-token coefficient (json/jsonl = 2,
  *  i.e. half of the 4 assumed here) and then confirms with a REAL tokenizer (`BLd` @518589); the
  *  budget itself is also overridable per call (`fileReadingLimits`) and by the `tengu_amber_wren` gate
- *  (`eze` @335063), neither of which has a sema lane. Consequence, stated rather than hidden: on
+ *  (`eze` @335063 (cli250.js:39563)), neither of which has a sema lane. Consequence, stated rather than hidden: on
  *  token-dense text (JSON/CJK/base64) this proxy UNDER-counts, so sema serves a page CC would have cut
  *  further; on token-sparse text it over-counts and paginates earlier than CC. A real tokenizer here
  *  would need a provider-neutral counting seam (BYOM — no single vocabulary), which is why the proxy
@@ -416,6 +445,28 @@ export declare function seedReadFileStateFromContext(state: ReadFileState, key:
  *    compaction. This text lives in the transcript and does not.
  */
 export declare function seedReadFileStateFromTranscript(state: ReadFileState, key: string, content: string, lastReadAt: number): void;
+/**
+ * #483 rung-1 — copy a SESSION-inherited read-file state into a new task's map, under the new task's
+ * own containment judgment (CC parity: readFileState is session-scoped — minted once per REPL session,
+ * mutated across turns, with no turn-boundary or abort clear site; sema's per-task map inherits the
+ * previous turn's live state instead).
+ *
+ * Two rules, each a claim inheritance cannot honestly skip:
+ *  - **Every key passes the CURRENT task's own key judgment** (`judgeKey` = the same resolveKey
+ *    containment the transcript-replay seed uses: write roots ∪ read roots, resolved read face). A
+ *    root or face narrowed between the turns must narrow what the state remembers, exactly as the
+ *    replay leg already judges — an unjudged copy would smuggle out-of-face entries into the task
+ *    (and into its checkpoints).
+ *  - **`seededFromContext` entries do not inherit.** That flag claims the file's text lives in the
+ *    system-prompt lane OF THIS TASK — a claim only this task's own startup seeding (T10) can make.
+ *    A still-declared file is re-seeded the same turn (no loss); a no-longer-declared one must not
+ *    keep answering reads with an "already in your context" reminder that is no longer true.
+ *
+ * Entries are copied by REFERENCE (ReadEntry values are never mutated in place — every write-back
+ * `set`s a fresh object), so recorded facts (view / isPartialView / lastReadAt) ride verbatim: the
+ * dedup stub and the partial-view refusal keep working across turns exactly as inside one task.
+ */
+export declare function inheritSessionReadFileState(target: ReadFileState, inherited: ReadFileState, judgeKey: (recordedKey: string) => Promise<string | undefined>): Promise<void>;
 /**
  * RB-197 (form-one audit, CC 2.1.220 @388663-388664): a landed compaction summarizes old Read results OUT
  * of the context, so every non-seeded read-state entry must be dropped — CC snapshots then

package/dist/tools/fs/fs-shared.js

@@ -39,6 +39,11 @@ export const BASH_READONLY_CONFINEMENT_NOTE = "bash_readonly is confined to the
 export function persistedTextOf(encoded) {
     return decodeTextBytes(typeof encoded === "string" ? Buffer.from(encoded, "utf8") : encoded).text;
 }
+export function applyRecordedEdit(text, edit) {
+    if (edit.oldString === "")
+        return edit.newString;
+    return edit.replaceAll ? text.split(edit.oldString).join(edit.newString) : text.replace(edit.oldString, () => edit.newString);
+}
 export async function notReadRefusalText(env, toolName, key, v, signal, fallbackHint) {
     const base = `Error (${toolName}): ${v.message}`;
     if (v.partialView === true && !isNotebookPath(key))
@@ -276,6 +281,15 @@ export function seedReadFileStateFromTranscript(state, key, content, lastReadAt)
     const text = normalizeFileText(content);
     state.set(key, { hash: sha256(text), totalLines: countLines(text), truncated: false, lastReadAt });
 }
+export async function inheritSessionReadFileState(target, inherited, judgeKey) {
+    for (const [key, entry] of inherited) {
+        if (entry.seededFromContext === true)
+            continue;
+        const judged = await judgeKey(key);
+        if (judged !== undefined)
+            target.set(judged, entry);
+    }
+}
 export function applyCompactionToReadFileState(state, attachedComplete, preserveKeys = []) {
     const preserve = new Set(preserveKeys);
     for (const [k, v] of [...state]) {

package/dist/tools/fs/fs-write.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import type { BeforeWriteHook } from "../../core/types.js";
+import type { BeforeWriteHook, TrackFileEditHook } from "../../core/types.js";
 import { type ReadFileState } from "./safety.js";
 import { type CwdRef } from "./fs-shared.js";
 /**
@@ -11,9 +11,9 @@ import { type CwdRef } from "./fs-shared.js";
  * MemoryEngine's write gate (`MemoryEngine.gateWrite`) — a non-memory path passes with one string
  * prefix comparison there (零开销直通). Absent hook ⇒ byte-identical behavior.
  */
-export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook } from "../../core/types.js";
-export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook): AgentTool;
-export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook): AgentTool;
+export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook } from "../../core/types.js";
+export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook): AgentTool;
+export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook): AgentTool;
 /**
  * design v1.163 — NotebookEdit: replace/insert/delete a single cell in a .ipynb. CC-parity tool over the SAME hand-band
  * safety skeleton as Edit/Write (resolveKey containment → requireRead read-before-edit → checkStale content-hash
@@ -21,4 +21,4 @@ export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileSt
  * .ipynb as the RB-227 cell projection but records read state (hash/totalLines) in the RAW notebook-text
  * coordinate — that raw-coordinate read record is what this tool's freshness check depends on.
  */
-export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook): AgentTool;
+export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook): AgentTool;