@sema-agent/core 7.24.4 → 7.25.1

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

@@ -0,0 +1,99 @@
+/**
+ * The shell read STATION — the gate input that judges where a shell command reads, before approval, on
+ * every shell face (`createShellReadCheck`), and the pre-spawn admission the shell tools call with the
+ * same establishment (`ShellReadAdmission`). ONE pipeline, one call:
+ *
+ *     planShellReads(text) → establish(plan, env) → judgeRead ×N → foldShellReadFindings → decideShellRead(seat)
+ *
+ * The station is a POLICY-class member of the gate fold: a `deny_hit` refuses outright (composing under
+ * `deny > ask > allow`, so it outranks a hook's or a policy's ask), a mandated finding tightens a surviving
+ * allow to a MANDATED ask (or marks an existing ask mandated), an ordinary finding tightens to an ORDINARY
+ * ask (or marks the pass `probeBoundaryDeclined`), and `none` leaves the decision untouched. The three
+ * 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.
+ */
+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 { 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. */
+declare function containmentDetails(paths: readonly string[]): {
+    readonly type: "readonly_out_of_root";
+    readonly code: "readonly_out_of_root";
+    readonly paths: readonly string[];
+};
+/** The structured details a refusal carries — the same two wire discriminants the shell tools' own
+ *  refusals carried before the station existed, so a consumer counting either code counts one thing: the deny
+ *  card is the read faces' own (`violationDetails`, safety.ts), the containment card is minted above. */
+export type ShellReadRefusalDetails = Extract<NonNullable<ReturnType<typeof violationDetails>>, {
+    code: "read_path_denied";
+}> | ReturnType<typeof containmentDetails>;
+/** What the station answers for ONE call. */
+export interface ShellReadVerdict {
+    readonly disposition: ShellReadDisposition;
+    readonly finding: ShellReadFinding;
+    /** `refuse`: the refusal text (`Error (<tool>): …`, the five-segment deny sentence or the containment
+     *  sentence). `mandated` / `ordinary`: the ACCOUNT of the finding, for the approval card's disclosure seat
+     *  (never the ask's own message — that is the auto-mode classifier's input). Absent for `vouch`. */
+    readonly sentence?: string;
+    /** `refuse`: the refusal's structured details. `mandated` on an `outside_roots` / `unestablishable` finding: the
+     *  same containment card, so an ask a person refuses or nobody can answer still carries WHAT was found on
+     *  its `tool_end` (`readonly_out_of_root`), as the tool's own refusal of that finding did. */
+    readonly details?: ShellReadRefusalDetails;
+    /** `mandated` on an `outside_roots` finding: the directory whose grant would clear this ask. */
+    readonly readRootCandidate?: ReadRootGrantCandidate;
+}
+/** The station seat one tool call is judged on (the `rejudge` seat is asked for by the caller). */
+export type ShellReadStationSeat = Exclude<ShellReadSeat, "rejudge">;
+/**
+ * The ENGINE-FILLED gate input. `judge` returns `null` SYNCHRONOUSLY when the call is not this station's
+ * business — not a shell-running tool, no command string — and otherwise the verdict, a promise. The split
+ * is load-bearing for the gate: a call the station does not cover must not cost the fold a suspension
+ * point. `unanswered` is the verdict the fold substitutes when the wait elapsed or threw — fail-closed as
+ * `unestablishable` on the call's own seat.
+ */
+export interface ShellReadCheck {
+    judge(toolName: string, args: unknown, cwd: string | undefined, signal: AbortSignal | undefined, opts: {
+        readonly toolCallId?: string;
+        readonly seat?: "rejudge";
+    }): Promise<ShellReadVerdict> | null;
+    unanswered(toolName: string, cause: string): ShellReadVerdict;
+}
+/** The pre-spawn admission the shell tools call: re-establishes what the station established for this
+ *  call and refuses when any canonical target moved. `undefined` ⇒ spawn. A call the station never judged
+ *  (no gate ran) has nothing to re-establish and spawns. */
+export type ShellReadAdmission = (toolName: string, toolCallId: string | undefined, command: string, signal?: AbortSignal) => Promise<{
+    content: string;
+    isError: true;
+    details?: unknown;
+} | undefined>;
+export interface ShellReadStation {
+    readonly check: ShellReadCheck;
+    readonly admit: ShellReadAdmission;
+}
+export interface ShellReadStationOptions {
+    readonly env: ExecutionEnv;
+    /** Which tool names spawn a shell command through this leg — the station's membership. */
+    readonly tools: ReadonlySet<string>;
+    /** The trust-policy seat a tool is judged on. */
+    readonly seatOf: (toolName: string) => ShellReadStationSeat;
+    /** The boundary for a call, read per call (the tracked working directory moves). `undefined` ⇒ no
+     *  boundary declared, nothing to be outside of — the station vouches. */
+    readonly boundaryOf: (toolName: string, cwd: string | undefined) => ShellReadBoundary | undefined;
+    /** The listed read verbs (decides whether a segment is read by verb slots or word by word). */
+    readonly readers?: ReadonlySet<string>;
+}
+/**
+ * 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
+ * spellings alone. `tool` names the face in the refusal sentence.
+ */
+export declare function judgeShellReadLexically(command: string, boundary: ShellReadBoundary, seat: ShellReadSeat, opts?: {
+    readonly readers?: ReadonlySet<string>;
+    readonly tool?: string;
+}): ShellReadVerdict;
+/** Mount the station for one execution environment. */
+export declare function createShellReadStation(opts: ShellReadStationOptions): ShellReadStation;
+export {};

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

@@ -0,0 +1,229 @@
+import { errorResult } from "../../core/tools.js";
+import { BASH_READONLY_CONFINEMENT_NOTE } from "./fs-shared.js";
+import { violationDetails } from "./safety.js";
+import { fitMiddle, READ_DENY_SENTENCE_PART_MAX, readDenySentence } from "./read-deny.js";
+import { NOT_AUTO_ALLOWED, programPositionRefusalSentence, readProgramPosition } from "./bash-program-position.js";
+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 { wordsOf, lexShellText } from "./bash-lexer.js";
+function containmentDetails(paths) {
+    return { type: "readonly_out_of_root", code: "readonly_out_of_root", paths };
+}
+const ADMISSION_MAX = 1024;
+function shellCommandOf(args) {
+    const command = args?.command;
+    return typeof command === "string" ? command : undefined;
+}
+function declineSentence(segment) {
+    const lexed = lexShellText(segment.text, { mode: "lenient" });
+    if (!("reject" in lexed) && lexed.segments[0] !== undefined) {
+        const pos = readProgramPosition(wordsOf(lexed.segments[0]));
+        if (pos.refusal !== undefined)
+            return programPositionRefusalSentence(pos.refusal);
+        if (pos.argvFromStdin) {
+            const runs = pos.program?.basename ?? "the program it runs";
+            return `"${segment.text.trim()}" hands ${runs} its operands on its standard input, which this station does not read ${NOT_AUTO_ALLOWED}`;
+        }
+    }
+    return `"${segment.text.trim()}" runs a program this station cannot name ${NOT_AUTO_ALLOWED}`;
+}
+const ACCOUNT_PART_MAX = READ_DENY_SENTENCE_PART_MAX;
+const CAUSE_SPELLING_MAX = 64;
+function fitCause(cause) {
+    return cause.replace(/^"([^"]*)"/, (_m, spelling) => `"${fitMiddle(spelling, CAUSE_SPELLING_MAX)}"`);
+}
+function findingAccount(fold, roots) {
+    const allowed = fitMiddle(roots.length > 0 ? roots.join(", ") : "(none)", ACCOUNT_PART_MAX);
+    const w = fold.witness;
+    switch (fold.finding) {
+        case "outside_roots":
+            return `reads outside the allowed directories for this session: "${fitMiddle(w?.read.target ?? "?", ACCOUNT_PART_MAX)}" is not under ${allowed} ${NOT_AUTO_ALLOWED}`;
+        case "unestablishable":
+            if (w?.read.cause !== undefined)
+                return `where this command reads could not be established: ${fitCause(w.read.cause)}, so it cannot be confirmed to read only inside the allowed directories for this session (${allowed}) ${NOT_AUTO_ALLOWED}`;
+            if (fold.declined?.baseMove !== undefined)
+                return `"${fitMiddle(fold.declined.text.trim(), ACCOUNT_PART_MAX)}" moves the working directory somewhere this command's text does not settle ${NOT_AUTO_ALLOWED}`;
+            if (fold.declined?.unreadProgramText !== undefined)
+                return `"${fitMiddle(fold.declined.text.trim(), ACCOUNT_PART_MAX)}": ${fold.declined.unreadProgramText}, so where it reads cannot be established ${NOT_AUTO_ALLOWED}`;
+            if (fold.declined !== undefined)
+                return `"${fitMiddle(fold.declined.text.trim(), ACCOUNT_PART_MAX)}" runs its argument as shell text this station does not parse ${NOT_AUTO_ALLOWED}`;
+            return `the command's text could not be read as shell, so where it reads cannot be established ${NOT_AUTO_ALLOWED}`;
+        case "declined":
+            return fold.declined !== undefined ? declineSentence(fold.declined) : `the station could not read which program runs ${NOT_AUTO_ALLOWED}`;
+        case "identity_changed":
+            return `"${fitMiddle(w?.read.candidate.raw ?? "?", ACCOUNT_PART_MAX)}" resolves to "${fitMiddle(w?.read.target ?? "?", ACCOUNT_PART_MAX)}" now, not where it resolved when this call was judged`;
+        case "deny_hit":
+        case "none":
+            return "";
+        default: {
+            const exhaustive = fold.finding;
+            return exhaustive;
+        }
+    }
+}
+function outsidePathsOf(judged) {
+    const out = [];
+    for (const f of allFindings(judged)) {
+        if (f.kind === "outside_roots" && f.read.target !== undefined && !out.includes(f.read.target))
+            out.push(f.read.target);
+    }
+    return out;
+}
+function refusalOf(tool, fold, roots, paths) {
+    const w = fold.witness;
+    if (fold.finding === "deny_hit" && w?.deny !== undefined) {
+        const target = w.read.target ?? w.deny.matchedView;
+        const core = readDenySentence({ target, pattern: w.deny.pattern, matchedView: w.deny.matchedView });
+        const sentence = `Error (${tool}): ${core} ${DENY_REFUSAL_NOTE}`;
+        return { sentence, details: violationDetails({ code: "read_path_denied", message: sentence, target, pattern: w.deny.pattern }) };
+    }
+    const account = findingAccount(fold, roots);
+    const sentence = `Error (${tool}): ${account}. ${BASH_READONLY_CONFINEMENT_NOTE}`;
+    return { sentence, details: containmentDetails(paths) };
+}
+const DENY_REFUSAL_NOTE = "The read boundary judges this command's written spelling and, where a filesystem can be consulted, the " +
+    "paths it would actually read; a deny-listed read is refused here rather than escalated.";
+function verdictOf(tool, seat, fold, judged, boundary) {
+    const disposition = decideShellRead(fold.finding, seat);
+    if (disposition === "vouch")
+        return { disposition, finding: fold.finding };
+    const paths = outsidePathsOf(judged);
+    if (disposition === "refuse") {
+        const r = refusalOf(tool, fold, boundary.roots, paths);
+        return { disposition, finding: fold.finding, sentence: r.sentence, details: r.details };
+    }
+    const grant = fold.finding === "outside_roots" ? readRootGrantCandidateOf(judged, boundary) : undefined;
+    const containment = fold.finding === "outside_roots" || fold.finding === "unestablishable";
+    return {
+        disposition,
+        finding: fold.finding,
+        sentence: findingAccount(fold, boundary.roots),
+        ...(disposition === "mandated" && containment ? { details: containmentDetails(paths) } : {}),
+        ...(grant !== undefined ? { readRootCandidate: { dir: grant.dir, ...(grant.covers !== undefined ? { covers: grant.covers } : {}), clearsThisAsk: true } } : {}),
+    };
+}
+function declarationsOf(boundary, readers) {
+    return { readers, cwd: boundary.cwd ?? boundary.roots[0] ?? "", roots: boundary.roots, ...(boundary.homeDir !== undefined ? { homeDir: boundary.homeDir } : {}), ...(boundary.face !== undefined ? { face: boundary.face } : {}) };
+}
+function judgePlan(plan, established, boundary) {
+    return judgeEstablishedPlan(plan, established.reads, boundary, (n) => {
+        const nested = established.nested.get(n);
+        return nested === undefined ? { plan: n, segments: [] } : judgePlan(n, nested, boundary);
+    });
+}
+export function judgeShellReadLexically(command, boundary, seat, opts) {
+    const readers = opts?.readers ?? new Set(bashClassifyDefaultAllow());
+    const plan = planShellReads(command, declarationsOf(boundary, readers));
+    const established = establishShellReadsLexically(plan, boundary);
+    const judged = judgePlan(plan, established, boundary);
+    return verdictOf(opts?.tool ?? "Bash", seat, foldShellReadFindings(judged), judged, boundary);
+}
+export function createShellReadStation(opts) {
+    const readers = opts.readers ?? new Set(bashClassifyDefaultAllow());
+    const establishers = new Map();
+    const establisherFor = (roots) => {
+        const key = roots.join("\0");
+        let e = establishers.get(key);
+        if (e === undefined) {
+            e = createShellReadEstablisher(opts.env, roots);
+            establishers.set(key, e);
+        }
+        return e;
+    };
+    const admissions = new Map();
+    const remember = (toolCallId, a) => {
+        if (admissions.size >= ADMISSION_MAX) {
+            const oldest = admissions.keys().next().value;
+            if (oldest !== undefined)
+                admissions.delete(oldest);
+        }
+        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))
+                return null;
+            const command = shellCommandOf(args);
+            if (command === undefined)
+                return null;
+            const boundary = opts.boundaryOf(toolName, cwd);
+            if (boundary === undefined)
+                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;
+            })();
+        },
+        unanswered(toolName, cause) {
+            const seat = opts.seatOf(toolName);
+            const fold = { finding: "unestablishable" };
+            const disposition = decideShellRead("unestablishable", seat);
+            const account = `${cause}, so where this command reads could not be established ${NOT_AUTO_ALLOWED}`;
+            const details = containmentDetails([]);
+            if (disposition === "refuse")
+                return { disposition, finding: "unestablishable", sentence: `Error (${toolName}): ${account}. ${BASH_READONLY_CONFINEMENT_NOTE}`, details };
+            return { disposition, finding: fold.finding, sentence: account, ...(disposition === "mandated" ? { details } : {}) };
+        },
+    };
+    const admit = async (toolName, toolCallId, command, signal) => {
+        if (toolCallId === undefined)
+            return undefined;
+        const a = admissions.get(toolCallId);
+        if (a === undefined)
+            return undefined;
+        admissions.delete(toolCallId);
+        if (a.toolName !== toolName || a.command !== command) {
+            return errorResult(`Error (${toolName}): the command that would run is not the one the read station judged for this call — refused before the spawn; re-submit it as a fresh call.`, containmentDetails([]));
+        }
+        const establisher = establisherFor(a.boundary.roots);
+        const { changed } = await establisher.reestablish(a.established, a.boundary, signal);
+        if (changed.length === 0)
+            return undefined;
+        const again = await establisher.establish(a.established.plan, a.boundary, signal);
+        const judged = await applyAlsoInside(judgePlan(a.established.plan, again, a.boundary), a.boundary);
+        const fold = foldShellReadFindings(judged);
+        if (fold.finding === "deny_hit") {
+            const r = refusalOf(toolName, fold, a.boundary.roots, outsidePathsOf(judged));
+            return errorResult(r.sentence, r.details);
+        }
+        const moved = changed[0];
+        const identity = { finding: "identity_changed", witness: { read: moved, kind: "none", containment: "unknown" } };
+        const r = refusalOf(toolName, identity, a.boundary.roots, []);
+        return errorResult(r.sentence, containmentDetails(changed.map((c) => c.target).filter((t) => t !== undefined)));
+    };
+    return { check, admit };
+}

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

@@ -1,127 +1,82 @@
 /**
- * ESTABLISHMENT — the filesystem-resolving half of the shell read boundary, as one value both shell
- * faces hold. The lexical pass (`bash-readonly-classifier.ts`) decides WHICH words a command may read;
- * this module decides WHERE those words land once the filesystem has answered: canonical targets, glob
- * expansions, and the fail-closed arm for what could not be established. It is the seam the read
- * judgment pipeline's `establish` step is built on; the candidate contract it will be fed from lives in
- * `shell-read-plan.ts`.
+ * ESTABLISHMENT — where a shell command's read candidates LAND once the filesystem has answered, as one
+ * value the gate's shell read station holds per execution environment. The plan (`shell-read-plan.ts`)
+ * decides WHICH words a command may read; this module decides WHERE each of them lands: the canonical
+ * target of a spelling (symlinks resolved, a `..` applied the way the kernel applies it), the expansion of
+ * a pattern (shell pathname semantics over `env.listDir`), the members of a traversal root (a bounded
+ * recursive enumeration, dot files included, symlinked directories not followed), and the fail-closed arm
+ * for what could not be established. The judge (`shell-read-judge.ts`) is downstream; nothing here decides
+ * allow/ask/deny.
  *
- * Extracted verbatim from `fs-bash.ts` (the `createCanonicalReadBoundary` family and its glob matcher):
- * behaviour is byte-for-byte the tool's own, and every property stated below is the property the tool
- * always held. Zero imports from `fs-bash.ts` (a leaf the shell faces import, never the reverse).
+ * Properties every consumer relies on:
+ *  1. A NON-EXISTENT target is not a refusal — `cat nope.txt` keeps the shell's own "No such file". The
+ *     deepest EXISTING ancestor is canonicalized and the missing tail rejoined, so a symlinked PARENT still
+ *     cannot carry a target out.
+ *  2. An unanswerable filesystem manufactures no refusal on its own: a chain no ancestor answered degrades
+ *     to the lexical spelling on an environment that declares no authority for its resolver, and is
+ *     `unestablishable` on one that does (`canonicalPathIsAuthoritative`).
+ *  3. An ISOLATED environment stays lexical, disclosed rather than silently degraded: the sandbox is the
+ *     containment there and `canonicalPath` is an RPC into a filesystem that is not this host's
+ *     (`boundaryIsTheSandbox`). The split is the DECLARED isolation capability, never the remote interface's
+ *     shape — a host lane or an SSH adapter implements the same interface and is resolved on its own paths.
+ *  4. NO MATCH is not a refusal: an unmatched pattern is handed to the command verbatim, so an empty
+ *     expansion falls back to the literal spelling.
+ *  5. What it cannot enumerate is `unestablishable`, never silently vouched: an unreadable directory, a
+ *     pattern construct the matcher does not model, an expansion or a traversal past
+ *     {@link MAX_GLOB_DIRS} / {@link MAX_GLOB_MATCHES}.
+ *  6. Cost is paid only by candidates that carry a metacharacter or a traversal, and only past the roots'
+ *     own spelling. Inside one enumerated directory only the SYMLINK entries need their own `realpath`.
+ *
+ * NOT cached deliberately: a per-run memo keyed on the spelling would answer from a snapshot of where a
+ * symlink pointed EARLIER in the run, which is the one thing establishment exists to observe. The residual
+ * it cannot remove is the classic one — the link can be re-pointed between establishment and the shell's
+ * own open; the pre-spawn re-establishment (`reestablish`) narrows that window to the one inside a single
+ * call.
  */
 import type { ExecutionEnv } from "../../internal/harness-types.js";
-import type { ReadDenySeat } from "./read-deny.js";
+import type { ShellReadPlan, ShellReadSegment } from "./shell-read-plan.js";
+import type { EstablishedRead, ShellReadBoundary } from "./shell-read-judge.js";
 /**
- * How many directories one glob operand may enumerate, and how many names it may match, before
- * the leg gives up and refuses.
+ * How many directories one glob operand (or one traversal root) may enumerate, and how many names it may
+ * match, before the leg gives up and answers `unestablishable`.
  *
  * Sized so the everyday shapes never hit them: 256 directories covers a two-level pattern over a source
- * tree's top level, and 8192 names covers `ls *` in a dependency directory an order of magnitude larger than a
- * normal one. Past those the answer is a REFUSAL naming the bound, never a silent allow — an operand
- * this leg could not finish enumerating is exactly an operand whose expansion it cannot vouch for.
+ * tree's top level, and 8192 names covers `ls *` in a dependency directory an order of magnitude larger
+ * than a normal one. Past those the answer is fail-closed, never a silent allow — an operand this leg could
+ * not finish enumerating is exactly an operand whose expansion it cannot vouch for.
  */
 export declare const MAX_GLOB_DIRS = 256;
 export declare const MAX_GLOB_MATCHES = 8192;
-/**
- * The SYMLINK-RESOLVING half of the `bash_readonly` read boundary.
- *
- * {@link classifySimpleCommandReadBoundary} is synchronous and pure, so its containment is lexical: it
- * judges the written spelling, while the kernel opens the symlink-resolved target. The two diverge in
- * both directions, and both are closed here — this is the caller that holds an {@link ExecutionEnv}:
- *   · LEAK — a symlink inside a root pointing out of it (`<root>/vendor` → `/etc`) has an in-root
- *     prefix, so `cat vendor/passwd` was auto-allowed and really read `/etc/passwd`. Every candidate
- *     the lexical pass accepted ({@link CompoundReadonlyVerdict.checkedPaths}) is canonicalized and
- *     re-compared; one that leaves the roots is refused.
- *   · FALSE REFUSAL — a non-canonical spelling of an in-root path (a symlinked `/tmp` → `/private/tmp`
- *     prefix, or any aliased root) does not textually match the canonical roots. A refusal whose paths
- *     ALL canonicalize back inside is dropped.
- *
- * Three properties this deliberately keeps:
- *  1. A NON-EXISTENT target must not become a boundary refusal — `cat nope.txt` has to keep producing
- *     the shell's own "No such file", or the boundary would break ordinary use. The deepest EXISTING
- *     ancestor is canonicalized and the missing tail rejoined (the rule safety.ts's `canonicalizeNewPath`
- *     already uses for the structured tools), so a symlinked PARENT still cannot carry across the target out.
- *  2. Nothing here can manufacture a refusal out of an unanswerable filesystem: a path whose whole
- *     ancestor chain fails to canonicalize degrades to the lexical verdict. (`/` resolves on any sane
- *     env, so this is a defensive arm, not a routine one.)
- *  3. An ISOLATED env stays lexical, disclosed rather than silently degraded: the sandbox itself is the
- *     containment there, and `canonicalPath` is an RPC into a filesystem that is not this host's. The
- *     split is the DECLARED {@link isIsolated} capability, never the remote interface's SHAPE — an
- *     adapter driving the operator's own machine (a host lane, an SSH host) implements that same
- *     interface and declares no containment, so the resolving pass runs there, on the env's own paths.
- *
- * NOT cached deliberately: a per-run memo keyed on the lexical spelling would answer from a snapshot of
- * where a symlink pointed EARLIER in the run, which is the one thing this check exists to observe. The
- * cost it would save is a `realpath` on a local env. The residual it cannot remove either way is the
- * classic one — the link can be re-pointed between this check and the shell's own open.
- *
- * The GLOB half of the same seam, added here for the same reason (this is where the filesystem
- * is). A candidate carrying `*`/`?`/`[…]` is a path that does NOT exist as spelled, so property 1's
- * deepest-existing-ancestor rule resolved `<root>/*` to the root itself and pronounced it inside — after
- * which the real shell expanded the pattern and handed the command every matching entry, including one
- * that is a symlink out of the root. `cat vendor/secret.txt` was refused while `cat *` over the same
- * link was not. Such a candidate is now expanded against the filesystem FIRST (`expandGlobCandidate`,
- * shell-semantics matcher over `env.listDir`) and each expansion resolved individually. Its own
- * properties, on top of the three above:
- *  4. NO MATCH is not a refusal. The shell hands an unmatched pattern to the command verbatim, which then
- *     reports its own "No such file" — so an empty expansion falls back to judging the literal spelling,
- *     i.e. the literal-spelling answer (which also covers a file literally named `nomatch*`).
- *  5. What it could not enumerate, it REFUSES (`unverifiable`), never silently allows: an unreadable
- *     directory, a pattern construct the matcher does not model, or an expansion past
- *     {@link MAX_GLOB_DIRS}/{@link MAX_GLOB_MATCHES}. This face has no approval channel to degrade to
- *     (see `createBashReadonlyTool`'s own note), so fail-closed is the only honest direction.
- *  6. Cost is paid only by candidates that actually carry a metacharacter, and only past the roots'
- *     own spelling (a root literally containing `[` must not be re-globbed). A plain path takes the
- *     same single `resolve` it always took. Inside one enumerated directory only the SYMLINK entries
- *     need their own `realpath` — the directory is canonicalized once and a non-symlink child of a
- *     canonical in-root directory is in-root by construction.
- */
-export declare function createCanonicalReadBoundary(env: ExecutionEnv, readRoots: readonly string[]): {
-    /** What the read boundary objects to once the filesystem has answered: canonical targets OUTSIDE the roots,
-     *  the fail-closed arm (`unverifiable` — a candidate this leg could not establish, property 5), and
-     *  `denied`, the first path the wired deny judge matched. All empty/absent ⇒ no objection.
-     *
-     *  The two input lists are NOT interchangeable, and the split is the lexical pass's answer, never a
-     *  re-reading of the text: `patterns` are the operands the shell will expand
-     *  ({@link CompoundReadonlyVerdict.undecidedPaths}), `literal` the ones it will not. Quoting separates them
-     *  and lives only in the RAW token, which these resolved paths no longer carry — `cat "link*"` reads a file
-     *  literally named `link*` and must not be re-globbed here. */
-    escapesAfterResolution: (paths: {
-        literal: readonly string[];
-        patterns: readonly string[];
-    }, ask: BoundaryQuestions, signal?: AbortSignal) => Promise<{
-        escaping: readonly string[];
-        unverifiable?: string;
-        denied?: {
-            path: string;
-            pattern: string;
-        };
+/** The reads of one plan, established: per segment, in the plan's own order, with nested plans beside. */
+export interface EstablishedPlan {
+    readonly plan: ShellReadPlan;
+    readonly reads: ReadonlyMap<ShellReadSegment, readonly EstablishedRead[]>;
+    readonly nested: ReadonlyMap<ShellReadPlan, EstablishedPlan>;
+    /** The roots the reads were judged against — canonical where the environment could say. */
+    readonly roots: readonly string[];
+}
+/** ONE establishment leg per execution environment — the filesystem half of the shell read station. */
+export interface ShellReadEstablisher {
+    /** Whether this environment is judged lexically (an isolated sandbox — property 3). */
+    readonly lexicalOnly: boolean;
+    /** Establish every read candidate of `plan` (nested plans included) against `boundary`'s roots. */
+    establish(plan: ShellReadPlan, boundary: ShellReadBoundary, signal?: AbortSignal): Promise<EstablishedPlan>;
+    /** Establish the same plan again and report every candidate whose canonical target moved — the pre-spawn
+     *  identity re-check. Candidates that were lexical or unestablishable are not compared: nothing was
+     *  established to move. */
+    reestablish(previous: EstablishedPlan, boundary: ShellReadBoundary, signal?: AbortSignal): Promise<{
+        readonly changed: readonly EstablishedRead[];
     }>;
-    /** Do ALL of `paths` canonicalize back INSIDE the roots? (false for an empty list, and where the sandbox is the containment.) */
-    allResolveInside: (paths: readonly string[], signal?: AbortSignal) => Promise<boolean>;
-    /** Where one spelling really lands, for a caller deciding a GRANT on something other than the roots.
-     *  `undefined` where the sandbox is the containment or the chain is unanswerable, and the
-     *  caller then judges the written spelling — what it had before. */
-    canonicalOf: (path: string, signal?: AbortSignal) => Promise<string | undefined>;
-};
-/** The symlink-resolving second pass, as one value both shell faces hold. */
-export type CanonicalReadBoundary = ReturnType<typeof createCanonicalReadBoundary>;
-/** WHICH of the boundary's two halves still has a question once the filesystem can answer. Not a mode and not
- *  a face: the face DECIDES these two, separately. Containment is structurally satisfied under the OPEN read
- *  face (an out-of-roots operand rides `checkedPaths` there as an ACCEPTED candidate); the deny half judges in
- *  BOTH faces by its seat's own contract, so a face-level exit takes it along with the other half. */
-export interface BoundaryQuestions {
-    readonly deny: ReadDenySeat["denyMatch"];
-    readonly containment: boolean;
-    /** Per HALF, the paths this face must NOT re-judge, because the approver was asked THAT question about
-     *  THAT path and said yes. Two sets, not one, and the difference is a leak: "release this deny row" is
-     *  not "release wherever it lands" (a deny-listed name that is a symlink OUT of the roots ran, and
-     *  ADDING the deny row is what turned the refusal off), and "read outside the roots" says nothing about
-     *  the deny table the target is on. Keyed on the folded spelling the card named; empty = nothing
-     *  answered. */
-    readonly denyAnswered: ReadonlySet<string>;
-    readonly containmentAnswered: ReadonlySet<string>;
 }
-/** The empty half-answer, for a face with no approval channel to have been answered through. */
-export declare const NOTHING_ANSWERED: ReadonlySet<string>;
+/**
+ * The PURE, lexical establishment of a whole plan — what an isolated sandbox gets, and what any consumer
+ * with no environment in hand (a unit pin, a lexical pre-read) can compute. Patterns and traversal roots
+ * are judged on their spelling alone here (KL-934a: the sandbox's own containment is the floor there).
+ */
+export declare function establishShellReadsLexically(plan: ShellReadPlan, boundary: ShellReadBoundary): EstablishedPlan;
+/**
+ * The filesystem-resolving establisher for one environment and one root set. `readRoots` are the roots
+ * as declared (canonical by contract); they are resolved once more per instance because the comparison is
+ * against `realpath` output on both sides — an aliased root would otherwise refuse every read under itself.
+ */
+export declare function createShellReadEstablisher(env: ExecutionEnv, readRoots: readonly string[]): ShellReadEstablisher;