@sema-agent/core 7.47.0 → 7.49.0

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

@@ -0,0 +1,35 @@
+/**
+ * WHETHER A BUILTIN RUNS BY ITS NAME — a binding of the same ordered thread as a variable's or a function's
+ * (`shell-read-bindings.ts`). `enable -n NAME` disables a builtin (the word then finds no command: "command not found"),
+ * `enable NAME` enables it again, and every builtin starts a text enabled. The thread keeps this the way it keeps a
+ * function's definition, under a key neither a variable nor a function can spell, and a reader at a segment asks the one
+ * ordered rule ({@link BuiltinState}) before it takes a word for the builtin of its name; this module is the vocabulary of
+ * that key and the reading of an `enable` into bindings.
+ */
+import type { LexedWord } from "../../shell/lex.js";
+import type { Binding, BoundValue, NameState } from "./shell-read-bindings.js";
+/** What a builtin is at a reader: `enabled` — it certainly runs by its name; `disabled` — it certainly does not (`enable -n`:
+ *  "command not found"); `maybe` — an `enable` that may not have run, a call that may have run one, one for every builtin. */
+export type BuiltinState = "enabled" | "maybe" | "disabled";
+/** The builtin whose words are read into the availability of the others. */
+export declare const ENABLE_BUILTIN = "enable";
+export declare const builtinKey: (name: string) => string;
+export declare const isBuiltinKey: (name: string) => boolean;
+/** Every builtin at once (`enable -f FILE` loads one over any name; a name the text computes may be any). */
+export declare const BUILTINS_ALL: string;
+export declare const BUILTIN_ENABLED: NameState;
+export declare const isDisabledValue: (v: BoundValue) => boolean;
+/** What the shell finds looking up each word of a chain it runs as builtins (`builtin` / `command` in front, then the name): the
+ *  same reading ({@link BuiltinState}) for every word, since the chain runs no further than its first word that finds no command —
+ *  one that certainly does not run makes the chain certainly not run, and one that may not makes it so. `ask` absent: all enabled. */
+export declare function chainAvailability(words: readonly string[], ask: ((builtin: string) => BuiltinState) | undefined): BuiltinState;
+/** Does an entry (or a made-unreadable name) with this name speak for `name`: no name (every name), the name itself, or —
+ *  for a builtin's key — every builtin at once. */
+export declare const speaksFor: (subject: string | undefined, name: string) => boolean;
+/** The bindings an `enable [-a] [-dnps] [-f FILE] [NAME…]` makes: `enable NAME` enables each name, `enable -n NAME` disables it
+ *  (a literal name: its key); any other switch — `-f FILE` loads a builtin over any name, `-d`, the listing switches — or a
+ *  name the text computes may change every builtin; a bare listing (`enable`, `enable -n`) changes none. The words in front of
+ *  the first name are read as the shell reads them: a word opening with `-` (but a lone `-`, which is a name) is switches, `--`
+ *  ends them, and a letter outside the switches is an invalid option — the shell rejects the whole call (status 2) and nothing
+ *  changes, whatever else the call says; a word after the first name is a name. */
+export declare function enableBindings(args: readonly LexedWord[]): Binding[];

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

@@ -0,0 +1,43 @@
+export const ENABLE_BUILTIN = "enable";
+const BUILTIN_KEY_PREFIX = "[]";
+export const builtinKey = (name) => BUILTIN_KEY_PREFIX + name;
+export const isBuiltinKey = (name) => name.startsWith(BUILTIN_KEY_PREFIX);
+export const BUILTINS_ALL = builtinKey("*");
+export const BUILTIN_ENABLED = [{ spelled: "enabled" }];
+const BUILTIN_DISABLED = [{ spelled: "disabled" }];
+export const isDisabledValue = (v) => v.spelled === "disabled";
+export function chainAvailability(words, ask) {
+    const states = words.map((w) => ask?.(w) ?? "enabled");
+    return states.includes("disabled") ? "disabled" : states.includes("maybe") ? "maybe" : "enabled";
+}
+export const speaksFor = (subject, name) => subject === undefined || subject === name || (subject === BUILTINS_ALL && isBuiltinKey(name));
+const ENABLE_SWITCHES = "adfnps";
+export function enableBindings(args) {
+    const computed = (w) => w.pieces.some((p) => p.expansion !== undefined || p.literal === undefined);
+    let disable = false;
+    let other = false;
+    let at = 0;
+    for (; at < args.length; at++) {
+        const w = args[at];
+        if (w.folded === "--") {
+            at++;
+            break;
+        }
+        if (computed(w) || w.folded.length < 2 || !w.folded.startsWith("-"))
+            break;
+        for (const letter of w.folded.slice(1)) {
+            if (!ENABLE_SWITCHES.includes(letter))
+                return [];
+            if (letter === "f")
+                return [{ name: BUILTINS_ALL, state: "unknown" }];
+            if (letter === "n")
+                disable = true;
+            else
+                other = true;
+        }
+    }
+    const names = args.slice(at);
+    if (other || names.some(computed))
+        return [{ name: BUILTINS_ALL, state: "unknown" }];
+    return names.map((w) => ({ name: builtinKey(w.folded), state: disable ? BUILTIN_DISABLED : BUILTIN_ENABLED }));
+}

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

@@ -44,6 +44,9 @@ export type ShellReadRefusalDetails = NonNullable<ReturnType<typeof violationDet
 export interface ShellReadVerdict {
     readonly disposition: ShellReadDisposition;
     readonly finding: ShellReadFinding;
+    /** `write` ⇔ the finding is about where the command WRITES — its witness is a write target (a redirection's, or a word
+     *  the program's row writes), judged against the write roots. Absent ⇒ a read's finding (or `vouch`). */
+    readonly face?: "write";
     /** `refuse`: the refusal text (`Error (<tool>): …`, the five-segment deny sentence or the containment
      *  sentence). `mandated` / `ordinary`: the ACCOUNT of the finding, for the approval card's disclosure seat
      *  (never the ask's own message — that is the auto-mode classifier's input). Absent for `vouch`. */
@@ -58,7 +61,7 @@ export interface ShellReadVerdict {
     /** 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
+     *  guarded write row (the leg's one write judgment, `ShellReadBoundary.writeTargetJudge`), 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. */
@@ -67,6 +70,11 @@ export interface ShellReadVerdict {
      *  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 the disposition: a target this command's program WRITES was placed and the environment could not say
+     *  where it leads ({@link EstablishedRead.unresolved}) — the reading's `target_unresolved` fact, the same one a write
+     *  tool's unresolved target states, so the command's ask carries that class (no automatic lane answers it; the shell face
+     *  releases it under bypassPermissions). Absent ⇒ every written target resolved, or was not placed for another reason. */
+    readonly targetUnresolved?: 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
@@ -149,6 +157,12 @@ export interface ShellReadStationOptions {
     /** The home views of the placement the boundary's deny seats were compiled at (read-deny-home.ts) — the Runner's. Absent,
      *  the declared home alone. */
     readonly homeViews?: HomeViewSource;
+    /** The engine's account of a REFUSED admission, called with the call's id before the refusal is handed back to the tool
+     *  — the one trusted channel by which a refusal after the gate reaches the call's record (the tool's result is the
+     *  tool's own word, and a refusal must not read as a tool failure under the gate's `allowed`). Every shell tool this
+     *  station admits (both Bash faces, Monitor) refuses through {@link ShellReadStation.admit}, so this is the one
+     *  place to hear it. The Runner's; absent outside one. */
+    readonly onAdmissionRefused?: (toolCallId: string) => void;
 }
 /** What a consumer hands {@link judgeShellRead}: the command as written, the environment whose filesystem
  *  answers where its words land (symlinks resolved, patterns expanded — a `NodeExecutionEnv` over a real

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

@@ -9,10 +9,11 @@ import { createShellReadEstablisher, establishShellReadsLexically } from "./shel
 import { declaredReadDenyHomes, homeViewsAt } from "./read-deny-home.js";
 import { programArgs } from "./shell-read-write-targets.js";
 import { programRow, selectedOptions } from "./program-read-model.js";
-import { allFindings, decideShellRead, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, stationGuards, } from "./shell-read-judge.js";
+import { allFindings, anyFaceGuards, decideShellRead, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, stationGuards, writeFaceGuards, } from "./shell-read-judge.js";
 import { seatOf } from "../../core/tool-name-readings.js";
 import { normalizeReadRootCandidate } from "../../core/read-root-candidate.js";
 import { argvOf, lexShellText } from "../../shell/lex.js";
+import { assertNoRetiredShellReadBoundaryKeys } from "../../core/retired-keys.js";
 function containmentDetails(paths) {
     return { type: "readonly_out_of_root", code: "readonly_out_of_root", paths };
 }
@@ -75,7 +76,7 @@ function writesPlacedOf(judged, boundary) {
             if (f.read.candidate.face !== "write")
                 continue;
             const target = f.read.target;
-            if (f.read.established === "unestablishable" || target === undefined || isPattern(f) || !withinAnyRoot(writeRoots, target))
+            if (f.read.established === "unestablishable" || target === undefined || isPattern(f) || f.kind !== "none" || (f.containment !== "inside" && f.containment !== "open"))
                 return false;
             if (beneath && denyRowAtOrBelow(f.read, boundary, !REMOVAL_COMMANDS.has(verb)))
                 return false;
@@ -97,10 +98,9 @@ function unplacedOptionsOf(judged) {
     }
     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)
+async function writeGuardsOf(judged, boundary, env, signal) {
+    const judge = boundary.writeTargetJudge;
+    if (judge === undefined)
         return { unplaced: false, writeProtected: false };
     const { runs, concurrent } = runOrderOf(judged);
     const asKey = new Map();
@@ -155,25 +155,17 @@ async function writeGuardsOf(judged, boundary, placed, env, signal) {
         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 answer = async (view, key) => (await judge(view, { ...(signal !== undefined ? { signal } : {}), ...(key ? { canonical: true } : {}) })) ?? "clear";
     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)
+        const found = await answer(view, key);
+        if (found === "protected")
             writeProtected = true;
-        if (covered !== false || guarded !== false)
+        if (found !== "clear")
             unplaced = true;
         if (writeProtected)
             break;
@@ -206,15 +198,21 @@ const CAUSE_SPELLING_MAX = 64;
 function fitCause(cause) {
     return cause.replace(/^"([^"]*)"/, (_m, spelling) => `"${fitMiddle(spelling, CAUSE_SPELLING_MAX)}"`);
 }
-function findingAccount(fold, roots, face) {
-    const allowed = fitMiddle(roots.length > 0 ? roots.join(", ") : "(none)", ACCOUNT_PART_MAX);
+function findingAccount(fold, boundary) {
     const w = fold.witness;
+    const writes = w?.read.candidate.face === "write";
+    const roots = writes ? (boundary.writeRoots ?? []) : boundary.roots;
+    const allowed = fitMiddle(roots.length > 0 ? roots.join(", ") : "(none)", ACCOUNT_PART_MAX);
     switch (fold.finding) {
         case "outside_roots":
-            return `reads outside the allowed directories for this session: "${fitMiddle(w?.read.target ?? "?", ACCOUNT_PART_MAX)}" is not under ${allowed} ${NOT_AUTO_ALLOWED}`;
+            return `${writes ? "writes" : "reads"} outside the allowed directories for this session: "${fitMiddle(w?.read.target ?? "?", ACCOUNT_PART_MAX)}" is not under ${allowed} ${NOT_AUTO_ALLOWED}`;
         case "unestablishable":
+            if (writes && boundary.writeRoots === undefined)
+                return `this command writes "${fitMiddle(w.read.target ?? w.read.candidate.spelled, ACCOUNT_PART_MAX)}", and this session declares no directories it may write ${NOT_AUTO_ALLOWED}`;
+            if (writes)
+                return `where this command writes could not be established${w.read.cause !== undefined ? `: ${fitCause(w.read.cause)}` : ""}, so it cannot be confirmed to write only inside the allowed directories for this session (${allowed}) ${NOT_AUTO_ALLOWED}`;
             if (w?.read.cause !== undefined)
-                return `where this command reads could not be established: ${fitCause(w.read.cause)}, so it cannot be confirmed ${face === "open" ? "not to read a path the deny list names" : `to read only inside the allowed directories for this session (${allowed})`} ${NOT_AUTO_ALLOWED}`;
+                return `where this command reads could not be established: ${fitCause(w.read.cause)}, so it cannot be confirmed ${boundary.face === "open" ? "not to read a path the deny list names" : `to read only inside the allowed directories for this session (${allowed})`} ${NOT_AUTO_ALLOWED}`;
             if (fold.declined?.baseMove !== undefined)
                 return `"${fitMiddle(fold.declined.text.trim(), ACCOUNT_PART_MAX)}" moves the working directory somewhere this command's text does not settle ${NOT_AUTO_ALLOWED}`;
             if (fold.declined?.unreadProgramText !== undefined)
@@ -243,7 +241,7 @@ function outsidePathsOf(judged) {
     }
     return out;
 }
-function refusalOf(tool, fold, roots, paths, face) {
+function refusalOf(tool, fold, boundary, paths) {
     const w = fold.witness;
     if (fold.finding === "deny_hit" && w?.deny !== undefined) {
         const target = w.read.target ?? w.deny.matchedView;
@@ -252,7 +250,7 @@ function refusalOf(tool, fold, roots, paths, face) {
         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, face);
+    const account = findingAccount(fold, boundary);
     const sentence = `Error (${tool}): ${account}. ${BASH_READONLY_CONFINEMENT_NOTE}`;
     return { sentence, details: findingDetails(fold.finding, paths) };
 }
@@ -268,37 +266,40 @@ function verdictOf(tool, seat, fold, judged, boundary) {
         return { disposition, finding: fold.finding };
     const paths = outsidePathsOf(judged);
     const unestablished = fold.unestablished === true ? { unestablished: true } : {};
+    const writes = fold.witness?.read.candidate.face === "write" ? { face: "write" } : {};
     if (disposition === "refuse") {
-        const r = refusalOf(tool, fold, boundary.roots, paths, boundary.face);
-        return { disposition, finding: fold.finding, sentence: r.sentence, ...(r.details !== undefined ? { details: r.details } : {}) };
+        const r = refusalOf(tool, fold, boundary, paths);
+        return { disposition, finding: fold.finding, ...writes, 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,
+        ...writes,
         ...unestablished,
-        sentence: findingAccount(fold, boundary.roots, boundary.face),
+        sentence: findingAccount(fold, boundary),
         ...(disposition === "mandated" && containment ? { details: findingDetails(fold.finding, paths) } : {}),
         ...(grant !== undefined ? { readRootCandidate: { dir: grant.dir, ...(grant.covers !== undefined ? { covers: grant.covers } : {}), clearsThisAsk: true } } : {}),
     };
 }
-function declarationsOf(boundary, readers) {
-    return { readers, cwd: boundary.cwd ?? boundary.roots[0] ?? "", roots: boundary.roots, ...(boundary.homeDir !== undefined ? { homeDir: boundary.homeDir } : {}), ...(boundary.face !== undefined ? { face: boundary.face } : {}) };
+function declarationsOf(boundary, readers, cdPath) {
+    return { readers, cwd: boundary.cwd ?? boundary.roots[0] ?? "", roots: boundary.roots, cdPath, ...(boundary.homeDir !== undefined ? { homeDir: boundary.homeDir } : {}), ...(boundary.face !== undefined ? { face: boundary.face } : {}) };
 }
 function judgePlan(plan, established, boundary) {
     return judgeEstablishedPlan(plan, established.reads, boundary, (n) => {
         const nested = established.nested.get(n);
-        return nested === undefined ? { plan: n, segments: [], guards: stationGuards(boundary) } : judgePlan(n, nested, boundary);
+        return nested === undefined ? { plan: n, segments: [], guards: stationGuards(boundary), writeGuards: writeFaceGuards(boundary) } : judgePlan(n, nested, boundary);
     });
 }
 async function applyAlsoInside(judged, boundary) {
     const alsoInside = boundary.alsoInside;
     if (alsoInside === undefined)
         return judged;
+    const outsideRead = (f) => f.kind === "outside_roots" && f.read.candidate.face !== "write" && f.read.target !== undefined;
     const rescued = new Set();
     for (const f of allFindings(judged)) {
-        if (f.kind !== "outside_roots" || f.read.target === undefined || rescued.has(f.read.target))
+        if (!outsideRead(f) || rescued.has(f.read.target))
             continue;
         if (await alsoInside(f.read.target))
             rescued.add(f.read.target);
@@ -308,28 +309,31 @@ async function applyAlsoInside(judged, boundary) {
     const rewrite = (j) => ({
         plan: j.plan,
         guards: j.guards,
+        writeGuards: j.writeGuards,
         segments: j.segments.map((s) => ({
             segment: s.segment,
-            findings: s.findings.map((f) => (f.kind === "outside_roots" && f.read.target !== undefined && rescued.has(f.read.target) ? { ...f, kind: "none", containment: "inside" } : f)),
+            findings: s.findings.map((f) => (outsideRead(f) && rescued.has(f.read.target) ? { ...f, kind: "none", containment: "inside" } : f)),
             nested: s.nested.map(rewrite),
         })),
     });
     return rewrite(judged);
 }
 async function runShellReadStation(tool, command, declared, seat, readers, establisher, env, signal) {
-    const plan = planShellReads(command, declarationsOf(declared, readers));
+    const plan = planShellReads(command, declarationsOf(declared, readers, env.cdPath));
     const established = await establisher.establish(plan, declared, signal);
     const boundary = { ...declared, roots: established.roots };
     const judged = await applyAlsoInside(judgePlan(plan, established, boundary), 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 guarded = judgedVerdict.disposition === "refuse" ? { unplaced: false, writeProtected: false } : await writeGuardsOf(judged, boundary, env, signal);
+    const unresolved = judgedVerdict.disposition !== "refuse" && runOrderOf(judged).runs.some((s) => s.findings.some((f) => f.read.written !== undefined && f.read.unresolved === true));
+    const facts = { ...judgedVerdict, ...(guarded.writeProtected ? { writeProtected: true } : {}), ...(unresolved ? { targetUnresolved: true } : {}) };
     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) {
+    assertNoRetiredShellReadBoundaryKeys(input.boundary);
     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, { homeViews: homeViewsAt(input.env, input.readDenyHomes === undefined ? declaredReadDenyHomes(input.env) : checkedReadDenyHomes(input.readDenyHomes)) }), input.env, input.signal);
     const offer = normalizeReadRootCandidate(run.verdict.readRootCandidate);
@@ -341,8 +345,9 @@ export async function judgeShellRead(input) {
     };
 }
 export function judgeShellReadLexically(command, boundary, seat, opts) {
+    assertNoRetiredShellReadBoundaryKeys(boundary);
     const readers = opts?.readers ?? new Set(bashClassifyDefaultAllow());
-    const plan = planShellReads(command, declarationsOf(boundary, readers));
+    const plan = planShellReads(command, declarationsOf(boundary, readers, []));
     const established = establishShellReadsLexically(plan, boundary);
     const judged = judgePlan(plan, established, boundary);
     return verdictOf(opts?.tool ?? "Bash", seat, foldShellReadFindings(judged), judged, boundary);
@@ -393,7 +398,7 @@ export function createShellReadStation(opts) {
             const member = memberOf(call) ?? toolName;
             const seat = opts.seatOf(member);
             const boundary = opts.boundaryOf(member, undefined);
-            if (boundary === undefined || !(stationGuards(boundary) || boundary.writeDenyMatch !== undefined))
+            if (boundary === undefined || !(anyFaceGuards(boundary) || boundary.writeTargetJudge !== undefined))
                 return { disposition: "vouch", finding: "none" };
             const fold = { finding: "unestablishable" };
             const disposition = decideShellRead("unestablishable", seat);
@@ -411,8 +416,12 @@ export function createShellReadStation(opts) {
         if (a === undefined)
             return undefined;
         admissions.delete(toolCallId);
+        const refused = (r) => {
+            opts.onAdmissionRefused?.(toolCallId);
+            return r;
+        };
         if (a.toolName !== toolName || a.command !== command) {
-            return errorResult(`Error (${toolName}): the command that would run is not the one the read station judged for this call — refused before the spawn; re-submit it as a fresh call.`, containmentDetails([]));
+            return refused(errorResult(`Error (${toolName}): the command that would run is not the one the read station judged for this call — refused before the spawn; re-submit it as a fresh call.`, containmentDetails([])));
         }
         const establisher = establisherFor(a.boundary.roots);
         const { changed } = await establisher.reestablish(a.established, a.boundary, signal);
@@ -422,13 +431,13 @@ export function createShellReadStation(opts) {
         const judged = await applyAlsoInside(judgePlan(a.established.plan, again, a.boundary), a.boundary);
         const fold = foldShellReadFindings(judged);
         if (fold.finding === "deny_hit") {
-            const r = refusalOf(toolName, fold, a.boundary.roots, outsidePathsOf(judged));
-            return errorResult(r.sentence, r.details);
+            const r = refusalOf(toolName, fold, a.boundary, outsidePathsOf(judged));
+            return refused(errorResult(r.sentence, r.details));
         }
         const moved = changed[0];
         const identity = { finding: "identity_changed", witness: { read: moved, kind: "none", containment: "unknown" } };
-        const r = refusalOf(toolName, identity, a.boundary.roots, []);
-        return errorResult(r.sentence, containmentDetails(changed.map((c) => c.target).filter((t) => t !== undefined)));
+        const r = refusalOf(toolName, identity, a.boundary, []);
+        return refused(errorResult(r.sentence, containmentDetails(changed.map((c) => c.target).filter((t) => t !== undefined))));
     };
     return { check, admit };
 }

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

@@ -1,4 +1,4 @@
-import { isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
+import { anchorSpelling, normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
 import { boundaryIsTheSandbox, canonicalPathIsAuthoritative } from "../../core/remote-env.js";
 import { resolveOperandSpellings } from "./bash-readonly-classifier.js";
 import { judgedCandidatesOf, sedBackupNames } from "./shell-read-write-targets.js";
@@ -57,11 +57,10 @@ function parseBracketExpression(pattern, start) {
             return { source: anyChar ? "[^/]" : `[${negate ? "^" : ""}${body}]`, end: i };
         }
         if (ch === "[" && (pattern[i + 1] === ":" || pattern[i + 1] === "." || pattern[i + 1] === "=")) {
-            const close = pattern.indexOf(`${pattern[i + 1]}]`, i + 2);
-            if (close < 0)
-                return undefined;
             anyChar = true;
-            i = close + 1;
+            const close = pattern.indexOf(`${pattern[i + 1]}]`, i + 2);
+            if (close >= 0 && (pattern[i + 1] === ":" ? /^[A-Za-z]+$/.test(pattern.slice(i + 2, close)) : close === i + 3))
+                i = close + 1;
             continue;
         }
         body += ch === "-" ? "-" : ch.replace(/[\]\\^]/g, "\\$&");
@@ -225,7 +224,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                 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);
+                    const landing = anchorSpelling(family, 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")
@@ -417,11 +416,11 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         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` };
+                return { candidate, established: "unestablishable", spellings, ...(origin !== undefined ? { origin } : {}), cause: `"${spelling}" cannot be resolved to verify where it reads`, unresolved: true };
             return { candidate, established: "lexical", target: normalizeAbsPathLexically(spelling), spellings, ...(origin !== undefined ? { origin } : {}) };
         }
         if (!real.exact && real.missing !== true) {
-            return { candidate, established: "unestablishable", spellings, ...(origin !== undefined ? { origin } : {}), cause: `"${spelling}" cannot be resolved to verify where it reads` };
+            return { candidate, established: "unestablishable", spellings, ...(origin !== undefined ? { origin } : {}), cause: `"${spelling}" cannot be resolved to verify where it reads`, unresolved: true };
         }
         return { candidate, established, target: real.value, spellings, ...(origin !== undefined ? { origin } : {}) };
     };
@@ -452,7 +451,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
             if (link?.ok !== true)
                 return undefined;
             const dir = name.slice(0, name.search(/[^/]*$/));
-            name = isAbsoluteForFamily(family, link.value) ? link.value : `${dir}${link.value}`;
+            name = dir === "" ? link.value : anchorSpelling(family, dir, link.value);
         }
         return undefined;
     };
@@ -559,7 +558,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
             };
             for (const [i, lexical] of lexicalReadsOf(candidate, boundary).entries()) {
                 if (lexical.established !== "lexical") {
-                    out.push(lexical);
+                    out.push(writtenAt(lexical, writtenSeats, writtenSeats.written.includes("landing") ? "landing" : "entry"));
                     continue;
                 }
                 const folded = lexical.target;

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

@@ -0,0 +1,22 @@
+/**
+ * THE FUNCTION READING — whether a command's program word is a function of the text where a reader stands. A function is a
+ * binding of its name in the binding thread (`shell-read-bindings.ts`: defined by its head, unbound by an `unset`, visible
+ * and certain by the one ordered rule); this module asks that thread's {@link FunctionState} for the word the shell looks up
+ * first, and names what the answer means for the walk. The text's functions (`functions`) are only the CANDIDATE names: the
+ * ones its definition heads show, and the ones a literal `eval` text defines.
+ */
+import { type LexedWord } from "../../shell/lex.js";
+import { type FunctionState } from "./shell-read-bindings.js";
+/** Does a command name one of the text's `functions` where a reader stands: the word the shell looks up first — the program,
+ *  or the launcher in front of it (`command`, `nice`, … are words like any, and a function of their name runs instead) —
+ *  `named`: it is a function's name and defined there (bash looks functions up before builtins: it shadows a builtin of the
+ *  name); `maybe`: it may be one (the definition may not have run, the word is one the text computes, or an external
+ *  launcher stands in front of a program word that may be); `undefined`: it is not (`builtin` / `command` skip functions).
+ *  The whole word names a function (`x/f` included: a `/` tells a function from a path in no way). `stateOf`: what a
+ *  function of a name is there ({@link BindingTable.functionState}) — the binding thread's one rule; absent, any
+ *  definition may be the one (the question put before the walk, where no reader stands yet). */
+export type FunctionCall = "named" | "maybe";
+export declare function functionCallOf(argv: readonly LexedWord[], functions: ReadonlySet<string>, stateOf?: (name: string) => FunctionState): FunctionCall | undefined;
+/** The functions a literal `eval` text defines — the shell that runs it is this one, so they stand after it like any: names
+ *  the text's own definition heads do not show (a text the plan cannot read hands none; the names it makes unknown are all). */
+export declare function evalDefinedFunctions(argvs: readonly (readonly LexedWord[])[], depth?: number): string[];

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

@@ -0,0 +1,29 @@
+import { lexShell, literalTextOf } from "../../shell/lex.js";
+import { readProgramPosition } from "./bash-program-position.js";
+import { SPECIAL_BUILTINS, projectSegment } from "./shell-read-bindings.js";
+import { reentryText } from "./shell-reentry-text.js";
+export function functionCallOf(argv, functions, stateOf = () => "maybe") {
+    const pos = readProgramPosition(argv);
+    const headAt = pos.launchers[0]?.index ?? pos.program?.index;
+    if (headAt === undefined || functions.size === 0)
+        return undefined;
+    const stateOfWord = (w) => (w.pieces.some((p) => p.expansion !== undefined || p.literal === undefined) ? ([...functions].some((name) => stateOf(name) !== "absent") ? "maybe" : "absent") : functions.has(w.folded) ? stateOf(w.folded) : "absent");
+    const headWord = argv[headAt];
+    const head = stateOfWord(headWord);
+    if (head !== "absent")
+        return head === "defined" && !SPECIAL_BUILTINS.has(headWord.folded) ? "named" : "maybe";
+    if (pos.program === undefined || pos.launchers.length === 0 || pos.launchers.some((l) => l.name === "builtin" || l.name === "command"))
+        return undefined;
+    return stateOfWord(argv[pos.program.index]) === "absent" ? undefined : "maybe";
+}
+export function evalDefinedFunctions(argvs, depth = 0) {
+    return depth > 4 ? [] : argvs.flatMap((argv) => {
+        const pos = readProgramPosition(argv);
+        const words = pos.program?.basename === "eval" ? argv.slice(pos.program.index + 1).map((w) => literalTextOf(w.pieces)) : [];
+        const lexed = words.length > 0 && words.every((t) => t !== undefined) ? lexShell(reentryText("eval", words) ?? "") : undefined;
+        if (lexed === undefined || "parseFailure" in lexed)
+            return [];
+        const inner = lexed.segments.map((segment) => projectSegment(segment));
+        return [...inner.flatMap((p) => p.defines), ...evalDefinedFunctions(inner.map((p) => p.argv), depth + 1)];
+    });
+}

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

@@ -8,7 +8,8 @@
  *    of a candidate that could not be established), then containment over the canonical target alone. The
  *    deny judge is the boundary's own `denyMatch` closure (`readDenySeat`, read-deny.ts) — the same function
  *    object every read face mounts; nothing here compiles a pattern or re-derives a view set. The containment
- *    judge is `withinAnyRoot` over the roots the boundary declares.
+ *    judge is `withinAnyRoot` over the roots the boundary declares — a WRITE target's over the write roots, at the
+ *    seat it is written, under the write face in force ({@link judgeWrite}).
  *  · `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
@@ -22,6 +23,7 @@
 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 ContainmentFace } from "./containment-face.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"];
@@ -122,21 +124,27 @@ export interface ShellReadBoundary extends BashReadonlyRootBoundary {
     /** 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. */
+    /** The WRITE roots (canonical) — the task root and every additional working directory, never a read-only grant: where a
+     *  command's write targets must land ({@link judgeRead}'s write face: a target written outside them is an
+     *  `outside_roots` finding), and so where a mode that accepts file commands may place them. Absent ⇒ where a write may
+     *  land is unknown: a written target is `unestablishable` and nothing 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?: {
+    /** The WRITE face in force — the same seat the structured write tools read (the run's resolved write face, read once per
+     *  judgment where the boundary is built): `"open"` skips the write roots' containment for a finding, as it skips the
+     *  structured tools' root fence ({@link skipsRootsContainment}; absent ⇒ roots). Placement still reads the write roots:
+     *  a mode accepting file commands accepts them inside its own directories, whatever the face. */
+    readonly writeFace?: ContainmentFace;
+    /** The leg's ONE write judgment of an ABSOLUTE write target — the one a write tool's target meets (its spelling, its real
+     *  target and every hop of its symlink chain, under the leg's one exempt root), over the write-protection TABLE and the
+     *  deployment's guarded write rows (`ToolPolicy.writeGuardRows`, every policy of the leg's chain) together; `canonical` ⇔
+     *  the path is a key the station established (judged as a key, never as a spelling). `"protected"`: the table covers it —
+     *  the target is not placed and the verdict says so ({@link import("./shell-read-check.js").ShellReadVerdict.writeProtected});
+     *  `"guarded"`: a deployment row covers it — the target is not placed; `undefined`: nothing covers it. Read by the
+     *  station's write facts only. A judgment that throws fails the station's answer (the caller's fail-closed arm). */
+    readonly writeTargetJudge?: (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>;
+    }) => Promise<"protected" | "guarded" | undefined>;
 }
 /** 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
@@ -163,6 +171,11 @@ export interface EstablishedRead {
     readonly walked?: true;
     /** Why the candidate could not be established. */
     readonly cause?: string;
+    /** The candidate's spelling WAS placed and the environment could not resolve where it leads (the whole chain unanswered by
+     *  a resolver that declares itself authoritative, or a component it could not follow) — the reading's
+     *  `target_unresolved` fact, as opposed to a text the station cannot read (a rewritten word, an unsettled working
+     *  directory). Present only on an `unestablishable` read. */
+    readonly unresolved?: true;
     /** 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
@@ -235,16 +248,30 @@ export interface JudgedSegment {
 export interface JudgedPlan {
     readonly plan: ShellReadPlan;
     readonly segments: readonly JudgedSegment[];
-    /** {@link stationGuards} of the boundary the plan was judged against. */
+    /** {@link stationGuards} of the boundary the plan was judged against — what a READ finding folds by. */
     readonly guards: boolean;
+    /** {@link writeFaceGuards} of the same boundary — what a WRITE target's finding folds by. */
+    readonly writeGuards: boolean;
 }
 /**
  * Does the station GUARD anything for this boundary — a closed face (roots: containment is what it guards; an absent
  * face reads as roots, as {@link containmentOf} does), or a deny table with rows (`denyMatch` is present exactly then)?
  * Where it guards nothing (an open face, no deny row), a read it could not establish has nothing to be confirmed
- * against: no finding. The deny judgment itself is untouched (with no row there is nothing to hit).
+ * against: no finding. The deny judgment itself is untouched (with no row there is nothing to hit). The READ face's
+ * question only: a write target folds by {@link writeFaceGuards}.
  */
 export declare function stationGuards(boundary: Pick<ShellReadBoundary, "face" | "denyMatch">): boolean;
+/**
+ * Does the station guard anything on the WRITE face — the same shape for the write seats: the write face in force runs
+ * the roots-containment step ({@link skipsRootsContainment}, the structured write tools' reading; absent ⇒ roots), or
+ * the write deny table has rows. Where it guards nothing (an open write face, no write row), a write target the station
+ * could not establish has nothing to be confirmed against — as a structured write under that face is not fenced.
+ */
+export declare function writeFaceGuards(boundary: Pick<ShellReadBoundary, "writeFace" | "writeDenyMatch">): boolean;
+/** Does the station guard anything on EITHER face? What a finding about the text's own structure folds by — a text the
+ *  lexer could not read, a program it cannot name, program text it does not read, a working directory it lost, a text the
+ *  shell re-enters — since what such a text reads AND what it writes are both unknown. */
+export declare function anyFaceGuards(boundary: Pick<ShellReadBoundary, "face" | "denyMatch" | "writeFace" | "writeDenyMatch">): boolean;
 /** The command-level fold and the finding that produced it. `witness` is absent for `none`; for `declined`
  *  the segment that declined stands in for a candidate. */
 export interface ShellReadFold {
@@ -256,8 +283,10 @@ export interface ShellReadFold {
 }
 /**
  * Fold a judged plan to ONE finding by {@link SHELL_READ_FINDING_RANK}, over every segment and every nested
- * plan. Where the station guards nothing ({@link JudgedPlan.guards}) an `unestablishable` or `declined` finding is no
- * finding: there is nothing to confirm the read against. Two structural rules ride the fold:
+ * plan. Where the station guards nothing an `unestablishable` or `declined` finding is no finding: there is nothing to
+ * confirm it against. Which guard is asked is the face the finding is about — a read candidate's by the read face's
+ * ({@link JudgedPlan.guards}), a write target's by the write face's ({@link JudgedPlan.writeGuards}), and a finding about
+ * the text's own structure (no candidate stands in for it) by either ({@link anyFaceGuards}). Two structural rules ride the fold:
  *  · a plan the lexer refused (`unreadable`) is `unestablishable`, unconditionally — a quote-blind re-read
  *    yields more words, never zero, so an unreadable text is never "no candidates";
  *  · a SHELL re-entry segment (`sh -c S`, `eval S`, `env -S 'S'`, a launcher handing text to a shell) is at
@@ -289,7 +318,8 @@ export declare function deepestCommonDir(a: string, b: string): string | undefin
  * The ONE directory whose addition to the declared roots would answer every `outside_roots` finding of a
  * command — offered only when re-judging the same established reads with that root added leaves no
  * finding at all (MEASURED, not argued: a deny row or an unestablishable candidate beside the out-of-root
- * one leaves the ask standing whatever root is granted, and then nothing is offered). `exact` ⇒ the value
+ * one leaves the ask standing whatever root is granted, and then nothing is offered; so does a target written outside
+ * the WRITE roots, which no read root answers — a read grant grants no write). `exact` ⇒ the value
  * is the one path the command NAMED, offered verbatim, because the containing directory would hand out the
  * home or a root. A `..` spelling gets no offer: the folded and the kernel reading of it can disagree about
  * whether the target is back inside, which no replay of the text settles.