@sema-agent/core 7.33.8 → 7.35.0

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

@@ -22,19 +22,23 @@ 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. */
+import { type ToolCallLike } from "../../core/tool-registry.js";
+/** 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 +47,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">;
@@ -58,14 +90,21 @@ export type ShellReadStationSeat = Exclude<ShellReadSeat, "rejudge">;
  * 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.
+ *
+ * Both take the CALL (`{ toolName, face }`), not a name: a station is a tighten keyed on the engine's own tool names,
+ * so it holds a call made under ANY of the call's names (`ruleNamesOf` — a tool that answers to `Bash` under another
+ * wire name is judged as `Bash`). The first of the names the station's membership holds keys its seat, its boundary
+ * and the admission the engine's tool reads before it spawns; the sentences name the call's wire name.
  */
 export interface ShellReadCheck {
-    judge(toolName: string, args: unknown, cwd: string | undefined, signal: AbortSignal | undefined, opts: {
+    judge(call: ReadStationCall, args: unknown, cwd: string | undefined, signal: AbortSignal | undefined, opts: {
         readonly toolCallId?: string;
         readonly seat?: "rejudge";
     }): Promise<ShellReadVerdict> | null;
-    unanswered(toolName: string, cause: string): ShellReadVerdict;
+    unanswered(call: ReadStationCall, cause: string): ShellReadVerdict;
 }
+/** The call a read station judges: its wire name and the face the gate stamped (whose `names` the station reads). */
+export type ReadStationCall = Pick<ToolCallLike, "toolName" | "face">;
 /** 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. */

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

@@ -1,17 +1,183 @@
 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 { ruleNamesOf } from "../../core/tool-registry.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 +242,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 +260,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 +308,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,
@@ -184,30 +360,33 @@ export function createShellReadStation(opts) {
         }
         admissions.set(toolCallId, a);
     };
+    const memberOf = (call) => ruleNamesOf(call).find((n) => opts.tools.has(n));
     const check = {
-        judge(toolName, args, cwd, signal, callOpts) {
-            if (!opts.tools.has(toolName))
+        judge(call, args, cwd, signal, callOpts) {
+            const member = memberOf(call);
+            if (member === undefined)
                 return null;
             const command = shellCommandOf(args);
             if (command === undefined)
                 return null;
-            const boundary = opts.boundaryOf(toolName, cwd);
+            const boundary = opts.boundaryOf(member, cwd);
             if (boundary === undefined)
                 return null;
-            const seat = callOpts.seat ?? opts.seatOf(toolName);
+            const seat = callOpts.seat ?? opts.seatOf(member);
             return (async () => {
-                const run = await runShellReadStation(toolName, command, boundary, seat, readers, establisherFor(boundary.roots), signal);
+                const run = await runShellReadStation(call.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 });
+                    remember(callOpts.toolCallId, { toolName: member, boundary: run.boundary, established: run.established, command });
                 return run.verdict;
             })();
         },
-        unanswered(toolName, cause) {
-            const seat = opts.seatOf(toolName);
+        unanswered(call, cause) {
+            const toolName = call.toolName;
+            const seat = opts.seatOf(memberOf(call) ?? 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([]);
+            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`.