@sema-agent/core 7.33.8 → 7.35.0

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

@@ -1,11 +1,12 @@
-import { normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
+import { isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
 import { boundaryIsTheSandbox, canonicalPathIsAuthoritative } from "../../core/remote-env.js";
 import { resolveOperandSpellings } from "./bash-readonly-classifier.js";
-import { denyFloorShadowsOf } from "./shell-read-judge.js";
-import { movedReads } from "./shell-read-identity.js";
+import { judgedCandidatesOf, sedBackupNames } from "./shell-read-write-targets.js";
+import { movedReads, withHomeViews } from "./shell-read-identity.js";
 const GLOB_METACHAR_RE = /[*?[]/;
 export const MAX_GLOB_DIRS = 256;
 export const MAX_GLOB_MATCHES = 8192;
+const WRITE_LINK_HOPS = 32;
 function compileGlobSegment(pattern) {
     if (pattern.includes("\\"))
         return undefined;
@@ -131,15 +132,25 @@ function lexicalReadsOf(candidate, boundary) {
     }
     return out;
 }
-function judgedCandidatesOf(segment) {
-    const reads = segment.reads.filter((c) => c.provenance !== "write_redirect_target");
-    return [...reads, ...denyFloorShadowsOf(reads)];
+function unfollowedBackupReads(j, boundary, cause) {
+    const spellings = sedBackupNames(j.followed.operand.spelled, j.followed.suffix).flatMap((name) => lexicalReadsOf({ ...j.candidate, spelled: name }, boundary).flatMap((r) => [...(r.target !== undefined ? [r.target] : []), ...r.spellings]));
+    return [{ candidate: j.candidate, established: "unestablishable", spellings: [...new Set(spellings)], cause }];
+}
+function writtenAt(read, j, seat) {
+    if (read.candidate.face !== "write" || !(j.written ?? j.seats ?? ["landing"]).includes(seat))
+        return read;
+    return { ...read, written: { seat, ...(j.child === true ? { child: true } : {}) } };
 }
 export function establishShellReadsLexically(plan, boundary) {
     const reads = new Map();
     const nested = new Map();
     for (const segment of plan.segments) {
-        reads.set(segment, judgedCandidatesOf(segment).flatMap((c) => lexicalReadsOf(c, boundary)));
+        reads.set(segment, judgedCandidatesOf(segment).flatMap((j) => {
+            if (j.followed !== undefined)
+                return unfollowedBackupReads({ ...j, followed: j.followed }, boundary, `"${j.followed.operand.raw}" names its backup through a link chain only the filesystem can follow`);
+            const seat = (j.written ?? j.seats ?? ["landing"]).includes("landing") ? "landing" : "entry";
+            return lexicalReadsOf(j.candidate, boundary).map((r) => writtenAt(r, j, seat));
+        }));
         for (const n of segment.nested)
             nested.set(n, establishShellReadsLexically(n, boundary));
     }
@@ -164,12 +175,23 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         })();
         return await rootsOnce;
     };
-    const resolveWithoutParentSteps = async (p, signal) => {
+    const resolveWithoutParentSteps = async (p, signal, writeTarget = false, linkHops = WRITE_LINK_HOPS) => {
         const parts = p.split(SEP);
         const tail = [];
         let allAbsent = true;
         while (parts.length > 0) {
-            const canon = await env.canonicalPath(parts.join("/") || "/", signal);
+            const at = parts.join("/") || "/";
+            const canon = await env.canonicalPath(at, signal);
+            if (!canon.ok && canon.error.code === "not_found" && writeTarget && allAbsent) {
+                const entry = await env.fileInfo(at, signal);
+                const link = entry.ok && entry.value.kind === "symlink" && linkHops > 0 ? await env.readLink?.(at, signal) : undefined;
+                if (link?.ok === true) {
+                    const landing = isAbsoluteForFamily(family, link.value) ? link.value : joinUnder(parts.slice(0, -1).join("/") || "/", link.value);
+                    return await resolve([landing, ...[...tail].reverse()].join("/"), signal, true, linkHops - 1);
+                }
+                if (entry.ok || entry.error.code !== "not_found")
+                    allAbsent = false;
+            }
             if (canon.ok) {
                 if (tail.length === 0)
                     return { value: canon.value, exact: true };
@@ -182,20 +204,20 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         return undefined;
     };
     const parentOf = (canonical) => normalizeAbsPathLexically(`${canonical}/..`);
-    const resolve = async (p, signal) => {
+    const resolve = async (p, signal, writeTarget = false, linkHops = WRITE_LINK_HOPS) => {
         const parts = p.split(SEP);
         const first = parts.findIndex((seg) => seg === "..");
         if (first < 0)
-            return await resolveWithoutParentSteps(p, signal);
+            return await resolveWithoutParentSteps(p, signal, writeTarget, linkHops);
         const headEnd = parts.slice(0, first).reduce((n, seg) => n + seg.length + 1, 0);
-        let head = await resolveWithoutParentSteps(p.slice(0, headEnd) || "/", signal);
+        let head = await resolveWithoutParentSteps(p.slice(0, headEnd) || "/", signal, writeTarget, linkHops);
         if (head === undefined)
             return undefined;
         let pending = [];
         const flush = async () => {
             if (pending.length === 0)
                 return true;
-            const next = await resolveWithoutParentSteps([head.value.replace(TRAILING_SEP, ""), ...pending].join("/"), signal);
+            const next = await resolveWithoutParentSteps([head.value.replace(TRAILING_SEP, ""), ...pending].join("/"), signal, writeTarget, linkHops);
             pending = [];
             if (next === undefined)
                 return false;
@@ -342,8 +364,18 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         const members = found.map(({ path, canonical, symlink }) => ({ path, ...(canonical !== undefined ? { canonical } : {}), node: (symlink && canonical !== undefined && listedDirs.has(canonical) ? "directory" : "file") }));
         return { ...(root !== undefined ? { root } : {}), members };
     };
-    const canonicalReadOf = async (candidate, spelling, spellings, established, origin, canonicalKnown, signal) => {
-        const real = canonicalKnown !== undefined ? { value: canonicalKnown, exact: true } : await resolve(spelling, signal);
+    const entryOf = async (spelling, signal) => {
+        const parts = spelling.split(SEP);
+        const leaf = parts.pop() ?? "";
+        if (leaf === "" || leaf === "." || leaf === ".." || parts.length === 0)
+            return await resolve(spelling, signal, true);
+        const parent = await resolve(parts.join("/") || "/", signal, true);
+        if (parent === undefined)
+            return undefined;
+        return { value: joinUnder(parent.value, leaf), exact: parent.exact, ...(parent.missing !== undefined ? { missing: parent.missing } : {}) };
+    };
+    const canonicalReadOf = async (candidate, spelling, spellings, established, origin, canonicalKnown, signal, seat = "landing") => {
+        const real = canonicalKnown !== undefined ? { value: canonicalKnown, exact: true } : seat === "entry" ? await entryOf(spelling, signal) : await resolve(spelling, signal, candidate.face === "write");
         if (real === undefined) {
             if (resolverIsAuthoritative)
                 return { candidate, established: "unestablishable", spellings, ...(origin !== undefined ? { origin } : {}), cause: `"${spelling}" cannot be resolved to verify where it reads` };
@@ -354,10 +386,88 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         }
         return { candidate, established, target: real.value, spellings, ...(origin !== undefined ? { origin } : {}) };
     };
+    const followedName = async (spelled, base, homeDir, signal) => {
+        let name = spelled;
+        for (let hop = 0; hop <= WRITE_LINK_HOPS; hop++) {
+            const at = resolveOperandSpellings(base === "" ? undefined : base, name, homeDir);
+            if (at === undefined)
+                return undefined;
+            const walked = at.spelled ?? at.folded;
+            if (TRAILING_SEP.test(walked))
+                return name;
+            const parts = walked.split(SEP);
+            const leaf = parts.pop() ?? "";
+            if (leaf === "" || leaf === "." || leaf === "..")
+                return name;
+            const parent = await resolve(parts.join("/") || "/", signal);
+            if (parent === undefined)
+                return undefined;
+            if (!parent.exact)
+                return parent.missing === true ? name : undefined;
+            const entry = await env.fileInfo(joinUnder(parent.value, leaf), signal);
+            if (!entry.ok)
+                return entry.error.code === "not_found" || entry.error.code === "not_directory" ? name : undefined;
+            if (entry.value.kind !== "symlink")
+                return name;
+            const link = await env.readLink?.(joinUnder(parent.value, leaf), signal);
+            if (link?.ok !== true)
+                return undefined;
+            const dir = name.slice(0, name.search(/[^/]*$/));
+            name = isAbsoluteForFamily(family, link.value) ? link.value : `${dir}${link.value}`;
+        }
+        return undefined;
+    };
+    const followedBackupReads = async (j, boundary, signal) => {
+        const { operand, suffix } = j.followed;
+        const bases = basesFor(operand, boundary);
+        const unfollowed = (cause) => unfollowedBackupReads(j, boundary, cause);
+        if (bases === "unmodelled")
+            return unfollowed(`"${operand.raw}" is relative to a working directory this command's text does not settle`);
+        const out = [];
+        for (const base of bases) {
+            const name = await followedName(operand.spelled, base, boundary.homeDir, signal);
+            if (name === undefined) {
+                out.push(...unfollowed(`"${operand.raw}" names its backup through a link chain that could not be read`));
+                continue;
+            }
+            for (const backup of sedBackupNames(name, suffix)) {
+                const at = resolveOperandSpellings(base === "" ? undefined : base, backup, boundary.homeDir);
+                if (at === undefined) {
+                    out.push(...unfollowed(`"${backup}" cannot be placed against "${base}"`));
+                    continue;
+                }
+                const spellings = at.spelled !== undefined ? [at.folded, at.spelled] : [at.folded];
+                for (const seat of j.seats ?? ["landing"])
+                    out.push(writtenAt(await canonicalReadOf(j.candidate, at.spelled ?? at.folded, spellings, "canonical", undefined, undefined, signal, seat), j, seat));
+            }
+        }
+        return out;
+    };
     const establishSegment = async (segment, boundary, roots, signal) => {
         const out = [];
-        for (const candidate of judgedCandidatesOf(segment)) {
+        for (const judged of judgedCandidatesOf(segment)) {
+            if (judged.followed !== undefined) {
+                out.push(...(await followedBackupReads({ ...judged, followed: judged.followed }, boundary, signal)));
+                continue;
+            }
+            const candidate = judged.candidate;
             const traversal = candidate.provenance === "traversal_root";
+            const resolvesItself = TRAILING_SEP.test(candidate.spelled) || [".", ".."].includes(candidate.spelled.split(SEP).pop() ?? "");
+            const landsToo = (ss) => (resolvesItself && ss.length > 0 && !ss.includes("landing") ? [...ss, "landing"] : ss);
+            const seats = judged.seats === undefined ? ["landing"] : landsToo(judged.seats);
+            const writtenSeats = { ...judged, written: judged.written === undefined ? seats : landsToo(judged.written) };
+            const atSeats = async (spelling, spellings, established, origin, canonicalKnown) => {
+                const reads = [];
+                for (const seat of seats) {
+                    const read = writtenAt(await canonicalReadOf(candidate, spelling, spellings, established, origin, canonicalKnown, signal, seat), writtenSeats, seat);
+                    const same = reads.findIndex((r) => r.established === read.established && r.target === read.target);
+                    if (same < 0)
+                        reads.push(read);
+                    else if (reads[same].written === undefined && read.written !== undefined)
+                        reads[same] = read;
+                }
+                return reads;
+            };
             const land = async (read, spellings, folded) => {
                 if (!traversal || (read.established !== "canonical" && read.established !== "expansion") || read.target === undefined) {
                     out.push(read);
@@ -371,7 +481,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                 }
                 out.push({ ...read, ...(walkedTree.root !== undefined ? { node: walkedTree.root } : {}) });
                 for (const m of walkedTree.members)
-                    out.push({ ...(await canonicalReadOf(candidate, m.path, [m.path], "expansion", folded, m.canonical, signal)), node: m.node });
+                    out.push({ ...(await canonicalReadOf(candidate, m.path, [m.path], "expansion", folded, m.canonical, signal)), node: m.node, walked: true });
             };
             for (const lexical of lexicalReadsOf(candidate, boundary)) {
                 if (lexical.established !== "lexical") {
@@ -393,14 +503,17 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                         if (expanded !== undefined && expanded.paths.length > 0) {
                             matched = true;
                             for (const t of expanded.paths)
-                                await land(await canonicalReadOf(candidate, t, [t, folded], "expansion", folded, expanded.canonical.get(t), signal), spellings, folded);
+                                for (const read of await atSeats(t, [t, folded], "expansion", folded, expanded.canonical.get(t)))
+                                    await land(read, spellings, folded);
                         }
                     }
                     if (!matched)
-                        await land(await canonicalReadOf(candidate, walked, spellings, "canonical", undefined, undefined, signal), spellings, folded);
+                        for (const read of await atSeats(walked, spellings, "canonical", undefined, undefined))
+                            await land(read, spellings, folded);
                     continue;
                 }
-                await land(await canonicalReadOf(candidate, walked, spellings, "canonical", undefined, undefined, signal), spellings, folded);
+                for (const read of await atSeats(walked, spellings, "canonical", undefined, undefined))
+                    await land(read, spellings, folded);
             }
         }
         return out;
@@ -421,7 +534,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
             if (lexicalOnly)
                 return establishShellReadsLexically(plan, boundary);
             const roots = await canonicalRoots(signal);
-            return await establishPlan(plan, { ...boundary, roots }, roots, signal);
+            return await withHomeViews(env, await establishPlan(plan, { ...boundary, roots }, roots, signal), signal);
         },
         reestablish: async (previous, boundary, signal) => {
             if (lexicalOnly)

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

@@ -9,5 +9,12 @@
  */
 import type { EstablishedPlan } from "./shell-read-establish.js";
 import type { EstablishedRead } from "./shell-read-judge.js";
+import { type HomeViewEnv } from "./read-deny-home.js";
 /** Every read of either establishment whose candidate's settled target set differs between the two. */
 export declare function movedReads(previous: EstablishedPlan, again: EstablishedPlan): EstablishedRead[];
+/**
+ * The establishment with every read that landed carrying its HOME VIEW (read-deny-home.ts) among its spellings, nested
+ * plans included: the deny judge then places a home-anchored row wherever the target IS below the home, whatever it is
+ * spelled through. A read that did not land (lexical, unestablishable) is left as it is.
+ */
+export declare function withHomeViews(env: HomeViewEnv, established: EstablishedPlan, signal?: AbortSignal): Promise<EstablishedPlan>;

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

@@ -1,3 +1,4 @@
+import { homeViewsOf } from "./read-deny-home.js";
 export function movedReads(previous, again) {
     const before = targetsByCandidate(previous);
     const after = targetsByCandidate(again);
@@ -37,3 +38,23 @@ function targetsByCandidate(e) {
 function sameTargets(a, b) {
     return a.size === b.size && [...a].every((t) => b.has(t));
 }
+export async function withHomeViews(env, established, signal) {
+    const views = homeViewsOf(env, signal);
+    const place = async (p) => {
+        const reads = new Map();
+        for (const [segment, rs] of p.reads) {
+            const out = [];
+            for (const r of rs) {
+                const landed = r.target !== undefined && (r.established === "canonical" || r.established === "expansion");
+                const view = landed ? await views.of(r.target, r.node === "file" ? { leaf: "file" } : undefined) : undefined;
+                out.push(view === undefined || r.spellings.includes(view) ? r : { ...r, spellings: [...r.spellings, view] });
+            }
+            reads.set(segment, out);
+        }
+        const nested = new Map();
+        for (const [n, np] of p.nested)
+            nested.set(n, await place(np));
+        return { ...p, reads, nested };
+    };
+    return await place(established);
+}

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

@@ -12,22 +12,25 @@
  *  · `foldShellReadFindings` folds a command's findings — every segment, every nested plan — to ONE word by
  *    the priority `identity_changed > deny_hit > outside_roots > unestablishable > declined > none`.
  *  · `SHELL_READ_DECISION` is the total table (finding × seat → disposition) that is the ONLY source of
- *    "refuse / mandated ask / ordinary ask / vouch" for a shell read. A seat is a TRUST POLICY word, not a
- *    tool name: the four seats differ on one row (`declined`) and nowhere else.
+ *    "refuse / mandated ask / ordinary ask / vouch" for a shell read. A seat is a FACE word, not a tool name
+ *    and not a permission mode: which shell face the call runs on (the full shell, the read-only shell) or
+ *    which moment judges it (the re-judge after approval). The permission mode is not read here — what a
+ *    mode does with the ask this table mints is decided once, downstream, where every ask is arbitrated.
  *
  * The floor this module is (`shell.read_boundary.friction_floor`) is stated on {@link judgeRead}.
  */
 import type { BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
 import type { ReadCandidate, ShellReadPlan, ShellReadSegment } from "./shell-read-plan.js";
+import type { WriteSeat } from "./shell-read-write-targets.js";
 import type { AssertAllKeysHandled } from "../../core/ask-origin.js";
 /** WHAT the judge found about a command — a closed set, registered in `docs/CLOSED-SETS.md`. */
 export declare const SHELL_READ_FINDINGS: readonly ["deny_hit", "outside_roots", "unestablishable", "declined", "identity_changed", "none"];
 export type ShellReadFinding = (typeof SHELL_READ_FINDINGS)[number];
-/** WHO is asking — the trust-policy seats the decision table is keyed on. `bash_off` covers the `off` and
- *  `always` doctrines (and a bypass mode); `bash_classify` the `classify` doctrine; `readonly` the read-only
- *  shell face (`handsReadOnly`); `rejudge` the post-approval re-judgment of rewritten bytes and the
- *  pre-spawn identity re-check. */
-export declare const SHELL_READ_SEATS: readonly ["bash_off", "bash_classify", "readonly", "rejudge"];
+/** WHERE a read is judged — the seats the decision table is keyed on, one per FACE: `full_shell` the
+ *  writable shell (`Bash`, `Monitor`) under every permission mode and every shell-gate floor; `readonly`
+ *  the read-only shell face (`handsReadOnly`); `rejudge` the post-approval re-judgment of rewritten bytes
+ *  and the pre-spawn identity re-check. */
+export declare const SHELL_READ_SEATS: readonly ["full_shell", "readonly", "rejudge"];
 export type ShellReadSeat = (typeof SHELL_READ_SEATS)[number];
 /** The fold priority: a command's finding is the highest-ranked finding of any candidate in it. */
 export declare const SHELL_READ_FINDING_RANK: {
@@ -47,56 +50,51 @@ export type RankTableCoversEveryFinding = AssertAllKeysHandled<Exclude<ShellRead
 export type ShellReadDisposition = "refuse" | "mandated" | "ordinary" | "vouch";
 /**
  * THE decision table — total over findings × seats; no cell is n/a. Row by row:
- *  · `deny_hit` — refused on every seat: a deny row is a floor no root grant and no approval moves.
- *  · `outside_roots` — asked where a person can be asked (the two full-shell seats), refused where none
- *    can (the read-only face has no approval channel; a rewrite that leaves the roots after approval was
- *    seen by nobody).
+ *  · `deny_hit` — refused on every seat, for a spelling the station can establish: a deny row is a floor
+ *    no root grant and no approval moves. A spelling the station cannot establish is not a deny hit (it is
+ *    the `unestablishable` row) — the floor holds what it can place, and says so rather than guessing.
+ *  · `outside_roots` — asked where a person can be asked (the full shell), refused where none can (the
+ *    read-only face has no approval channel; a rewrite that leaves the roots after approval was seen by
+ *    nobody).
  *  · `unestablishable` — the same shape: the floor could not say where the command reads, so it is not
  *    vouched anywhere; a person may still answer it on the full shell.
- *  · `declined` — the one row the seats disagree on, and the one deliberate fail-open of this table: the
- *    scan could not read the program bash will run or the operands arrive on a stream. The `off` doctrine
- *    mounts nothing else that could ask, so it mandates; the `classify` doctrine composes a shape classifier
- *    beside this station and the ruled trade is an ORDINARY ask there — an answerer may settle it, and an
- *    out-of-root read hidden inside such a command is then not asked again. The read-only face refuses:
- *    its allowlist is a deployment knob, so this cell is reachable and must not be n/a.
+ *  · `declined` — the one deliberate fail-open of this table: the scan could not read the program bash
+ *    will run, or the operands arrive on a stream. On the full shell it is an ORDINARY ask — an answerer
+ *    may settle it, and an out-of-root read hidden inside such a command is then not asked again. The
+ *    read-only face refuses: its allowlist is a deployment knob, so this cell is reachable and must not be
+ *    n/a.
  *  · `identity_changed` — a candidate established at approval time resolves elsewhere at spawn time:
  *    refused everywhere (it is only ever produced on the `rejudge` seat).
- *  · `none` — vouched: the station has no question (the classify seat's shape classifier may still ask).
+ *  · `none` — vouched: the station has no question (the full shell's shape tier may still ask).
  */
 export declare const SHELL_READ_DECISION: {
     readonly deny_hit: {
-        readonly bash_off: "refuse";
-        readonly bash_classify: "refuse";
+        readonly full_shell: "refuse";
         readonly readonly: "refuse";
         readonly rejudge: "refuse";
     };
     readonly outside_roots: {
-        readonly bash_off: "mandated";
-        readonly bash_classify: "mandated";
+        readonly full_shell: "mandated";
         readonly readonly: "refuse";
         readonly rejudge: "refuse";
     };
     readonly unestablishable: {
-        readonly bash_off: "mandated";
-        readonly bash_classify: "mandated";
+        readonly full_shell: "mandated";
         readonly readonly: "refuse";
         readonly rejudge: "refuse";
     };
     readonly declined: {
-        readonly bash_off: "mandated";
-        readonly bash_classify: "ordinary";
+        readonly full_shell: "ordinary";
         readonly readonly: "refuse";
         readonly rejudge: "refuse";
     };
     readonly identity_changed: {
-        readonly bash_off: "refuse";
-        readonly bash_classify: "refuse";
+        readonly full_shell: "refuse";
         readonly readonly: "refuse";
         readonly rejudge: "refuse";
     };
     readonly none: {
-        readonly bash_off: "vouch";
-        readonly bash_classify: "vouch";
+        readonly full_shell: "vouch";
         readonly readonly: "vouch";
         readonly rejudge: "vouch";
     };
@@ -106,7 +104,9 @@ export type DecisionTableCoversEveryFinding = AssertAllKeysHandled<Exclude<Shell
 /** Compile-time fence: `never` while every seat has a cell on the `none` row (the `satisfies` above holds
  *  every other row to the same shape). */
 export type DecisionTableCoversEverySeat = AssertAllKeysHandled<Exclude<ShellReadSeat, keyof (typeof SHELL_READ_DECISION)["none"]>>;
-/** The disposition of one command-level finding on one seat — the table, read. */
+/** The disposition of one command-level finding on one seat — the table, read. A seat word outside
+ *  {@link SHELL_READ_SEATS} (an untyped caller, or one still passing a retired word) is refused loudly: an
+ *  absent disposition would read as "no verdict", which no caller can act on safely. */
 export declare function decideShellRead(finding: ShellReadFinding, seat: ShellReadSeat): ShellReadDisposition;
 /**
  * The boundary a shell read is judged against: the declared roots (canonical), the working directory and
@@ -116,6 +116,27 @@ export declare function decideShellRead(finding: ShellReadFinding, seat: ShellRe
  */
 export interface ShellReadBoundary extends BashReadonlyRootBoundary {
     readonly alsoInside?: (canonicalTarget: string) => Promise<boolean>;
+    /** The deny table's WRITE face (`compileWriteDeny`, read-deny.ts): judges a command's write targets (candidates marked
+     *  `face: "write"`) and returns the matched row's rule, or null. PRESENT-IFF there is something to judge. */
+    readonly writeDenyMatch?: (resolvedPath: string) => string | null;
+    /** The read table's rows AT or BELOW a path (`readDenySeat`'s `denyAtOrBelow`, read-deny.ts): read by the station's
+     *  `writesPlaced` fact only, through {@link denyRowAtOrBelow}. */
+    readonly denyAtOrBelow?: (resolvedPath: string) => string | null;
+    /** The WRITE roots (canonical) — where a write may land without a question under a mode that accepts file commands
+     *  (the task root and every additional working directory; never a read-only grant). Read for the station's
+     *  `writesPlaced` fact only; the read judgment never reads it. Absent ⇒ no write is placed. */
+    readonly writeRoots?: readonly string[];
+    /** The write-protection TABLE's judge — the one a write tool's target meets (its spelling, its real target and every hop
+     *  of its symlink chain): `true` ⇔ a row covers this ABSOLUTE write target; `canonical` ⇔ the path is a key the station
+     *  established (judged as a key, never as a spelling). Read by the station's write facts only: a covered target is not
+     *  placed, and the verdict says it was found ({@link import("./shell-read-check.js").ShellReadVerdict.writeProtected}). */
+    readonly writeProtectionJudge?: (target: string, opts?: {
+        readonly signal?: AbortSignal;
+        readonly canonical?: true;
+    }) => Promise<boolean>;
+    /** The deployment's write-target guard (`ToolPolicy.writeTargetGuard`, every policy of the leg's chain): `true` ⇔ a
+     *  policy guards this ABSOLUTE write target. Read by the station's `writesPlaced` fact only: a guarded target is not placed. */
+    readonly writeTargetGuard?: (target: string, signal?: AbortSignal) => Promise<boolean>;
 }
 /** How far one candidate got before it was judged. `lexical` = the folded spelling is the judged target
  *  (an isolated sandbox, or a resolver that declares no authority and did not answer); `canonical` = the
@@ -136,18 +157,31 @@ export interface EstablishedRead {
     /** What the environment said the target IS, where a read asked — only a traversal asks (it lists the root and
      *  every member it walks; a link's answer is its target's). Absent = nothing asked; a plain read never lists. */
     readonly node?: "directory" | "file";
+    /** A MEMBER a traversal enumerated below its root — never a spelling of the command. The deny judge reads it
+     *  ({@link import("./read-deny.js").ReadDenyMatcher.matchPath} `walked`): the segment rows still judge it, a
+     *  rule-DSL row does not. Absent on the root itself, on a pattern's own matches and on every spelled operand. */
+    readonly walked?: true;
     /** Why the candidate could not be established. */
     readonly cause?: string;
+    /** WHERE the command's program writes this target — present only on a write target the program itself writes, at the
+     *  seat this read was established at (`landing`: through the path's links; `entry`: the directory entry, a link there
+     *  not followed). Absent on a read, and on a write-face target the program only names (a copy's source). `child`: the
+     *  candidate's own mark ({@link import("./shell-read-write-targets.js").JudgedCandidate.child}), carried to the read. */
+    readonly written?: {
+        readonly seat: WriteSeat;
+        readonly child?: true;
+    };
 }
 /** What the judge found about ONE candidate. `kind` is one of the four candidate-level findings
  *  (`declined` is a segment fact, `identity_changed` a re-establishment fact — neither is a candidate's). */
 export interface ReadFinding {
     readonly read: EstablishedRead;
     readonly kind: Extract<ShellReadFinding, "deny_hit" | "outside_roots" | "unestablishable" | "none">;
-    /** The deny row that matched and the view it matched on. */
+    /** The deny row that matched, the view it matched on, and — for a write target — the face (`write`) that refused. */
     readonly deny?: {
         readonly pattern: string;
         readonly matchedView: string;
+        readonly face?: "write";
     };
     readonly containment: "inside" | "outside" | "open" | "unknown";
 }
@@ -173,6 +207,17 @@ export interface ReadFinding {
  * neither is a containment candidate — both still meet the deny judge, on every spelling.
  */
 export declare function judgeRead(read: EstablishedRead, boundary: ShellReadBoundary): ReadFinding;
+/**
+ * Does a deny row lie AT or BELOW this write target, on any view the judge reads? Then a command that moves, copies or
+ * removes the target changes what the row covers, and a mode must not answer it unasked. WHICH tables answer is what the
+ * command does to the content below the target: a move or a copy carries it somewhere else (`mv .docker d` leaves
+ * `d/config.json` outside `.docker/config.json`; `mv <home> x` takes every home-anchored row's file along), so the READ
+ * table's rows answer too (`carriesContent`); a removal carries nothing anywhere — it is a write and nothing else, and
+ * only the write table answers it (the reference implementation's path check reads the read rows for a copy's or a
+ * move's sources and for sed, never for `rm` / `rmdir`). The read table answers per row (`denyAtOrBelow`); the write
+ * table's rows are rule rows, whose reach below a path is not enumerable, so any of them answers.
+ */
+export declare function denyRowAtOrBelow(read: EstablishedRead, boundary: ShellReadBoundary, carriesContent: boolean): boolean;
 /**
  * The deny floor of every home word the plan does not place: each candidate carrying a `floorSpelled` (the word
  * spelled with the DECLARED home) gets a SHADOW candidate at that spelling, established exactly as a read is — the
@@ -197,6 +242,8 @@ export interface ShellReadFold {
     readonly finding: ShellReadFinding;
     readonly witness?: ReadFinding;
     readonly declined?: ShellReadSegment;
+    /** Some read of the text could not be established (an `unestablishable` or `declined` finding anywhere, winning or not). */
+    readonly unestablished?: true;
 }
 /**
  * Fold a judged plan to ONE finding by {@link SHELL_READ_FINDING_RANK}, over every segment and every nested
@@ -215,6 +262,9 @@ export declare function foldShellReadFindings(judged: JudgedPlan): ShellReadFold
 export declare function judgeEstablishedPlan(plan: ShellReadPlan, established: ReadonlyMap<ShellReadSegment, readonly EstablishedRead[]>, boundary: ShellReadBoundary, nestedOf: (plan: ShellReadPlan) => JudgedPlan): JudgedPlan;
 /** Every finding of a judged plan, flattened (segments and nested plans alike). */
 export declare function allFindings(judged: JudgedPlan): ReadFinding[];
+/** One lexical step up, family-aware. A family ROOT is its own parent — the fixpoint the climb below ends
+ *  on, and the one spelling this file can recognise as "the whole filesystem" without I/O. */
+export declare function parentDirLexically(p: string): string;
 /**
  * The deepest directory containing both, or `undefined` when they share none (two path families).
  *
@@ -238,5 +288,15 @@ export declare function readRootGrantCandidateOf(judged: JudgedPlan, boundary: S
     readonly dir: string;
     readonly covers?: "exact";
 } | undefined;
+/**
+ * The grant a read-root card offers for the directory `candidate` it would add. A directory that would hand out more
+ * than was read is not offered: a family root grants the whole filesystem, and one CONTAINING the declared home or a
+ * root grants the workspace. ONE fallback for both rather than no offer at all — the single path that WAS read
+ * (`single`), named VERBATIM (`covers: "exact"`); with several paths read, no offer.
+ */
+export declare function grantOfferFor(candidate: string, single: string | undefined, bounds: Pick<ShellReadBoundary, "roots" | "homeDir">): {
+    dir: string;
+    covers?: "exact";
+} | undefined;
 /** The same judged plan under another boundary — the established reads are kept, only the judgment reruns. */
 export declare function rejudge(judged: JudgedPlan, boundary: ShellReadBoundary): JudgedPlan;