@sema-agent/core 7.51.2 → 7.52.0

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

@@ -2,12 +2,84 @@ import { literalTildeSpelling } from "../../shell/lex.js";
 import { expandsOf, partPattern, readOfText, rewritten } from "./shell-read-word.js";
 import { arithmeticSubstitutions } from "./shell-read-bindings.js";
 import { argvProgramOf, attachedOptionPayloads, isPathShapedToken } from "./bash-readonly-classifier.js";
-import { assignmentArgumentsAreNotPaths, evaluatesOperands, messageWords, moduleTailOf, objectPathsOf, opensNoOperand, programRow, programTextMayOpen, programTextOpensOf, readArgs, selectsContentsTraversal, slotValueCandidates, subcommandOf, valuesAreLiteral, walksCwdWithoutOperand, wordsReadBySomeImplementations, } from "./program-read-model.js";
+import { assignmentArgumentsAreNotPaths, deliversOperands, evaluatesOperands, messageWords, moduleTailOf, objectPathsOf, opensNoOperand, programRow, programTextMayOpen, programTextOpensOf, readArgs, readOptionSlot, selectsContentsTraversal, slotValueCandidates, subcommandOf, valuesAreLiteral, walksCwdWithoutOperand, wordsReadBySomeImplementations, } from "./program-read-model.js";
 export function pathSubcommandOf(row, args) {
     const sub = subcommandOf(row, args);
     return sub !== undefined && (sub.row.operands !== undefined || sub.row.traversal !== undefined) ? sub : undefined;
 }
+function slotOperandAt(row, words) {
+    for (const e of readArgs(row, words, { firstOperandSlot: true }))
+        if (e.kind === "operand" && e.slot !== undefined)
+            return e.at;
+    return undefined;
+}
+function mayOwnNextWord(row, tok) {
+    if (tok.startsWith("--"))
+        return !tok.includes("=");
+    for (let k = 2; k <= tok.length; k++)
+        if (readOptionSlot(row, tok.slice(0, k)).form === "unexplained")
+            return k === tok.length;
+    return false;
+}
+const rootValue = (spec) => spec?.walks === true || spec?.delivers === "operands";
+class RootsGathered {
+    positional = [];
+    places = [];
+    maybeValues = new Set();
+    stdinOperands = 0;
+    slotOwned = false;
+    unsettled = false;
+    slotWord;
+    value(r, e, namesPath) {
+        if (!e.consumed) {
+            this.maybeValues.add(r);
+            if (e.unsettled === true)
+                this.unsettled = true;
+        }
+        else if (namesPath && rootValue(e.spec))
+            this.positional.push(r);
+    }
+    attached(named, spec) {
+        if (rootValue(spec))
+            for (const c of named)
+                if (c.denyOnly !== true)
+                    this.places.push({ ...c, provenance: "traversal_root" });
+    }
+    slot(r) {
+        this.slotWord = r;
+        if (this.maybeValues.has(r))
+            this.slotOwned = true;
+    }
+    operand(r, namesPath, stdin) {
+        if (stdin) {
+            if (!this.maybeValues.has(r))
+                this.stdinOperands++;
+        }
+        else if (namesPath)
+            this.positional.push(r);
+    }
+    restart() {
+        this.positional.length = 0;
+        this.places.length = 0;
+        this.stdinOperands = 0;
+        this.slotOwned = false;
+        this.unsettled = false;
+        this.slotWord = undefined;
+    }
+    roots(row) {
+        const leftOver = this.positional.filter((r) => !this.maybeValues.has(r)).length + this.places.length + this.stdinOperands;
+        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];
+    }
+}
 export const programTextSentence = (language) => `runs inline ${language} program text, which may open files this station does not read`;
+const deliveredOperandsSentence = "takes the files it works on from a list file, whose names this station does not read";
+function noteDeliveredOperands(row, words, ctx) {
+    if (deliversOperands(row, words))
+        ctx.programText ??= deliveredOperandsSentence;
+}
 export function bare(r, provenance, spelled = r.folded) {
     const whole = spelled === r.folded;
     const pattern = whole ? r.pattern : partPattern(r, spelled);
@@ -105,9 +177,9 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
         else if (j > argvStart && !declaredNotPaths)
             pushAssignment(reads, toks[j].word, provenance);
     }
-    const positional = [];
+    const gathered = new RootsGathered();
+    let slotWord;
     const pastOperand = new Set();
-    let stdinOperand = false;
     let globs = "expanded";
     let walkRow = slotRow;
     let walkFrom = argvStart + 1;
@@ -159,8 +231,11 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
             const at = (k) => first + k;
             const words = toks.slice(first, last).map((r, k) => ({ folded: r.folded, skip: skipped(at(k)) }));
             globs = valuesAreLiteral(row, words.map((w) => w.folded)) ? "literal" : "expanded";
+            noteDeliveredOperands(row, words.map((w) => w.folded), ctx);
             const someRead = wordsReadBySomeImplementations(row, words.map((w) => w.folded));
-            for (const e of readArgs(row, words, { firstOperandSlot: slotKind })) {
+            const slotAt = slotOperandAt(row, words);
+            slotWord = slotAt === undefined ? undefined : at(slotAt);
+            for (const e of readArgs(row, words, { firstOperandSlot: slotKind, ownedValues: true })) {
                 const start = reads.length;
                 handleUnlistedEvent(e, at(e.at));
                 if (someRead.has(e.at))
@@ -175,8 +250,7 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
             walkRow = sub.row;
             walkFrom = argvStart + 2 + sub.at;
             relocated = sub.relocated;
-            positional.length = 0;
-            stdinOperand = false;
+            gathered.restart();
             walk(sub.row, walkFrom, toks.length, true);
         }
         else
@@ -199,6 +273,7 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
                 return;
             case "value": {
                 if (!e.consumed) {
+                    gathered.value(r, e, false);
                     if (r.expands !== "unresolvable")
                         reads.push(...roleReads(r, "option_value", r.folded, e.role, globs, ctx, true));
                     return;
@@ -207,8 +282,7 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
                     return;
                 const named = roleReads(r, "option_value", r.folded, e.role, globs, ctx);
                 reads.push(...named);
-                if (named.some((c) => c.denyOnly !== true))
-                    positional.push(r);
+                gathered.value(r, e, named.some((c) => c.denyOnly !== true));
                 return;
             }
             case "option":
@@ -224,15 +298,20 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
                     speculate(whole, "whole");
                     return;
                 }
-                reads.push(...roleReads(r, "option_value", literalTildeSpelling(e.reading.attached), e.reading.role, globs, ctx, pastOperand.has(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)];
-                if (e.dash === "stdin")
-                    stdinOperand = true;
-                else if (named.some((c) => c.denyOnly !== true))
-                    positional.push(r);
+                const inSlot = j === slotWord;
+                if (inSlot)
+                    gathered.slot(r);
+                else
+                    gathered.operand(r, named.some((c) => c.denyOnly !== true), e.dash === "stdin");
                 reads.push(...named);
                 speculate(start, r.word.assignment !== undefined ? "whole" : "containment");
                 const values = reads.length;
@@ -244,9 +323,8 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
         }
     }
     if (walkRow !== undefined && argv !== undefined && selectsContentsTraversal(walkRow, toks.slice(walkFrom).map((x) => x.folded))) {
-        const roots = positional.length > 0 ? positional : stdinOperand || !walksCwdWithoutOperand(walkRow) ? [] : [readOfText(".")];
-        for (const root of roots)
-            reads.push(relocated ? { ...bare(root, "traversal_root"), expands: "unresolvable" } : bare(root, "traversal_root"));
+        for (const root of gathered.roots(walkRow))
+            reads.push(relocated ? { ...root, expands: "unresolvable" } : root);
     }
     for (let j = from; j < toks.length; j++) {
         if (launcherIndices.has(j) || j === argvStart)
@@ -293,17 +371,19 @@ export function listedVerbCandidates(name, argReads, reads, ctx) {
 function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated) {
     const slice = argReads.slice(first, last);
     const args = slice.map((r) => r.folded);
-    const positional = [];
-    let stdinOperand = false;
+    const gathered = new RootsGathered();
+    let unexplained = false;
     const globs = valuesAreLiteral(row, args) ? "literal" : "expanded";
+    noteDeliveredOperands(row, args, ctx);
     const someRead = wordsReadBySomeImplementations(row, args);
     const pastOperand = new Set();
     const offer = (k, value, role, provenance, alsoOperand = false) => {
         const named = roleReads(slice[k], provenance, value, role, globs, ctx, alsoOperand);
         reads.push(...named);
-        return named.filter((c) => c.denyOnly !== true).length;
+        return named;
     };
-    for (const e of readArgs(row, args.map((folded, k) => ({ folded, skip: expanding.has(first + k) })), { firstOperandSlot: true })) {
+    const opensPath = (named) => named.some((c) => c.denyOnly !== true);
+    for (const e of readArgs(row, args.map((folded, k) => ({ folded, skip: expanding.has(first + k) })), { firstOperandSlot: true, ownedValues: true })) {
         const t = args[e.at];
         const start = reads.length;
         switch (e.kind) {
@@ -316,42 +396,43 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
             case "value": {
                 if (expanding.has(first + e.at))
                     break;
-                if (offer(e.at, t, e.role, "option_value", !e.consumed) > 0 && e.consumed)
-                    positional.push(slice[e.at]);
+                gathered.value(slice[e.at], e, opensPath(offer(e.at, t, e.role, "option_value", !e.consumed)));
                 break;
             }
             case "option":
                 if (e.reading === "no-value")
                     break;
                 if (e.reading === "speculative") {
+                    if (row === undefined || mayOwnNextWord(row, t))
+                        unexplained = true;
                     for (const payload of attachedOptionPayloads(t))
                         reads.push(bare(slice[e.at], "option_value", payload));
                     break;
                 }
-                offer(e.at, literalTildeSpelling(e.reading.attached), e.reading.role, "option_value", pastOperand.has(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": {
                 if (e.dash !== undefined) {
-                    if (e.slot !== undefined)
+                    if (e.slot !== undefined) {
+                        gathered.slot(slice[e.at]);
                         break;
-                    if (e.dash === "stdin")
-                        stdinOperand = true;
-                    else
-                        positional.push(slice[e.at]);
+                    }
+                    gathered.operand(slice[e.at], true, e.dash === "stdin");
                     break;
                 }
                 if (e.slot !== undefined) {
-                    if (offer(e.at, t, e.slot, "operand") > 0)
-                        positional.push(slice[e.at]);
+                    offer(e.at, t, e.slot, "operand");
+                    if (unexplained && e.slot.kind === "datum" && e.slot.form === "pattern")
+                        reads.push(bare(slice[e.at], "operand"));
+                    gathered.slot(slice[e.at]);
                     break;
                 }
-                let named = 1;
+                let opens = true;
                 if (e.role !== undefined)
-                    named = offer(e.at, t, e.role, "operand");
+                    opens = opensPath(offer(e.at, t, e.role, "operand"));
                 else
                     reads.push(bare(slice[e.at], "operand"));
-                if (named > 0)
-                    positional.push(slice[e.at]);
+                gathered.operand(slice[e.at], opens, false);
                 if (row?.operands?.assignmentArguments !== "not-paths")
                     pushAssignment(reads, slice[e.at].word, "operand");
                 break;
@@ -362,10 +443,9 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
                 if (reads[i].expands !== "unresolvable" && reads[i].denyOnly !== true)
                     reads[i] = { ...reads[i], speculative: "containment" };
     }
-    if (selectsContentsTraversal(row, args)) {
-        const roots = positional.length > 0 ? positional : stdinOperand || !walksCwdWithoutOperand(row) ? [] : [readOfText(".")];
-        for (const root of roots)
-            reads.push(relocated ? { ...bare(root, "traversal_root"), expands: "unresolvable" } : bare(root, "traversal_root"));
+    if (row !== undefined && selectsContentsTraversal(row, args)) {
+        for (const root of gathered.roots(row))
+            reads.push(relocated ? { ...root, expands: "unresolvable" } : root);
     }
 }
 export function subscriptOnly(word) {

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

@@ -4,8 +4,8 @@
  * decides WHICH words a command may read, `shell-read-write-targets.ts` which words it writes and at which seat;
  * this module decides WHERE each of them lands: the canonical
  * target of a spelling (symlinks resolved, a `..` applied the way the kernel applies it), the expansion of
- * a pattern (shell pathname semantics over `env.listDir`), the members of a traversal root (a bounded
- * recursive enumeration, dot files included, symlinked directories not followed), and the fail-closed arm
+ * a pattern (shell pathname semantics over `env.listDir`), what a traversal root is (one stat: a recursive read is
+ * judged by the root it names, its tree is never enumerated), and the fail-closed arm
  * for what could not be established. The judge (`shell-read-judge.ts`) is downstream; nothing here decides
  * allow/ask/deny.
  *
@@ -27,9 +27,9 @@
  *  4. NO MATCH is not a refusal: an unmatched pattern is handed to the command verbatim, so an empty
  *     expansion falls back to the literal spelling.
  *  5. What it cannot enumerate is `unestablishable`, never silently vouched: an unreadable directory, a
- *     pattern construct the matcher does not model, an expansion or a traversal past
+ *     pattern construct the matcher does not model, an expansion past
  *     {@link MAX_GLOB_DIRS} / {@link MAX_GLOB_MATCHES}.
- *  6. Cost is paid only by candidates that carry a metacharacter or a traversal, and only past the roots'
+ *  6. Cost is paid only by candidates that carry a metacharacter, and only past the roots'
  *     own spelling. Inside one enumerated directory only the SYMLINK entries need their own `realpath`.
  *
  * NOT cached deliberately: a per-run memo keyed on the spelling would answer from a snapshot of where a
@@ -44,7 +44,7 @@ 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";
 /**
- * How many directories one glob operand (or one traversal root) may enumerate, and how many names it may
+ * How many directories one glob operand may enumerate, and how many names it may
  * match, before the leg gives up and answers `unestablishable`.
  *
  * Sized so the everyday shapes never hit them: 256 directories covers a two-level pattern over a source

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

@@ -366,54 +366,11 @@ function establishLegOver(seen, readRoots) {
         }
         return { paths: frontier, canonical: canonicalOfMatch };
     };
-    const enumerateTraversal = async (rootCanonical, signal) => {
-        const found = [];
-        const listedDirs = new Set();
-        let root;
-        const stack = [{ dir: rootCanonical, spell: rootCanonical }];
-        const visited = new Set([rootCanonical]);
-        let dirsUsed = 0;
-        while (stack.length > 0) {
-            const { dir, spell } = stack.pop();
-            if (++dirsUsed > MAX_GLOB_DIRS)
-                return bounded(`"${rootCanonical}" holds more than ${MAX_GLOB_DIRS} directories, too many to enumerate to verify what a recursive read would open`);
-            const listed = await env.listDir(dir, signal);
-            if (!listed.ok) {
-                if (dir === rootCanonical && listed.error.code === "not_directory")
-                    root = "file";
-                if (listed.error.code === "not_directory" || listed.error.code === "not_found")
-                    continue;
-                return { unverifiable: `"${dir}" cannot be enumerated to verify what a recursive read would open (${listed.error.code})` };
-            }
-            listedDirs.add(dir);
-            if (dir === rootCanonical)
-                root = "directory";
-            for (const entry of listed.value) {
-                if (found.length >= MAX_GLOB_MATCHES)
-                    return bounded(`"${rootCanonical}" holds more than ${MAX_GLOB_MATCHES} entries, too many to enumerate to verify what a recursive read would open`);
-                const path = joinUnder(spell, entry.name);
-                const canonicalPath = joinUnder(dir, entry.name);
-                if (entry.kind === "symlink") {
-                    const canon = await env.canonicalPath(canonicalPath, signal);
-                    found.push({ path, ...(canon.ok ? { canonical: canon.value } : {}), symlink: true });
-                    if (canon.ok && !visited.has(canon.value)) {
-                        visited.add(canon.value);
-                        stack.push({ dir: canon.value, spell: path });
-                    }
-                    continue;
-                }
-                if (entry.kind === "directory") {
-                    if (!visited.has(canonicalPath)) {
-                        visited.add(canonicalPath);
-                        stack.push({ dir: canonicalPath, spell: path });
-                    }
-                    continue;
-                }
-                found.push({ path, canonical: canonicalPath, symlink: false });
-            }
-        }
-        const members = found.map(({ path, canonical, symlink }) => ({ path, ...(canonical !== undefined ? { canonical } : {}), node: (symlink && canonical !== undefined && listedDirs.has(canonical) ? "directory" : "file") }));
-        return { ...(root !== undefined ? { root } : {}), members };
+    const rootKindOf = async (rootCanonical, signal) => {
+        const info = await env.fileInfo(rootCanonical, signal);
+        if (!info.ok)
+            return undefined;
+        return info.value.kind === "directory" ? "directory" : info.value.kind === "file" ? "file" : undefined;
     };
     const entryOf = async (spelling, signal) => {
         const parts = spelling.split(SEP);
@@ -554,20 +511,13 @@ function establishLegOver(seen, readRoots) {
                 }
                 return reads;
             };
-            const land = async (read, spellings, folded) => {
+            const land = async (read) => {
                 if (!traversal || (read.established !== "canonical" && read.established !== "expansion") || read.target === undefined) {
                     out.push(read);
                     return;
                 }
-                const walkedTree = await enumerateTraversal(read.target, signal);
-                if ("unverifiable" in walkedTree) {
-                    out.push(read);
-                    out.push({ candidate, established: "unestablishable", spellings, origin: folded, cause: walkedTree.unverifiable });
-                    return;
-                }
-                out.push({ ...read, ...(walkedTree.root !== undefined ? { node: walkedTree.root } : {}) });
-                for (const m of walkedTree.members)
-                    out.push({ ...(await canonicalReadOf(candidate, m.path, [m.path], "expansion", folded, m.canonical, signal)), node: m.node, walked: true });
+                const node = await rootKindOf(read.target, signal);
+                out.push({ ...read, ...(node !== undefined ? { node } : {}) });
             };
             for (const [i, lexical] of lexicalReadsOf(candidate, boundary).entries()) {
                 if (lexical.established !== "lexical" || passesUnasked(candidate)) {
@@ -590,16 +540,16 @@ function establishLegOver(seen, readRoots) {
                             matched = true;
                             for (const t of expanded.paths)
                                 for (const read of await atSeats(t, [t, folded], "expansion", folded, expanded.canonical.get(t)))
-                                    await land(read, spellings, folded);
+                                    await land(read);
                         }
                     }
                     if (!matched || candidate.pattern !== undefined)
                         for (const read of await atSeats(walked, spellings, "canonical", undefined, undefined))
-                            await land(read, spellings, folded);
+                            await land(read);
                     continue;
                 }
                 for (const read of await atSeats(walked, spellings, "canonical", undefined, undefined))
-                    await land(read, spellings, folded);
+                    await land(read);
             }
         }
         return out;

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

@@ -40,14 +40,17 @@ function sameTargets(a, b) {
 }
 export async function withHomeViews(door, placed, established, signal) {
     const views = homeViewsOf(door.fs, placed, signal);
+    const unread = [];
     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] });
+                const home = landed ? await views.of(r.target, r.node === "file" ? { leaf: "file" } : undefined) : {};
+                if (home.unread !== undefined && !unread.includes(home.unread))
+                    unread.push(home.unread);
+                out.push(home.view === undefined || r.spellings.includes(home.view) ? r : { ...r, spellings: [...r.spellings, home.view] });
             }
             reads.set(segment, out);
         }
@@ -57,6 +60,6 @@ export async function withHomeViews(door, placed, established, signal) {
         return { ...p, reads, nested };
     };
     const withViews = await place(established);
-    door.adopt(views.unread.map((p) => ({ op: "fileIdentity", detail: `"${p}" cannot be identified against the home directories` })));
+    door.adopt(unread.map((p) => ({ op: "fileIdentity", detail: `"${p}" cannot be identified against the home directories` })));
     return withViews;
 }

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

@@ -96,7 +96,9 @@ export declare function dispositionOfCell(cell: ShellReadCell, context?: ShellRe
  *  · `unanswered` — the judge did not FINISH: it threw or timed out, the lookup it stands on was absent, or — recorded at the
  *    one door to the environment ({@link import("./shell-read-environment.js").Incomplete}) — an environment lookup gave no
  *    answer (an error that is no conclusive "not there"), the station stopped at its own bound (more directories or names than
- *    it enumerates, a link chain past its hop bound), or a home view could not be read. Any one makes the whole command
+ *    it enumerates, a link chain past its hop bound), or a home view could not be read — or a recursive read's root may hold a
+ *    home-anchored deny row that no home places (the environment declares none, or its placement did not answer), a home the
+ *    station cannot place either. Any one makes the whole command
  *    `unanswered`, whatever the other words found. Not a fact about the command but the state of the station, so it is not
  *    the `unestablishable` row's question (a text the station cannot place — a word the shell rewrites, a lost working
  *    directory, a pattern its matcher does not model). Absence is not
@@ -239,13 +241,9 @@ export interface EstablishedRead {
     readonly spellings: readonly string[];
     /** The pattern or traversal root an `expansion` came from, as folded. */
     readonly origin?: string;
-    /** 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. */
+    /** What the environment said the target IS, where a read asked — only a traversal root asks (it lists the root
+     *  once; 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;
     /** The candidate's spelling WAS placed and the environment could not resolve where it leads (the whole chain unanswered by
@@ -263,12 +261,12 @@ export interface EstablishedRead {
         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, `unanswered` a fact of the whole establishment —
- *  none is a candidate's). */
+/** What the judge found about ONE candidate. `kind` is one of the five candidate-level findings (`declined` is a segment fact,
+ *  `identity_changed` a re-establishment fact — neither is a candidate's; `unanswered` is a fact of the whole establishment, and
+ *  a candidate's where a recursive read's root may hold a deny row no home places, {@link judgeRead}). */
 export interface ReadFinding {
     readonly read: EstablishedRead;
-    readonly kind: Extract<ShellReadFinding, "deny_hit" | "outside_roots" | "unestablishable" | "none">;
+    readonly kind: Extract<ShellReadFinding, "deny_hit" | "outside_roots" | "unestablishable" | "unanswered" | "none">;
     /** 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;
@@ -379,10 +377,10 @@ export interface ShellReadFold {
  *    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
  *    least `unestablishable` — what runs is text the shell parses, not this plan — and its nested plan may
- *    only RAISE that to `deny_hit`: the nested text's deny hits count (a refusal is a refusal whatever runs
- *    it), its containment and its silence do not (an inner `cat inside.txt` vouches nothing about the
- *    outer text). A substitution body (`$(…)`, a backtick, `<(…)`) is nested WITHOUT re-entry and folds
- *    in full.
+ *    only RAISE that: the nested text's deny-relation answers count — a deny hit (a refusal is a refusal whatever
+ *    runs it) and a root that may hold a row no home places — its containment and its other silence do not (an inner
+ *    `cat inside.txt` vouches nothing about the outer text). A substitution body (`$(…)`, a backtick, `<(…)`) is nested
+ *    WITHOUT re-entry and folds in full.
  */
 export declare function foldShellReadFindings(judged: JudgedPlan): ShellReadFold;
 /** Judge every established read of a plan, in place. `establish` runs per segment so a caller can bound it. */

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

@@ -46,14 +46,28 @@ export function judgeRead(read, boundary) {
     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 = writeTarget ? boundary.writeDenyMatch(folded) : boundary.denyMatch(folded, walked);
+            const pattern = writeTarget ? boundary.writeDenyMatch(folded) : boundary.denyMatch(folded);
             if (pattern !== null)
                 return { read, kind: "deny_hit", deny: { pattern, matchedView: folded, ...(writeTarget ? { face: "write" } : {}) }, containment: writeTarget ? writeContainmentOf(read, boundary) : containmentOf(read, boundary) };
         }
+        if (!writeTarget && read.candidate.provenance === "traversal_root" && boundary.denyUnder !== undefined) {
+            let unplaced;
+            for (const view of views) {
+                const folded = normalizeAbsPathLexically(view);
+                const under = boundary.denyUnder(folded);
+                if (typeof under === "string")
+                    return { read, kind: "deny_hit", deny: { pattern: under, matchedView: folded }, containment: containmentOf(read, boundary) };
+                if (under !== null && typeof under === "object")
+                    unplaced ??= under.unplaced;
+            }
+            if (unplaced !== undefined) {
+                const cause = `the home-anchored deny row "${unplaced}" cannot be placed (no home directory is known for this environment), so "${read.target ?? read.candidate.spelled}" may hold it`;
+                return { read: { ...read, cause }, kind: "unanswered", containment: containmentOf(read, boundary) };
+            }
+        }
     }
     if (writeTarget)
         return judgeWrite(read, boundary);
@@ -119,7 +133,7 @@ export function foldShellReadFindings(judged) {
     let unestablished = false;
     let unplacedRead = false;
     const raise = (next) => {
-        if (next.finding === "unestablishable" || next.finding === "declined") {
+        if (next.finding === "unestablishable" || next.finding === "declined" || next.finding === "unanswered") {
             const face = next.witness?.read.candidate.face;
             if (!(next.witness === undefined ? judged.guards || judged.writeGuards : face === "write" ? judged.writeGuards : judged.guards))
                 return;
@@ -136,7 +150,7 @@ export function foldShellReadFindings(judged) {
             raise({ finding: "unestablishable" });
         for (const s of j.segments) {
             for (const f of s.findings) {
-                if (denyOnly && f.kind !== "deny_hit")
+                if (denyOnly && f.kind !== "deny_hit" && f.kind !== "unanswered")
                     continue;
                 if (f.kind !== "none")
                     raise({ finding: f.kind, witness: f });

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

@@ -119,8 +119,8 @@ export interface ShellReadSegment {
     /** `shell` = the program runs its argument as shell text; `argv` = its operands arrive on a stream;
      *  `interpreter` = it runs an inline program in a language this parser does not read (a shape fact only). */
     readonly reentry?: "shell" | "argv" | "interpreter";
-    /** Program text the station READS as a rule (a `sed` script names the files it opens) but could not read here —
-     *  supplied from a file, or not parseable to its end. What such a segment reads is then not established. */
+    /** Why what this segment reads is not established, as a sentence: program text the station could not read (a script supplied
+     *  from a file, text not parseable to its end, a program on standard input) or the list file the operands come from. */
     readonly unreadProgramText?: string;
     readonly declines: readonly ShellScanDecline[];
     readonly reads: readonly ReadCandidate[];

package/dist/tools/web.js

@@ -6,7 +6,7 @@ import { egressThrownText } from "../core/untrusted-egress.js";
 import { isPrivateHost } from "../core/runner/image.js";
 import { DEFAULT_CHARS_PER_TOKEN } from "../internal/harness.js";
 import { binaryMagicFormat } from "./fs/safety.js";
-import { pdfMagicMatches } from "./fs/pdf.js";
+import { pdfMagicMatches } from "../core/image-admission.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
 import { thrownText } from "../core/thrown-value.js";
 const MAX_REDIRECTS = 10;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.51.2",
+  "version": "7.52.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -46,6 +46,9 @@
   "engines": {
     "node": ">=20.18.1"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.build.json --emitDeclarationOnly --removeComments false",
     "typecheck": "tsc --noEmit && echo \"typecheck OK (tsc --noEmit clean)\"",
@@ -78,8 +81,14 @@
     "gate:error-surface": "node scripts/verify-error-surface.mjs",
     "gate:criteria": "node scripts/criteria-lint.mjs",
     "gate:reminder-literal": "node scripts/verify-reminder-literal.mjs",
+    "gate:catalog-literal": "node scripts/verify-catalog-literal.mjs",
+    "gate:sugar-single-site": "node scripts/verify-sugar-single-site.mjs",
     "gate:wire": "node scripts/wire-changes.mjs",
     "gate:layering": "node scripts/verify-layering.mjs",
+    "gate:import-cycles": "node scripts/verify-import-cycles.mjs",
+    "gate:packages": "node scripts/verify-packages.mjs",
+    "gate:packages:pack": "node scripts/verify-packages.mjs --pack",
+    "build:packages": "node scripts/verify-packages.mjs --build",
     "gate:phase-api": "node scripts/verify-phase-api.mjs",
     "gate:closed-sets": "node scripts/verify-closed-sets.mjs",
     "gate:agent-returns": "node scripts/verify-agent-returns.mjs",
@@ -88,7 +97,10 @@
     "gate:tool-names": "node scripts/verify-tool-name-tables.mjs",
     "gate:name-readings": "node scripts/verify-name-readings.mjs",
     "gate:tool-docs": "node scripts/gen-tool-spec-fields.mjs --check",
+    "gate:prompt-docs": "node scripts/gen-prompt-docs.mjs --check",
+    "gen:prompt-docs": "node scripts/gen-prompt-docs.mjs",
     "gate:backlog-ledger": "node scripts/verify-backlog-ledger.mjs",
+    "gate:changelog-coverage": "node scripts/verify-changelog-coverage.mjs",
     "gate:child-clamp-seats": "node scripts/verify-child-clamp-seats.mjs",
     "gate:spawn-sites": "node scripts/verify-spawn-sites.mjs",
     "gate:point-free-callbacks": "node scripts/verify-point-free-callbacks.mjs",