@sema-agent/core 5.65.0 → 7.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.d.ts

@@ -111,6 +111,17 @@ declare class FilePermissionRuleStore implements WritablePermissionRuleStore {
     /** Read and validate. Any refusal answers with an empty set AND says so — never a silent empty store. */
     private read;
     private disclose;
+    /**
+     * design/382 §4.3 — the AT-REST half of the durable two-member scope face: rows carrying a session
+     * scope, read out of persisted bytes (a hand edit or a foreign writer — the engine's own write arms
+     * refuse them loudly), are DROPPED from every read face and DISCLOSED. Never quarantined (the
+     * quarantine area is itself durable), never silently ridden: a session authorization must not gain
+     * an afterlife by being planted where the store cannot legally hold it. The write base
+     * (`current()`) is deliberately NOT screened — foreign bytes are left in place for a person to look
+     * at, exactly like every other damaged-row posture here; they simply never reach a live view, the
+     * sync wire (`readRaw`) or adjudication.
+     */
+    private screenDurableRows;
     private write;
     list(): Promise<StoredAllowRules>;
     /** The quarantine area (design/182 §5.2/§8.3): introspection only — never part of `list()`. */

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

@@ -1,7 +1,7 @@
 import { closeSync, constants as FS, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
-import { PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, foldDelta, } from "../../core/permission-rule-store.js";
+import { PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, } from "../../core/permission-rule-store.js";
 import { canonicalize } from "../../core/canonical-json.js";
 import { BootLock } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
@@ -158,6 +158,17 @@ class FilePermissionRuleStore {
         catch {
         }
     }
+    screenDurableRows(file) {
+        const isSession = (scope) => scope?.kind === "session";
+        const rules = file.rules.filter((r) => !isSession(r?.scope));
+        const tombstones = file.tombstones.filter((t) => !isSession(t?.scope));
+        const quarantined = (file.quarantined ?? []).filter((q) => !isSession(q?.scope));
+        const dropped = file.rules.length - rules.length + (file.tombstones.length - tombstones.length) + ((file.quarantined ?? []).length - quarantined.length);
+        if (dropped > 0) {
+            this.disclose(`${this.file} carries ${dropped} session-scope row(s) — a session authorization cannot live in the durable store (design/382 §4.3); those rows are ignored on every read face and never ride sync`);
+        }
+        return { rules, tombstones, quarantined };
+    }
     write(next) {
         assertSafeDir(this.dir);
         atomicPublish(this.dir, this.file, JSON.stringify({ ...next, checksum: checksumOf(next) }, null, 2));
@@ -166,16 +177,17 @@ class FilePermissionRuleStore {
         const r = this.read();
         if (!("file" in r))
             return { ...EMPTY_READ };
+        const screened = this.screenDurableRows(r.file);
         return {
-            rules: applyTombstones(r.file.rules, r.file.tombstones),
-            tombstones: r.file.tombstones,
+            rules: applyTombstones(screened.rules, screened.tombstones),
+            tombstones: screened.tombstones,
             rev: r.file.rev,
             checksum: r.file.checksum,
         };
     }
     async quarantined() {
         const r = this.read();
-        return "file" in r ? (r.file.quarantined ?? []) : [];
+        return "file" in r ? this.screenDurableRows(r.file).quarantined : [];
     }
     async readOrgState() {
         const r = this.read();
@@ -245,17 +257,19 @@ class FilePermissionRuleStore {
         }),
         readRaw: async () => this.serialize(() => {
             const cur = this.current();
+            const screened = this.screenDurableRows(cur);
             return {
                 actor: cur.actor,
                 counter: cur.counter,
                 rev: cur.rev,
-                rules: structuredClone(cur.rules),
-                tombstones: structuredClone(cur.tombstones),
+                rules: structuredClone(screened.rules),
+                tombstones: structuredClone(screened.tombstones),
                 ...(cur.sync?.observedVector !== undefined ? { observedVector: structuredClone(cur.sync.observedVector) } : {}),
-                quarantined: structuredClone(cur.quarantined ?? []),
+                quarantined: structuredClone(screened.quarantined),
             };
         }),
         apply: async (delta, opts) => this.serialize(() => {
+            delta = structuredClone(delta);
             const cur = this.current();
             if (cur.rev !== opts.expectedRev)
                 return { conflict: true, rev: cur.rev };
@@ -286,8 +300,8 @@ class FilePermissionRuleStore {
                 return { rev: cur.rev + 1, sync: report };
             }
             const next = delta.kind === "redemption-add"
-                ? (assertRedemptionNotQuarantined(cur.quarantined ?? [], delta), { ...cur, rev: cur.rev + 1, rules: foldDelta(cur.rules, delta) })
-                : (assertDeleteDeltaCarriesNoAdd(delta), { ...cur, rev: cur.rev + 1, tombstones: [...cur.tombstones, delta.tombstone] });
+                ? (assertWriteDeltaScopeDurable(delta), assertRedemptionNotQuarantined(cur.quarantined ?? [], delta), { ...cur, rev: cur.rev + 1, rules: foldDelta(cur.rules, delta) })
+                : (assertWriteDeltaScopeDurable(delta), assertDeleteDeltaCarriesNoAdd(delta), { ...cur, rev: cur.rev + 1, tombstones: [...cur.tombstones, delta.tombstone] });
             if (!this.writeAndVerify(next)) {
                 throw new Error("the permission-rule store did not survive its own write; the change was not committed");
             }

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";