@sema-agent/core 7.44.0 → 7.46.0

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

@@ -7,8 +7,9 @@ import { bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { planShellReads } from "./shell-read-plan.js";
 import { createShellReadEstablisher, establishShellReadsLexically } from "./shell-read-establish.js";
 import { declaredReadDenyHomes, homeViewsAt } from "./read-deny-home.js";
-import { programArgs, spellsOption } from "./shell-read-write-targets.js";
-import { allFindings, decideShellRead, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, } from "./shell-read-judge.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 { seatOf } from "../../core/tool-name-readings.js";
 import { normalizeReadRootCandidate } from "../../core/read-root-candidate.js";
 import { argvOf, lexShellText } from "../../shell/lex.js";
@@ -25,14 +26,14 @@ const REMOVAL_COMMANDS = new Set(["rm", "rmdir"]);
 const WRITES_BENEATH = {
     cp: () => true,
     mv: () => true,
-    rm: (s) => s.argv.some((w) => spellsOption(w.folded, "recursive", "[rR]")),
+    rm: (s) => selectedOptions(programRow("rm"), programArgs(s).map((w) => w.spelled)).some((o) => o.selects === "traversal"),
 };
 const isPattern = (f) => f.read.candidate.expands !== false && f.read.candidate.expands !== "unresolvable";
 const RESHAPES_TREE = new Set(["mv"]);
 const anyOptionWord = (words) => words.some((w) => w.startsWith("-"));
 const UNPLACED_OPTIONS = {
-    rmdir: (ws) => ws.some((w) => spellsOption(w, "parents", "p")),
-    sed: (ws) => ws.some((w) => spellsOption(w, "file", "f")),
+    rmdir: (ws) => selectedOptions(programRow("rmdir"), ws).some((o) => o.effect === "writes"),
+    sed: (ws) => selectedOptions(programRow("sed"), ws).some((o) => o.value?.kind === "program-file"),
     cp: anyOptionWord,
     mv: anyOptionWord,
 };
@@ -205,7 +206,7 @@ const CAUSE_SPELLING_MAX = 64;
 function fitCause(cause) {
     return cause.replace(/^"([^"]*)"/, (_m, spelling) => `"${fitMiddle(spelling, CAUSE_SPELLING_MAX)}"`);
 }
-function findingAccount(fold, roots) {
+function findingAccount(fold, roots, face) {
     const allowed = fitMiddle(roots.length > 0 ? roots.join(", ") : "(none)", ACCOUNT_PART_MAX);
     const w = fold.witness;
     switch (fold.finding) {
@@ -213,7 +214,7 @@ function findingAccount(fold, roots) {
             return `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 (w?.read.cause !== undefined)
-                return `where this command reads could not be established: ${fitCause(w.read.cause)}, so it cannot be confirmed 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 ${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)
@@ -242,7 +243,7 @@ function outsidePathsOf(judged) {
     }
     return out;
 }
-function refusalOf(tool, fold, roots, paths) {
+function refusalOf(tool, fold, roots, paths, face) {
     const w = fold.witness;
     if (fold.finding === "deny_hit" && w?.deny !== undefined) {
         const target = w.read.target ?? w.deny.matchedView;
@@ -251,14 +252,16 @@ function refusalOf(tool, fold, roots, paths) {
         const sentence = `Error (${tool}): ${core} ${write ? WRITE_DENY_REFUSAL_NOTE : DENY_REFUSAL_NOTE}`;
         return { sentence, ...(write ? {} : { details: violationDetails({ code: "read_path_denied", message: sentence, target, pattern: w.deny.pattern }) }) };
     }
-    const account = findingAccount(fold, roots);
+    const account = findingAccount(fold, roots, face);
     const sentence = `Error (${tool}): ${account}. ${BASH_READONLY_CONFINEMENT_NOTE}`;
     return { sentence, details: findingDetails(fold.finding, paths) };
 }
 const WRITE_DENY_REFUSAL_NOTE = "The boundary judges this command's write targets — its output redirections and the operands of mkdir, touch, rm, " +
     "rmdir, mv, cp, tee and an in-place sed — against the write deny list; a denied write is refused here rather than escalated.";
-const DENY_REFUSAL_NOTE = "The read boundary judges this command's written spelling and, where a filesystem can be consulted, the " +
-    "paths it would actually read; a deny-listed read is refused here rather than escalated.";
+const DENY_REFUSAL_NOTE = "The read boundary judges the paths this command names — as written and, where a filesystem can be consulted, where " +
+    "they resolve and what a pattern among them matches — and refuses a deny-listed one here rather than escalating it; " +
+    "a file the command reaches without naming it is judged only where a segment deny row (built in, or the deployment's " +
+    "own pattern) reaches into the tree a recursive read walks.";
 function verdictOf(tool, seat, fold, judged, boundary) {
     const disposition = decideShellRead(fold.finding, seat);
     if (disposition === "vouch")
@@ -266,7 +269,7 @@ function verdictOf(tool, seat, fold, judged, boundary) {
     const paths = outsidePathsOf(judged);
     const unestablished = fold.unestablished === true ? { unestablished: true } : {};
     if (disposition === "refuse") {
-        const r = refusalOf(tool, fold, boundary.roots, paths);
+        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 grant = fold.finding === "outside_roots" ? readRootGrantCandidateOf(judged, boundary) : undefined;
@@ -275,7 +278,7 @@ function verdictOf(tool, seat, fold, judged, boundary) {
         disposition,
         finding: fold.finding,
         ...unestablished,
-        sentence: findingAccount(fold, boundary.roots),
+        sentence: findingAccount(fold, boundary.roots, boundary.face),
         ...(disposition === "mandated" && containment ? { details: findingDetails(fold.finding, paths) } : {}),
         ...(grant !== undefined ? { readRootCandidate: { dir: grant.dir, ...(grant.covers !== undefined ? { covers: grant.covers } : {}), clearsThisAsk: true } } : {}),
     };
@@ -286,7 +289,7 @@ function declarationsOf(boundary, readers) {
 function judgePlan(plan, established, boundary) {
     return judgeEstablishedPlan(plan, established.reads, boundary, (n) => {
         const nested = established.nested.get(n);
-        return nested === undefined ? { plan: n, segments: [] } : judgePlan(n, nested, boundary);
+        return nested === undefined ? { plan: n, segments: [], guards: stationGuards(boundary) } : judgePlan(n, nested, boundary);
     });
 }
 async function applyAlsoInside(judged, boundary) {
@@ -304,6 +307,7 @@ async function applyAlsoInside(judged, boundary) {
         return judged;
     const rewrite = (j) => ({
         plan: j.plan,
+        guards: j.guards,
         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)),
@@ -386,7 +390,11 @@ export function createShellReadStation(opts) {
         },
         unanswered(call, cause) {
             const toolName = call.toolName;
-            const seat = opts.seatOf(memberOf(call) ?? toolName);
+            const member = memberOf(call) ?? toolName;
+            const seat = opts.seatOf(member);
+            const boundary = opts.boundaryOf(member, undefined);
+            if (boundary === undefined || !(stationGuards(boundary) || boundary.writeDenyMatch !== undefined))
+                return { disposition: "vouch", finding: "none" };
             const fold = { finding: "unestablishable" };
             const disposition = decideShellRead("unestablishable", seat);
             const account = `${cause}, so where this command reads could not be established ${NOT_AUTO_ALLOWED}`;

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

@@ -132,6 +132,45 @@ function lexicalReadsOf(candidate, boundary) {
     }
     return out;
 }
+function writtenByText(plan, boundary) {
+    const targets = new Set();
+    const speculativeSeen = new Set();
+    let unplaced = false;
+    const walk = (p) => {
+        for (const s of p.segments) {
+            for (const c of s.reads) {
+                if (c.speculative === undefined || c.expands !== false || c.bases === "unmodelled")
+                    continue;
+                for (const r of lexicalReadsOf(c, boundary)) {
+                    if (r.target === undefined)
+                        continue;
+                    const t = normalizeAbsPathLexically(r.target);
+                    if (speculativeSeen.has(t))
+                        targets.add(t);
+                    speculativeSeen.add(t);
+                }
+            }
+            for (const j of judgedCandidatesOf(s)) {
+                if (j.candidate.face !== "write" || j.onlyIfExists !== undefined)
+                    continue;
+                if (j.candidate.expands !== false || j.candidate.bases === "unmodelled") {
+                    unplaced = true;
+                    continue;
+                }
+                for (const r of lexicalReadsOf(j.candidate, boundary)) {
+                    if (r.target === undefined)
+                        unplaced = true;
+                    else
+                        targets.add(normalizeAbsPathLexically(r.target));
+                }
+            }
+            for (const n of s.nested)
+                walk(n);
+        }
+    };
+    walk(plan);
+    return { targets, unplaced };
+}
 function unfollowedBackupReads(j, boundary, cause) {
     const spellings = sedBackupNames(j.followed.operand.spelled, j.followed.suffix).flatMap((name) => lexicalReadsOf({ ...j.candidate, spelled: name }, boundary).flatMap((r) => [...(r.target !== undefined ? [r.target] : []), ...r.spellings]));
     return [{ candidate: j.candidate, established: "unestablishable", spellings: [...new Set(spellings)], cause }];
@@ -443,9 +482,44 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         }
         return out;
     };
-    const establishSegment = async (segment, boundary, roots, signal) => {
+    const confirmedMissing = async (candidate, boundary, signal) => {
+        if (candidate.expands !== false)
+            return false;
+        const reads = lexicalReadsOf(candidate, boundary);
+        if (reads.length === 0)
+            return false;
+        for (const r of reads) {
+            if (r.established !== "lexical" || r.target === undefined)
+                return false;
+            const real = await resolve(r.target, signal);
+            if (real === undefined || real.exact || real.missing !== true)
+                return false;
+        }
+        return true;
+    };
+    const establishSegment = async (segment, boundary, roots, written, signal) => {
         const out = [];
-        for (const judged of judgedCandidatesOf(segment)) {
+        const missing = new Map();
+        for (const listed of judgedCandidatesOf(segment)) {
+            let judged = listed;
+            const speculative = judged.candidate.speculative;
+            if (speculative !== undefined && !written.unplaced) {
+                const c = judged.candidate;
+                if (!missing.has(c))
+                    missing.set(c, (await confirmedMissing(c, boundary, signal)) && !lexicalReadsOf(c, boundary).some((r) => r.target !== undefined && written.targets.has(normalizeAbsPathLexically(r.target))));
+                if (missing.get(c) === true) {
+                    if (speculative === "whole")
+                        continue;
+                    judged = { ...judged, candidate: { ...c, denyOnly: true } };
+                }
+            }
+            const decides = judged.onlyIfExists;
+            if (decides !== undefined) {
+                if (!missing.has(decides))
+                    missing.set(decides, await confirmedMissing(decides, boundary, signal));
+                if (missing.get(decides) === true)
+                    continue;
+            }
             if (judged.followed !== undefined) {
                 out.push(...(await followedBackupReads({ ...judged, followed: judged.followed }, boundary, signal)));
                 continue;
@@ -518,13 +592,13 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         }
         return out;
     };
-    const establishPlan = async (plan, boundary, roots, signal) => {
+    const establishPlan = async (plan, boundary, roots, signal, written = writtenByText(plan, boundary)) => {
         const reads = new Map();
         const nested = new Map();
         for (const segment of plan.segments) {
-            reads.set(segment, await establishSegment(segment, boundary, roots, signal));
+            reads.set(segment, await establishSegment(segment, boundary, roots, written, signal));
             for (const n of segment.nested)
-                nested.set(n, await establishPlan(n, boundary, roots, signal));
+                nested.set(n, await establishPlan(n, boundary, roots, signal, written));
         }
         return { plan, reads, nested, roots };
     };

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

@@ -235,7 +235,16 @@ export interface JudgedSegment {
 export interface JudgedPlan {
     readonly plan: ShellReadPlan;
     readonly segments: readonly JudgedSegment[];
+    /** {@link stationGuards} of the boundary the plan was judged against. */
+    readonly guards: 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).
+ */
+export declare function stationGuards(boundary: Pick<ShellReadBoundary, "face" | "denyMatch">): 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 {
@@ -247,7 +256,8 @@ export interface ShellReadFold {
 }
 /**
  * Fold a judged plan to ONE finding by {@link SHELL_READ_FINDING_RANK}, over every segment and every nested
- * plan. Two structural rules ride the fold:
+ * 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:
  *  · 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

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

@@ -72,12 +72,18 @@ function containmentOf(read, boundary) {
         return "unknown";
     return withinAnyRoot(boundary.roots, read.target) ? "inside" : "outside";
 }
+export function stationGuards(boundary) {
+    return boundary.face !== "open" || boundary.denyMatch !== undefined;
+}
 export function foldShellReadFindings(judged) {
     let best = { finding: "none" };
     let unestablished = false;
     const raise = (next) => {
-        if (next.finding === "unestablishable" || next.finding === "declined")
+        if (next.finding === "unestablishable" || next.finding === "declined") {
+            if (!judged.guards)
+                return;
             unestablished = true;
+        }
         if (SHELL_READ_FINDING_RANK[next.finding] > SHELL_READ_FINDING_RANK[best.finding])
             best = next;
     };
@@ -118,6 +124,7 @@ export function judgeEstablishedPlan(plan, established, boundary, nestedOf) {
             findings: (established.get(segment) ?? []).map((r) => judgeRead(r, boundary)),
             nested: segment.nested.map(nestedOf),
         })),
+        guards: stationGuards(boundary),
     };
 }
 export function allFindings(judged) {
@@ -200,5 +207,6 @@ export function rejudge(judged, boundary) {
             findings: s.findings.map((f) => judgeRead(f.read, boundary)),
             nested: s.nested.map((n) => rejudge(n, boundary)),
         })),
+        guards: stationGuards(boundary),
     };
 }

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

@@ -10,8 +10,8 @@
  * (`shell-read-establish.ts`) and judgment are downstream; nothing here decides allow/ask/deny.
  *
  * Contract, in one sentence per rule:
- *  · a LISTED reader hands its positional operands and the declared option-value slots (the verb tables of
- *    `bash-readonly-classifier.ts`, read here through their exported readers, never copied);
+ *  · a LISTED reader hands its positional operands and the declared option-value slots (the program read model's
+ *    rows, `program-read-model.ts`, walked by its one argv reader — this module only maps what it read to candidates);
  *  · an UNLISTED program hands every word of its argv (a program declared to open no path operand hands none);
  *  · an ASSIGNMENT's value is a candidate only in a text that runs a program able to open a file;
  *  · a LAUNCHER chain is peeled to its program and the chain's own words are never candidates; a launcher
@@ -21,7 +21,8 @@
  *    an argv re-entry (`xargs`) is a decline unless the target opens nothing it is handed;
  *  · an INTERPRETER's inline program is a shape fact (`reentry:"interpreter"`), never parsed, never a finding;
  *  · `<` targets are read candidates, `>`-family targets are write targets (tagged, not read), here-documents
- *    and here-strings are data (an UNQUOTED here-document body's substitutions are nested plans);
+ *    and here-strings are data (an UNQUOTED here-document body's substitutions are nested plans) — except to a shell
+ *    whose argv names no script: what arrives on its standard input is its script, a nested plan where the text spells it;
  *  · `$(…)`, backticks and `<(…)` bodies are nested plans; a word carrying one cannot be resolved from the text;
  *  · `cd` moves the base the LATER segments resolve against, as a candidate SET (`&&` proves a move, nothing
  *    else does); `pushd`/`popd` lose the base; a loop body with a base move is replayed per LITERAL beat and
@@ -29,9 +30,11 @@
  * Every ambiguity resolves toward MORE candidates, never fewer.
  */
 import { type LenientConnector, type LexedRedirect, type LexedWord } from "../../shell/lex.js";
+import { type BindingTable, type NameReader } from "./shell-read-bindings.js";
 import { type ShellScanDecline } from "./bash-program-position.js";
+import { type StdinText } from "./shell-reentry-text.js";
 /** WHY a word is a read candidate — a closed set, registered in `docs/CLOSED-SETS.md`. */
-export declare const READ_CANDIDATE_PROVENANCES: readonly ["operand", "option_value", "stdin_redirect", "write_redirect_target", "env_assignment", "unlisted_word", "traversal_root", "cd_target", "program_path", "script_slot_file"];
+export declare const READ_CANDIDATE_PROVENANCES: readonly ["operand", "option_value", "stdin_redirect", "write_redirect_target", "env_assignment", "unlisted_word", "traversal_root", "cd_target", "program_path", "script_slot_file", "mount_source", "object_path"];
 export type ReadCandidateProvenance = (typeof READ_CANDIDATE_PROVENANCES)[number];
 /** What the caller declares about the deployment: the listed readers and the boundary the bases start from. */
 export interface ShellReadDeclarations {
@@ -71,6 +74,12 @@ export interface ReadCandidate {
     /** A WRITE target of the command (a `>`-family redirection, a `sed` `w` file, the operands of a file-writing command):
      *  established like a read and judged against the deny table's WRITE face only — never for containment, never a read. */
     readonly face?: "write";
+    /** A reading the station takes where no row says the program opens the word — a word of a program with no row, a
+     *  role only another implementation reads — so the filesystem decides it: `containment` = the spelling always meets
+     *  the deny rows and is a containment candidate only where it exists; `whole` = a whole word (`NAME=value`, an option
+     *  word) that is a candidate at all only where it exists as a file. Where the filesystem confirms it is not there (and
+     *  nothing in the text writes or creates it), it is no read; a lexical establishment keeps it whole. */
+    readonly speculative?: "containment" | "whole";
 }
 /** How the shell reached one segment — what the base-candidate walk needs from the connectors. */
 export interface SegmentReach {
@@ -107,6 +116,9 @@ export interface ShellReadSegment {
     readonly declines: readonly ShellScanDecline[];
     readonly reads: readonly ReadCandidate[];
     readonly redirects: readonly ShellReadRedirect[];
+    /** A shell re-entry's standard input: each text that may arrive there. The shell runs it where its argv names no script
+     *  (`reentryText`); a text the command spells is then a nested plan. */
+    readonly stdin?: readonly StdinText[];
     readonly baseMove?: {
         readonly target: ReadCandidate | "home" | "previous" | "unmodelled";
     };
@@ -129,6 +141,18 @@ export interface ShellReadPlan {
         readonly strayRedirection: boolean;
     };
 }
-/** Plan every read candidate of one command (the contract is this module's header). `arithmetic` = the text is an
- *  `$((…))` body, which bash evaluates and never globs (no extended-glob floor). */
-export declare function planShellReads(command: string, decl: ShellReadDeclarations, depth?: number, homeRebound?: boolean, arithmetic?: boolean): ShellReadPlan;
+/** Where a nested text starts its names: a substitution body inherits the table of the segment it sits in (a subshell
+ *  holds every variable); a text the shell runs later or elsewhere (a code body, `eval`'s text, a child shell's `-c`)
+ *  starts from the text's own start — every name unknown, `HOME` the declared home unless the enclosing text binds it
+ *  anywhere. `boundAnywhere` answers for the enclosing texts. */
+interface PlanStart {
+    readonly initial: NameReader;
+    readonly boundAnywhere: (name: string) => boolean;
+    /** `HOME` may already hold something other than the declared home where the nested text starts. */
+    readonly homeTouched: boolean;
+    /** The attributes and name references in force where the nested text starts. */
+    readonly inherited: BindingTable["inherited"];
+}
+/** Plan every read candidate of one command (the contract is this module's header). */
+export declare function planShellReads(command: string, decl: ShellReadDeclarations, depth?: number, start?: PlanStart): ShellReadPlan;
+export {};