@sema-agent/core 7.33.8 → 7.34.0

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;

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

@@ -2,7 +2,7 @@ import { hasWin32AliasedComponent, normalizeAbsPathLexically, withinAnyRoot } fr
 import { globInWord } from "./bash-readonly-classifier.js";
 import { readOfText } from "./shell-read-word.js";
 export const SHELL_READ_FINDINGS = ["deny_hit", "outside_roots", "unestablishable", "declined", "identity_changed", "none"];
-export const SHELL_READ_SEATS = ["bash_off", "bash_classify", "readonly", "rejudge"];
+export const SHELL_READ_SEATS = ["full_shell", "readonly", "rejudge"];
 export const SHELL_READ_FINDING_RANK = {
     identity_changed: 6,
     deny_hit: 5,
@@ -12,27 +12,36 @@ export const SHELL_READ_FINDING_RANK = {
     none: 0,
 };
 export const SHELL_READ_DECISION = {
-    deny_hit: { bash_off: "refuse", bash_classify: "refuse", readonly: "refuse", rejudge: "refuse" },
-    outside_roots: { bash_off: "mandated", bash_classify: "mandated", readonly: "refuse", rejudge: "refuse" },
-    unestablishable: { bash_off: "mandated", bash_classify: "mandated", readonly: "refuse", rejudge: "refuse" },
-    declined: { bash_off: "mandated", bash_classify: "ordinary", readonly: "refuse", rejudge: "refuse" },
-    identity_changed: { bash_off: "refuse", bash_classify: "refuse", readonly: "refuse", rejudge: "refuse" },
-    none: { bash_off: "vouch", bash_classify: "vouch", readonly: "vouch", rejudge: "vouch" },
+    deny_hit: { full_shell: "refuse", readonly: "refuse", rejudge: "refuse" },
+    outside_roots: { full_shell: "mandated", readonly: "refuse", rejudge: "refuse" },
+    unestablishable: { full_shell: "mandated", readonly: "refuse", rejudge: "refuse" },
+    declined: { full_shell: "ordinary", readonly: "refuse", rejudge: "refuse" },
+    identity_changed: { full_shell: "refuse", readonly: "refuse", rejudge: "refuse" },
+    none: { full_shell: "vouch", readonly: "vouch", rejudge: "vouch" },
 };
 export function decideShellRead(finding, seat) {
-    return SHELL_READ_DECISION[finding][seat];
+    const row = Object.hasOwn(SHELL_READ_DECISION, finding) ? SHELL_READ_DECISION[finding] : undefined;
+    const disposition = row !== undefined && Object.hasOwn(row, seat) ? row[seat] : undefined;
+    if (disposition === undefined) {
+        throw new Error(`shell read decision: no cell for finding ${JSON.stringify(finding)} on seat ${JSON.stringify(seat)} — the seats are ${SHELL_READ_SEATS.map((w) => JSON.stringify(w)).join(", ")} (a seat names the face the command runs on)`);
+    }
+    return disposition;
 }
 export function judgeRead(read, boundary) {
-    const deny = boundary.denyMatch;
+    const writeTarget = read.candidate.face === "write";
+    const deny = writeTarget ? boundary.writeDenyMatch : boundary.denyMatch;
     if (deny !== undefined) {
+        const walked = read.walked === true ? { walked: true } : undefined;
         const views = [...(read.target !== undefined ? [read.target] : []), ...read.spellings];
         for (const view of views) {
             const folded = normalizeAbsPathLexically(view);
-            const pattern = deny(folded);
+            const pattern = writeTarget ? boundary.writeDenyMatch(folded) : boundary.denyMatch(folded, walked);
             if (pattern !== null)
-                return { read, kind: "deny_hit", deny: { pattern, matchedView: folded }, containment: containmentOf(read, boundary) };
+                return { read, kind: "deny_hit", deny: { pattern, matchedView: folded, ...(writeTarget ? { face: "write" } : {}) }, containment: containmentOf(read, boundary) };
         }
     }
+    if (writeTarget)
+        return { read, kind: "none", containment: containmentOf(read, boundary) };
     const containment = containmentOf(read, boundary);
     if (read.candidate.denyOnly === true)
         return { read, kind: "none", containment };
@@ -43,8 +52,18 @@ export function judgeRead(read, boundary) {
         return { read, kind: "unestablishable", containment };
     return { read, kind: containment === "outside" ? "outside_roots" : "none", containment };
 }
+export function denyRowAtOrBelow(read, boundary, carriesContent) {
+    if (boundary.writeDenyMatch !== undefined)
+        return true;
+    if (!carriesContent)
+        return false;
+    const atOrBelow = boundary.denyAtOrBelow;
+    if (atOrBelow === undefined)
+        return false;
+    return [...(read.target !== undefined ? [read.target] : []), ...read.spellings].some((view) => atOrBelow(normalizeAbsPathLexically(view)) !== null);
+}
 export function denyFloorShadowsOf(candidates) {
-    return candidates.flatMap((c) => (c.floorSpelled === undefined ? [] : [{ spelled: c.floorSpelled, raw: c.raw, provenance: c.provenance, expands: globInWord(readOfText(c.raw).word) ? "glob" : false, bases: [], denyOnly: true }]));
+    return candidates.flatMap((c) => (c.floorSpelled === undefined ? [] : [{ spelled: c.floorSpelled, raw: c.raw, provenance: c.provenance, expands: globInWord(readOfText(c.raw).word) ? "glob" : false, bases: [], denyOnly: true, ...(c.face !== undefined ? { face: c.face } : {}) }]));
 }
 function containmentOf(read, boundary) {
     if (boundary.face === "open")
@@ -55,7 +74,10 @@ function containmentOf(read, boundary) {
 }
 export function foldShellReadFindings(judged) {
     let best = { finding: "none" };
+    let unestablished = false;
     const raise = (next) => {
+        if (next.finding === "unestablishable" || next.finding === "declined")
+            unestablished = true;
         if (SHELL_READ_FINDING_RANK[next.finding] > SHELL_READ_FINDING_RANK[best.finding])
             best = next;
     };
@@ -86,7 +108,7 @@ export function foldShellReadFindings(judged) {
         }
     };
     walk(judged, false);
-    return best;
+    return unestablished ? { ...best, unestablished: true } : best;
 }
 export function judgeEstablishedPlan(plan, established, boundary, nestedOf) {
     return {
@@ -110,7 +132,7 @@ export function allFindings(judged) {
     walk(judged);
     return out;
 }
-function parentDirLexically(p) {
+export function parentDirLexically(p) {
     return normalizeAbsPathLexically(`${p}/..`);
 }
 export function deepestCommonDir(a, b) {
@@ -157,16 +179,19 @@ export function readRootGrantCandidateOf(judged, boundary) {
     }
     if (candidate === undefined)
         return undefined;
-    const tooWide = parentDirLexically(candidate) === candidate ||
-        (boundary.homeDir !== undefined && withinAnyRoot([candidate], boundary.homeDir)) ||
-        boundary.roots.some((root) => withinAnyRoot([candidate], root));
-    const proposed = tooWide ? (paths.length === 1 ? { dir: paths[0], covers: "exact" } : undefined) : { dir: candidate };
+    const proposed = grantOfferFor(candidate, paths.length === 1 ? paths[0] : undefined, boundary);
     if (proposed === undefined)
         return undefined;
     const widened = { ...boundary, roots: [...boundary.roots, proposed.dir] };
     const replay = rejudge(judged, widened);
     return foldShellReadFindings(replay).finding === "none" ? proposed : undefined;
 }
+export function grantOfferFor(candidate, single, bounds) {
+    const tooWide = parentDirLexically(candidate) === candidate ||
+        (bounds.homeDir !== undefined && withinAnyRoot([candidate], bounds.homeDir)) ||
+        bounds.roots.some((root) => withinAnyRoot([candidate], root));
+    return tooWide ? (single !== undefined ? { dir: single, covers: "exact" } : undefined) : { dir: candidate };
+}
 export function rejudge(judged, boundary) {
     return {
         plan: judged.plan,

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

@@ -13,6 +13,7 @@
  *  · a LISTED reader hands its positional operands and the declared option-value slots (the verb tables of
  *    `bash-readonly-classifier.ts`, read here through their exported readers, never copied);
  *  · an UNLISTED program hands every word of its argv (a program declared to open no path operand hands none);
+ *  · an ASSIGNMENT's value is a candidate only in a text that runs a program able to open a file;
  *  · a LAUNCHER chain is peeled to its program and the chain's own words are never candidates; a launcher
  *    option the row cannot read is recorded as a decline and every word after it is handed over;
  *  · a SHELL re-entry (`sh -c S`, `eval S`, a launcher handing text to a shell, `env -S S`, a builtin's code-body
@@ -67,6 +68,9 @@ export interface ReadCandidate {
     readonly floorSpelled?: string;
     /** A deny-floor shadow of a `floorSpelled` spelling, established as a read and judged for deny rows only. */
     readonly denyOnly?: true;
+    /** A WRITE target of the command (a `>`-family redirection, a `sed` `w` file, the operands of a file-writing command):
+     *  established like a read and judged against the deny table's WRITE face only — never for containment, never a read. */
+    readonly face?: "write";
 }
 /** How the shell reached one segment — what the base-candidate walk needs from the connectors. */
 export interface SegmentReach {

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

@@ -1,7 +1,7 @@
 import { lexShell, PARSE_FAILURE_SENTENCE, substitutionsInHeredocBody, literalTildeSpelling, } from "../../shell/lex.js";
 import { compoundArrayElements, dropDefinitionHeads, expandsOf, readOfText, readsOf, rewritten, spelledWithHome, isArithmeticBody, unreadableSentenceOf } from "./shell-read-word.js";
 import { LAUNCHER_TABLE, SHELL_BLOCK_WORDS, programBasename, programPositionRunsShell, readProgramPosition, shellScanDeclineOf, } from "./bash-program-position.js";
-import { ASSIGNMENT_VALUE_NOT_PATHS, INTERPRETER_INLINE_PROGRAMS, NO_PATH_OPERAND_COMMANDS, POLL_LOOP_MAX_BEATS, RECURSIVE_READ_FORMS, SHELL_REENTRY_PROGRAM_RE, UNMODELLED_BASE_MOVERS, argvProgramOf, homeMayBeRebound, attachedOptionPayloads, resolveOperandLexically, inlineProgramClause, interpreterKey, isPathShapedToken, readVerbOptionSlot, sedScriptSlotFiles, segmentSelectsRecursiveRead, slotValueCandidates, suppliesFirstOperandSlot, verbFirstOperandSlot, verbOptionsArePositionIndependent, } from "./bash-readonly-classifier.js";
+import { ASSIGNMENT_VALUE_NOT_PATHS, DECLARATION_BUILTINS, INERT_BUILTINS, INTERPRETER_INLINE_PROGRAMS, NO_PATH_OPERAND_COMMANDS, NO_PATH_OPERAND_EVALUATORS, POLL_LOOP_MAX_BEATS, RECURSIVE_READ_FORMS, SHELL_REENTRY_PROGRAM_RE, UNMODELLED_BASE_MOVERS, argvProgramOf, homeMayBeRebound, attachedOptionPayloads, resolveOperandLexically, inlineProgramClause, interpreterKey, isPathShapedToken, messageSlotWords, readVerbOptionSlot, sedScriptSlotFiles, segmentSelectsRecursiveRead, slotValueCandidates, suppliesFirstOperandSlot, verbFirstOperandSlot, verbOptionsArePositionIndependent, } from "./bash-readonly-classifier.js";
 import { isAbsolutePathForm } from "./safety.js";
 import { codeBodies, reentryText } from "./shell-reentry-text.js";
 export const READ_CANDIDATE_PROVENANCES = [
@@ -29,7 +29,9 @@ export function planShellReads(command, decl, depth = 0, homeRebound = false, ar
     const unreadable = unreadableSentenceOf(lexed, command, !arithmetic);
     const nestedPlan = (text, arithmetic = false) => planShellReads(text, decl, depth + 1, home === undefined, arithmetic);
     const projected = lexed.segments.map((segment) => projectSegment(segment));
-    const facts = projected.map((p, si) => segmentFacts(lexed.segments[si], p, decl, home, nestedPlan));
+    const planned = projected.map((p, si) => segmentFacts(lexed.segments[si], p, decl, home, nestedPlan));
+    const inert = depth === 0 && unreadable === undefined && planned.every(segmentOpensNothing);
+    const facts = inert ? planned.map((f) => ({ ...f, reads: f.reads.filter((c) => c.provenance !== "env_assignment") })) : planned;
     shape.grouped = projected.some((p) => p.grouped);
     shape.backgrounded = lexed.segments.some((s) => s.connector === "&") || facts.some((f) => f.backgrounds === true);
     shape.strayRedirection = projected.some((p) => p.argv.length === 0 && p.redirects.length > 0);
@@ -165,6 +167,14 @@ export function planShellReads(command, decl, depth = 0, homeRebound = false, ar
     }
     return { segments, shape, ...(unreadable !== undefined ? { unreadable } : {}) };
 }
+function segmentOpensNothing(f) {
+    if (f.empty)
+        return true;
+    const program = f.verb;
+    const at = program === undefined ? -1 : f.argv.findIndex((w) => w.folded === program.name);
+    const inertProgram = program === undefined || (program.name === program.basename && INERT_BUILTINS.has(program.basename) && !(DECLARATION_BUILTINS.has(program.basename) && f.argv.slice(at + 1).some((w) => /^[-+]/.test(w.folded))));
+    return inertProgram && f.argv.every((w) => !/[[\]$`]/.test(w.raw)) && f.nested.length === 0 && f.reentry === undefined && f.declines.length === 0 && f.launcherChain.length === 0 && f.redirects.every((r) => r.direction !== "in") && f.reads.every((c) => c.provenance === "env_assignment");
+}
 function projectSegment(segment) {
     const tokens = [...segment.tokens];
     let grouped = tokens.some((t) => t.kind === "group");
@@ -389,6 +399,17 @@ function segmentFactsRead(segment, p, decl, home, nestedPlan) {
     else if (listed) {
         listedVerbCandidates(basename, argReads, reads);
     }
+    else if (DECLARATION_BUILTINS.has(basename) && program.name === basename) {
+        for (const r of argReads) {
+            const a = r.word.assignment;
+            if (a !== undefined && (r.expands !== "unresolvable" || a.value.expansions.length > 0))
+                pushAssignment(reads, r.word, "env_assignment");
+            else if (r.expands === "unresolvable") {
+                reads.push(bare(r, "unlisted_word"));
+                pushAssignment(reads, r.word, "unlisted_word");
+            }
+        }
+    }
     else {
         unlistedWords(reads, toks, program.index, launcherIndices, "unlisted_word", program);
     }
@@ -518,6 +539,7 @@ function unlistedWords(reads, toks, from, launcherIndices, provenance, program)
     const argv = program !== undefined ? { program: program.basename, from: program.index } : argvProgramOf(toks.map((r) => r.word));
     const argvStart = argv?.from ?? toks.length;
     const slotVerb = argv?.program;
+    const message = slotVerb === undefined || argv === undefined ? new Set() : messageSlotWords(slotVerb, toks, argvStart);
     const declaredNotPaths = ASSIGNMENT_VALUE_NOT_PATHS.has(slotVerb ?? "");
     const noPathOperands = slotVerb !== undefined && NO_PATH_OPERAND_COMMANDS.has(slotVerb);
     const permutes = slotVerb === undefined || !verbOptionsArePositionIndependent(slotVerb);
@@ -525,7 +547,7 @@ function unlistedWords(reads, toks, from, launcherIndices, provenance, program)
     for (let j = from; j < toks.length; j++) {
         if (launcherIndices.has(j))
             continue;
-        if (noPathOperands && j > argvStart)
+        if (noPathOperands && j > argvStart && !NO_PATH_OPERAND_EVALUATORS.has(slotVerb))
             break;
         if (toks[j].expands !== "unresolvable")
             continue;
@@ -541,7 +563,7 @@ function unlistedWords(reads, toks, from, launcherIndices, provenance, program)
     let endOfOptions = false;
     let sawArgvOperand = false;
     for (let j = from; j < toks.length; j++) {
-        if (launcherIndices.has(j) || expanding.has(j))
+        if (launcherIndices.has(j) || expanding.has(j) || message.has(j))
             continue;
         const r = toks[j];
         const word = r.folded;

package/dist/tools/fs/shell-read-write-targets.d.ts

@@ -0,0 +1,73 @@
+/**
+ * WRITE TARGETS — which words of a shell segment a program writes, under which names, and at which seat, read off the
+ * plan's text alone (no filesystem): the `>`-family redirections and a `sed` script's `w` files, the operands of the
+ * write commands ({@link SHELL_WRITE_COMMANDS}), a copy's or a move's destination children (GNU's argument grammar), an
+ * in-place `sed`'s backups, and the seat each is written at ({@link WriteSeat}: the directory entry, or where the path
+ * lands). The establisher (`shell-read-establish.ts`) places what this module names; the judge reads the result on the
+ * deny table's write face; the station's `writesPlaced` fact reads the option readers exported here.
+ */
+import type { ReadCandidate, ShellReadSegment } from "./shell-read-plan.js";
+/**
+ * The commands whose operands are WRITE targets — the reference implementation's path-checked commands whose operation
+ * is a write or a create (`mkdir` / `touch` create; `rm` / `rmdir` / `mv` / `cp` / `tee` write; `sed` writes when it
+ * edits in place). Every operand counts (a `cp` source is judged as a write too, as the reference judges it): the write
+ * face only ever REFUSES, so a word read as a target it is not costs a refusal of a command that names a denied path.
+ */
+export declare const SHELL_WRITE_COMMANDS: readonly ["mkdir", "touch", "rm", "rmdir", "mv", "cp", "tee", "sed"];
+/**
+ * Does an option WORD spell this option — the long name or any abbreviation of it GNU getopt accepts (`--in-p`, `--fi`,
+ * `--par`: an unambiguous prefix, `=value` allowed), or the short letter alone or inside a bundle (`-i`, `-ni`, `-i.bak`)?
+ * Read in the tightening direction: a prefix that another long option shares still counts (the program would refuse it).
+ */
+export declare function spellsOption(word: string, long: string, short: string): boolean;
+/** A word of a program's argv: its raw spelling (the plan's candidates are keyed by it) and its folded spelling. */
+export interface ArgWord {
+    readonly raw: string;
+    readonly spelled: string;
+}
+/** The words a segment hands its program — the argv after the program word (a launcher's own words are not the program's). */
+export declare function programArgs(segment: ShellReadSegment): ArgWord[];
+/** What a `sed` invocation's option words say about writing, under either grammar ({@link SED_GRAMMARS}): whether it edits
+ *  in place (`-i` / `-I` / `--in-place`), the backup suffixes it is given (their values; an empty value keeps no backup),
+ *  and whether GNU `--follow-symlinks` is on. */
+export interface SedOptions {
+    readonly inPlace: boolean;
+    readonly suffixes: readonly string[];
+    readonly followsLinks: boolean;
+}
+export declare function sedOptionsOf(segment: ShellReadSegment): SedOptions;
+/**
+ * The BACKUP names an in-place `sed` gives the file it knows as `name` — both readings a suffix has: GNU sed replaces every
+ * `*` in the suffix with the name (`bak/*` on `d/f` is `bak/d/f`, `/elsewhere/*` is `/elsewhere/d/f`) and appends a suffix
+ * without one (`d/f.bak`); the BSD and BusyBox seds append the suffix literally (`d/f` + `bak/*`). A name resolves against
+ * the working directory like the operand itself, so a suffix carrying a separator places the backup wherever it points.
+ */
+export declare function sedBackupNames(name: string, suffix: string): string[];
+/**
+ * WHERE a write reaches a path it names. `landing` — the path followed through every link to where it lands: the program
+ * opens the path and writes through it. `entry` — the directory entry itself, the canonical parent joined with the last
+ * name: the program renames over the entry, unlinks it or replaces it, and a link there is not followed (a name ending in
+ * a separator, `.` or `..` resolves itself, so it lands).
+ */
+export type WriteSeat = "landing" | "entry";
+/** One candidate handed to the judge. `seats`: where a write target is established ({@link WriteSeat}; absent ⇒ it lands —
+ *  every read does). `written`: the seats among `seats` the program itself WRITES the target at (absent ⇒ all of them;
+ *  `[]` ⇒ none — a copy's source, judged on the write face as a write path and read by the program); the write guards are
+ *  asked about these alone. `child`: a copy's or a move's destination child, written only where the destination is a
+ *  directory when the program runs. `followed`: a GNU sed `--follow-symlinks` backup — its names are {@link sedBackupNames}
+ *  of the operand's FOLLOWED name, which only the filesystem answers (the candidate's own spelling is the operand's as
+ *  written, the identity the pre-spawn re-check compares). */
+export interface JudgedCandidate {
+    readonly candidate: ReadCandidate;
+    readonly seats?: readonly WriteSeat[];
+    readonly written?: readonly WriteSeat[];
+    readonly child?: true;
+    readonly followed?: {
+        readonly operand: ReadCandidate;
+        readonly suffix: string;
+    };
+}
+/** Every candidate a segment hands the judge: its reads minus the write targets, plus its `cd` target (the plan already
+ *  lists it among the reads), plus its WRITE targets for the write face ({@link writeTargetsOf}), plus the deny-floor
+ *  shadow of every unplaced home word ({@link denyFloorShadowsOf}) on both faces. */
+export declare function judgedCandidatesOf(segment: ShellReadSegment): readonly JudgedCandidate[];