@sema-agent/core 7.17.4 → 7.17.5

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 7.17.5 — 2026-09-14
+
+### Narrowing — two reads the boundary walk vouched for without seeing: operands that arrive on a stream, and a directory change that did not happen (#766, #767; @server @cli @test)
+- **#766 — before.** A program that turns its STANDARD INPUT into another program's OPERANDS (`xargs`, GNU `parallel`) sat on the launcher table, so the walk unwrapped it to the program it runs and judged the operands that program was WRITTEN with — while its real argv arrives on a stream no token of the walk ever sees. Measured on the real load path (Runner prepare → NodeExecutionEnv → the gate) under the default doctrine AND `"classify"`: `echo <outside> | xargs cat`, `xargs cat <<< <outside>`, `xargs cat <<'EOF'…<outside>…EOF` and `echo .ssh/id_rsa | xargs cat` were asks=0 and EXECUTED — an out-of-root read and a deny-row read with no card at all — while the same read spelled `cat <outside>` is one mandated ask and the off tier's own disclosure promises exactly that ("a deny-listed or out-of-root read asks; the ask is mandated").
+- **#766 — after (the re-entry doctrine, one level down; no new rule).** A shell re-entry program (`sh -c …`, `eval …`) is refused whole because what it reads is decided by TEXT this walk never parses. An ARGV re-entry program is refused whole because what the program it runs reads is decided by a STREAM this walk never sees. Same class, same answer, one predicate (`argvReentryUnjudged`) read by both sites that can answer for it — the walk's launcher branch and the refused-command whitelist — so the two cannot say different things. The exemption is the walk's existing one rather than a second rule: a program DECLARED to read no path (`echo`, `true`, `basename`, …) does not open its words whatever stream they arrived on, so `ls | xargs echo` stays silent, and a bare `xargs` runs `echo` and is exempt by the same reading. The CHAIN is what is read, not the first word, and it is read to its END: `env xargs cat` and `timeout 5 xargs cat` are the same command as `xargs cat`, and a chain that ENDS on another launcher (`xargs env`, `xargs sudo`, `xargs timeout 5`) names no program at all — reading that as the default `echo` vouched for `echo cat <outside> | xargs env`, where `env` runs whatever the stream names, so the default-program exemption holds only when nothing follows the re-entry.
+- **#766 — behaviour, for consumers.** Under BOTH doctrines a command that feeds another program's argv from a stream now asks ONCE, mandated (a stored allow rule is disclosed as shadowed and does not clear it), unless the program it runs is one declared to read no path. **Under the default doctrine these ran with ZERO asks before**, so on a headless deployment — no approver wired — the card is a REFUSAL, not a prompt: `ls | xargs cat`, `git ls-files | xargs grep -l TODO`, `cat list.txt | xargs cat`, `ls | parallel cat`, `xargs cat < list.txt`, `env xargs cat`, `ls | xargs env`, `ls | xargs nice`. **Stated over-fire, pinned rather than described:** a stream-fed program reads MORE files than the ones written beside it, so `xargs cat <in-root file>` and `find . -name x | xargs wc -l` are mandated asks even though every path in the text is inside the roots — telling "stdin is empty here" from "stdin carries a path" is exactly the fact the text does not contain. The floor is unchanged and pinned: `ls | xargs echo`, `echo a | xargs echo`, `ls | xargs true`, and every command with no stream re-entry. The literal-operand form `xargs cat <outside>` was already one mandated ask and still is — its verdict now carries the refusal sentence rather than `outOfRootPaths`, so no "allow reading from …" directory grant is offered for it.
+- **#767 — before.** The walk threaded a `cd` as if it had SUCCEEDED. It is lexical and holds no filesystem, so it cannot know the directory exists; bash, when `cd` fails, leaves the process standing where it was and runs the rest of the command from there. Measured on the same path, both doctrines: `cd <missing>; cat ../secret` and `cd <missing> || cat ../secret` were asks=0 and EXECUTED — the walk placed `../secret` under `<root>/<missing>`, read it as the in-root `<root>/secret`, and vouched, while bash resolves it to `/secret`, outside every root. The `||` spelling runs the read ONLY when the change failed, i.e. against the one base the walk could not be using.
+- **#767 — after (a value becomes a set; no new rule, and no I/O).** The base a segment's relative operands resolve against is every directory the shell could be standing in, and any one of them outside the roots or on the deny table is the answer — the same fail-closed direction the walk already takes for an operand it cannot resolve at all. **`&&` is the one connector that closes the gap and it closes it exactly:** bash runs the right-hand side only after the left-hand side exited zero, so a segment reached from a `cd` through an unbroken run of `&&` is the shell's own proof the change happened, and the pre-move base is not a base that segment can be in. The verification is per CHANGE, not per command (`cd a && cd b; cat ../x` has its first change proven and its second not), and a run broken by anything else — `;`, `||`, `|`, a segment the walk dropped — gives the proof back. Connector information that is missing entirely is read as broken, which is the fail-closed side: the candidate set can only widen, never narrow. A candidate set that outgrows its cap is answered as an unresolvable directory change — the reading the walk already had for a `cd` it cannot track — so the seats keep one meaning of "the boundary did not judge this".
+- **#766 — what looks like a member and is not.** GNU `parallel` does not exec the program beside it with the stream's words appended: it BUILDS a command line and hands it to a shell, and given no command word at all it runs each input LINE as a command. Both halves of this class's exemption fail there — measured, `echo <program> <path> | parallel` runs the line and `parallel echo "…; <reader> <path>; echo"` runs the `;` pieces — so `parallel` left the launcher table for the SHELL re-entry class, where it is refused whole with no exemption and nothing looks through it. @server @cli: `parallel …` in any spelling is a mandated ask on both tiers.
+- **#767 — behaviour, for consumers.** Under BOTH doctrines a relative read placed after a directory change the shell did not prove now asks ONCE, mandated, when either reading leaves the roots or lands on the deny table: `cd <dir>; cat ../secret`, `cd <dir> || cat ../secret`, `cd <dir> && ls; cat ../secret`, `cd <dir> | cat ../x`. **Measured against a 55-command everyday corpus, no other cell moves** — `cd sub && npm test`, `cd pkg && cat package.json`, `cd sub && cat ../x`, `cd packages/foo && cat ../bar/package.json`, `cd sub && cd .. && ls`, `cd sub; ls` all keep their zero-ask verdict, because either both readings land inside or the `&&` run proves the change. A change whose target the walk cannot resolve at all (`cd -`, bare `cd`) is unchanged: the plain ask it always was.
+- **What the `&&` proof does NOT prove, each measured as a live vouch before it was closed.** `&&` and `||` associate leftward with equal precedence, so `x || cd <dir> && <read>` is `(x || cd <dir>) && <read>`: the `&&` proves the status of the whole left LIST, which when `x` succeeds is `x`'s status — the change never ran. A run that BEGINS after a `||` therefore proves nothing about its first segment, while a change at any later position of the same run is still proven. Every element of a PIPELINE runs in a subshell, so `echo hi | cd sub && <read>` leaves the parent standing exactly where it started however well the change went. A control word in front of the change hides or inverts the status the run reads (`! cd <dir>` exits zero precisely when the change FAILED). And an EXTERNAL `cd` — a path-prefixed spelling, or one behind a launcher — runs a program whose zero exit says nothing about this shell's directory at all, so the proof requires that the written word WAS the bare builtin. All three are now unprovable by construction, and the connector row the boundary reads carries the three facts (reached through `&&`, the crossing carried a `||`, the change can move the parent's base at all) rather than one boolean.
+- **Cost, measured back to back on one machine and bounded.** The candidate set makes the walk's work candidates × operands, so the two shapes that carry many of both got slower and are stated rather than left to be discovered: a 120-beat poll-loop body with one directory change goes from 1.8 ms to 25 ms, and eight unverifiable changes followed by 128 reads from 0.6 ms to 56 ms. Both are the WORKED versions — the first naive cut of the same code measured 1.4 s and 13.4 s respectively, and two changes bound it: the finding accumulators dedupe through sets instead of linear scans, and a per-(segment words, base) memo collapses the poll-loop face's replicated body. An ordinary command is unmeasurable either way (0.0 ms before and after), and a candidate set that outgrows its cap stops the walk instead of growing.
+- **Known residual, NOT closed here and filed separately:** a `sed` whose script is not the pure print form still carries its refusal as a SHAPE reason rather than a whole refusal, so under the default doctrine `sed -n '1r /etc/hosts' <file>` — and the `-e`, `-f` and no-`-n` spellings of the same script indirection — read a file outside the roots with zero asks. Closing it needs a decision about how much of the sed script grammar this walk admits, which is a design question rather than a site fix. **Also open, and stated rather than implied:** a spelling of the stdin-to-argv class this file has no name for (an aliased or renamed `xargs`) is judged as any other unlisted program — the name-table floor the shell re-entry class already records for itself; `CDPATH`, a `cd` through a symlink, and a directory change made by a shell function or a `DEBUG` trap are not modelled, all pre-existing and none touched here.
+- Pins: `test/backlog766-argv-reentry.test.ts` (the real load path, two doctrines × three feeds × three wrapped programs including a synthetic name on no table, the deny half, the mandated-ask lane under an exact covering rule and under an armed-but-not-matching lane, the off-tier disclosure held against the same run, `parallel` as the class's second member, the launcher chain to its end including an absolute-path re-entry inside one, GNU `parallel` as the near-member that is refused as shell re-entry instead, the negative controls and the stated over-fire; six mutation directions measured in the header), `test/backlog767-cd-unverifiable-base.test.ts` (both connectors that leave a change unproven, the deny regression, the mandated-ask lane, the `&&` negative controls including the two everyday monorepo spellings, the broken-run cases, per-change verification, the three shapes the `&&` proof does not cover, and the unresolvable-target regression; five mutation directions measured in the header, one of them the fail-closed check that a missing connector row costs only negative controls).
+
+### Narrowing — the full shell's read boundary is re-judged on the FILESYSTEM before the command runs (#768; test [7178] ③; @server @cli @test)
+- **Before.** The shell read boundary was LEXICAL containment: it judges the paths a command's TEXT may name, resolved against the declared roots, home and cwd. A symlink inside a root that points out of it therefore read as in-root — with `<root>/vendor` → an outside directory, `cat vendor/secret` was an in-root spelling, the boundary seat vouched it, ZERO asks were raised under every doctrine, and the outside bytes reached the model record. Measured on the real load path (Runner prepare → NodeExecutionEnv → the gate). The filesystem-resolving second pass that closes exactly this gap (`createCanonicalReadBoundary`) already existed and was wired on the `bash_readonly` face ALONE; the full face had no recheck at all, and no ticket tracked the asymmetry.
+- **After (a leg reused, not a rule added).** The full `bash` face runs the SAME pass on its own execute path — after the gate allowed the call and before anything spawns, ahead of the `run_in_background` branch (the flag changes WHEN a command runs, never WHERE it reads). **Its scope is the whole design: it re-judges only what the boundary SILENTLY vouched** — the literal locations the walk resolved and placed INSIDE the roots (`checkedPaths`), which raise no question at any tier and are therefore the one class where nobody was ever asked. A target that canonicalizes outside the roots is REFUSED, never asked: execution is past the approval step, so there is nothing left to escalate to. A call ABORTED before the spawn starts nothing — `spawnBackground` takes no signal of its own, so the cancellation is checked once, last, immediately before it.
+- **What the boundary ASKED about belongs to whoever answered it, and this leg does not revisit it.** A path the walk placed outside the roots (`outOfRootPaths`) is a mandated ask, and a person's yes on `cat <outside>/x` still runs. An unexpanded GLOB (`undecidedPaths`) is not judged here at all: it is an ask under every doctrine, so someone looked at "a pattern nobody could resolve" and said yes — expanding it afterwards and refusing what it matched would override that answer. Two consequences, both deliberate: the leg gives up the glob lane (`cat <link>/*`, and the same read piped anywhere, are NOT refused — disclosed, pinned, and the literal spelling of the identical read still is), and it loses the only refusals it had that needed no symlink at all (a dot pattern reaching `..`, an expansion past 256 directories / 8192 names, and a bracket construct the matcher cannot compile). The `bash_readonly` face keeps every one of those — its containment is load-bearing and it has no approval channel to have asked with.
+- **A refusal earned by one segment does not disable the check on another.** Within its scope the leg does not read the verdict's sentence, and it takes BOTH read faces (the compound walk and the bounded read-only poll loop): `cat <link>/secret | jq .` and `cat <link>/secret ; :` are refused compounds whose `checkedPaths` still carry the reader's real operand. Reading the sentence first — "the face refused, so it vouched nothing" — left the everyday shape (a read piped into any program the reader table does not list) outside the check entirely, and made the whole leg one appended `; :` away from silence.
+- **A path that does not EXIST is not a refusal.** The resolver takes the deepest existing ancestor and rejoins the missing tail, so `cat missing.txt` still gets the shell's own "No such file"; a chain that cannot be answered at all keeps the lexical verdict rather than manufacturing one.
+- **Behaviour, for consumers.** On the full shell, a command whose operands the read boundary resolved inside the roots now RETURNS AN ERROR instead of running when one of them resolves through a symlink to a directory outside the session's read roots. The result carries the read-only face's own card (`details.type` / `code`: `readonly_out_of_root`, `paths` = the canonical targets), now declared on the full shell's catalog row: ONE code for both faces, because the finding is one finding and a second word would make a consumer's count depend on which shell was mounted. Unchanged and pinned: an in-root symlink, a plain in-root read, a link into a declared additional READ root, a command with no path operand, every glob, the OPEN read face (containment is structurally satisfied there, so an out-of-roots operand rides `checkedPaths` as an ACCEPTED one and re-judging it would make "open" stricter than "roots"), a REMOTE execution env (no local `realpath`; the same locality split the read-only face's tool card already discloses), and every library-direct mount that declares no boundary. The `bash_readonly` face is byte-unchanged in verdict and wording — it already ran this leg.
+- **The over-fire, one shape and one premise.** The walk is program-blind, so a refused compound's `checkedPaths` include the argv WORDS of its non-reader segments (`make build` offers `<root>/build`, `npm test` offers `<root>/test`) and an option's separated value rides beside the operands (`grep -e vendor pkg.json` offers `<root>/vendor`); a read OF a link also counts as a read of its target (`readlink vendor`, `ls -d vendor`). Such a command is refused only where the workspace really holds an entry of that name that is a symlink OUT of the roots — **the condition is the point**: that same link already refuses every genuine read through it, so the deployment has to answer for it either way, and the answer is the same, DECLARE the target (`TaskSpec.additionalReadDirectories`), which the leg honours (measured: with the target declared, `make build` runs again). Telling an operand from an argv word needs a per-segment provenance fact the verdict does not carry, and inventing one here means a second hand-written parser beside the classifier's — the thing #753 exists to stop this file from growing. The refusal says the command NAMES the path, never that it reads it.
+- **Also fixed, found by exposing it.** The resolver stripped a trailing separator before rejoining the missing tail, which turns a canonical FILESYSTEM ROOT into the empty string — inside no root. A deployment declaring `/` among its read roots therefore had `ls -d /` refused, with an empty path in the refusal's own text. With nothing to rejoin, the canonical answer is now returned unchanged. Pre-existing and equally live on `bash_readonly`; it only became reachable in practice when the full face started calling the same resolver.
+- **Blind spots, disclosed and pinned as facts rather than assumed closed.** From the LEXICAL resolution that produces the candidates, all equally live on the read-only face: a `..` is collapsed in the TEXT before any link is resolved (`<link>/../x` is checked as `<root>/x`); a working-directory move is modelled as always succeeding (`cd nope || cat <link>/x` is checked under `<root>/nope/`); a command the GRAMMAR gate refuses whole yields no candidates at all. One is structural: a glob's ask can be retired by a stored allow rule or an auto tier, and this leg cannot tell that from a person's yes — `ToolExecuteContext` carries no record of how this call's gate settled, so both are left to the answerer. One is the ENVIRONMENT's: `ExecutionEnv.canonicalPath` takes a signal it is free to ignore (the built-in node env does), so a STALLED filesystem holds the recheck's await open and a cancellation cannot reach the spawn guard until it returns — a property of every caller of that resolver, filed against the adapter rather than raced around here.
+- **API (additive, optional).** `HandsToolkitOptions.shellReadBoundary` and `createBashTool`'s `taskOpts.readBoundary` take the deployment's read boundary — the SAME declaration the gate's two shell probe seats read, so one closure now feeds three consumers and the two answers about one path cannot disagree. ABSENT ⇒ the leg does not run and costs no I/O (no boundary declared, no "outside" to be outside of — the reading the seats already take), and it deliberately does NOT fall back to the write side's `additionalRoots`, which would stand up a second root table that excludes the read roots and refuse reads the deployment sanctions.
+- **Contract.** What this seat is and is not is now stated once, as `shell.read_boundary.friction_floor` on `bashReadBoundaryProbe`: the seat answers a question about TEXT; the containment for what a shell may reach is the `ExecutionEnv` the command runs in; the execute leg is the floor's last cell. Every other site links to it instead of restating it.
+- Pins: `test/backlog768-bash-canonical-recheck.test.ts` (the real load path on both doctrines: the leak itself across reading verbs, compounds, the pipe-into-an-unlisted-program and `; :` shapes, the bounded poll loop and the background leg, with the wire card asserted on the frame; the read-root, in-root-symlink, plain-read, everyday-lower-bound, open-face and no-boundary negatives; the glob arm's deliberate silence beside the literal spelling that still refuses; the answered-question arm (an approved out-of-root read runs); the stated over-fire WITH its declare-the-target control; the blind spots as facts; two cancellation windows with a positive control on the spy; the `bash_readonly` face's own wording; the operator note; and the single-construction-site pins — eight mutation directions measured in the header).
+
 ## 7.17.4 — 2026-09-14
 
 ### Narrowing — an option's ATTACHED payload is a word like any other: the boundary walk judges it (#763; the residual filed at 7.17.3; @server @cli @test)

package/dist/core/runner/prepare-hands-readface.js

@@ -1,6 +1,7 @@
 import { emitTrace } from "../trace.js";
 import { StubExecutionEnv } from "../stub-env.js";
 import { hasBackgroundShell } from "../background-shell.js";
+import { isRemoteExecutionEnv } from "../remote-env.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { bashReadBoundaryProbe, bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, inheritSessionReadFileState, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
 import { resolveKey, sha256 } from "../../tools/fs/safety.js";
@@ -293,6 +294,13 @@ export async function prepareHandsMount(input) {
                         sessionSeats.reanchor(sessionId, readFileState, ownCommittedTailEntryId);
                 }
                 : undefined;
+        const shellReadBoundary = () => ({
+            roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
+            ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+            ...(executionEnv.homeDir !== undefined ? { homeDir: executionEnv.homeDir } : {}),
+            denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
+            ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
+        });
         const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
             ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
             ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
@@ -306,6 +314,7 @@ export async function prepareHandsMount(input) {
             ...(input.onFileEdited !== undefined ? { onFileEdited: input.onFileEdited } : {}),
             includeShell: handsIncludeShell,
             readOnly: handsReadOnly,
+            shellReadBoundary,
             ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
             taskRegistry: defaultTaskRegistry,
             taskOwner: hostTaskId,
@@ -346,18 +355,11 @@ export async function prepareHandsMount(input) {
         if (!(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
             if (shellGate === "off") {
                 deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — the read boundary is ` +
-                    `still judged on every command (a deny-listed or out-of-root read asks; the ask is mandated), but no ` +
+                    `still judged on every command (a deny-listed or out-of-root read asks; the ask is mandated${isRemoteExecutionEnv(executionEnv) ? "" : "; a read that only leaves the roots after symlink resolution is refused before it runs"}), but no ` +
                     `residual shell-risk classifier is installed: writes, egress and unknown commands are adjudicated by ` +
                     `the ordinary policy/hook chain only. Set spec.shellGate to "classify" or "always" if this deployment ` +
                     `expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
             }
-            const shellReadBoundary = () => ({
-                roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
-                ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
-                ...(executionEnv.homeDir !== undefined ? { homeDir: executionEnv.homeDir } : {}),
-                denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
-                ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
-            });
             const installShellSeat = (name) => {
                 const tierBefore = irreversibilityTier.get(name);
                 const seatOwned = !egressTools.has(name) && tierBefore !== "always" && tierBefore !== "maybe";

package/dist/core/tool-catalog-entries.js

@@ -56,7 +56,7 @@ export const TOOL_CATALOG_ENTRIES = [
     },
     {
         id: "bash", name: "Bash", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"],
-        cards: ["bash", "bash_invalid_timeout"],
+        cards: ["bash", "readonly_out_of_root", "bash_invalid_timeout"],
         face: {
             family: "shell", effect: "write", contentOrigin: "execution", contract: c(FULL_SHELL_CONTRACT_ID),
             ruleFace: SHELL_RULE_FACE,

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -140,10 +140,22 @@ export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<
 export declare function carriesShellRedirection(text: string): boolean;
 /** What {@link splitShellCompoundSegments} produces: the connector-delimited segments, plus which of
  *  them a PIPE fed (the read-only classifier's stdin arm needs that distinction; a rule lane does not). */
+/** The connector bash ran a segment through — `"start"` for the first one. A closed set, because the read
+ *  boundary distinguishes all four: `&&` is the only one under which the previous segment is known to have
+ *  exited ZERO, `||` is the only one under which the previous segment may have been SKIPPED ENTIRELY, `|`
+ *  puts the segment in a subshell whose directory changes never reach the parent, and `;` is plain sequence. */
+export type ShellSegmentConnector = "start" | ";" | "&&" | "||" | "|";
 export interface ShellCompoundSegments {
     segments: string[];
-    /** Parallel to {@link segments}: was this segment preceded by `|` (rather than `;`/`&&`/`||`/nothing)? */
+    /** Parallel to {@link segments}: was this segment preceded by `|` (rather than `;`/`&&`/`||`/nothing)?
+     *  A VIEW of {@link connectors}, derived at the one place both are minted — two rows that could drift are
+     *  two rows that will. */
     pipeFed: boolean[];
+    /** Parallel to {@link segments}: the connector bash reached this segment through. Read by the read
+     *  boundary, where it is the difference between a directory change the shell itself proved happened and
+     *  one this walk cannot verify. A consumer that does not read it gets the unverified reading, which is
+     *  the fail-closed one. */
+    connectors: ShellSegmentConnector[];
 }
 /**
  * Split a compound command into the segments bash would run, or refuse the whole string.
@@ -228,10 +240,10 @@ export interface BashReadonlyRootBoundary {
      *  allowlists classifies by its ordinary form and can auto-run a traversal unjudged);
      *  ② LEXICAL only — an in-root symlink whose target is a
      *  guarded path reads as its innocent spelling here, exactly as it does for the containment half
-     *  (the enforcing/canonicalizing recheck is the bash_readonly leg's job via checkedPaths; the
+     *  (the enforcing/canonicalizing recheck is both shell faces' execute leg, via checkedPaths; the
      *  classify auto-allow lane has no I/O seat by contract). The structured read faces judge BOTH
-     *  views (canonical + lexical) — this seat is the shell lane's honest-friction floor, not its
-     *  security boundary. The `bash_readonly` face deliberately does NOT wire this seat (its
+     *  views (canonical + lexical); what this seat is and is not is stated once, at
+     *  `shell.read_boundary.friction_floor`. The `bash_readonly` face deliberately does NOT wire this seat (its
      *  roots containment + command allowlist double gate is the deployment's own read-safety
      *  declaration — v1 ruling). */
     denyMatch?: (resolvedPath: string) => string | null;
@@ -459,7 +471,8 @@ opts?: {
  * so this face bounds where a command may NAME a file, not where the kernel will ultimately take it.
  * A deployment that needs filesystem-true containment resolves the operands itself, and this
  * verdict hands it the list to resolve ({@link CompoundReadonlyVerdict.checkedPaths}, on both arms).
- * `createBashReadonlyTool` is that caller for the `bash_readonly` leg and does it on a local env.
+ * The engine's own shell legs are that caller on a local env — the read-only face before it runs an
+ * allowlisted command, the full face after its gate allowed one.
  */
 export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
 /**

package/dist/tools/fs/bash-readonly-classifier.js

@@ -109,7 +109,7 @@ export function splitShellCompoundSegments(source, options) {
     }
     const scanned = options?.trailingTerminator !== "keep" ? source.replace(/;\s*$/, "") : source;
     const segments = [];
-    const pipeFed = [false];
+    const connectors = ["start"];
     const mask = quoteMask(scanned);
     const quoted = (i) => mask.balanced && mask.quoted[i] === true;
     let cur = "";
@@ -122,7 +122,7 @@ export function splitShellCompoundSegments(source, options) {
             if (scanned[i + 1] === "&") {
                 segments.push(cur);
                 cur = "";
-                pipeFed.push(false);
+                connectors.push("&&");
                 i++;
             }
             else
@@ -132,25 +132,25 @@ export function splitShellCompoundSegments(source, options) {
             if (scanned[i + 1] === "|") {
                 segments.push(cur);
                 cur = "";
-                pipeFed.push(false);
+                connectors.push("||");
                 i++;
             }
             else {
                 segments.push(cur);
                 cur = "";
-                pipeFed.push(true);
+                connectors.push("|");
             }
         }
         else if (c === ";") {
             segments.push(cur);
             cur = "";
-            pipeFed.push(false);
+            connectors.push(";");
         }
         else
             cur += c;
     }
     segments.push(cur);
-    return { segments, pipeFed };
+    return { segments, pipeFed: connectors.map((k) => k === "|"), connectors };
 }
 const EXEMPT_REDIRECTION = /^(?:2>\/dev\/null|[12]?>&[12])$/;
 function stripExemptRedirections(command) {
@@ -259,7 +259,8 @@ function tokensMoveBase(toks, allow) {
     const unwrapped = unwrapLauncher(toks.folded.slice(from), allow);
     return unwrapped.kind === "refused" || (unwrapped.kind === "reader" && unwrapped.head === "cd");
 }
-const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi)?sh|eval|source|\.)$/;
+const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi)?sh|eval|source|\.|parallel)$/;
+const ARGV_REENTRY_PROGRAM_RE = /^xargs$/;
 export function refusedCommandMayRead(command, allow, boundary) {
     return !refusedCommandExempt(command, allow, boundary, 0);
 }
@@ -579,6 +580,8 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
             const unwrapped = unwrapLauncher(toks.slice(i).map(fold), allow);
             if (unwrapped.kind === "refused")
                 return false;
+            if (argvReentryUnjudged(unwrapped))
+                return false;
             if (unwrapped.kind === "unlisted") {
                 if (!unlistedSegmentJudgedInside(toks, i))
                     return false;
@@ -621,18 +624,35 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
     return true;
 }
 function unwrapLauncher(folded, allow) {
+    let argvFromStdin = ARGV_REENTRY_PROGRAM_RE.test(programBasename(folded[0] ?? ""));
+    let lastReentry = argvFromStdin ? 0 : -1;
     for (let i = 1; i < folded.length; i++) {
         const t = folded[i];
-        if (ASSIGNMENT_WORD.test(t) || /^\d+[smhd]?$/.test(t) || COMMAND_LAUNCHERS.has(t))
+        if (ASSIGNMENT_WORD.test(t) || /^\d+[smhd]?$/.test(t))
+            continue;
+        const wordBasename = programBasename(t);
+        if (ARGV_REENTRY_PROGRAM_RE.test(wordBasename)) {
+            argvFromStdin = true;
+            lastReentry = i;
+            continue;
+        }
+        if (COMMAND_LAUNCHERS.has(wordBasename))
             continue;
         if (t.startsWith("-"))
             return { kind: "refused", reason: `"${folded[0]}" is given an option before the program it runs — which program runs is not readable without the launcher's option table ${NOT_AUTO_ALLOWED}` };
-        const head = t.includes("/") ? t.slice(t.lastIndexOf("/") + 1) : t;
+        const head = wordBasename;
         if (SHELL_CONTROL_PREFIXES.has(head) || SHELL_BLOCK_WORDS.has(head))
             return { kind: "refused", reason: `"${folded[0]}" is given shell control syntax ("${head}") where the program it runs would be ${NOT_AUTO_ALLOWED}` };
-        return allow.has(head) || head === "cd" ? { kind: "reader", index: i, head } : { kind: "unlisted", head };
+        return allow.has(head) || head === "cd" ? { kind: "reader", index: i, head, argvFromStdin } : { kind: "unlisted", head, argvFromStdin };
     }
-    return { kind: "unlisted" };
+    return { kind: "unlisted", argvFromStdin, runsDefaultProgram: lastReentry === folded.length - 1 };
+}
+const ARGV_REENTRY_DEFAULT_PROGRAM = "echo";
+function argvReentryUnjudged(unwrapped) {
+    if (!unwrapped.argvFromStdin)
+        return false;
+    const runs = unwrapped.head ?? (unwrapped.runsDefaultProgram === true ? ARGV_REENTRY_DEFAULT_PROGRAM : undefined);
+    return runs === undefined || !NO_PATH_OPERAND_COMMANDS.has(runs);
 }
 function tokenizeSegment(segment) {
     const raw = splitWordsQuoteAware(segment);
@@ -1208,7 +1228,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     const split = segmentCompoundForReadonly(command, boundary?.homeDir);
     if ("reject" in split)
         return { reason: split.reject, refusedWhole: true };
-    const { segments, pipeFed } = split;
+    const { segments, pipeFed, connectors } = split;
     let nameRefusal;
     const unlistedSegments = new Set();
     const reheaded = new Map();
@@ -1250,6 +1270,9 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
             if (unwrapped.kind === "unlisted" && unwrapped.head !== undefined && SHELL_REENTRY_PROGRAM_RE.test(unwrapped.head)) {
                 return { reason: `"${written}" runs "${unwrapped.head}", which runs its argument as shell text this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
             }
+            if (argvReentryUnjudged(unwrapped)) {
+                return { reason: `"${written}" takes the operands of the program it runs from its standard input, which this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
+            }
             if (unwrapped.kind === "unlisted")
                 unlistedSegments.add(si);
             else
@@ -1288,13 +1311,29 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     };
     const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity, diff: 2, cmp: 2, comm: 2, sed: 2 };
     const foldedSegments = [];
+    const foldedReach = [];
+    let crossedAllAnd = true;
+    let crossedAnyOr = false;
     let shapeRefusal = nameRefusal;
     for (let si = 0; si < segments.length; si++) {
+        if (si > 0) {
+            if (connectors[si] !== "&&")
+                crossedAllAnd = false;
+            if (connectors[si] === "||")
+                crossedAnyOr = true;
+        }
+        const moveProvable = pipeFed[si] !== true && pipeFed[si + 1] !== true && reheaded.get(si) === undefined;
+        const pushReach = () => {
+            foldedReach.push({ andJoined: si > 0 && crossedAllAnd, orBroken: !crossedAllAnd && crossedAnyOr, moveProvable });
+            crossedAllAnd = true;
+            crossedAnyOr = false;
+        };
         if (unlistedSegments.has(si)) {
             const unlisted = tokenizeSegment(segments[si]);
             if (unlisted.folded.length === 0)
                 continue;
             foldedSegments.push({ folded: [LAUNCHER_SCAN_HEAD, ...unlisted.folded], raw: [LAUNCHER_SCAN_HEAD, ...unlisted.raw] });
+            pushReach();
             continue;
         }
         const rehead = reheaded.get(si);
@@ -1303,6 +1342,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
         if (toks.length === 0)
             continue;
         foldedSegments.push(segmentTokens);
+        pushReach();
         const name = toks[0];
         const guardReason = guardedVerbFormReason(name, toks, segmentTokens.raw);
         if (guardReason !== undefined) {
@@ -1383,7 +1423,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
             shapeRefusal ??= `multiple directory changes in one command require approval for clarity ${NOT_AUTO_ALLOWED}`;
     }
     if (boundary !== undefined) {
-        const walk = evaluateReadBoundary(foldedSegments, boundary);
+        const walk = evaluateReadBoundary(foldedSegments, boundary, foldedReach);
         if (shapeRefusal === undefined)
             return walk;
         const { reason: _walkSentence, ...structure } = walk;
@@ -1396,7 +1436,9 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     }
     return {};
 }
-function evaluateReadBoundary(foldedSegments, boundary) {
+const BASE_CANDIDATE_MAX = 256;
+function evaluateReadBoundary(foldedSegments, boundary, reach) {
+    const seen = { outside: new Set(), inside: new Set(), undecided: new Set(), recursive: new Set(), unresolved: new Set() };
     const outside = [];
     const inside = [];
     let unresolvable;
@@ -1404,60 +1446,120 @@ function evaluateReadBoundary(foldedSegments, boundary) {
     let baseLost = false;
     const undecided = [];
     const recursive = [];
-    let currentBase = boundary.cwd ?? boundary.roots[0];
-    for (const toks of foldedSegments) {
+    let candidates = [{ base: boundary.cwd ?? boundary.roots[0], skippedCd: -1 }];
+    let andRunStart = 0;
+    const findingsByWords = new Map();
+    const findingsRowFor = (wordsKey) => {
+        const row = findingsByWords.get(wordsKey);
+        if (row !== undefined)
+            return row;
+        const fresh = new Map();
+        findingsByWords.set(wordsKey, fresh);
+        return fresh;
+    };
+    const findingsFor = (row, toks, base) => {
+        const hit = row.get(base);
+        if (hit !== undefined)
+            return hit;
+        const segBoundary = base === (boundary.cwd ?? boundary.roots[0]) ? boundary : { ...boundary, cwd: base };
+        const computed = collectSegmentBoundaryFindings(toks, segBoundary);
+        row.set(base, computed);
+        return computed;
+    };
+    for (let si = 0; si < foldedSegments.length; si++) {
+        const toks = foldedSegments[si];
         if (baseLost)
             break;
-        const segBoundary = currentBase === (boundary.cwd ?? boundary.roots[0]) ? boundary : { ...boundary, cwd: currentBase };
-        for (const finding of collectSegmentBoundaryFindings(toks, segBoundary)) {
-            if (finding.kind === "unresolvable") {
-                unresolvable ??= finding.reason;
-                if (!unresolved.includes(finding.operand))
-                    unresolved.push(finding.operand);
-                if (toks.folded[0] === "cd")
-                    baseLost = true;
-                continue;
-            }
-            const denied = boundary.denyMatch?.(finding.path);
-            if (denied != null) {
-                return {
-                    reason: `a command operand resolves to "${finding.path}", which matches the sensitive-path read deny list (pattern "${denied}") ${NOT_AUTO_ALLOWED}`,
-                    readDenied: true,
-                };
-            }
-            if (finding.kind === "inside") {
-                if (!inside.includes(finding.path))
-                    inside.push(finding.path);
-                continue;
-            }
-            if (finding.kind === "undecided") {
-                if (!undecided.includes(finding.path))
-                    undecided.push(finding.path);
-                continue;
-            }
-            if (finding.kind === "recursive") {
-                if (!recursive.includes(finding.path))
-                    recursive.push(finding.path);
-                continue;
-            }
-            if (boundary.face === "open") {
-                if (!inside.includes(finding.path))
-                    inside.push(finding.path);
-                continue;
+        if (si > 0 && reach?.[si]?.andJoined !== true)
+            andRunStart = reach?.[si]?.orBroken === true ? si + 1 : si;
+        const reachable = candidates.filter((c) => c.skippedCd < andRunStart);
+        const row = findingsRowFor(JSON.stringify([toks.folded, toks.raw]));
+        for (const { base: currentBase } of reachable) {
+            for (const finding of findingsFor(row, toks, currentBase)) {
+                if (finding.kind === "unresolvable") {
+                    unresolvable ??= finding.reason;
+                    if (!seen.unresolved.has(finding.operand)) {
+                        seen.unresolved.add(finding.operand);
+                        unresolved.push(finding.operand);
+                    }
+                    if (toks.folded[0] === "cd")
+                        baseLost = true;
+                    continue;
+                }
+                const denied = boundary.denyMatch?.(finding.path);
+                if (denied != null) {
+                    return {
+                        reason: `a command operand resolves to "${finding.path}", which matches the sensitive-path read deny list (pattern "${denied}") ${NOT_AUTO_ALLOWED}`,
+                        readDenied: true,
+                    };
+                }
+                if (finding.kind === "inside") {
+                    if (!seen.inside.has(finding.path)) {
+                        seen.inside.add(finding.path);
+                        inside.push(finding.path);
+                    }
+                    continue;
+                }
+                if (finding.kind === "undecided") {
+                    if (!seen.undecided.has(finding.path)) {
+                        seen.undecided.add(finding.path);
+                        undecided.push(finding.path);
+                    }
+                    continue;
+                }
+                if (finding.kind === "recursive") {
+                    if (!seen.recursive.has(finding.path)) {
+                        seen.recursive.add(finding.path);
+                        recursive.push(finding.path);
+                    }
+                    continue;
+                }
+                if (boundary.face === "open") {
+                    if (!seen.inside.has(finding.path)) {
+                        seen.inside.add(finding.path);
+                        inside.push(finding.path);
+                    }
+                    continue;
+                }
+                if (!seen.outside.has(finding.path)) {
+                    seen.outside.add(finding.path);
+                    outside.push(finding);
+                }
             }
-            if (!outside.some((o) => o.path === finding.path))
-                outside.push(finding);
         }
         if (!baseLost && toks.folded[0] === "cd") {
             const cdArgs = toks.folded.slice(1);
             const cdTargetIdx = cdArgs.findIndex((t) => !t.startsWith("-") || t === "-");
             const cdTarget = cdTargetIdx === -1 ? undefined : cdArgs[cdTargetIdx];
             if (cdTarget !== undefined && cdTarget !== "-") {
-                currentBase = resolveOperandLexically(currentBase, cdTarget, boundary.homeDir) ?? currentBase;
+                const provable = reach?.[si]?.moveProvable === true;
+                const branched = [];
+                for (const c of candidates) {
+                    if (c.skippedCd < andRunStart)
+                        branched.push({ base: resolveOperandLexically(c.base, cdTarget, boundary.homeDir) ?? c.base, skippedCd: c.skippedCd });
+                    branched.push({ base: c.base, skippedCd: provable ? si : c.skippedCd });
+                }
+                const byBase = new Map();
+                for (const c of branched) {
+                    const prior = byBase.get(c.base);
+                    if (prior === undefined || c.skippedCd < prior.skippedCd)
+                        byBase.set(c.base, c);
+                }
+                const next = [...byBase.values()];
+                if (next.length > BASE_CANDIDATE_MAX) {
+                    unresolvable ??= `too many directory changes to track where "${cdTarget}" leaves the working directory ${NOT_AUTO_ALLOWED}`;
+                    if (!seen.unresolved.has(cdTarget)) {
+                        seen.unresolved.add(cdTarget);
+                        unresolved.push(cdTarget);
+                    }
+                    baseLost = true;
+                }
+                else
+                    candidates = next;
             }
         }
     }
-    const undecidedAll = [...undecided, ...recursive.filter((p) => !undecided.includes(p))];
+    const undecidedAll = [...undecided, ...recursive.filter((p) => !seen.undecided.has(p))];
     const undecidedField = {
         ...(undecidedAll.length > 0 ? { undecidedPaths: undecidedAll } : {}),
         ...(recursive.length > 0 ? { recursiveReadPaths: recursive } : {}),
@@ -1504,7 +1606,7 @@ const COMMAND_LAUNCHERS = new Set([
     "env", "command", "builtin", "exec", "noglob", "xargs",
     "sudo", "doas", "pkexec", "su", "runuser", "chroot", "setpriv",
     "nohup", "nice", "ionice", "chrt", "taskset", "stdbuf", "timeout", "time", "watch",
-    "setsid", "flock", "unshare", "nsenter", "script", "numactl", "prlimit", "systemd-run", "parallel",
+    "setsid", "flock", "unshare", "nsenter", "script", "numactl", "prlimit", "systemd-run",
     "strace", "ltrace", "valgrind", "firejail", "bwrap",
 ]);
 export const COMMAND_LAUNCHERS_FOR_TEST = COMMAND_LAUNCHERS;
@@ -1524,8 +1626,25 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
         if ("reject" in split)
             return NOT_GATED;
         const readers = [];
+        const readerReach = [];
+        let crossedAllAnd = true;
+        let crossedAnyOr = false;
         let baseMoved = false;
-        for (const segment of split.segments) {
+        for (let si = 0; si < split.segments.length; si++) {
+            const segment = split.segments[si];
+            if (si > 0) {
+                if (split.connectors[si] !== "&&")
+                    crossedAllAnd = false;
+                if (split.connectors[si] === "||")
+                    crossedAnyOr = true;
+            }
+            const moveProvable = split.pipeFed[si] !== true && split.pipeFed[si + 1] !== true;
+            const pushReader = (st) => {
+                readers.push(st);
+                readerReach.push({ andJoined: si > 0 && crossedAllAnd, orBroken: !crossedAllAnd && crossedAnyOr, moveProvable });
+                crossedAllAnd = true;
+                crossedAnyOr = false;
+            };
             const toks = tokenizeSegment(segment);
             if (toks.folded.length === 0)
                 continue;
@@ -1539,16 +1658,16 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
             if (UNMODELLED_BASE_MOVERS.has(name))
                 baseMoved = true;
             if (!allow.has(name) && name !== "cd") {
-                readers.push({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)] });
+                pushReader({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)] });
                 continue;
             }
-            readers.push(i === 0 && name === written ? toks : { folded: [name, ...toks.folded.slice(i + 1)], raw: [toks.raw[i] ?? name, ...toks.raw.slice(i + 1)] });
+            pushReader(i === 0 && name === written ? toks : { folded: [name, ...toks.folded.slice(i + 1)], raw: [toks.raw[i] ?? name, ...toks.raw.slice(i + 1)] });
         }
         if (readers.length === 0)
             return NOT_GATED;
         if (baseMoved)
             return { gated: true, paths: [] };
-        const verdict = evaluateReadBoundary(readers, containmentOnly);
+        const verdict = evaluateReadBoundary(readers, containmentOnly, readerReach);
         return verdict.outOfRootRead === true ? { gated: true, paths: verdict.outOfRootPaths ?? [] } : NOT_GATED;
     };
     const direct = judge(command);

package/dist/tools/fs/fs-bash.d.ts

@@ -54,6 +54,10 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * The other non-reversible arms stay bare on purpose — their cause is legible in the command itself (a
  * write verb, a pipe, an unlisted name), and manufacturing an account for them would put text on a card
  * that adds nothing the reader cannot already see.
+ *
+ * What the boundary half of this probe is — and what it is not — is stated once on the seat that owns it
+ * ({@link bashReadBoundaryProbe}, `@contract shell.read_boundary.friction_floor`); composing it with the
+ * shape classifier here changes what happens to the residual shell risk, never that reading.
  */
 export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
@@ -99,6 +103,19 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  * The reader set is the engine's classify set ({@link BASH_CLASSIFY_DEFAULT_ALLOW}) — here it is NOT an
  * auto-allow list but the set of programs whose operands the faces read; a wider set means more reads are
  * judged, never that more runs are vouched.
+ *
+ * @contract shell.read_boundary.friction_floor — what this seat answers is a question about TEXT: which
+ * files the words of a command may name, resolved against the declared roots, the declared home and the
+ * observed working directory. It is not a question about what the process will open, and no amount of
+ * parsing makes it one. A deployment's containment for what a shell may reach is the `ExecutionEnv` the
+ * command runs in (a sandbox, a container, a remote adapter); everything here is the friction floor under
+ * that containment — it raises the cost of an accidental or careless read, and it is not a defence against
+ * a command written to defeat it. The floor's last cell belongs to the full shell's own execute leg: once
+ * the gate has allowed a call and before anything spawns, the candidates this seat accepted are resolved
+ * on the filesystem, and a target that leaves the roots only after a symlink is followed is REFUSED —
+ * refused rather than asked, because by then the approval step is behind the call (see `createBashTool`'s
+ * `readBoundary` option). The leg runs where an environment can resolve a link locally; a remote adapter
+ * keeps the textual answer alone.
  */
 export declare function bashReadBoundaryProbe(boundary: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
@@ -171,6 +188,17 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      * unconfined; passing this never gates anything.
      */
     additionalRoots?: readonly string[];
+    /**
+     * The deployment's shell READ BOUNDARY — the same seat the gate's shell probes read
+     * ({@link bashReadBoundaryProbe}), handed to the tool so its execute leg can close the one gap a
+     * synchronous seat structurally cannot: the seat judges the WRITTEN spelling, the kernel opens the
+     * symlink-resolved target. Passed as a FUNCTION wherever the working directory is observable (an
+     * in-task `cd` moves the base a relative operand resolves against); evaluated per call.
+     *
+     * Absent ⇒ no recheck and no I/O: a deployment with no read boundary declared has no roots for a
+     * read to be outside of, exactly as the seat itself reads an absent boundary.
+     */
+    readBoundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined);
     /** Override of the `timeout` parameter's DEFAULT budget, in ms — see
      *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} for the resolution
      *  contract (options over env over constant; invalid values discarded). */