@sema-agent/core 7.33.7 → 7.34.0

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

@@ -22,19 +22,22 @@ import { violationDetails } from "./safety.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. */
+/** The ONE mint of the containment card — the targets a finding established OUTSIDE the roots (an out-of-root read, a
+ *  target that resolves elsewhere by the spawn). */
 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>;
+/** The ONE mint of the card of a finding that established nothing: where the command reads could not be established
+ *  (an unreadable or re-entered program text, a program named from its input, a station that could not answer). */
+declare function unestablishedDetails(): {
+    readonly type: "read_unestablished";
+    readonly code: "read_unestablished";
+};
+/** The structured details a refusal or a mandated card carries: the deny card is the read faces' own (`violationDetails`,
+ *  safety.ts), the containment and the unestablished cards are minted above. */
+export type ShellReadRefusalDetails = NonNullable<ReturnType<typeof violationDetails>> | ReturnType<typeof containmentDetails> | ReturnType<typeof unestablishedDetails>;
 /** What the station answers for ONE call. */
 export interface ShellReadVerdict {
     readonly disposition: ShellReadDisposition;
@@ -43,12 +46,40 @@ export interface ShellReadVerdict {
      *  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. */
+    /** `refuse`: the refusal's structured details. `mandated` on an `outside_roots` / `unestablishable` finding (and
+     *  `ordinary` on the file tools' out-of-root read): the finding's card, so an ask a person refuses or nobody can answer
+     *  still carries WHAT was found on its `tool_end` — the targets outside the roots (`readonly_out_of_root`, or the file
+     *  tools' `path_not_in_root`), or that nothing could be established (`read_unestablished`). */
     readonly details?: ShellReadRefusalDetails;
     /** `mandated` on an `outside_roots` finding: the directory whose grant would clear this ask. */
     readonly readRootCandidate?: ReadRootGrantCandidate;
+    /** A FACT beside the disposition, for the mode that answers a file command itself: every write target this command
+     *  names was established inside the boundary's WRITE roots at every seat the program writes it (the entry, where it
+     *  lands, or both — `WriteSeat`, shell-read-write-targets.ts), off the write-protection table and off every deployment
+     *  write guard (`ShellReadBoundary.writeProtectionJudge` / `writeTargetGuard`), no removal (`rm` / `rmdir`) targets a
+     *  write root or a directory containing one, every program the command runs is in its text (no `sed -f` file, no
+     *  re-entered shell, no unreadable text), and the line's order keeps each segment's establishment true
+     *  ({@link lineOrderPlaced}). Absent ⇒ not established — the mode does not answer; the station's own table is unchanged. */
+    readonly writesPlaced?: true;
+    /** A FACT beside the disposition: a write target this command names lands on the write-protection table — judged by
+     *  the table's own judge, as a write tool's target is — so the command's ask carries that table's class, whichever
+     *  mode reads it. Absent ⇒ no target the station established is covered (or no judge is mounted). */
+    readonly writeProtected?: true;
+    /** A FACT beside `writesPlaced`'s absence: the command is one of the mode's file commands whose writes the station would
+     *  have placed but for an OPTION WORD on a `cp` / `mv` segment ({@link UNPLACED_OPTIONS}: any word starting with `-` — the
+     *  reference implementation's rule, "with flags requires manual approval to ensure path safety"). Names the first such
+     *  program, so the approval card and the headless refusal can say WHY the mode did not answer. Absent ⇒ not that reason
+     *  (or the writes were placed). */
+    readonly unplacedOptions?: {
+        readonly program: "cp" | "mv";
+    };
+    /** A FACT beside the disposition: some read of the command could not be established (an `unestablishable` or `declined`
+     *  finding anywhere in it, whichever finding won). A mode that releases the call releases it past the read-deny table. */
+    readonly unestablished?: true;
+    /** The station's admission of this call's judged target, activated only by the caller that APPLIES this verdict (the
+     *  gate's fold, the resumed leg's belt): a verdict nobody received — a wait that elapsed, a judgment that threw —
+     *  admits nothing, whenever it completes. */
+    readonly admit?: () => void;
 }
 /** The station seat one tool call is judged on (the `rejudge` seat is asked for by the caller). */
 export type ShellReadStationSeat = Exclude<ShellReadSeat, "rejudge">;

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

@@ -1,17 +1,182 @@
 import { errorResult } from "../../core/tools.js";
 import { BASH_READONLY_CONFINEMENT_NOTE } from "./fs-shared.js";
-import { violationDetails } from "./safety.js";
+import { isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf, violationDetails, withinAnyRoot } 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 { programArgs, spellsOption } from "./shell-read-write-targets.js";
+import { allFindings, decideShellRead, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, } from "./shell-read-judge.js";
 import { normalizeReadRootCandidate } from "../../core/read-root-candidate.js";
 import { argvOf, lexShellText } from "../../shell/lex.js";
 function containmentDetails(paths) {
     return { type: "readonly_out_of_root", code: "readonly_out_of_root", paths };
 }
+function unestablishedDetails() {
+    return { type: "read_unestablished", code: "read_unestablished" };
+}
+function findingDetails(finding, paths) {
+    return finding === "unestablishable" || finding === "declined" ? unestablishedDetails() : containmentDetails(paths);
+}
+const REMOVAL_COMMANDS = new Set(["rm", "rmdir"]);
+const WRITES_BENEATH = {
+    cp: () => true,
+    mv: () => true,
+    rm: (s) => s.argv.some((w) => spellsOption(w.folded, "recursive", "[rR]")),
+};
+const isPattern = (f) => f.read.candidate.expands !== false && f.read.candidate.expands !== "unresolvable";
+const RESHAPES_TREE = new Set(["mv"]);
+const anyOptionWord = (words) => words.some((w) => w.startsWith("-"));
+const UNPLACED_OPTIONS = {
+    rmdir: (ws) => ws.some((w) => spellsOption(w, "parents", "p")),
+    sed: (ws) => ws.some((w) => spellsOption(w, "file", "f")),
+    cp: anyOptionWord,
+    mv: anyOptionWord,
+};
+function runOrderOf(judged) {
+    const runs = [];
+    const plans = [];
+    let concurrent = false;
+    const walk = (j) => {
+        plans.push(j);
+        for (const s of j.segments) {
+            s.nested.forEach(walk);
+            runs.push(s);
+            if (j.plan.shape.backgrounded || s.segment.connector === "|")
+                concurrent = true;
+        }
+    };
+    walk(judged);
+    return { runs, plans, concurrent };
+}
+function lineOrderPlaced(runs, concurrent) {
+    const reshapes = (s) => RESHAPES_TREE.has(s.segment.verb?.basename ?? "");
+    const writes = (s) => s.findings.some((f) => f.read.candidate.face === "write");
+    const stepsUp = (s) => s.findings.some((f) => f.read.candidate.spelled.split(/[\\/]/).includes(".."));
+    return runs.every((later, j) => runs.every((earlier, i) => i === j || (i > j && !concurrent) || (!reshapes(earlier) && !(writes(earlier) && stepsUp(later)))));
+}
+function writesPlacedOf(judged, boundary) {
+    const writeRoots = boundary.writeRoots;
+    if (writeRoots === undefined || writeRoots.length === 0)
+        return false;
+    const { runs, plans, concurrent } = runOrderOf(judged);
+    const placed = (s) => {
+        const verb = s.segment.verb?.basename ?? "";
+        if (s.segment.reentry === "shell" || s.segment.unreadProgramText !== undefined)
+            return false;
+        if (UNPLACED_OPTIONS[verb]?.(programArgs(s.segment).map((w) => w.spelled)) === true)
+            return false;
+        const beneath = WRITES_BENEATH[verb]?.(s.segment) === true;
+        for (const f of s.findings) {
+            if (f.read.candidate.face !== "write")
+                continue;
+            const target = f.read.target;
+            if (f.read.established === "unestablishable" || target === undefined || isPattern(f) || !withinAnyRoot(writeRoots, target))
+                return false;
+            if (beneath && denyRowAtOrBelow(f.read, boundary, !REMOVAL_COMMANDS.has(verb)))
+                return false;
+            if (REMOVAL_COMMANDS.has(verb) && writeRoots.some((root) => withinAnyRoot([target], root)))
+                return false;
+        }
+        return true;
+    };
+    return plans.every((p) => p.plan.unreadable === undefined) && runs.every(placed) && lineOrderPlaced(runs, concurrent);
+}
+function unplacedOptionsOf(judged) {
+    for (const s of judged.segments) {
+        const nested = s.nested.map(unplacedOptionsOf).find((u) => u !== undefined);
+        if (nested !== undefined)
+            return nested;
+        const verb = s.segment.verb?.basename;
+        if ((verb === "cp" || verb === "mv") && anyOptionWord(programArgs(s.segment).map((w) => w.spelled)))
+            return { program: verb };
+    }
+    return undefined;
+}
+async function writeGuardsOf(judged, boundary, placed, env, signal) {
+    const protection = boundary.writeProtectionJudge;
+    const guard = placed ? boundary.writeTargetGuard : undefined;
+    if (protection === undefined && guard === undefined)
+        return { unplaced: false, writeProtected: false };
+    const { runs, concurrent } = runOrderOf(judged);
+    const asKey = new Map();
+    const asSpelling = new Map();
+    const landingKeys = new Set();
+    const writtenBy = runs.map(() => []);
+    const add = (into, view, child, at) => {
+        if (!isAbsoluteForFamily(pathFamilyOf({ root: view }), view))
+            return;
+        const seen = into.get(view);
+        into.set(view, seen === undefined ? { child, at } : { child: seen.child && child, at: Math.max(seen.at, at) });
+    };
+    runs.forEach((s, at) => {
+        for (const f of s.findings) {
+            const written = f.read.written;
+            if (written === undefined || f.read.established === "unestablishable" || f.read.target === undefined)
+                continue;
+            const child = written.child === true;
+            const key = f.read.established === "canonical" || f.read.established === "expansion";
+            add(key ? asKey : asSpelling, f.read.target, child, at);
+            if (key && written.seat === "landing")
+                landingKeys.add(f.read.target);
+            if (written.seat === "landing")
+                for (const spelling of f.read.spellings)
+                    add(asSpelling, spelling, child, at);
+            writtenBy[at].push(f.read.target, ...f.read.spellings);
+        }
+    });
+    const probes = new Map();
+    const probe = (p) => {
+        let r = probes.get(p);
+        if (r === undefined) {
+            r = env.canonicalPath(p, signal).catch(() => undefined);
+            probes.set(p, r);
+        }
+        return r;
+    };
+    const parentOf = (view) => normalizeAbsPathLexically(`${view}/..`);
+    const writable = async (view, v) => {
+        const at = await probe(view);
+        if (at === undefined || at.ok)
+            return true;
+        if (at.error.code === "not_directory")
+            return false;
+        if (!v.child || at.error.code !== "not_found")
+            return true;
+        const dest = await probe(parentOf(view));
+        return dest === undefined || dest.ok || (dest.error.code !== "not_found" && dest.error.code !== "not_directory");
+    };
+    const changedBefore = (view, at) => {
+        const fold = (p) => p.normalize("NFC").toLowerCase();
+        const dir = fold(parentOf(view));
+        return writtenBy.some((paths, i) => i !== at && (i < at || concurrent) && paths.some((w) => withinAnyRoot([fold(w)], dir) || withinAnyRoot([dir], fold(w))));
+    };
+    const answer = async (ask) => {
+        try {
+            return (await ask()) === true;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const asked = [...[...asKey].map(([view, v]) => [view, v, true]), ...[...asSpelling].filter(([view]) => !landingKeys.has(view)).map(([view, v]) => [view, v, false])];
+    let unplaced = false;
+    let writeProtected = false;
+    for (const [view, v, key] of asked) {
+        if (!(await writable(view, v)) && !changedBefore(view, v.at))
+            continue;
+        const covered = protection === undefined ? false : await answer(() => protection(view, { ...(signal !== undefined ? { signal } : {}), ...(key ? { canonical: true } : {}) }));
+        const guarded = guard === undefined ? false : await answer(() => guard(view, signal));
+        if (covered === true)
+            writeProtected = true;
+        if (covered !== false || guarded !== false)
+            unplaced = true;
+        if (writeProtected)
+            break;
+    }
+    return { unplaced, writeProtected };
+}
 const ADMISSION_MAX = 1024;
 function shellCommandOf(args) {
     const command = args?.command;
@@ -76,14 +241,17 @@ 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 write = w.deny.face === "write";
+        const core = readDenySentence({ target, pattern: w.deny.pattern, matchedView: w.deny.matchedView, ...(write ? { face: "write" } : {}) });
+        const sentence = `Error (${tool}): ${core} ${write ? WRITE_DENY_REFUSAL_NOTE : DENY_REFUSAL_NOTE}`;
+        return { sentence, ...(write ? {} : { 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) };
+    return { sentence, details: findingDetails(fold.finding, paths) };
 }
+const WRITE_DENY_REFUSAL_NOTE = "The boundary judges this command's write targets — its output redirections and the operands of mkdir, touch, rm, " +
+    "rmdir, mv, cp, tee and an in-place sed — against the write deny list; a denied write is refused here rather than escalated.";
 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) {
@@ -91,17 +259,19 @@ function verdictOf(tool, seat, fold, judged, boundary) {
     if (disposition === "vouch")
         return { disposition, finding: fold.finding };
     const paths = outsidePathsOf(judged);
+    const unestablished = fold.unestablished === true ? { unestablished: true } : {};
     if (disposition === "refuse") {
         const r = refusalOf(tool, fold, boundary.roots, paths);
-        return { disposition, finding: fold.finding, sentence: r.sentence, details: r.details };
+        return { disposition, finding: fold.finding, sentence: r.sentence, ...(r.details !== undefined ? { 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,
+        ...unestablished,
         sentence: findingAccount(fold, boundary.roots),
-        ...(disposition === "mandated" && containment ? { details: containmentDetails(paths) } : {}),
+        ...(disposition === "mandated" && containment ? { details: findingDetails(fold.finding, paths) } : {}),
         ...(grant !== undefined ? { readRootCandidate: { dir: grant.dir, ...(grant.covers !== undefined ? { covers: grant.covers } : {}), clearsThisAsk: true } } : {}),
     };
 }
@@ -137,17 +307,22 @@ async function applyAlsoInside(judged, boundary) {
     });
     return rewrite(judged);
 }
-async function runShellReadStation(tool, command, declared, seat, readers, establisher, signal) {
+async function runShellReadStation(tool, command, declared, seat, readers, establisher, env, 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);
+    const judgedVerdict = verdictOf(tool, seat, foldShellReadFindings(judged), judged, boundary);
+    const unplaced = unplacedOptionsOf(judged);
+    const placed = writesPlacedOf(judged, boundary);
+    const guarded = judgedVerdict.disposition === "refuse" ? { unplaced: false, writeProtected: false } : await writeGuardsOf(judged, boundary, placed, env, signal);
+    const facts = guarded.writeProtected ? { ...judgedVerdict, writeProtected: true } : judgedVerdict;
+    const verdict = placed && !guarded.unplaced ? { ...facts, writesPlaced: true } : unplaced !== undefined ? { ...facts, unplacedOptions: unplaced } : facts;
     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 run = await runShellReadStation(input.tool ?? "Bash", input.command, input.boundary, input.seat, readers, createShellReadEstablisher(input.env, input.boundary.roots), input.env, input.signal);
     const offer = normalizeReadRootCandidate(run.verdict.readRootCandidate);
     return {
         plan: run.plan,
@@ -196,7 +371,7 @@ export function createShellReadStation(opts) {
                 return null;
             const seat = callOpts.seat ?? opts.seatOf(toolName);
             return (async () => {
-                const run = await runShellReadStation(toolName, command, boundary, seat, readers, establisherFor(boundary.roots), signal);
+                const run = await runShellReadStation(toolName, command, boundary, seat, readers, establisherFor(boundary.roots), opts.env, signal);
                 if (run.verdict.disposition !== "refuse" && callOpts.toolCallId !== undefined)
                     remember(callOpts.toolCallId, { toolName, boundary: run.boundary, established: run.established, command });
                 return run.verdict;
@@ -207,7 +382,7 @@ export function createShellReadStation(opts) {
             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([]);
+            const details = unestablishedDetails();
             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 } : {}) };

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

@@ -1,7 +1,8 @@
 /**
  * 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
+ * decides WHICH words a command may read, `shell-read-write-targets.ts` which words it writes and at which seat;
+ * 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
@@ -11,7 +12,10 @@
  * 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.
+ *     cannot carry a target out. For a WRITE target a component the resolver cannot find but the filesystem
+ *     still holds (a link whose target does not exist) is not absent: a write through it creates the link's
+ *     target, so the target is established where the link lands (read one hop at a time, bounded) — or not at
+ *     all when the environment cannot read the link.
  *  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`).
@@ -35,7 +39,7 @@
  */
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import type { ShellReadPlan, ShellReadSegment } from "./shell-read-plan.js";
-import { type EstablishedRead, type ShellReadBoundary } from "./shell-read-judge.js";
+import type { EstablishedRead, ShellReadBoundary } from "./shell-read-judge.js";
 /**
  * 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`.

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