@sema-agent/core 7.55.0 → 7.57.0

package/dist/tools/fs/search.js

@@ -4,6 +4,7 @@ import { MAX_EXEC_OUTPUT_BYTES } from "../../core/exec-output-tail.js";
 import { anchorSpelling, hasBinaryExtension, isWinFormPath, pathFamilyOf } from "./safety.js";
 import { HomeViewUnreadError, homeViewsOf } from "./read-deny-home.js";
 import { createEntryDenyJudge } from "./dir-entries.js";
+import { compileFsGlob, fsGlobClass } from "./fs-glob.js";
 import { thrownText } from "../../core/thrown-value.js";
 const WALK_MAX_FILES = 5000;
 const WALK_MAX_DEPTH = 32;
@@ -78,32 +79,31 @@ export function splitGlobParam(glob) {
 export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-function globTokenToRegExp(token, anchored, glob = false, report) {
-    const charToRe = (ch) => ch === "*" ? "[^/]*" : ch === "?" ? "[^/]" : ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-    let re = "";
+export function compileGlobToken(token, anchored, glob = false, report) {
+    const unitOf = (ch) => (ch === "*" ? { kind: "star" } : ch === "?" ? { kind: "one" } : { kind: "text", text: ch });
+    const tokens = [];
     for (let i = 0; i < token.length; i++) {
         const c = token[i];
         if (c === "*") {
             if (token[i + 1] === "*") {
-                re += ".*";
+                tokens.push({ kind: "globstar" });
                 i++;
                 if (token[i + 1] === "/")
                     i++;
             }
             else
-                re += "[^/]*";
+                tokens.push({ kind: "star" });
         }
         else if (c === "?")
-            re += "[^/]";
+            tokens.push({ kind: "one" });
         else if (glob && c === "{") {
             const close = token.indexOf("}", i);
             if (close > i + 1) {
-                const alts = token.slice(i + 1, close).split(",").map((alt) => [...alt].map(charToRe).join(""));
-                re += `(?:${alts.join("|")})`;
+                tokens.push({ kind: "alt", alternatives: token.slice(i + 1, close).split(",").map((alt) => [...alt].map(unitOf)) });
                 i = close;
             }
             else {
-                re += "\\{";
+                tokens.push({ kind: "text", text: "{" });
                 if (report)
                     report.degraded = true;
             }
@@ -122,34 +122,28 @@ function globTokenToRegExp(token, anchored, glob = false, report) {
             let cls;
             if (close !== -1) {
                 const body = token.slice(bodyStart, close).replace(/[\\[\]]/g, "\\$&").replace(/\//g, "");
-                cls = `[${neg ? "^/" : ""}${body}]`;
-                try {
-                    new RegExp(cls);
-                }
-                catch {
-                    cls = undefined;
-                }
+                cls = fsGlobClass(`[${neg ? "^/" : ""}${body}]`);
             }
             if (cls !== undefined) {
-                re += cls;
+                tokens.push({ kind: "class", class: cls });
                 i = close;
             }
             else {
-                re += "\\[";
+                tokens.push({ kind: "text", text: "[" });
                 if (report)
                     report.degraded = true;
             }
         }
         else
-            re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+            tokens.push({ kind: "text", text: c });
     }
-    return new RegExp(`${anchored ? "^" : "(^|/)"}${re}$`);
+    return compileFsGlob(tokens, anchored ? "start" : "segment");
 }
 export function invalidGlobTokens(glob) {
     const bad = [];
     for (const token of splitGlobParam(glob)) {
         const report = { degraded: false };
-        globTokenToRegExp(normalizeGlobToken(token), globIsAnchored(token), true, report);
+        compileGlobToken(normalizeGlobToken(token), globIsAnchored(token), true, report);
         if (report.degraded)
             bad.push(token);
     }
@@ -187,7 +181,7 @@ export function gitignoreMatcher(content) {
         const anchored = pat.startsWith("/");
         if (anchored)
             pat = pat.replace(/^\/+/, "");
-        return { neg, dirOnly, anchored, re: globTokenToRegExp(pat, anchored), bare: pat };
+        return { neg, dirOnly, anchored, re: compileGlobToken(pat, anchored), bare: pat };
     });
     return (relRaw, isDir) => {
         const rel = relRaw.replace(/\\/g, "/");
@@ -834,7 +828,7 @@ export async function jsGrepDetailed(env, root, p, signal, guards, deny, denyOut
         return rel(abs);
     };
     if (p.glob) {
-        const globRes = splitGlobParam(p.glob).map((g) => globTokenToRegExp(normalizeGlobToken(g), globIsAnchored(g), true));
+        const globRes = splitGlobParam(p.glob).map((g) => compileGlobToken(normalizeGlobToken(g), globIsAnchored(g), true));
         if (globRes.length > 0)
             files = files.filter((f) => globRes.some((re) => re.test(rel(f).replace(/\\/g, "/"))));
     }
@@ -842,7 +836,7 @@ export async function jsGrepDetailed(env, root, p, signal, guards, deny, denyOut
     if (p.type) {
         const tg = TYPE_GLOBS[p.type.toLowerCase()];
         if (tg) {
-            const typeRe = globTokenToRegExp(tg, false, true);
+            const typeRe = compileGlobToken(tg, false, true);
             files = files.filter((f) => typeRe.test(basename(f)));
         }
         else {
@@ -1380,7 +1374,7 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
     }
     const pat = normalizeGlobToken(pattern);
     const anchored = globIsAnchored(pattern);
-    const re = globTokenToRegExp(pat, anchored, true);
+    const re = compileGlobToken(pat, anchored, true);
     const startPrefix = start.replace(/[\\/]+$/, "") + (start.includes("\\") ? "\\" : "/");
     const startRelPrefix = startPrefix.startsWith(rootPrefix) ? startPrefix.slice(rootPrefix.length) : startPrefix;
     const toStartRel = (p) => {
@@ -1396,7 +1390,7 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
     const prunable = anchored && !groupSpansSlash;
     const firstStarStar = patternSegs.findIndex((s) => s.includes("**"));
     const starStarIdx = firstStarStar === -1 ? Infinity : firstStarStar;
-    const segRes = prunable ? patternSegs.map((s) => globTokenToRegExp(s, true, true)) : [];
+    const segRes = prunable ? patternSegs.map((s) => compileGlobToken(s, true, true)) : [];
     const isLiteralSeg = (s) => s.length > 0 && !/[*?[{]/.test(s);
     const literalAt = prunable ? patternSegs.map((s) => (isLiteralSeg(s) ? s : undefined)) : [];
     const literalAfterStarStar = new Set(prunable ? patternSegs.filter((s, i) => i > starStarIdx && isLiteralSeg(s)) : []);

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

@@ -21,9 +21,46 @@ function mayOwnNextWord(row, tok) {
             return k === tok.length;
     return false;
 }
+class OperandBase {
+    base;
+    taken = [];
+    move(spec, value, settled, at) {
+        if (spec?.rebases !== true)
+            return;
+        if (!settled)
+            this.base = "unsettled";
+        else if (namesOwnPlace(value))
+            this.base = value;
+        else if (this.base !== "unsettled")
+            this.base = this.base === undefined ? value : joinSpelling(this.base, value);
+        if (typeof this.base === "string" && this.base !== "unsettled")
+            this.taken.push({ at, base: this.base });
+    }
+    of(r) {
+        if (this.base === undefined || namesOwnPlace(r.folded))
+            return r;
+        if (this.base === "unsettled" || r.expands !== false)
+            return { ...r, expands: "unresolvable" };
+        return { word: r.word, raw: r.raw, folded: joinSpelling(this.base, r.folded), expands: false };
+    }
+    covers(unsettled) {
+        const out = new Set();
+        for (const u of unsettled) {
+            if (namesOwnPlace(u.folded) || u.folded.split("/").includes(".."))
+                continue;
+            for (const t of this.taken)
+                if (t.at < u.at)
+                    out.add(t.base);
+        }
+        return [...out].map((b) => readOfText(b));
+    }
+}
+const namesOwnPlace = (spelled) => spelled.startsWith("/") || spelled.startsWith("~");
+const joinSpelling = (base, rel) => (base.endsWith("/") ? `${base}${rel}` : `${base}/${rel}`);
 const rootValue = (spec) => spec?.walks === true || spec?.delivers === "operands";
 class RootsGathered {
     positional = [];
+    opened = new Map();
     places = [];
     maybeValues = new Set();
     stdinOperands = 0;
@@ -50,16 +87,23 @@ class RootsGathered {
         if (this.maybeValues.has(r))
             this.slotOwned = true;
     }
-    operand(r, namesPath, stdin) {
+    operand(r, namesPath, stdin, opened = r) {
         if (stdin) {
             if (!this.maybeValues.has(r))
                 this.stdinOperands++;
         }
-        else if (namesPath)
+        else if (namesPath) {
             this.positional.push(r);
+            if (opened !== r)
+                this.opened.set(r, opened);
+        }
+    }
+    cover(place) {
+        this.places.push(bare(place, "traversal_root"));
     }
     restart() {
         this.positional.length = 0;
+        this.opened.clear();
         this.places.length = 0;
         this.stdinOperands = 0;
         this.slotOwned = false;
@@ -71,7 +115,7 @@ class RootsGathered {
         const reads = this.unsettled
             ? [...this.positional, ...(this.slotWord !== undefined ? [this.slotWord] : []), ...(walksCwdWithoutOperand(row) ? [readOfText(".")] : [])]
             : walksCwdWithoutOperand(row) && leftOver <= (this.slotOwned ? 1 : 0) ? [...this.positional, readOfText(".")] : [...this.positional];
-        return [...reads.map((r) => bare(r, "traversal_root")), ...this.places];
+        return [...reads.map((r) => bare(this.opened.get(r) ?? r, "traversal_root")), ...this.places];
     }
 }
 export const programTextSentence = (language) => `runs inline ${language} program text, which may open files this station does not read`;
@@ -178,6 +222,9 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
             pushAssignment(reads, toks[j].word, provenance);
     }
     const gathered = new RootsGathered();
+    let base = new OperandBase();
+    const valueAt = new Set();
+    const unsettledAt = [];
     let slotWord;
     const pastOperand = new Set();
     let globs = "expanded";
@@ -251,6 +298,8 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
             walkFrom = argvStart + 2 + sub.at;
             relocated = sub.relocated;
             gathered.restart();
+            base = new OperandBase();
+            unsettledAt.length = 0;
             walk(sub.row, walkFrom, toks.length, true);
         }
         else
@@ -268,10 +317,12 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
                 return;
             case "dash-word-operand":
                 pastOperand.add(j);
-                reads.push(bare(r, provenance));
+                reads.push(bare(base.of(r), provenance));
                 speculate(start, "whole");
                 return;
             case "value": {
+                base.move(e.spec, r.folded, e.consumed && r.expands === false, j);
+                valueAt.add(j);
                 if (!e.consumed) {
                     gathered.value(r, e, false);
                     if (r.expands !== "unresolvable")
@@ -299,19 +350,23 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
                     return;
                 }
                 {
+                    base.move(e.reading.spec, literalTildeSpelling(e.reading.attached), r.expands === false, j);
                     const named = roleReads(r, "option_value", literalTildeSpelling(e.reading.attached), e.reading.role, globs, ctx, pastOperand.has(j));
                     reads.push(...named);
                     gathered.attached(named, e.reading.spec);
                 }
                 return;
             case "operand": {
-                const role = e.dash === undefined ? (e.slot ?? e.role) : undefined;
-                const named = role !== undefined ? roleReads(r, provenance, r.folded, role, globs, ctx) : [bare(r, provenance)];
                 const inSlot = j === slotWord;
+                const o = inSlot || e.dash !== undefined ? r : base.of(r);
+                const role = e.dash === undefined ? (e.slot ?? e.role) : undefined;
+                const named = role !== undefined ? roleReads(o, provenance, o.folded, role, globs, ctx) : [bare(o, provenance)];
                 if (inSlot)
                     gathered.slot(r);
                 else
-                    gathered.operand(r, named.some((c) => c.denyOnly !== true), e.dash === "stdin");
+                    gathered.operand(r, named.some((c) => c.denyOnly !== true), e.dash === "stdin", o);
+                if (!inSlot && e.dash === undefined && r.expands !== false)
+                    unsettledAt.push({ at: j, folded: r.folded });
                 reads.push(...named);
                 speculate(start, r.word.assignment !== undefined ? "whole" : "containment");
                 const values = reads.length;
@@ -323,6 +378,11 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
         }
     }
     if (walkRow !== undefined && argv !== undefined && selectsContentsTraversal(walkRow, toks.slice(walkFrom).map((x) => x.folded))) {
+        for (const j of expanding)
+            if (j >= walkFrom && !valueAt.has(j))
+                unsettledAt.push({ at: j, folded: toks[j].folded });
+        for (const place of base.covers(unsettledAt))
+            gathered.cover(place);
         for (const root of gathered.roots(walkRow))
             reads.push(relocated ? { ...root, expands: "unresolvable" } : root);
     }
@@ -372,6 +432,9 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
     const slice = argReads.slice(first, last);
     const args = slice.map((r) => r.folded);
     const gathered = new RootsGathered();
+    const base = new OperandBase();
+    const valueAt = new Set();
+    const unsettledAt = [];
     let unexplained = false;
     const globs = valuesAreLiteral(row, args) ? "literal" : "expanded";
     noteDeliveredOperands(row, args, ctx);
@@ -391,9 +454,11 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                 break;
             case "dash-word-operand":
                 pastOperand.add(e.at);
-                reads.push(bare(slice[e.at], "operand"));
+                reads.push(bare(base.of(slice[e.at]), "operand"));
                 break;
             case "value": {
+                base.move(e.spec, t, e.consumed && slice[e.at].expands === false, e.at);
+                valueAt.add(e.at);
                 if (expanding.has(first + e.at))
                     break;
                 gathered.value(slice[e.at], e, opensPath(offer(e.at, t, e.role, "option_value", !e.consumed)));
@@ -409,6 +474,7 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                         reads.push(bare(slice[e.at], "option_value", payload));
                     break;
                 }
+                base.move(e.reading.spec, literalTildeSpelling(e.reading.attached), slice[e.at].expands === false, e.at);
                 gathered.attached(offer(e.at, literalTildeSpelling(e.reading.attached), e.reading.role, "option_value", pastOperand.has(e.at)), e.reading.spec);
                 break;
             case "operand": {
@@ -428,11 +494,17 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                     break;
                 }
                 let opens = true;
-                if (e.role !== undefined)
-                    opens = opensPath(offer(e.at, t, e.role, "operand"));
+                const o = base.of(slice[e.at]);
+                if (e.role !== undefined) {
+                    const named = roleReads(o, "operand", o.folded, e.role, globs, ctx);
+                    reads.push(...named);
+                    opens = opensPath(named);
+                }
                 else
-                    reads.push(bare(slice[e.at], "operand"));
-                gathered.operand(slice[e.at], opens, false);
+                    reads.push(bare(o, "operand"));
+                gathered.operand(slice[e.at], opens, false, o);
+                if (slice[e.at].expands !== false)
+                    unsettledAt.push({ at: e.at, folded: t });
                 if (row?.operands?.assignmentArguments !== "not-paths")
                     pushAssignment(reads, slice[e.at].word, "operand");
                 break;
@@ -444,6 +516,11 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                     reads[i] = { ...reads[i], speculative: "containment" };
     }
     if (row !== undefined && selectsContentsTraversal(row, args)) {
+        for (let k = 0; k < slice.length; k++)
+            if (expanding.has(first + k) && !valueAt.has(k))
+                unsettledAt.push({ at: k, folded: args[k] });
+        for (const place of base.covers(unsettledAt))
+            gathered.cover(place);
         for (const root of gathered.roots(row))
             reads.push(relocated ? { ...root, expands: "unresolvable" } : root);
     }

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

@@ -106,6 +106,37 @@ export declare const functionKey: (name: string) => string;
 /** What a function name is at a reader: `defined` — it certainly is one; `absent` — it certainly is not; `maybe` — a branch,
  *  a loop, a body that may not have run, a removal that may not have found it. */
 export type FunctionState = "defined" | "maybe" | "absent";
+/** The function names a segment exports to child shells — the `-f` function flag with export (`export` always exports;
+ *  `declare` / `typeset` need `-x`), its bare-name operands. A child `bash -c` inherits them as functions
+ *  ({@link inheritedExportedFunctions}); their definitions are text this reader does not hold, so a call to one shadows
+ *  the builtin of the name (#1628). */
+export declare function exportedFunctionNames(argv: readonly LexedWord[]): string[];
+/** A function the CHILD inherits through its ENVIRONMENT: bash exports a function as a `BASH_FUNC_<name>%%` variable
+ *  (older bashes `BASH_FUNC_<name>()`), and a child reading that variable from its environment defines `<name>` as a
+ *  function whose body the engine cannot read. Delivered on a child's env by `env BASH_FUNC_x%%=… cmd` (env's own
+ *  assignment grammar accepts the `%%` name the shell's does not). Each such assignment word of a segment names an
+ *  inherited function — the same law as {@link exportedFunctionNames}, a different delivery; a value the shell rewrites
+ *  (`env "BASH_FUNC_$n%%=…"`) names a function the text cannot settle and is not tracked (KL-1628-a). */
+export declare function envFunctionNames(argv: readonly LexedWord[]): string[];
+/** Whether the BODY of a function a child shell inherits is text the engine read: `read` — the text (or a shell above it)
+ *  defines the function it exports (`f(){ …; }; export -f f`, `declare -fx f`), so the body's segments are read where it
+ *  is defined; `unread` — delivered on an environment (`BASH_FUNC_f%%=…`, {@link envFunctionNames}), or exported with no
+ *  definition the text holds (one a `source` or an `eval` made): a body nobody read. */
+export type InheritedBody = "read" | "unread";
+/** The functions a text's child shells inherit, each with its {@link InheritedBody}: what the shell running the text
+ *  inherited; then each name the text exports — `read` where the text defines it, else what it was inherited as, else
+ *  `unread`; then each name it delivers on an environment, `unread` whatever else holds it. */
+export declare function inheritedFunctionsOf(segments: readonly {
+    readonly argv: readonly LexedWord[];
+    readonly defines: readonly string[];
+}[], inherited: ReadonlyMap<string, InheritedBody> | undefined): ReadonlyMap<string, InheritedBody>;
+/** What a child shell (`bash -c`) inherits from a parent that EXPORTED functions ({@link exportedFunctionNames}): each
+ *  such name is a `defined` function in the child — bash looks a function up before the builtin of its name, so
+ *  `declare X=…` run under an exported `declare` function is the FUNCTION (it binds nothing), not the declaration
+ *  builtin. Every other function key is `absent` (a child inherits only exported functions), every builtin enabled;
+ *  the child holds none of their bodies, so a call to one may change any name (`bound: "all"`). The existing binding
+ *  carrier ({@link PlanStart.names}), not a second table (#1628). */
+export declare function inheritedExportedFunctions(names: ReadonlyMap<string, InheritedBody>): InheritedFunctions;
 /** One binding a segment makes: a name and what it now holds (`unknown` = made unknown). `prefix`: a binding that may or
  *  may not take effect (a prefix assignment to a special builtin, which may or may not outlive its command; an `unset` of a
  *  function, which a read-only function refuses). `loopVar`: a `for` loop's variable, held through its body. */

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

@@ -46,6 +46,47 @@ const isFunctionKey = (name) => name.startsWith(FUNCTION_KEY_PREFIX);
 const FUNCTION_DEFINED = [{ spelled: "defined" }];
 const FUNCTION_ABSENT = [{ spelled: "absent" }];
 const isDefinedValue = (v) => v.spelled === "defined";
+const EXPORT_FUNCTION_BUILTINS = new Set(["export", "declare", "typeset"]);
+export function exportedFunctionNames(argv) {
+    const program = readProgramPosition(argv).program;
+    const prog = program?.basename;
+    if (program === undefined || prog === undefined || !EXPORT_FUNCTION_BUILTINS.has(prog))
+        return [];
+    const literal = (w) => w.expansions.length === 0;
+    const rest = argv.slice(program.index + 1);
+    const flags = new Set(rest.filter((w) => literal(w) && /^-[A-Za-z]+$/.test(w.folded)).flatMap((w) => [...w.folded.slice(1)]));
+    if (!flags.has("f") || !(prog === "export" || flags.has("x")))
+        return [];
+    return rest.filter((w) => literal(w) && w.assignment === undefined && /^[A-Za-z_][A-Za-z0-9_]*$/.test(w.folded)).map((w) => w.folded);
+}
+export function envFunctionNames(argv) {
+    const out = [];
+    for (const w of argv) {
+        if (w.expansions.length !== 0)
+            continue;
+        const m = /^BASH_FUNC_([A-Za-z_][A-Za-z0-9_]*)(?:%%|\(\))=/.exec(w.folded);
+        if (m !== null)
+            out.push(m[1]);
+    }
+    return out;
+}
+export function inheritedFunctionsOf(segments, inherited) {
+    const defined = new Set(segments.flatMap((s) => s.defines));
+    const out = new Map(inherited ?? []);
+    for (const s of segments)
+        for (const name of exportedFunctionNames(s.argv))
+            out.set(name, defined.has(name) ? "read" : out.get(name) ?? "unread");
+    for (const s of segments)
+        for (const name of envFunctionNames(s.argv))
+            out.set(name, "unread");
+    return out;
+}
+export function inheritedExportedFunctions(names) {
+    return {
+        start: (key) => (isFunctionKey(key) ? (names.has(key.slice(FUNCTION_KEY_PREFIX.length)) ? FUNCTION_DEFINED : FUNCTION_ABSENT) : BUILTIN_ENABLED),
+        bound: "all",
+    };
+}
 const ATTRIBUTE_KINDS = { integer: "integer", transformed: "transformed", frozen: "frozen" };
 const EVERY_ATTRIBUTE = Object.values(ATTRIBUTE_KINDS).map((kind) => ({ kind }));
 export function projectSegment(segment) {

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

@@ -20,6 +20,7 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { violationDetails } from "./safety.js";
 import { type ShellReadPlan } from "./shell-read-plan.js";
+import { type ReadLanding } from "./shell-read-identity.js";
 import { type HomeViewSource } from "./read-deny-home.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";
@@ -169,9 +170,18 @@ export type ShellReadAdmission = (toolName: string, toolCallId: string | undefin
     isError: true;
     details?: unknown;
 } | undefined>;
+/** Where the station's last non-refused judgment of a call found its reads land (`readLandingsOf`): the judgment its
+ *  admission holds for the call id — the one the spawn re-establishes — read without consuming it. `undefined` ⇒ the
+ *  station holds none (a refused judgment records nothing). Its readers take it right where the latest judgment is a
+ *  non-refused one of the bytes they hold: the park when the filed bytes are the judged ones, the resumed leg's execution
+ *  station after its belt. A judgment that settles after a newer one replaced it is what the spawn would re-establish too:
+ *  the spawn then refuses bytes the entry does not describe, and a row bound to it vetoes the resume wherever the two
+ *  commands' reads differ (fail-closed either way). */
+export type ShellReadLandings = (toolCallId: string) => readonly ReadLanding[] | undefined;
 export interface ShellReadStation {
     readonly check: ShellReadCheck;
     readonly admit: ShellReadAdmission;
+    readonly landings: ShellReadLandings;
 }
 export interface ShellReadStationOptions {
     readonly env: ExecutionEnv;

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

@@ -3,19 +3,20 @@ import { errorResult } from "../../core/tools.js";
 import { BASH_READONLY_CONFINEMENT_NOTE } from "./fs-shared.js";
 import { isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf, violationDetails, withinAnyRoot } from "./safety.js";
 import { checkedReadDenyHomes, fitMiddle, READ_DENY_SENTENCE_PART_MAX, readDenySentence } from "./read-deny.js";
-import { NOT_AUTO_ALLOWED, programPositionRefusalSentence, readProgramPosition } from "./bash-program-position.js";
+import { NOT_AUTO_ALLOWED, declinedProgramSentence } 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 { readLandingsOf } from "./shell-read-identity.js";
 import { declaredReadDenyHomes, homeViewsAt } from "./read-deny-home.js";
 import { anyOptionWord, programArgs } from "./shell-read-write-targets.js";
 import { shellReadFaceWords } from "./shell-read-face.js";
 import { passesUnasked } from "./shell-read-device.js";
 import { programRow, selectedOptions } from "./program-read-model.js";
+import { refusedByRemoval, SHELL_REMOVAL_COMMANDS } from "./removal-targets.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 };
@@ -26,7 +27,6 @@ function unestablishedDetails() {
 function findingDetails(finding, paths) {
     return finding === "unestablishable" || finding === "declined" || finding === "unanswered" ? unestablishedDetails() : containmentDetails(paths);
 }
-const REMOVAL_COMMANDS = new Set(["rm", "rmdir"]);
 const WRITES_BENEATH = {
     cp: () => true,
     mv: () => true,
@@ -74,15 +74,16 @@ function writesPlacedOf(judged, boundary) {
         if (UNPLACED_OPTIONS[verb]?.(programArgs(s.segment).map((w) => w.spelled)) === true)
             return false;
         const beneath = WRITES_BENEATH[verb]?.(s.segment) === true;
+        const removal = SHELL_REMOVAL_COMMANDS.includes(verb);
         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) || f.kind !== "none" || (f.containment !== "inside" && f.containment !== "open"))
                 return false;
-            if (beneath && denyRowAtOrBelow(f.read, boundary, !REMOVAL_COMMANDS.has(verb)))
+            if (beneath && denyRowAtOrBelow(f.read, boundary, !removal))
                 return false;
-            if (REMOVAL_COMMANDS.has(verb) && writeRoots.some((root) => withinAnyRoot([target], root)))
+            if (removal && !refusedByRemoval(f.read) && writeRoots.some((root) => withinAnyRoot([target], root)))
                 return false;
         }
         return true;
@@ -182,19 +183,6 @@ function shellCommandOf(args) {
     const command = args?.command;
     return typeof command === "string" ? command : undefined;
 }
-function declineSentence(segment) {
-    const lexed = lexShellText(segment.text);
-    if (!("reject" in lexed) && lexed.segments[0] !== undefined) {
-        const pos = readProgramPosition(argvOf(lexed.segments[0]));
-        if (pos.refusal !== undefined)
-            return programPositionRefusalSentence(pos.refusal);
-        if (pos.argvFromStdin) {
-            const runs = pos.program?.basename ?? "the program it runs";
-            return `"${segment.text.trim()}" hands ${runs} its operands on its standard input, which this station does not read ${NOT_AUTO_ALLOWED}`;
-        }
-    }
-    return `"${segment.text.trim()}" runs a program this station cannot name ${NOT_AUTO_ALLOWED}`;
-}
 const ACCOUNT_PART_MAX = READ_DENY_SENTENCE_PART_MAX;
 const CAUSE_SPELLING_MAX = 64;
 function fitCause(cause) {
@@ -236,7 +224,7 @@ function findingAccount(fold, boundary) {
                 return `the text given to ${reenteredPrograms(fold)} — as an argument, on standard input, or in the file it names — runs as shell text this station does not parse ${NOT_AUTO_ALLOWED}`;
             return `the command's text could not be read as shell, so where it ${verb} cannot be established ${NOT_AUTO_ALLOWED}`;
         case "declined":
-            return fold.declined !== undefined ? declineSentence(fold.declined) : `the station could not read which program runs ${NOT_AUTO_ALLOWED}`;
+            return fold.declined !== undefined ? declinedProgramSentence(fold.declined.text) : `the station could not read which program runs ${NOT_AUTO_ALLOWED}`;
         case "identity_changed":
             return `"${fitMiddle(w?.read.candidate.raw ?? "?", ACCOUNT_PART_MAX)}" resolves to "${fitMiddle(w?.read.target ?? "?", ACCOUNT_PART_MAX)}" now, not where it resolved when this call was judged`;
         case "deny_hit":
@@ -408,6 +396,7 @@ export function createShellReadStation(opts) {
     };
     const admissions = new Map();
     const remember = (toolCallId, a) => {
+        admissions.delete(toolCallId);
         if (admissions.size >= ADMISSION_MAX) {
             const oldest = admissions.keys().next().value;
             if (oldest !== undefined)
@@ -491,5 +480,9 @@ export function createShellReadStation(opts) {
         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 };
+    const landings = (toolCallId) => {
+        const a = admissions.get(toolCallId);
+        return a !== undefined ? readLandingsOf(a.established) : undefined;
+    };
+    return { check, admit, landings };
 }

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

@@ -9,7 +9,8 @@
  * establisher and the write guards are handed an {@link ObservedFilesystem}, never the environment, so a lookup they make
  * cannot escape the record.
  *
- * What is NOT a failure: a conclusive absence (`not_found`, `not_directory` — the answer is "nothing there") and an adapter
+ * What is NOT a failure: a conclusive absence (`not_found`, `not_directory`, `name_too_long` — the answer is "nothing there", or
+ * "nothing can be there": the program that opens such a name fails the same way) and an adapter
  * that has no filesystem surface (`not_supported` — its answer that there is no file face: a chain it answers so keeps the
  * lexical reading). Everything else is, and is recorded wherever it falls — a resolver that answered nothing at all in the
  * command included: a lookup that failed (`permission_denied`, `timeout`, `unknown`, a throw) is a resolver failing, whose
@@ -47,6 +48,9 @@ export interface ObservedEnvironment {
     /** Records that came from outside the door: the declared roots' own lookup and the home views a read could not be placed against. */
     adopt(records: readonly Incomplete[]): void;
 }
+/** The answers that say NOTHING IS THERE — no entry (`not_found`), nothing reachable under a non-directory (`not_directory`), a
+ *  name the filesystem cannot hold (`name_too_long`): the station's one reading of an absence, wherever a lookup is read. */
+export declare const isAbsence: (code: string) => boolean;
 /** The declared roots, canonicalized ONCE per establisher (through the same door), with what that lookup could not finish —
  *  merged into every establishment. `known`: the caller already holds them as canonical identities and they are used verbatim
  *  (re-resolving one that was since swapped for a link would substitute the link's target for the root that was approved). */

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

@@ -1,6 +1,7 @@
 import { canonicalPathIsAuthoritative } from "../../core/remote-env.js";
 const OBSERVED = Symbol("observedFilesystem");
-const CONCLUSIVE = new Set(["not_found", "not_directory", "not_supported"]);
+export const isAbsence = (code) => code === "not_found" || code === "not_directory" || code === "name_too_long";
+const conclusive = (code) => isAbsence(code) || code === "not_supported";
 export function canonicalRootsOnce(env, readRoots, known) {
     let once = known ? Promise.resolve({ roots: readRoots, incomplete: [] }) : undefined;
     return (signal) => (once ??= (async () => {
@@ -21,7 +22,7 @@ export function observeEnvironment(env) {
     const records = [];
     const note = (op, path, what, code) => void records.push({ op, detail: `"${path}" ${what} (${code})` });
     const watch = (op, path, what, ask) => new Promise((resolve) => resolve(ask())).then((r) => {
-        if (!r.ok && !CONCLUSIVE.has(r.error.code))
+        if (!r.ok && !conclusive(r.error.code))
             note(op, path, what, r.error.code);
         return r;
     }, (e) => {

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

@@ -43,6 +43,7 @@ import { type ObservedEnvironment } from "./shell-read-environment.js";
 import type { ShellReadPlan, ShellReadSegment } from "./shell-read-plan.js";
 import type { EstablishedRead, ShellReadBoundary } from "./shell-read-judge.js";
 import type { HomeViewSource } from "./read-deny-home.js";
+import { type FsGlob } from "./fs-glob.js";
 /**
  * How many directories one glob operand may enumerate, and how many names it may
  * match, before the leg gives up and answers `unestablishable`.
@@ -54,6 +55,20 @@ import type { HomeViewSource } from "./read-deny-home.js";
  */
 export declare const MAX_GLOB_DIRS = 256;
 export declare const MAX_GLOB_MATCHES = 8192;
+/**
+ * Compile ONE path segment of a shell glob into a whole-name matcher (the engine in `fs-glob.ts`), or `undefined` when the
+ * pattern uses a construct this matcher does not model (the caller then fails closed).
+ *
+ * Modelled: `*` (any run of non-separator characters), `?` (one), and bracket expressions with `!`/`^`
+ * negation, `a-z` ranges, and a literal `]` in first position. A POSIX class (`[[:alpha:]]`) is deliberately widened to
+ * "any one character" rather than refused — the lexer spells such a class, and one holding a quoted character, `?` —
+ * over-matching only adds candidates to verify, the safe direction here, while refusing would cost a usable idiom.
+ *
+ * NOT modelled: a backslash. Its escaping semantics interact with the lexer's quote folding (which has
+ * already rewritten the token), so a segment carrying one is failed closed rather than guessed at. The
+ * leading-dot rule is not a property of the pattern's own text and lives in {@link globSegmentMatches}.
+ */
+export declare function compileGlobSegment(pattern: string): FsGlob | undefined;
 /** The reads of one plan, established: per segment, in the plan's own order, with nested plans beside. */
 export interface EstablishedPlan {
     readonly plan: ShellReadPlan;