@sema-agent/core 7.26.0 → 7.26.1

package/dist/core/store-contracts/read-back-shape-contract.js

@@ -0,0 +1,78 @@
+import assert from "node:assert";
+import { thrownText } from "../thrown-value.js";
+import { beginContract } from "./contract-harness.js";
+export const CORRUPT_BODY_FORMS = ["not-an-object", "missing-required", "wrong-type", "torn-json"];
+async function observe(subject) {
+    try {
+        const value = await subject.read();
+        return { threw: false, body: safeStringify(value) };
+    }
+    catch (err) {
+        return { threw: true, message: thrownText(err) };
+    }
+}
+function safeStringify(value) {
+    const seen = new WeakSet();
+    try {
+        return (JSON.stringify(value, (_k, v) => {
+            if (typeof v === "object" && v !== null) {
+                if (seen.has(v))
+                    return "[circular]";
+                seen.add(v);
+            }
+            return v;
+        }) ?? String(value));
+    }
+    catch {
+        return String(value);
+    }
+}
+function render(o) {
+    return o.threw ? `threw(${o.message})` : `answered ${o.body}`;
+}
+async function withSubject(hooks, fn) {
+    const subject = await hooks.open();
+    try {
+        return await fn(subject);
+    }
+    finally {
+        subject.close?.();
+    }
+}
+export async function storeReadBackShapeContract(hooks) {
+    const { run, settle } = beginContract(hooks.runAssertion);
+    const where = hooks.face;
+    run(`${where}: the read face tells a present row from an absent one (positive control)`, async () => {
+        const empty = await withSubject(hooks, observe);
+        const seeded = await withSubject(hooks, async (s) => {
+            await s.seed();
+            return observe(s);
+        });
+        assert.equal(empty.threw, false, `${where}: reading an EMPTY store must answer, not throw (${render(empty)}) — absence is not damage`);
+        assert.equal(seeded.threw, false, `${where}: reading a well-formed row must answer, not throw (${render(seeded)})`);
+        const again = await withSubject(hooks, observe);
+        assert.deepEqual(again, empty, `${where}: two reads of two EMPTY stores answered differently (${render(empty)} then ${render(again)}) — this suite's oracle is "the corrupt answer differs from the empty one", which is free for a face carrying incidental data; project it away in the binding`);
+        assert.notDeepEqual(seeded, empty, `${where}: a seeded store and an empty one answered identically (${render(empty)}) — this face reports nothing a corrupt body could differ from, so every clause below would pass without meaning anything`);
+    });
+    for (const form of CORRUPT_BODY_FORMS) {
+        run(`${where}: a ${form} body is not read as an absent row`, async () => {
+            const sentinel = `sema-corrupt-sentinel-${form}`;
+            const empty = await withSubject(hooks, observe);
+            const corrupt = await withSubject(hooks, async (s) => {
+                if (s.unplantable !== undefined) {
+                    assert.ok(s.unplantable.length > 0, `${where}: a subject declaring no plantable body must say WHY`);
+                    return undefined;
+                }
+                await s.plant(form, sentinel);
+                return observe(s);
+            });
+            if (corrupt === undefined)
+                return;
+            assert.notDeepEqual(corrupt, empty, `${where}: a ${form} body was answered exactly as an absent row is (${render(empty)}) — a corrupt body must reach the caller as a refusal or as an absence that names the loss, never as the store's empty answer`);
+            if (!corrupt.threw) {
+                assert.ok(!corrupt.body.includes(sentinel), `${where}: a ${form} body was handed back through the read face (the planted marker is in the answer) — the read judged nothing`);
+            }
+        });
+    }
+    await settle();
+}

package/dist/index.d.ts

@@ -142,6 +142,9 @@ export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, RO
 export { type ToolCallFace } from "./core/tool-policy.js";
 export { effectivePathTargetOf, pathTargetBaseOf, type ToolPathBases, type PathTargetReading } from "./core/effective-path-target.js";
 export { pathFamilyOf, isAbsoluteForFamily, pathIdentityOf, win32NamespaceScreen, WIN32_NAMESPACE_REFUSALS, type PathFamily, type PathIdentity, type PathIdentityReading, type Win32NamespaceRefusal } from "./tools/fs/safety.js";
+export { judgeShellRead, type ShellReadJudgeInput, type ShellReadJudgment, type ShellReadVerdict, type ShellReadStationSeat, type ShellReadAdmission, } from "./tools/fs/shell-read-check.js";
+export { SHELL_READ_FINDINGS, SHELL_READ_SEATS, SHELL_READ_DECISION, SHELL_READ_FINDING_RANK, type ShellReadFinding, type ShellReadSeat, type ShellReadDisposition, type ShellReadBoundary, type ReadEstablishment, type EstablishedRead, type ReadFinding, } from "./tools/fs/shell-read-judge.js";
+export { type ReadCandidate, type ShellReadPlan, type ShellReadSegment } from "./tools/fs/shell-read-plan.js";
 export { TOOL_CONFORMANCE_VECTORS, type ToolConformanceVector } from "./core/tool-conformance.js";
 export { applyMcpToolFaces, toolFaceProblem, APPROVAL_CARD_REQUIRED_KEYS, type McpToolFace } from "./core/runner/tool-face-overlay.js";
 export { createStructuredProjector } from "./core/runner/tool-output-projection.js";
@@ -271,6 +274,7 @@ export { type WorkflowRunStore, type WorkflowRunSummary, summarizeWorkflowRun, i
 export { FileWorkflowRunStore, type FileWorkflowRunStoreOptions } from "./stores/file/workflow-run-store.js";
 export { workflowRunStoreContract } from "./core/workflow-run-store-contract.js";
 export { CONTRACT_KIT_ENGINE_VERSION } from "./core/store-contracts/contract-kit-version.js";
+export { CORRUPT_BODY_FORMS, storeReadBackShapeContract, type CorruptBodyForm, type ReadBackShapeSubject, type StoreReadBackShapeHooks, } from "./core/store-contracts/read-back-shape-contract.js";
 export { type ContractAssertionRunner } from "./core/store-contracts/contract-harness.js";
 export { checkpointStoreContract } from "./core/store-contracts/checkpoint-store-contract.js";
 export { sessionRepoContract } from "./core/store-contracts/session-repo-contract.js";

package/dist/index.js

@@ -115,6 +115,9 @@ export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, RO
 export {} from "./core/tool-policy.js";
 export { effectivePathTargetOf, pathTargetBaseOf } from "./core/effective-path-target.js";
 export { pathFamilyOf, isAbsoluteForFamily, pathIdentityOf, win32NamespaceScreen, WIN32_NAMESPACE_REFUSALS } from "./tools/fs/safety.js";
+export { judgeShellRead, } from "./tools/fs/shell-read-check.js";
+export { SHELL_READ_FINDINGS, SHELL_READ_SEATS, SHELL_READ_DECISION, SHELL_READ_FINDING_RANK, } from "./tools/fs/shell-read-judge.js";
+export {} from "./tools/fs/shell-read-plan.js";
 export { TOOL_CONFORMANCE_VECTORS } from "./core/tool-conformance.js";
 export { applyMcpToolFaces, toolFaceProblem, APPROVAL_CARD_REQUIRED_KEYS } from "./core/runner/tool-face-overlay.js";
 export { createStructuredProjector } from "./core/runner/tool-output-projection.js";
@@ -225,6 +228,7 @@ export { summarizeWorkflowRun, isTerminalWorkflowStatus, WorkflowRunStoreError,
 export { FileWorkflowRunStore } from "./stores/file/workflow-run-store.js";
 export { workflowRunStoreContract } from "./core/workflow-run-store-contract.js";
 export { CONTRACT_KIT_ENGINE_VERSION } from "./core/store-contracts/contract-kit-version.js";
+export { CORRUPT_BODY_FORMS, storeReadBackShapeContract, } from "./core/store-contracts/read-back-shape-contract.js";
 export {} from "./core/store-contracts/contract-harness.js";
 export { checkpointStoreContract } from "./core/store-contracts/checkpoint-store-contract.js";
 export { sessionRepoContract } from "./core/store-contracts/session-repo-contract.js";

package/dist/stores/file/adoption/adopt.js

@@ -3,7 +3,7 @@ import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { adoptFilePermissionRuleStore } from "../permission-rule-adopt.js";
 import { BootLock, atomicWriteFile, ensureDir, sanitizeScope } from "../fs-atomic.js";
-import { SESSION_POLICY_MARK_SUFFIX, readSessionPolicyMark } from "../session-policy-store.js";
+import { SESSION_POLICY_MARK_SUFFIX, judgeSessionPolicyRowObject, readSessionPolicyMark } from "../session-policy-store.js";
 import { thrownText } from "../../../core/thrown-value.js";
 import { AdoptionError, NOT_MIGRATED_BY_DESIGN, readRootAdoptionFile, writeRootAdoptionFile, } from "./marker.js";
 const CONFIG_ACCOUNT_FILE = "adoption-configs.json";
@@ -209,16 +209,10 @@ function rewriteSessionPolicyRows(root, fromPrincipal, toPrincipal) {
                 continue;
             throw err;
         }
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            continue;
-        }
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        const judged = judgeSessionPolicyRowObject(raw);
+        if ("corrupt" in judged)
             continue;
-        const row = parsed;
+        const row = judged.row;
         if (row.__principal !== fromPrincipal)
             continue;
         if (typeof row.__sid !== "string")

package/dist/stores/file/permission-rule-store.d.ts

@@ -139,7 +139,11 @@ declare class FileDurableRulePartition implements WritableDurableRulePartition {
     private screenDurableRows;
     private write;
     list(): Promise<StoredRules>;
-    /** The quarantine area (design/182 §5.2/§8.3): introspection only — never part of `list()`. */
+    /** The quarantine area (design/182 §5.2/§8.3): introspection only — never part of `list()`. Its posture
+     *  on an unreadable bucket is `list()`'s, for the reason `list()` has it: "the quarantine is empty" and
+     *  "the bucket cannot be read" are different facts about rows a person is meant to go and look at, and a
+     *  face that answers the first about the second is the one shape this store never renders. An ABSENT
+     *  bucket is still an empty quarantine. */
     quarantined(): Promise<QuarantinedRuleAdd[]>;
     /**
      * The current file, for a WRITE.

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

@@ -220,6 +220,8 @@ class FileDurableRulePartition {
     }
     async quarantined() {
         const r = this.read();
+        if ("unreadable" in r)
+            throw new Error(r.unreadable);
         return "file" in r ? this.screenDurableRows(r.file).quarantined : [];
     }
     current() {
@@ -307,7 +309,7 @@ class FileDurableRulePartition {
                         ...(joined.quarantined.length > 0 ? { quarantined: joined.quarantined } : {}),
                     };
                     if (!this.writeAndVerify(landed)) {
-                        throw new Error("the permission-rule store did not survive its own write; the change was not committed");
+                        throw new Error("the permission-rule store did not read back as the version just written; whether the change reached the bytes on disk is unobservable from here — reconcile by reading the store");
                     }
                     return { rev: cur.rev + 1, sync: report };
                 }
@@ -334,7 +336,7 @@ class FileDurableRulePartition {
                 }
             }
             if (!this.writeAndVerify(next)) {
-                throw new Error("the permission-rule store did not survive its own write; the change was not committed");
+                throw new Error("the permission-rule store did not read back as the version just written; whether the change reached the bytes on disk is unobservable from here — reconcile by reading the store");
             }
             return { rev: cur.rev + 1 };
         }),
@@ -452,7 +454,7 @@ class FileOrgRuleStatePersistence {
         atomicPublish(this.dir, this.file, JSON.stringify({ ...body, checksum: checksumOf(body) }, null, 2));
         const after = this.readSync();
         if (after === undefined || canonicalize(after) !== canonicalize(state)) {
-            const why = "the org state file did not survive its own write; the org snapshot was not installed";
+            const why = "the org state file did not read back as the version just written; whether the snapshot reached the bytes on disk is unobservable from here — reconcile by reading the file";
             this.onError?.(why);
             throw new Error(why);
         }

package/dist/stores/file/session-policy-store.d.ts

@@ -31,6 +31,8 @@ export interface StoredHighWaterMark {
     __gen?: number;
     __sid?: string;
     __principal?: string | null;
+    /** The erase's tombstone (a torn row purged with no mark): writes are refused until an operator deletes this file. */
+    __lineage?: "lost";
 }
 /**
  * The ONE reader of a mark file — the number it holds, or `null` when there is no file (the ordinary state of
@@ -41,6 +43,34 @@ export interface StoredHighWaterMark {
  * these files too, and a second, more tolerant reader over there is how the guarantee goes quietly missing.
  */
 export declare function readSessionPolicyMark(path: string): StoredHighWaterMark | null;
+/** Why one row file's bytes are not a row. `unparseable` is the ONE grade saying they are not JSON at all — the
+ *  only evidence the erase sweep's crash-artifact ruling rests on. `reason` is the disclosure text, so two faces
+ *  judging the SAME file name the same fault in the same words. */
+export interface SessionPolicyRowFault {
+    grade: "unparseable" | "malformed";
+    reason: string;
+}
+/** One row file's bytes → the JSON object every face of this directory requires before reading a field off it.
+ *  Split from the rules-shape judgment below because the erase sweep and the ownership rebind treat a row as
+ *  bytes-with-attribution: a malformed-rules row is still erasable and still travels with its key. */
+export declare function judgeSessionPolicyRowObject(raw: string): {
+    row: Record<string, unknown>;
+} | {
+    corrupt: SessionPolicyRowFault;
+};
+/**
+ * The SHAPE of a stored row, judged ONCE for every face that serves its rules to a reader — the per-key read
+ * and the session-wide enumeration alike, so one store cannot answer two things about one file.
+ *
+ * Required: `rev` >= 1 (a rev-0 row would read as the live reader's SYNTHETIC empty seed); `gen`, when present, a
+ * whole number; every rule field a string array (a STRING `rev` poisons the CAS arithmetic). The `__sid`/`__principal`
+ * metadata is STRIPPED so the value is byte-identical to the in-memory twin's.
+ */
+export declare function judgeSessionPolicyRowShape(row: Record<string, unknown>): {
+    rules: StoredSessionRules;
+} | {
+    corrupt: SessionPolicyRowFault;
+};
 export declare class FileSessionPolicyStore implements SessionPolicyStore {
     private readonly dir;
     private readonly onCorruptRead;
@@ -71,6 +101,8 @@ export declare class FileSessionPolicyStore implements SessionPolicyStore {
     private basenameFor;
     private markPathFor;
     private writeMarkFile;
+    /** The mark as given — the erase's lineage transition rewrites a mark keeping whatever attribution it had. */
+    private writeMark;
     private read;
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;

package/dist/stores/file/session-policy-store.js

@@ -40,6 +40,34 @@ export function readSessionPolicyMark(path) {
         return refuse("carries a lineage that is not a whole number");
     return mark;
 }
+export function judgeSessionPolicyRowObject(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { corrupt: { grade: "unparseable", reason: "unparseable JSON (torn/zero-byte write?)" } };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { corrupt: { grade: "malformed", reason: "not a JSON object" } };
+    }
+    return { row: parsed };
+}
+export function judgeSessionPolicyRowShape(row) {
+    const bad = (reason) => ({ corrupt: { grade: "malformed", reason } });
+    if (typeof row.rev !== "number" || !Number.isFinite(row.rev) || row.rev < 1)
+        return bad("rev is not a positive number");
+    if (row.gen !== undefined && (typeof row.gen !== "number" || !Number.isInteger(row.gen) || row.gen < 0))
+        return bad("gen is not a whole number");
+    const strArr = (x) => x === undefined || (Array.isArray(x) && x.every((e) => typeof e === "string"));
+    if (!strArr(row.toolAllow) || !strArr(row.toolDeny) || !strArr(row.commandAllow) || !strArr(row.commandDeny) || !strArr(row.allowDirs)) {
+        return bad("malformed rule field");
+    }
+    const { __sid: _sid, __principal: _principal, ...clean } = row;
+    void _sid;
+    void _principal;
+    return { rules: clean };
+}
 export class FileSessionPolicyStore {
     dir;
     onCorruptRead;
@@ -75,7 +103,9 @@ export class FileSessionPolicyStore {
         return join(this.dir, `${this.basenameFor(sessionId, principal)}${MARK_SUFFIX}`);
     }
     writeMarkFile(path, rev, sessionId, principal, gen) {
-        const mark = { __hwm: rev, __gen: gen, __sid: sessionId, __principal: principal };
+        this.writeMark(path, { __hwm: rev, __gen: gen, __sid: sessionId, __principal: principal });
+    }
+    writeMark(path, mark) {
         atomicWriteFile(join(this.dir, "tmp"), path, JSON.stringify(mark));
     }
     read(sessionId, principal) {
@@ -88,35 +118,17 @@ export class FileSessionPolicyStore {
                 return null;
             throw err;
         }
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                this.discloseCorrupt(sessionId, principal, "not a JSON object");
-                return null;
-            }
-            const r = parsed;
-            if (typeof r.rev !== "number" || !Number.isFinite(r.rev) || r.rev < 1) {
-                this.discloseCorrupt(sessionId, principal, "rev is not a positive number");
-                return null;
-            }
-            if (r.gen !== undefined && (typeof r.gen !== "number" || !Number.isInteger(r.gen) || r.gen < 0)) {
-                this.discloseCorrupt(sessionId, principal, "gen is not a whole number");
-                return null;
-            }
-            const strArr = (x) => x === undefined || (Array.isArray(x) && x.every((e) => typeof e === "string"));
-            if (!strArr(r.toolAllow) || !strArr(r.toolDeny) || !strArr(r.commandAllow) || !strArr(r.commandDeny) || !strArr(r.allowDirs)) {
-                this.discloseCorrupt(sessionId, principal, "malformed rule field");
-                return null;
-            }
-            const { __sid: _sid, __principal: _principal, ...clean } = r;
-            void _sid;
-            void _principal;
-            return clean;
+        const judged = judgeSessionPolicyRowObject(raw);
+        if ("corrupt" in judged) {
+            this.discloseCorrupt(sessionId, principal, judged.corrupt.reason);
+            return null;
         }
-        catch {
-            this.discloseCorrupt(sessionId, principal, "unparseable JSON (torn/zero-byte write?)");
+        const shaped = judgeSessionPolicyRowShape(judged.row);
+        if ("corrupt" in shaped) {
+            this.discloseCorrupt(sessionId, principal, shaped.corrupt.reason);
             return null;
         }
+        return shaped.rules;
     }
     async getRules(sessionId, principal) {
         return this.read(sessionId, principal);
@@ -134,8 +146,12 @@ export class FileSessionPolicyStore {
             }
         }
         const mark = readSessionPolicyMark(this.markPathFor(sessionId, principal));
+        const rowFilePresent = prior === null && existsSync(this.pathFor(sessionId, principal));
+        if (mark?.__lineage === "lost" || (rowFilePresent && mark === null)) {
+            throw new SessionPolicyError("corrupt", `session rules for ${JSON.stringify(sessionId)} have no lineage evidence (${mark?.__lineage === "lost" ? "the erase left a lost-lineage mark" : "an unreadable row and no high-water mark"}) — refusing to restart the key's lineage by guessing; delete the mark${rowFilePresent ? " and the row file" : ""} to restart it`);
+        }
         const floor = Math.max(prior?.rev ?? 0, mark?.__hwm ?? 0);
-        const gen = prior?.gen ?? (existsSync(this.pathFor(sessionId, principal)) ? (mark?.__gen ?? 0) + 1 : (mark?.__gen ?? 0));
+        const gen = prior !== null ? (prior.gen ?? 0) : rowFilePresent ? (mark?.__gen ?? 0) + 1 : (mark?.__gen ?? 0);
         const next = { ...clean, rev: floor + 1, gen };
         const attributedPrincipal = (principal ?? this.anonymousAlias) ?? null;
         this.writeMarkFile(this.markPathFor(sessionId, principal), next.rev, sessionId, attributedPrincipal, gen);
@@ -169,24 +185,28 @@ export class FileSessionPolicyStore {
                 }
                 continue;
             }
-            let parsed;
-            try {
-                parsed = JSON.parse(raw);
+            const judged = judgeSessionPolicyRowObject(raw);
+            if ("corrupt" in judged) {
+                this.disclose({ sessionId, path: full, reason: judged.corrupt.reason });
+                continue;
             }
-            catch {
-                this.disclose({ sessionId, path: full, reason: "unparseable JSON (torn/zero-byte write?)" });
+            if (typeof judged.row.__sid !== "string") {
+                this.disclose({ sessionId, path: full, reason: "session metadata is not a string" });
                 continue;
             }
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-                this.disclose({ sessionId, path: full, reason: "not a JSON object" });
+            if (judged.row.__sid !== sessionId)
+                continue;
+            const shaped = judgeSessionPolicyRowShape(judged.row);
+            if ("corrupt" in shaped) {
+                this.disclose({ sessionId, path: full, reason: shaped.corrupt.reason });
                 continue;
             }
-            const r = parsed;
-            if (r.__sid !== sessionId)
+            const attributed = judged.row.__principal;
+            if (attributed !== undefined && attributed !== null && typeof attributed !== "string") {
+                this.disclose({ sessionId, path: full, reason: "principal metadata is not a string" });
                 continue;
-            const { __sid: _sid, __principal, ...rules } = r;
-            void _sid;
-            out.push({ principal: __principal ?? undefined, rules: rules });
+            }
+            out.push({ principal: attributed ?? undefined, rules: shaped.rules });
         }
         return out;
     }
@@ -212,21 +232,25 @@ export class FileSessionPolicyStore {
             catch {
                 continue;
             }
-            let parsed;
-            try {
-                parsed = JSON.parse(raw);
-            }
-            catch {
+            const judged = judgeSessionPolicyRowObject(raw);
+            if ("corrupt" in judged) {
+                if (judged.corrupt.grade !== "unparseable")
+                    continue;
                 const tornMarkPath = join(this.dir, `${file.slice(0, -".json".length)}${MARK_SUFFIX}`);
                 try {
                     const tornMark = readSessionPolicyMark(tornMarkPath);
-                    if (tornMark !== null && tornMark.__sid === sessionId) {
-                        this.writeMarkFile(tornMarkPath, tornMark.__hwm, sessionId, tornMark.__principal ?? null, (tornMark.__gen ?? 0) + 1);
+                    if (tornMark === null) {
+                        this.writeMark(tornMarkPath, { __hwm: 0, __gen: 0, __lineage: "lost" });
+                        this.disclose({ sessionId, path: join(this.dir, file), reason: "erase purged a torn row that had no high-water mark: the key's lineage is lost, writes are refused until the mark is deleted" });
+                    }
+                    else {
+                        this.writeMark(tornMarkPath, { ...tornMark, __gen: (tornMark.__gen ?? 0) + 1 });
                     }
                 }
                 catch (err) {
                     if (!(err instanceof SessionPolicyError))
                         throw err;
+                    this.disclose({ sessionId, path: join(this.dir, file), reason: `erase purged a torn row whose high-water mark is corrupt (${err.message}); the mark is left for the operator` });
                 }
                 try {
                     unlinkSync(join(this.dir, file));
@@ -237,9 +261,7 @@ export class FileSessionPolicyStore {
                 }
                 continue;
             }
-            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-                continue;
-            const row = parsed;
+            const row = judged.row;
             if (row.__sid !== sessionId)
                 continue;
             const markPath = join(this.dir, `${file.slice(0, -".json".length)}${MARK_SUFFIX}`);

package/dist/tools/fs/shell-read-check.d.ts

@@ -12,10 +12,15 @@
  * tools' execute legs judge nothing: what they run is what this station admitted, and the admission only
  * re-establishes the SAME candidates (a symlink re-pointed while the approver was thinking) — it never
  * parses text or judges a word the station did not.
+ *
+ * That pipeline is written ONCE (`runShellReadStation`) and has two entries: the gate input above, and
+ * {@link judgeShellRead}, the offline face. The steps between stay private — the station's working, not
+ * its answer, and a caller composing them would be a second judgment of the same question.
  */
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { violationDetails } from "./safety.js";
-import { type ShellReadBoundary, type ShellReadDisposition, type ShellReadFinding, type ShellReadSeat } from "./shell-read-judge.js";
+import { type ShellReadPlan } from "./shell-read-plan.js";
+import { type EstablishedRead, type ShellReadBoundary, type ShellReadDisposition, type ShellReadFinding, type ShellReadSeat } from "./shell-read-judge.js";
 import type { ReadRootGrantCandidate } from "../../core/tool-spec.js";
 /** The ONE mint of the containment card — every arm that refuses or asks on a containment finding (a refusal, a
  *  mandated card's own card, a station that could not answer, the pre-spawn re-establishment) spells it here. */
@@ -85,6 +90,58 @@ export interface ShellReadStationOptions {
     /** The listed read verbs (decides whether a segment is read by verb slots or word by word). */
     readonly readers?: ReadonlySet<string>;
 }
+/** What a consumer hands {@link judgeShellRead}: the command as written, the environment whose filesystem
+ *  answers where its words land (symlinks resolved, patterns expanded — a `NodeExecutionEnv` over a real
+ *  directory is what the gate itself runs on), the boundary it is judged against, and the trust-policy seat
+ *  it is judged on. The working directory a relative operand starts from is the boundary's own `cwd`. */
+export interface ShellReadJudgeInput {
+    readonly command: string;
+    readonly env: ExecutionEnv;
+    readonly boundary: ShellReadBoundary;
+    readonly seat: ShellReadSeat;
+    /** The listed read verbs — which words of a segment are read operands. Defaults to the classify face's. */
+    readonly readers?: ReadonlySet<string>;
+    /** The face named in a refusal sentence. Defaults to `Bash`. */
+    readonly tool?: string;
+    /** Handed to the ENVIRONMENT's own primitives (`canonicalPath`, `listDir`) while the reads are
+     *  established; whether an abort stops one is the adapter's answer, and a walk short enough to finish
+     *  first finishes. It is NOT a deadline and it does not reach `boundary.alsoInside`, whose signature
+     *  carries no signal — see {@link judgeShellRead} on which layer owns the bound. */
+    readonly signal?: AbortSignal;
+}
+/** What {@link judgeShellRead} answers about ONE command. */
+export interface ShellReadJudgment {
+    /** What the station read out of the command's text before any filesystem was consulted. */
+    readonly plan: ShellReadPlan;
+    /** Every read candidate the station established, in the plan's own order, nested plans included — each
+     *  carrying how far it got (`EstablishedRead.established`) and the target it was judged on. */
+    readonly establishment: readonly EstablishedRead[];
+    readonly verdict: ShellReadVerdict;
+    /** The directory-scoped grant offer THIS STATION is willing to make — the verdict's candidate through the
+     *  same validator the gate applies, so a candidate that validator drops is absent here as it is there. It
+     *  is the station's offer, not the composed card's: over an ask another layer already raised, the fold
+     *  adds the mandate and nothing else, so the offer does not land there. */
+    readonly offer?: ReadRootGrantCandidate;
+}
+/**
+ * The station's judgment of ONE command, OUTSIDE a run — the consumer face of everything above. Same plan,
+ * same establishment, same judge, same table, same verdict the gate fold reads: this is
+ * {@link createShellReadStation}'s own derivation with the admission bookkeeping left out, so a caller
+ * holding a command, an environment and a boundary gets the decision the gate would reach for them.
+ *
+ * An ENVIRONMENT question, not a text question: a symlink that leaves the roots, a pattern that expands
+ * onto a deny row, a traversal root that cannot be enumerated are answered by `env`, not guessed from the
+ * spelling. {@link judgeShellReadLexically} is the no-environment reading and not a substitute — it is
+ * LAXER where only a filesystem sees the escape (an in-root symlink pointing out vouches) and answers a
+ * pattern on its spelling alone, so the two diverge in both directions.
+ *
+ * It carries NO deadline. Bounding an environment-facing wait and substituting a fail-closed verdict is the
+ * gate FOLD's policy on the gate's one deadline seat; the station has never held one on either entry, and a
+ * second default here would decide the same number twice and turn a slow-but-correct filesystem's true
+ * answer into a fail-closed one unasked. A consumer wanting that posture races its own deadline and reads
+ * the row the fold reads: `SHELL_READ_DECISION.unestablishable[seat]`.
+ */
+export declare function judgeShellRead(input: ShellReadJudgeInput): Promise<ShellReadJudgment>;
 /**
  * The station's verdict with NO environment — the lexical reading (what an isolated sandbox gets, and what a
  * pin or a lexical pre-read can compute): the same plan, the same judge, the same table, over the folded

package/dist/tools/fs/shell-read-check.js

@@ -7,6 +7,7 @@ import { bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { planShellReads } from "./shell-read-plan.js";
 import { createShellReadEstablisher, establishShellReadsLexically } from "./shell-read-establish.js";
 import { allFindings, decideShellRead, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, } from "./shell-read-judge.js";
+import { normalizeReadRootCandidate } from "../../core/read-root-candidate.js";
 import { wordsOf, lexShellText } from "./bash-lexer.js";
 function containmentDetails(paths) {
     return { type: "readonly_out_of_root", code: "readonly_out_of_root", paths };
@@ -113,6 +114,48 @@ function judgePlan(plan, established, boundary) {
         return nested === undefined ? { plan: n, segments: [] } : judgePlan(n, nested, boundary);
     });
 }
+async function applyAlsoInside(judged, boundary) {
+    const alsoInside = boundary.alsoInside;
+    if (alsoInside === undefined)
+        return judged;
+    const rescued = new Set();
+    for (const f of allFindings(judged)) {
+        if (f.kind !== "outside_roots" || f.read.target === undefined || rescued.has(f.read.target))
+            continue;
+        if (await alsoInside(f.read.target))
+            rescued.add(f.read.target);
+    }
+    if (rescued.size === 0)
+        return judged;
+    const rewrite = (j) => ({
+        plan: j.plan,
+        segments: j.segments.map((s) => ({
+            segment: s.segment,
+            findings: s.findings.map((f) => (f.kind === "outside_roots" && f.read.target !== undefined && rescued.has(f.read.target) ? { ...f, kind: "none", containment: "inside" } : f)),
+            nested: s.nested.map(rewrite),
+        })),
+    });
+    return rewrite(judged);
+}
+async function runShellReadStation(tool, command, declared, seat, readers, establisher, signal) {
+    const plan = planShellReads(command, declarationsOf(declared, readers));
+    const established = await establisher.establish(plan, declared, signal);
+    const boundary = { ...declared, roots: established.roots };
+    const judged = await applyAlsoInside(judgePlan(plan, established, boundary), boundary);
+    const verdict = verdictOf(tool, seat, foldShellReadFindings(judged), judged, boundary);
+    return { plan, established, judged, boundary, verdict };
+}
+export async function judgeShellRead(input) {
+    const readers = input.readers ?? new Set(bashClassifyDefaultAllow());
+    const run = await runShellReadStation(input.tool ?? "Bash", input.command, input.boundary, input.seat, readers, createShellReadEstablisher(input.env, input.boundary.roots), input.signal);
+    const offer = normalizeReadRootCandidate(run.verdict.readRootCandidate);
+    return {
+        plan: run.plan,
+        establishment: allFindings(run.judged).map((f) => f.read),
+        verdict: run.verdict,
+        ...(offer !== undefined ? { offer } : {}),
+    };
+}
 export function judgeShellReadLexically(command, boundary, seat, opts) {
     const readers = opts?.readers ?? new Set(bashClassifyDefaultAllow());
     const plan = planShellReads(command, declarationsOf(boundary, readers));
@@ -141,29 +184,6 @@ export function createShellReadStation(opts) {
         }
         admissions.set(toolCallId, a);
     };
-    const applyAlsoInside = async (judged, boundary) => {
-        const alsoInside = boundary.alsoInside;
-        if (alsoInside === undefined)
-            return judged;
-        const rescued = new Set();
-        for (const f of allFindings(judged)) {
-            if (f.kind !== "outside_roots" || f.read.target === undefined || rescued.has(f.read.target))
-                continue;
-            if (await alsoInside(f.read.target))
-                rescued.add(f.read.target);
-        }
-        if (rescued.size === 0)
-            return judged;
-        const rewrite = (j) => ({
-            plan: j.plan,
-            segments: j.segments.map((s) => ({
-                segment: s.segment,
-                findings: s.findings.map((f) => (f.kind === "outside_roots" && f.read.target !== undefined && rescued.has(f.read.target) ? { ...f, kind: "none", containment: "inside" } : f)),
-                nested: s.nested.map(rewrite),
-            })),
-        });
-        return rewrite(judged);
-    };
     const check = {
         judge(toolName, args, cwd, signal, callOpts) {
             if (!opts.tools.has(toolName))
@@ -176,16 +196,10 @@ export function createShellReadStation(opts) {
                 return null;
             const seat = callOpts.seat ?? opts.seatOf(toolName);
             return (async () => {
-                const plan = planShellReads(command, declarationsOf(boundary, readers));
-                const establisher = establisherFor(boundary.roots);
-                const established = await establisher.establish(plan, boundary, signal);
-                const judgedBoundary = { ...boundary, roots: established.roots };
-                const judged = await applyAlsoInside(judgePlan(plan, established, judgedBoundary), judgedBoundary);
-                const fold = foldShellReadFindings(judged);
-                const verdict = verdictOf(toolName, seat, fold, judged, judgedBoundary);
-                if (verdict.disposition !== "refuse" && callOpts.toolCallId !== undefined)
-                    remember(callOpts.toolCallId, { toolName, boundary: judgedBoundary, established, command });
-                return verdict;
+                const run = await runShellReadStation(toolName, command, boundary, seat, readers, establisherFor(boundary.roots), signal);
+                if (run.verdict.disposition !== "refuse" && callOpts.toolCallId !== undefined)
+                    remember(callOpts.toolCallId, { toolName, boundary: run.boundary, established: run.established, command });
+                return run.verdict;
             })();
         },
         unanswered(toolName, cause) {