@sema-agent/core 7.23.0 → 7.23.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 7.23.1 — 2026-09-18
+
+### Read boundary — a `$` inside SINGLE QUOTES no longer refuses the whole command (#921, ruling C-R67 ③; behaviour face, both seats; @cli @server @client-core re-pin)
+- **Before.** The compound classifier's whole-string gate scanned for `$` character by character with no idea of quoting, so the most ordinary lines there are carried a card no rule could clear: `awk '{print $1}' f`, `awk -F: '{print $1}' f`, `awk '{print $NF}' f`, `grep 'x$' f`, `sed -n 's/$/x/p' f`. One character decided it — `awk '{print}' f`, the same invocation, was auto-allowed. Inside single quotes the character is a field reference or an end-of-line anchor; bash expands nothing there.
+- **After.** ONE sieve, two passes in a load-bearing order. Everything whose ABSENCE makes quoting exact — escapes, subshells, line breaks, and redirection outside the tolerate mode — is still refused QUOTE-BLIND; only then, with a backslash guaranteed gone, is the lexer's existing quote mask built and `$` refused wherever bash would expand it (unquoted, or inside double quotes). Rules: −1 (the tolerate arm and the default arm were two refusal paths and are now one, with the sentence as the parameter). `quoteMask` reports WHICH quote holds each character; `quoted` is a view of that, minted in the same step.
+- **A BACKTICK is not read through the mask, and the line between the two is measured.** Quoting stops the FIRST expansion, not a later one: `let` and `declare -i` evaluate their argument as an ARITHMETIC expression, and that evaluation performs command substitution on the text it is handed, single quotes included. Against real bash, `let 'a[0`<command>`]'` and `declare -i 'a=b[0$(<command>)]'` RUN the command; `let 'a=$x'` and `let 'a[0$x]'` hand the evaluator the literal characters `$x`, which is a syntax error and runs nothing, and a value arriving through `${x}` is expanded but never re-substituted. So the two spellings that can EXECUTE — `` ` `` and `$(` — stay refused wherever they stand (`(` being in the blind class is what keeps the second one out), which is the same fact the whitelist already states about an assignment word whose value spells a substitution literally. `$` alone cannot execute, so it is the only character this mask decides.
+- **Exactness, since the two characters are the ones that could break the mask.** The mask and bash agree left to right until something stops a quote character from being one. Two things can: a backslash, refused before the mask is built, and the `$'…'` / `$"…"` forms, whose `$` stands OUTSIDE the region it opens — where the mask still reports it unquoted and the gate refuses the string. Either the string is refused or the mask is exact; there is no third case. An unbalanced mask is not used at all.
+- **Reach.** Ten measured shapes stop being whole-refused, and each then answers exactly as the same command without the character. Two directions, both pinned: `awk '{print $1}' f` / `grep 'x$' f` / `cat '$F'` go to zero asks on the default/off and bypass tiers, while `awk '{print $1}' /etc/passwd` and `grep 'x$' <deny row>` STAY mandated — and now name the file they read instead of refusing the string. `awk "{print $1}" f` (double quotes, a real expansion), `cat $F`, `cat $'a\tb'`, `cat \`echo f\``, `echo '\`id\`'` (single-quoted backtick — see above) and every unbalanced-quote spelling are unchanged. `cat '$HOME/.ssh/<key>'` goes from one mandated ask to zero: bash hands `cat` the literal directory name `$HOME`, so the command cannot reach the key — and a deployment whose deny table covers that literal path still gets its refusal (`test/backlog714-home-expansion-precise.test.ts` re-pinned).
+- **The rule lane too.** The segmenter is shared with the persisted permission-rule lane, where a whole-string refusal put the command outside the lane entirely and no stored rule of EITHER polarity could speak about it. These commands are now nameable: a deny rule reaches them, and so does an allow rule.
+- **Not fixed, and now visible rather than assumed gone.** (i) An interpreter's inline program that opens with a slash-addressed pattern is still read as an absolute path: `awk '/error/' app.log` reports a phantom out-of-root read of `/error`, and `perl -pe '/x/' f` of `/x`. sed's positional script got a first-operand row in #892; the interpreter family has not. Pinned in `test/backlog791-interpreter-inline-program.test.ts` G-9. (ii) `trap` / `alias` / `history -s` / `git -c 'core.pager=…'` hand a LATER evaluation a command line and are not in the shell re-entry class, so the boundary walks their argument as an ordinary in-root word and vouches it. That hole is PRE-EXISTING — `trap 'cat /etc/passwd' EXIT` measured vouched on 66b7e7c5 too — and this change adds the `$` spelling (`trap 'cat $F' EXIT`) to the same already-open door; no capability is new, since anyone who can write the one can write the other. Both ticketed, pinned in `test/backlog921-single-quoted-expansion.test.ts` ④.
+- **headless.** Both tiers, permissive direction: a headless run that refused these awk/grep/sed lines for want of an approver now executes them. Nothing is newly refused. Pins: `test/backlog921-single-quoted-expansion.test.ts`.
+
+### Read boundary — a verb's FIRST OPERAND can be a slot its grammar fills, not a file: `sed -n '/error/p' app.log` stops asking (#892; behaviour face, both seats; @cli @server @client-core re-pin)
+- **Before.** Only grep's PATTERN slot was modelled, by a hand-written predicate and a hand-written branch in each of the two walks that needed it. sed's SCRIPT slot was modelled for the `-e` spelling and not for the positional one, so `sed -n '/error/p' app.log` — a script opening with an address regexp, spelled with slashes — was read as the absolute path `/error/p`, found outside the roots, and carried a MANDATED card on an everyday log-reading line. The `-e` spelling of the same script was already exempt: one invocation, two readings.
+- **After.** `VerbOptionSlots.firstOperand` is a declaration row (grep's `pattern`, sed's `script`) read with the same `OptionValueKind` vocabulary the option slots already use, and ONE reader (`suppliesFirstOperandSlot`) answers "did an option supply this slot instead" for both walks. Rules: −1 (the verb-named branch and its private predicate are gone; a verb with no row keeps an ordinary first operand). The slot's value is judged exactly as a declared option value is — a kind that cannot name a file yields no candidate, one that can is a file as before.
+- **Reach — a NARROWING, listed per spelling.** Six shapes lose a mandated card on the default/off and bypass tiers (and take an ordinary ask on the classify tier instead): `sed -n '/error/p' <log>`, `sed -n '/x/r <out-of-root>' f` (see Stated), and the four spellings in which a path-shaped token IS sed's script — `sed <path>`, `sed <deny row>`, `sed -l <path>`, `sed -l <deny row>`. The last four are not a file under EITHER implementation: the token is the script where `-l` takes no value and `-l`'s length argument where it does, so the verb-blind reading that recorded it as a read was an over-approximation the row now retires (`test/backlog764-verb-option-slots.test.ts` G-2b re-pinned; the one spelling whose token really is an input, `sed -n -e 1p -l <file>`, still mandates and still catches the arity mutation). The narrowing is exactly one operand wide: `sed -f prog.sed <path>`, `sed p <path>`, `sed -n p /etc/passwd` and `grep pat /etc/passwd` all still mandate, and no other verb grew a row. Pins: `test/backlog892-first-operand-slot.test.ts`.
+- **Stated (ruled reach, C-R67 ②).** `sed -n '/x/r <out-of-root>' f` was mandated only because its script's first character was `/` and the operand walk read the whole script as an absolute path — an accident, not a promise: `sed -n 'p;r <out-of-root>' f` was never caught, and `sed -n '1r <out-of-root>' f` has been the ruled, disclosed reach of the friction floor since 7.22.0. Removing the misreading removes the accident with it, so that spelling now answers like its siblings. The script slot's named files do not reach the read boundary by ruling; the floor for what they open is the execution environment's sandbox.
+- **headless.** Both tiers, permissive direction and narrow: a headless run that refused `sed -n '/error/p' <log>` for want of an approver now executes it. Nothing is newly refused.
+
+### Read boundary — a decline is read as evidence by the SEAT that declares it; the classify tier trades the mandate for an ordinary ask (#891, ruling C-R67 ①; behaviour face, classify tier only; @cli @server @client-core re-pin)
+- **Before.** The shell scan declines two ways — it cannot name the program bash will run (`env -- ls`, `nice -x 5 cat f`, `xargs -0 wc -l`, `sudo -u root cat f`), or it read the program and the operands arrive on a STREAM it never saw (`find … | xargs wc -l`, `git ls-files | xargs grep -l TODO`, `ls | xargs cat`). Both refused the command outright on BOTH seats, so under `shellGate: "classify"` these everyday pipelines carried a card no allow rule and no auto classifier could retire. Neither decline names a word: they say only that the scan could not tell.
+- **After.** Which decline a seat reads as read evidence is a TABLE the seat declares against (`SHELL_SCAN_DECLINES`, two members; `BOUNDARY_SEAT_DECLINE_EVIDENCE` keeps both, `CLASSIFY_SEAT_DECLINE_EVIDENCE` keeps neither). The question is asked ONCE for the whole command, ahead of every per-verb exit, so nothing downstream stands in front of the table — the blanket refusal of a listed reader whose operands the whitelist does not enumerate included. Rules: −4 (four per-segment refusals fold into that one pass), +1 (the pass). No third verdict state: both seats still raise an ask on the same shapes.
+- **Reach — default and bypass tiers: none, measured byte for byte.** The read-boundary seat is what those tiers mount ALONE, where "not mandated" is VOUCHED, so it keeps both members: all 78 rows of the differential corpus answer identically, `echo /etc/passwd | xargs cat` included (the closed P0 stays closed). Under `shellGate: "classify"` 17 of those rows move from a mandated card to an ordinary one.
+- **What the release does NOT buy, and it is one rule.** The boundary's objection over an operand the command NAMES still mandates, on BOTH halves of that judgement — the deny table and the roots. It is asked by the face that already answered the containment half (`classifyOutOfRootReadGate`), which now reports the deny finding too: ONE extraction of what the operands are, two findings over it, computed in a second pass with the deny judge present so the containment answer stays deny-free and keeps its `paths` contract. So `cat <deny row> && ls | xargs wc -l` answers exactly as its twin `cat /etc/passwd && ls | xargs wc -l`, and so do `ls | xargs wc -l; cat <deny row>`, `echo x | xargs cat <deny row>`, `ls | xargs grep -l TODO <deny row>`, the attached and separated payload spellings (`grep -f<deny row>`), a `NAME=value` operand (`dd if=<deny row>`) and a read standing before a directory change. Because the extraction is the face's own, no read is invented either: a sed SCRIPT is still not a path.
+- **🔔 This reaches the DEFAULT/OFF and BYPASS tiers too, and it is the only place in this batch where they move.** That face reads a segment under a control word VERB-BLIND, so it was already mandating `! echo /etc/passwd` on every tier while `! echo <deny row>` was vouched — the same asymmetry, one layer up, and one its own header claims to cover. Giving it the deny half closes that as well: 252 rows of a 39,930-row control-word corpus move, every one V → M (a tightening; zero M → V), every one carrying a deny-listed operand, under `!` / `if` / `while` / `time` / `command` / `env` / `xargs` and the unreadable-launcher heads. A deployment with no deny table sees nothing (the face never reports the half its boundary cannot answer); the plain spelling is untouched, since a program declared to read no path still names no read.
+- **Accepted reach, stated rather than mitigated.** On the classify tier, once that ordinary ask is retired by a rule or the auto classifier, a read HIDDEN inside such a command is not asked again: a stream is re-split by its consumer (`echo <deny row> | xargs cat` — the path is in `echo`'s words, and what `xargs` hands `cat` is a stream nobody read), whitespace is re-split with it (`echo " /etc/passwd" | xargs cat`), an option the walk could not read may move the working directory first (`env -q cd ..; strings ../secret`), text reaching a shell through stdin is a command line nobody parsed (`echo "cat /etc/passwd" | env -- sh`), and a stdin literal (`env -- ls < /etc/passwd`) or a substitution body (`env -- ls $(cat /etc/passwd)`) behind a decline is not walked. An operand the scan could not READ at all — an unexpanded glob — is not an objection either, which is why `find . -name '*.ts' | xargs wc -l` still drops. Each is pinned at that answer in `test/backlog891-seat-keyed-declines.test.ts`. What such a command may read is floored by the execution environment's sandbox.
+- **headless.** Classify tier only, and in the permissive direction: a headless run (no approver) that refused these commands on a mandated card now refuses them on an ordinary one — and where a stored allow rule covers the command, it now RUNS instead of being refused. Default/off and bypass tiers are unchanged, so a deployment on those tiers sees no lane change.
+- **@cli @server @client-core.** Re-pin any probe that expects `mandated` for these shapes under `shellGate: "classify"`; the default tier's expectations are unchanged. The PUBLIC export face is unchanged (`handoff:diff` 66b7e7c5..HEAD = +0/−0 over all three changes in this batch): the new names — `SHELL_SCAN_DECLINES`, `ShellScanDecline`, `programPositionRunsShell`, `shellScanDeclineOf`, `BOUNDARY_SEAT_DECLINE_EVIDENCE`, `CLASSIFY_SEAT_DECLINE_EVIDENCE` — are module exports inside `src/tools/fs`, not re-exported from `src/index.ts`, and `refusedCommandMayRead`'s new required fourth argument is likewise internal.
+
+### Gates — the debts gate reds text that spills past the seventh cell (`gate:debts`; no product code)
+- A ledger row with one bare `|` inside a cell and no closing pipe still splits into nine segments, so the column-count check passed while the tail after the last pipe sat in no cell at all — unread by the gate's positional readers and dropped by the renderer (found by the cli debt survey: five rows whose open remainders lived in that tail; one server row measured the same way today). A row must open and close with a pipe; a non-empty first or last segment is red and names the row. Negative control in `test/gate-negative-controls.test.ts`.
+
+### Loading — every `src/tools/fs` module is a safe first entry; the gate's crash tracer leaves the record floor (#918; no behaviour change)
+- **Before.** A host that imported `dist/tools/fs/bash-readonly-classifier.js` BEFORE `dist/tools/fs/fs-bash.js` (the cli's danger-matrix harness) got `ReferenceError: Cannot access 'NOT_AUTO_ALLOWED' before initialization` on 7.21.1, 7.22.0 and 7.23.0 alike. The runtime cycle: `tools/fs/safety` → `core/gate-bounded-await` → `runner/gate-exit` (one VALUE import, the crash tracer) → `tool-policy` → `tools/fs/index` → `fs-bash` → the classifier still mid-evaluation, whose re-export of the phrase constant fs-bash's top-level table read had not been reached. A bare import of fs-bash never showed it: ESM evaluation order is the entry's.
+- **After.** `traceHookCrash` lives in `src/core/gate-crash-trace.ts` (two type-only edges, one call); `gate-bounded-await` has no runtime edge into `runner/`; `fs-bash` reads `NOT_AUTO_ALLOWED` from its declaring module (`bash-program-position`) and the classifier's dead re-export is retired. The built dist has no path from the classifier back to fs-bash; the cli's import order loads. Pins (`test/backlog918-module-entry-order.test.ts`): the cli order in a fresh process, every `src/tools/fs` module as a first entry (one fresh `node --import tsx` process each), and no runtime `runner/` import in the bounded-await helper.
+- **Reach.** No wire, no export change (`traceHookCrash` was never public), no behaviour; a host importing engine modules directly in any order now loads them.
+
+### Write protection — the NTFS data-stream strip is the reference fold's `:.*$` pattern; a stream name carrying a line terminator is a STATED miss (#912, ruling C-R66 (b))
+- **Before.** The win32 reading cut the stream suffix by index (`indexOf(":")`), one notch stricter than the reference: `name:stream\nrest` was stripped to `name`, where the reference's regexp `.` stops at the terminator and names nothing.
+- **After.** The cut is the reference's `/:.*$/`. `\.bashrc:evil` still names `.bashrc`; `\.bashrc:evil\nrest` (and `\r`, U+2028, U+2029) no longer does — the reference misses that spelling the same way, and alignment was the ruling. Pin `test/backlog841-invisible-and-stream-fold.test.ts` ⑥ holds the aligned form.
+- **Reach.** One fewer question on exactly that control-character spelling, win32 readings only; no wire key, no closed set, no export change. Headless: that spelling's overwrite goes from refused to executed under the write-protection table (the opt-in deny set and the data-root passthrough are untouched).
+
 ## 7.23.0 — 2026-09-18
 
 ### Gates — every script's CLI entry guard folded into ONE helper; the roster runner no longer reads silence as green (#915; `gate:all` and its 21 guarded children; no product code)

package/dist/core/gate-bounded-await.d.ts

@@ -1,4 +1,4 @@
-import { traceHookCrash } from "./runner/gate-exit.js";
+import { traceHookCrash } from "./gate-crash-trace.js";
 import type { WriteProtectionVerdict } from "./write-protect.js";
 /**
  * design/77 §4: resolve `p`, but REJECT (so the caller catches and fails closed) if it hasn't settled within

package/dist/core/gate-bounded-await.js

@@ -1,4 +1,4 @@
-import { traceHookCrash } from "./runner/gate-exit.js";
+import { traceHookCrash } from "./gate-crash-trace.js";
 export function gateWaitFailureOf(err) {
     const mark = err?.gateWait;
     return mark === "timeout" || mark === "aborted" ? mark : undefined;

package/dist/core/gate-crash-trace.d.ts

@@ -0,0 +1,7 @@
+import type { ToolGateInput } from "./hooks.js";
+import type { SafeNotifier } from "./safe-notify.js";
+/** Hand the crash itself to the deployment's trace lane (`onError(phase:"hook")`), never letting a
+ *  throwing sink alter the fail-closed outcome — the same swallow posture as every other observer here.
+ *  Shared by the gate's dispatch (the phase-1 crash arm, the seat-bound refusal), the reversibility probe's
+ *  two failure arms, the approved-edit re-screen and the bounded-await deadline. */
+export declare function traceHookCrash(input: ToolGateInput, err: unknown, notifier: SafeNotifier): void;

package/dist/core/gate-crash-trace.js

@@ -0,0 +1,3 @@
+export function traceHookCrash(input, err, notifier) {
+    notifier.notify(() => input.onHookError?.(err), "toolGate.onHookError");
+}

package/dist/core/gate-fold.js

@@ -1,7 +1,8 @@
 import { inlineUntrusted } from "./untrusted-text.js";
 import { PROBE_REASON_MAX, normalizeProbeCause } from "./checkpoint-store.js";
 import { normalizeReadRootCandidate } from "./read-root-candidate.js";
-import { traceHookCrash } from "./runner/gate-exit.js";
+import {} from "./runner/gate-exit.js";
+import { traceHookCrash } from "./gate-crash-trace.js";
 import { writeProtectionMandated, writeProtectionTightenDecision, writeProtectionUnresolved } from "./write-protect.js";
 import { createGateDeadline, awaitWriteProtectionJudgment, gateWaitFailureOf, withGateTimeout } from "./gate-bounded-await.js";
 export async function runGateFold(pass) {

package/dist/core/gate-lanes.js

@@ -9,7 +9,8 @@ import { readOnlyShellVerdict } from "./read-only-shell.js";
 import { COMMAND_RULE_TOOL } from "./permission-rule-model.js";
 import { catalogRuleFaceOf } from "./tool-registry.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
-import { exitGate, traceHookCrash } from "./runner/gate-exit.js";
+import { exitGate } from "./runner/gate-exit.js";
+import { traceHookCrash } from "./gate-crash-trace.js";
 import { createGateDeadline, awaitWriteProtectionJudgment } from "./gate-bounded-await.js";
 function isPlainOwnRecord(x) {
     try {

package/dist/core/hooks.js

@@ -1,5 +1,6 @@
 import { decisionText, refuseOutOfContractDecision } from "./tool-policy.js";
-import { createSettlementLedger, engineFailClosedExit, hookDenyExit, traceHookCrash } from "./runner/gate-exit.js";
+import { createSettlementLedger, engineFailClosedExit, hookDenyExit } from "./runner/gate-exit.js";
+import { traceHookCrash } from "./gate-crash-trace.js";
 import { runGateFold } from "./gate-fold.js";
 import { runGateLanes } from "./gate-lanes.js";
 export { normalizeOrgGateVerdict, normalizePersistedRuleHit } from "./gate-lanes.js";

package/dist/core/runner/gate-exit.d.ts

@@ -112,11 +112,6 @@ export declare function createSettlementLedger(call: {
  * a non-object primitive passes through as-is (immutable anyway).
  */
 export declare function cloneObserverInput(input: unknown): unknown;
-/** Hand the crash itself to the deployment's trace lane (`onError(phase:"hook")`), never letting a
- *  throwing sink alter the fail-closed outcome — the same swallow posture as every other observer here.
- *  Shared by the gate's dispatch (the phase-1 crash arm, the seat-bound refusal), the reversibility probe's
- *  two failure arms and the approved-edit re-screen. */
-export declare function traceHookCrash(input: ToolGateInput, err: unknown, notifier: SafeNotifier): void;
 /**
  * The PreToolUse screening face as the gate's stations see it — the hook machinery of `runToolGate` (the seat
  * runner, the per-call seat bound, the fresh per-screening context, the result screen, the two fail-closed

package/dist/core/runner/gate-exit.js

@@ -76,9 +76,6 @@ export function cloneObserverInput(input) {
         return input;
     }
 }
-export function traceHookCrash(input, err, notifier) {
-    notifier.notify(() => input.onHookError?.(err), "toolGate.onHookError");
-}
 const PARK_FAILURE_CAUSE_MAX = 600;
 function withParkFailureCause(reason, parkFailed) {
     if (parkFailed === undefined)

package/dist/core/write-protect.js

@@ -66,8 +66,7 @@ function stripInvisibleFormat(s) {
 }
 function stripWin32Component(raw, normalization) {
     const base = normalization.invisibleFirst ? stripInvisibleFormat(raw) : raw;
-    const colon = normalization.stream ? base.indexOf(":") : -1;
-    return (colon < 0 ? base : base.slice(0, colon)).replace(/[. ]+$/, "");
+    return (normalization.stream ? base.replace(/:.*$/, "") : base).replace(/[. ]+$/, "");
 }
 function foldWriteProtectName(name) {
     return name.split("/").map(foldWriteProtectSegment).join("/");

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

@@ -92,20 +92,27 @@ export interface SegmentTokens {
 /** What a substitution leaves in a word's FOLDED spelling: a marker no argv word can spell, so a consumer that
  *  judges words sees "this word carries text the shell computes" rather than the computing text itself. */
 export declare const SUBSTITUTION_PLACEHOLDER = " subst";
+export type QuoteOpen = '"' | "'" | undefined;
 /**
- * Which characters of `s` sit inside a QUOTED region, by the same pairing rule the lexer walks with. The pairing
- * quote characters themselves are reported as quoted — they are not operators either way.
+ * Which QUOTE holds each character of `s`, by the same pairing rule the lexer walks with, and the boolean view
+ * of it. The pairing quote characters themselves belong to the region they bound — they are not operators
+ * either way — so `openedBy` names that region's quote character at their own index too.
+ *
+ * `quoted` is a VIEW of `openedBy`, minted in the same step: a consumer asking only "is this inside quotes"
+ * reads it, one asking WHICH quote (single quotes suppress every expansion, double quotes suppress neither `$`
+ * nor the backtick) reads `openedBy`, and the two cannot drift.
  *
  * `balanced` is false when a region is still open at the end of the string. Callers must then NOT use the mask:
  * an unterminated quote is a string bash itself cannot parse, and every consumer falls back to the quote-BLIND
  * reading, which is the stricter one.
  *
  * EXACTNESS. This models bash only for the residual character space the strict faces operate in, where backslash
- * escapes, `$`, backticks, and subshells are rejected outright — there `'` and `"` pairing is the whole of
- * quoting, so a region computed here is exactly a region bash quotes. It is NOT a general shell quoting parser
- * and must not be used before those characters are excluded.
+ * escapes and subshells are rejected outright — there `'` and `"` pairing is the whole of quoting, so a region
+ * computed here is exactly a region bash quotes. A caller deciding about `$` or a backtick on this mask owes
+ * the argument in `bash-readonly-classifier.ts`. It is NOT a general shell quoting parser.
  */
 export declare function quoteMask(s: string): {
+    openedBy: readonly QuoteOpen[];
     quoted: readonly boolean[];
     balanced: boolean;
 };

package/dist/tools/fs/bash-lexer.js

@@ -5,14 +5,17 @@ function quoteStep(open, ch) {
     return open === ch ? undefined : open;
 }
 export function quoteMask(s) {
+    const openedBy = new Array(s.length).fill(undefined);
     const quoted = new Array(s.length).fill(false);
     let open;
     for (let i = 0; i < s.length; i++) {
         const before = open;
         open = quoteStep(open, s[i]);
-        quoted[i] = before !== undefined || open !== undefined;
+        const holds = before ?? open;
+        openedBy[i] = holds;
+        quoted[i] = holds !== undefined;
     }
-    return { quoted, balanced: open === undefined };
+    return { openedBy, quoted, balanced: open === undefined };
 }
 export function literalTildeSpelling(word) {
     return word.startsWith("~") ? `./${word}` : word;

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

@@ -114,6 +114,9 @@ export type ProgramPositionRefusal = {
     readonly kind: "control_syntax_at_program_position";
     readonly owner: string;
     readonly word: string;
+    /** Not a DECLINE ({@link programPositionRunsShell}): the row WAS read and a SHELL stands at the program
+     *  position. Absent ⇒ genuine control syntax, which IS one. */
+    readonly runsShell?: true;
 };
 export interface ProgramPosition {
     /** Indices of the bare control words stripped in front (`!`, `if`, `time`, …), in order; their declared options
@@ -159,5 +162,20 @@ export declare function readProgramPosition(toks: SegmentTokens): ProgramPositio
  *  stdin AND the program it runs is not one the caller accepts as a stream target. ONE reading, shared by every
  *  consumer; WHICH targets are accepted is the caller's declaration, not this reader's. */
 export declare function argvReentryUnjudged(pos: ProgramPosition, acceptedTargets: ReadonlySet<string>): boolean;
+/**
+ * The two ways this reader DECLINES rather than judges — a CLOSED set, because which of them a seat reads as
+ * evidence is a table each seat declares against (`fs-bash.ts`, where the argument is), not a boolean buried
+ * in a caller. `unreadable_program_position`: the walk cannot name the program bash will run (`env -- ls`).
+ * `stream_fed_operands`: the operands arrive on a STREAM it never saw (`… | xargs cat`). Neither names a WORD.
+ */
+export declare const SHELL_SCAN_DECLINES: readonly ["unreadable_program_position", "stream_fed_operands"];
+export type ShellScanDecline = (typeof SHELL_SCAN_DECLINES)[number];
+/** Does a SHELL stand where this segment's program would be — as the program itself (`sh -c`), or as a launcher
+ *  ROW handing its operands to one (`watch "…"`)? ONE predicate for the re-entry class, so the two spellings
+ *  cannot be answered differently; which names are shells is the caller's declaration. Not a decline. */
+export declare function programPositionRunsShell(pos: ProgramPosition, shellProgram: RegExp): boolean;
+/** Which decline, if any, this program position raises — ONE reading of the two facts above, so no consumer
+ *  re-derives either. A refusal that says a SHELL runs is NOT one: it names what runs. */
+export declare function shellScanDeclineOf(pos: ProgramPosition, acceptedStreamTargets: ReadonlySet<string>): ShellScanDecline | undefined;
 /** ONE sentence per refusal kind, minted here and nowhere else. */
 export declare function programPositionRefusalSentence(refusal: ProgramPositionRefusal): string;

package/dist/tools/fs/bash-program-position.js

@@ -107,7 +107,7 @@ export function readProgramPosition(toks) {
     }
     const launchers = [{ index: i, name: basename }];
     const owner = head;
-    const shellRefusal = () => ({ kind: "control_syntax_at_program_position", owner, word: "sh" });
+    const shellRefusal = () => ({ kind: "control_syntax_at_program_position", owner, word: "sh", runsShell: true });
     let owedOperands = LAUNCHER_TABLE.get(basename)?.requiredOperands ?? 0;
     let lastRow = LAUNCHER_TABLE.get(basename);
     const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal });
@@ -158,6 +158,18 @@ export function argvReentryUnjudged(pos, acceptedTargets) {
     const runs = pos.program?.basename ?? (pos.runsDefaultProgram ? ARGV_REENTRY_DEFAULT_PROGRAM : undefined);
     return runs === undefined || !acceptedTargets.has(runs);
 }
+export const SHELL_SCAN_DECLINES = ["unreadable_program_position", "stream_fed_operands"];
+export function programPositionRunsShell(pos, shellProgram) {
+    if (pos.refusal !== undefined)
+        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true;
+    return pos.program !== undefined && shellProgram.test(pos.program.basename);
+}
+export function shellScanDeclineOf(pos, acceptedStreamTargets) {
+    if (pos.refusal !== undefined) {
+        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true ? undefined : "unreadable_program_position";
+    }
+    return argvReentryUnjudged(pos, acceptedStreamTargets) ? "stream_fed_operands" : undefined;
+}
 export function programPositionRefusalSentence(refusal) {
     switch (refusal.kind) {
         case "option_at_program_position":

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

@@ -1,4 +1,5 @@
 import { type ShellSegmentConnector } from "./bash-lexer.js";
+import { type ShellScanDecline } from "./bash-program-position.js";
 /**
  * Bare command names `bash_readonly` permits out of the box, ALSO the default reversible set for the
  * The {@link import("./fs-bash.js").bashReversibilityProbe} classifier. **Coarse first filter, NOT a security
@@ -31,7 +32,6 @@ import { type ShellSegmentConnector } from "./bash-lexer.js";
  * value-taking options defeat the stdin-floor operand count without a per-verb option-value model
  * — those are a follow-on slice, not a silent drop.
  */
-export { NOT_AUTO_ALLOWED } from "./bash-program-position.js";
 export type { ShellSegmentConnector } from "./bash-lexer.js";
 export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
 /**
@@ -174,7 +174,7 @@ export interface ShellCompoundSegments {
  * drift in a segmentation is drift in what a deny rule is even looking at.
  *
  * Three steps, in this order and load-bearing:
- *  1. WHOLE-STRING hard reject of {@link SHELL_SEGMENT_HARD_REJECT} — redirection, substitution,
+ *  1. WHOLE-STRING hard reject ({@link hardRejectReason}) — redirection, substitution,
  *     subshells, escapes, line breaks. This is what makes step 3's quote mask EXACT: with those
  *     characters gone, `'`/`"` pairing is the entirety of quoting, so the mask's regions are exactly
  *     bash's quoted regions and the unquoted connectors are exactly bash's command boundaries. Callers
@@ -524,7 +524,10 @@ export declare function resolveOperandSpellings(base: string | undefined, operan
  *  here-document, a here-string or a literal in-root stdin file; a directory change (which then makes every relative
  *  stdin literal in the command unjudged). A substitution body (`$(…)`, backticks, `<(…)`) is judged on its own: green
  *  under the compound walk, or exempt under this whitelist; a here-document body is text, not commands. */
-export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): boolean;
+export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>, boundary: BashReadonlyRootBoundary | undefined, 
+/** The {@link ShellScanDecline} members THIS SEAT reads as evidence (tables and argument: `fs-bash.ts`); one
+ *  the table omits ends the scan with "exempt". */
+declinesAreEvidence: ReadonlySet<ShellScanDecline>): boolean;
 /**
  * The home directory's VARIABLE spellings, SUBSTITUTED with the declared value before a read face segments the
  * command: `$HOME` / `${HOME}` at the START of a word (an empty quote pair before it included), unquoted or
@@ -602,6 +605,10 @@ export interface OutOfRootReadGateVerdict {
      *  operand is placed against a base bash has already left, so no path can be named honestly. Read it
      *  as display/triage evidence; emptiness is not "not gated". */
     readonly paths: readonly string[];
+    /** Did the deployment's DENY judge speak about an operand this command names? The other half of the same
+     *  question, over the very same readers, in a second pass WITH the deny judge — which is what lets the
+     *  containment answer above stay deny-free and keep its `paths` contract. Absent ⇔ it said nothing. */
+    readonly denied?: true;
 }
 /** Test seam for the lockstep pin that the launcher table (the ONE launcher truth, in the program-position
  *  reader's module) stays a SUBSET of the rule lane's curated `BARE_INTERPRETER_NAMES`. Exported for that one

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

@@ -1,7 +1,6 @@
 import { hasWin32AliasedComponent, isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf, withinAnyRoot } from "./safety.js";
 import { lexShellText, literalTildeSpelling, quoteMask, substitutionsInHeredocBody, SUBSTITUTION_PLACEHOLDER, wordsOf, } from "./bash-lexer.js";
-import { ASSIGNMENT_WORD, COMMAND_LAUNCHERS, NOT_AUTO_ALLOWED, SHELL_BLOCK_WORDS, argvReentryUnjudged, isBareControlWord, programBasename, programPositionRefusalSentence, readProgramPosition, } from "./bash-program-position.js";
-export { NOT_AUTO_ALLOWED } from "./bash-program-position.js";
+import { ASSIGNMENT_WORD, COMMAND_LAUNCHERS, NOT_AUTO_ALLOWED, SHELL_BLOCK_WORDS, argvReentryUnjudged, isBareControlWord, programPositionRunsShell, shellScanDeclineOf, programBasename, programPositionRefusalSentence, readProgramPosition, } from "./bash-program-position.js";
 export const BASH_READONLY_DEFAULT_ALLOW = [
     "ls", "cat", "head", "tail", "wc", "pwd", "echo", "whoami", "uname",
     "grep", "cut", "tr", "basename", "dirname", "stat", "du", "df", "which",
@@ -52,7 +51,8 @@ export function coarseReadonlyCheck(command, allow, options) {
         return `command "${parsed.name}" is not in the read-only allowlist`;
     return undefined;
 }
-const SHELL_SEGMENT_HARD_REJECT = /[<>$()`\n\r\\]/;
+const SHELL_SEGMENT_QUOTE_BLIND_REJECT = /[<>()`\n\r\\]/;
+const SHELL_EXPANSION_CHARS = /[$]/;
 export function carriesShellRedirection(text) {
     return SHELL_REDIRECTION_OPERATORS.test(text);
 }
@@ -78,10 +78,25 @@ function rejectedSansRedirection(source) {
     if (redirectionPrecedesConnector(source)) {
         return "a redirection followed by `|`, `&` or `;` is not allowed — the operator's own characters cannot be told apart from a command boundary";
     }
+    return hardRejectReason(source, true);
+}
+function hardRejectReason(source, tolerateRedirection) {
+    const reason = tolerateRedirection
+        ? "command/variable substitution, subshells, escapes, and line breaks are not allowed"
+        : "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed";
     for (const ch of source) {
-        if (SHELL_SEGMENT_HARD_REJECT.test(ch) && !SHELL_REDIRECTION_OPERATORS.test(ch)) {
-            return "command/variable substitution, subshells, escapes, and line breaks are not allowed";
-        }
+        if (SHELL_SEGMENT_QUOTE_BLIND_REJECT.test(ch) && !(tolerateRedirection && SHELL_REDIRECTION_OPERATORS.test(ch)))
+            return reason;
+    }
+    if (!SHELL_EXPANSION_CHARS.test(source))
+        return undefined;
+    const mask = quoteMask(source);
+    for (let i = 0; i < source.length; i++) {
+        if (!SHELL_EXPANSION_CHARS.test(source[i]))
+            continue;
+        if (mask.balanced && mask.openedBy[i] === "'")
+            continue;
+        return reason;
     }
     return undefined;
 }
@@ -91,8 +106,10 @@ export function splitShellCompoundSegments(source, options) {
         if (refused !== undefined)
             return { reject: refused };
     }
-    else if (SHELL_SEGMENT_HARD_REJECT.test(source)) {
-        return { reject: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
+    else {
+        const refused = hardRejectReason(source, false);
+        if (refused !== undefined)
+            return { reject: refused };
     }
     const scanned = options?.trailingTerminator !== "keep" ? source.replace(/;\s*$/, "") : source;
     const lexed = lexShellText(scanned, { mode: "strict" });
@@ -239,8 +256,8 @@ function tokensMoveBase(toks) {
     return pos.refusal !== undefined || pos.program?.basename === "cd";
 }
 const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi|a|mk|ya|pdk|c|tc)?sh|eval|source|\.|parallel)$/;
-export function refusedCommandMayRead(command, allow, boundary) {
-    return !refusedCommandExempt(command, allow, boundary, 0);
+export function refusedCommandMayRead(command, allow, boundary, declinesAreEvidence) {
+    return !refusedCommandExempt(command, allow, boundary, declinesAreEvidence, 0);
 }
 const STDIN_ONLY_READER_FLAGS = new Map([
     ["cat", /^-[AbeEnstTuv]+$/],
@@ -262,7 +279,7 @@ function whitelistSegment(segment) {
         redirects: tokens.filter((t) => t.kind === "redirect"),
     };
 }
-function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside = false) {
+function refusedCommandExempt(command, allow, boundary, declinesAreEvidence, depth, baseMovedOutside = false) {
     if (depth > 4)
         return false;
     const lexed = lexShellText(command, { mode: "lenient" });
@@ -282,12 +299,21 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
         }
         segments.push(whitelistSegment(segment));
     }
+    let declined;
+    for (const { words } of segments) {
+        const pos = readProgramPosition(words);
+        if (programPositionRunsShell(pos, SHELL_REENTRY_PROGRAM_RE))
+            return false;
+        const decline = shellScanDeclineOf(pos, XARGS_TARGETS_ACCEPTED_UNJUDGED);
+        if (decline !== undefined && declinesAreEvidence.has(decline))
+            return false;
+        declined ??= decline;
+    }
+    if (declined !== undefined)
+        return true;
     const baseMoved = baseMovedOutside ||
         segments.some(({ words }) => {
-            const pos = readProgramPosition(words);
-            if (pos.refusal !== undefined)
-                return true;
-            const runs = pos.program?.basename;
+            const runs = readProgramPosition(words).program?.basename;
             return runs === "cd" || (runs !== undefined && UNMODELLED_BASE_MOVERS.has(runs));
         });
     for (const body of bodies) {
@@ -296,7 +322,7 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
             (walked.undecidedPaths?.length ?? 0) === 0 && (walked.unresolvedOperands?.length ?? 0) === 0 && (walked.recursiveReadPaths?.length ?? 0) === 0;
         if (fullyGreen)
             continue;
-        if (!refusedCommandExempt(body, allow, boundary, depth + 1, baseMoved))
+        if (!refusedCommandExempt(body, allow, boundary, declinesAreEvidence, depth + 1, baseMoved))
             return false;
     }
     const stdinFileJudgedInside = (word) => {
@@ -353,8 +379,6 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
             if (r.op === "<" && !stdinFileJudgedInside(r.target?.folded))
                 return false;
         const pos = readProgramPosition(words);
-        if (pos.refusal !== undefined)
-            return false;
         for (const k of words.folded.keys()) {
             const word = words.folded[k];
             if (ASSIGNMENT_WORD.test(word) && /\$\(|`/.test(word) && (pos.assignments.includes(k) || pos.launchers.some((l) => l.index < k)))
@@ -365,24 +389,16 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
         if (program === undefined) {
             if (pos.launchers.length === 0)
                 continue;
-            if (argvReentryUnjudged(pos, XARGS_TARGETS_ACCEPTED_UNJUDGED))
-                return false;
             if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index, pos.assignments))
                 return false;
             continue;
         }
         if (program.name.includes(SUBSTITUTION_PLACEHOLDER) || /[$`]/.test(program.name))
             return false;
-        if (SHELL_REENTRY_PROGRAM_RE.test(program.basename))
-            return false;
-        if (pos.launchers.length > 0) {
-            if (argvReentryUnjudged(pos, XARGS_TARGETS_ACCEPTED_UNJUDGED))
+        if (pos.launchers.length > 0 && !listed(program.basename)) {
+            if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index, pos.assignments))
                 return false;
-            if (!listed(program.basename)) {
-                if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index, pos.assignments))
-                    return false;
-                continue;
-            }
+            continue;
         }
         const head = program.basename;
         if (head === "cd" || UNMODELLED_BASE_MOVERS.has(head))
@@ -455,12 +471,12 @@ function longOptionNameOf(tok) {
 function isLongOptionAbbrevOf(name, full) {
     return full.startsWith(name);
 }
-function isGrepPatternFlagToken(tok) {
+function suppliesFirstOperandSlot(slot, tok) {
     if (tok.startsWith("--")) {
         const long = longOptionNameOf(tok);
-        return long !== undefined && (isLongOptionAbbrevOf(long, "regexp") || isLongOptionAbbrevOf(long, "file"));
+        return long !== undefined && slot.suppliedByLongNames.some((full) => isLongOptionAbbrevOf(long, full));
     }
-    return /^-[A-Za-z0-9]*[ef]/.test(tok);
+    return new RegExp(`^-[A-Za-z0-9]*[${slot.suppliedByLetters}]`).test(tok);
 }
 function isGrepClusterFileStdin(tok) {
     if (tok.startsWith("--") || !/^-[A-Za-z0-9]/.test(tok))
@@ -534,6 +550,7 @@ const VERB_OPTION_SLOTS = {
             regexp: "pattern",
         },
         longOptionalValue: { color: "label", colour: "label", context: "count" },
+        firstOperand: { kind: "pattern", suppliedByLetters: "ef", suppliedByLongNames: ["regexp", "file"] },
         longPlain: [
             "basic-regexp", "byte-offset", "count", "dereference-recursive", "extended-regexp",
             "files-with-matches", "files-without-match", "fixed-strings", "help", "ignore-case", "initial-tab",
@@ -579,6 +596,7 @@ const VERB_OPTION_SLOTS = {
         shortPlain: "nrEszu",
         longValue: { expression: "script", file: "path", "line-length": "count" },
         longOptionalValue: { "in-place": "label" },
+        firstOperand: { kind: "script", suppliedByLetters: "ef", suppliedByLongNames: ["expression", "file"] },
         longPlain: [
             "debug", "follow-symlinks", "help", "null-data", "posix", "quiet", "regexp-extended", "sandbox",
             "separate", "silent", "unbuffered", "version", "zero-terminated",
@@ -1670,7 +1688,8 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     }
     else {
         const eoo = args.indexOf("--");
-        const patternSuppliedByFlag = name === "grep" && (eoo === -1 ? args : args.slice(0, eoo)).some(isGrepPatternFlagToken);
+        const firstOperandSlot = VERB_OPTION_SLOTS[name]?.firstOperand;
+        const firstOperandSuppliedByFlag = firstOperandSlot !== undefined && (eoo === -1 ? args : args.slice(0, eoo)).some((t) => suppliesFirstOperandSlot(firstOperandSlot, t));
         let sawOperand = false;
         let sawArgvOperand = false;
         let endOfOptions = false;
@@ -1718,12 +1737,12 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
                     continue;
                 }
             }
-            const isGrepPatternSlot = name === "grep" && !patternSuppliedByFlag && !sawOperand;
+            const inFirstOperandSlot = firstOperandSlot !== undefined && !firstOperandSuppliedByFlag && !sawOperand;
             sawOperand = true;
             if (k >= argvOperandsStartAt)
                 sawArgvOperand = true;
             if (t === "-") {
-                if (isGrepPatternSlot)
+                if (inFirstOperandSlot)
                     continue;
                 const m = RECURSIVE_READ_FORMS[slotVerb];
                 if (m === undefined || m.dashIsStdin === true) {
@@ -1734,8 +1753,14 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
                     positionalOperands.push(t);
                 continue;
             }
-            if (isGrepPatternSlot)
+            if (inFirstOperandSlot) {
+                const named = slotValueCandidates(t, firstOperandSlot.kind);
+                for (const c of named)
+                    judgeOperand(c, argGlobs(k));
+                if (named.length > 0 && k >= argvOperandsStartAt)
+                    positionalOperands.push(t);
                 continue;
+            }
             if (k >= argvOperandsStartAt)
                 positionalOperands.push(t);
             judgeOperand(t, argGlobs(k));
@@ -1987,7 +2012,8 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
         if (!(pipeFed[si] ?? false)) {
             const floor = STDIN_FILE_FLOOR[name];
             const restArgs = toks.slice(1);
-            const grepPatternSuppliedByFlag = name === "grep" && restArgs.some(isGrepPatternFlagToken);
+            const floorFirstOperandSlot = VERB_OPTION_SLOTS[name]?.firstOperand;
+            const floorSlotSuppliedByFlag = floorFirstOperandSlot !== undefined && restArgs.some((t) => suppliesFirstOperandSlot(floorFirstOperandSlot, t));
             let sawNonFlagOperand = false;
             let hasStdinDash = false;
             let operandCount = 0;
@@ -2013,10 +2039,10 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
                         if (t.startsWith("-") && t !== "-")
                             continue;
                     }
-                    const isGrepPatternPosition = name === "grep" && !grepPatternSuppliedByFlag && !sawNonFlagOperand;
+                    const inFirstOperandSlot = floorFirstOperandSlot !== undefined && !floorSlotSuppliedByFlag && !sawNonFlagOperand;
                     sawNonFlagOperand = true;
                     operandCount++;
-                    if (isGrepPatternPosition)
+                    if (inFirstOperandSlot)
                         continue;
                     if (t === "-") {
                         hasStdinDash = true;
@@ -2329,10 +2355,13 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
         if (baseMoved)
             return { gated: true, paths: [] };
         const verdict = evaluateReadBoundary(readers, containmentOnly, false, readerReach);
-        return verdict.outOfRootRead === true ? { gated: true, paths: verdict.outOfRootPaths ?? [] } : NOT_GATED;
+        const denied = boundary.denyMatch === undefined ? false : evaluateReadBoundary(readers, boundary, false, readerReach).readDenied === true;
+        if (verdict.outOfRootRead === true)
+            return { gated: true, paths: verdict.outOfRootPaths ?? [], ...(denied ? { denied: true } : {}) };
+        return denied ? { gated: false, paths: [], denied: true } : NOT_GATED;
     };
     const direct = judge(command);
-    if (direct.gated)
+    if (direct.gated || direct.denied === true)
         return direct;
     const shape = POLL_LOOP_SHAPE.exec(command.trim());
     return shape !== null ? judge(shape[3]) : NOT_GATED;

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

@@ -3,6 +3,7 @@ import { type TaskRegistry } from "../../core/task-registry.js";
 import { type CwdRef } from "./fs-shared.js";
 import type { ReversibilityVerdict } from "../../core/types.js";
 import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
+import { type ShellScanDecline } from "./bash-program-position.js";
 /**
  * A parsed-command classifier for the `bash` tool, exposed as a
  * `ToolSpec.reversibilityProbe`. A full shell is treated as egress+irreversible by DEFAULT; this probe is the
@@ -60,6 +61,27 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * 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;
+/**
+ * ONE rule, TWO TABLES: which {@link ShellScanDecline} a SEAT reads as read evidence. A decline names no word,
+ * so it is never the boundary DECLARING anything about a path.
+ *
+ * The READ-BOUNDARY seat is what the default/off doctrine and a bypass mode mount ALONE: there "not mandated"
+ * is VOUCHED, so a decline must count as evidence or a read nobody judged runs silently (`<out-of-root> |
+ * xargs cat` at zero asks — a closed P0). It keeps both. The CLASSIFY seat composes the same boundary with the
+ * SHAPE classifier, which refuses all these shapes anyway: the only question left is whether a stored answer
+ * may retire the ask. It keeps NEITHER — empty by the argument, not by omission.
+ * THE COST, stated rather than mitigated: once that ask is retired, an out-of-root or deny-listed read HIDDEN
+ * inside such a command is not asked again. A command's words are not the argv its programs receive (a stream
+ * is re-split by its consumer, an unread option may move the working directory first, stdin text is a command
+ * line nobody parsed), so a scan of them cannot be the guarantee it was claimed to be — three independently
+ * exploitable shapes measured that. "A read the boundary objects to is never retired by a stored rule" does
+ * NOT hold on the classify seat for this class, and holds unchanged elsewhere; below it is the execution
+ * environment's sandbox. One word-level check survives on both seats and is not part of the trade: a token the
+ * scan DID read naming a path outside the roots still gates the call ({@link classifyOutOfRootReadGate}).
+ */
+export declare const BOUNDARY_SEAT_DECLINE_EVIDENCE: ReadonlySet<ShellScanDecline>;
+/** The classify doctrine's table — see above; empty by the argument. */
+export declare const CLASSIFY_SEAT_DECLINE_EVIDENCE: ReadonlySet<ShellScanDecline>;
 /**
  * The READ-BOUNDARY seat of the full shell: a `ToolSpec.reversibilityProbe` that answers exactly ONE
  * question — does the deployment's read boundary object to where this command reads? — and nothing about

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

@@ -13,7 +13,8 @@ import { boundaryIsTheSandbox, canonicalPathIsAuthoritative, hasDestroy, isIsola
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, stripCwdSentinel, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
-import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, refusedCommandMayRead, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, refusedCommandMayRead, classifySimpleCommandReadBoundary, } from "./bash-readonly-classifier.js";
+import { NOT_AUTO_ALLOWED, SHELL_SCAN_DECLINES } from "./bash-program-position.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 const RECURSIVE_CAUSE_MAX_PATHS = 3;
 const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
@@ -27,8 +28,8 @@ function operandFamily(paths) {
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? bashClassifyDefaultAllow());
     const judge = (args, command, resolved, offers) => {
-        const boundaryGate = (verdict) => readBoundaryMandate(command, allowSet, resolved, verdict);
-        const outOfRootGate = () => readBoundaryMandate(command, allowSet, resolved, {});
+        const boundaryGate = (verdict) => readBoundaryMandate(command, allowSet, resolved, verdict, CLASSIFY_SEAT_DECLINE_EVIDENCE);
+        const outOfRootGate = () => readBoundaryMandate(command, allowSet, resolved, {}, CLASSIFY_SEAT_DECLINE_EVIDENCE);
         const backgrounded = isBackgroundShellCall(args);
         const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
         if (backgrounded)
@@ -46,7 +47,7 @@ export function bashReversibilityProbe(allow, boundary) {
         if (loop.reason === undefined)
             return { reversible: true };
         const seatOffer = (verdict) => (offers ? readRootCandidateOf(verdict) : {});
-        if (boundaryDeclared(loop) || unjudgedRead(command, allowSet, resolved, loop))
+        if (boundaryDeclared(loop) || unjudgedRead(command, allowSet, resolved, loop, CLASSIFY_SEAT_DECLINE_EVIDENCE))
             return { reversible: false, mandated: true, ...seatOffer(loop) };
         const refusedCause = recursiveReadCause(detailed);
         return { reversible: false, ...boundaryGate(detailed), ...seatOffer(detailed), ...(refusedCause !== undefined ? { cause: refusedCause } : {}) };
@@ -86,24 +87,30 @@ function shellCommandOf(args) {
 function isBackgroundShellCall(args) {
     return args?.run_in_background === true;
 }
-function readBoundaryMandate(command, allowSet, resolved, verdict) {
+export const BOUNDARY_SEAT_DECLINE_EVIDENCE = new Set(SHELL_SCAN_DECLINES);
+export const CLASSIFY_SEAT_DECLINE_EVIDENCE = new Set();
+function readBoundaryMandate(command, allowSet, resolved, verdict, declineEvidence) {
     if (resolved === undefined)
         return {};
-    if (denyJudgeSpoke(verdict) || unjudgedRead(command, allowSet, resolved, verdict))
+    if (denyJudgeSpoke(verdict) || unjudgedRead(command, allowSet, resolved, verdict, declineEvidence))
         return { mandated: true };
-    return classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
+    const named = classifyOutOfRootReadGate(command, allowSet, resolved);
+    return named.gated || named.denied === true ? { mandated: true } : {};
 }
 function boundaryUnjudged(verdict) {
     return verdict.refusedWhole === true || (verdict.unresolvedOperands !== undefined && verdict.unresolvedOperands.length > 0);
 }
-function unjudgedRead(command, allowSet, resolved, verdict) {
+function unjudgedRead(command, allowSet, resolved, verdict, declineEvidence) {
     if (verdict.unresolvedOperands !== undefined && verdict.unresolvedOperands.length > 0)
         return true;
     if (verdict.refusedWhole !== true)
         return false;
-    if (refusedCommandMayRead(command, allowSet, resolved))
+    if (refusedCommandMayRead(command, allowSet, resolved, declineEvidence))
         return true;
-    return resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated;
+    if (resolved === undefined)
+        return false;
+    const named = classifyOutOfRootReadGate(command, allowSet, resolved);
+    return named.gated || named.denied === true;
 }
 function recursiveReadCause(detailed) {
     const recursive = detailed.recursiveReadPaths;
@@ -121,7 +128,7 @@ export function bashReadBoundaryProbe(boundary) {
     const allowSet = new Set(bashClassifyDefaultAllow());
     const judge = (command, resolved, offers) => {
         const seatVerdict = (verdict) => {
-            if (boundaryDeclared(verdict) || unjudgedRead(command, allowSet, resolved, verdict)) {
+            if (boundaryDeclared(verdict) || unjudgedRead(command, allowSet, resolved, verdict, BOUNDARY_SEAT_DECLINE_EVIDENCE)) {
                 const cause = recursiveReadCause(verdict);
                 return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
             }
@@ -145,7 +152,7 @@ export function bashReadBoundaryProbe(boundary) {
         const offerFrom = (verdict) => (offers ? readRootCandidateOf(verdict) : {});
         if (mandated !== undefined)
             return { ...mandated, ...offerFrom(detailed), ...offerFrom(loop) };
-        if (readBoundaryMandate(command, allowSet, resolved, detailed).mandated === true)
+        if (readBoundaryMandate(command, allowSet, resolved, detailed, BOUNDARY_SEAT_DECLINE_EVIDENCE).mandated === true)
             return { reversible: false, mandated: true };
         return compoundVerdict ?? loopVerdict ?? { reversible: true };
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.23.0",
+  "version": "7.23.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/wire-changes/core@7.23.1.json

@@ -0,0 +1,205 @@
+{
+  "repo": "core",
+  "version": "7.23.1",
+  "from": "0f45a3d257bcdb5f38faaa7c75a6fa1298685402",
+  "to": "v7.23.1",
+  "added": [],
+  "removed": [],
+  "changed": [],
+  "narrowed": [
+    {
+      "id": "F2",
+      "source": "behaviorFlips.summary",
+      "text": "FEWER CARDS, both seats (#892): a verb's FIRST OPERAND can be a slot its grammar fills rather than a file. `VerbOptionSlots.firstOperand` (`src/tools/fs/bash-readonly-classifier.ts:1562`) is a declaration ROW — grep's `pattern` (`:1621`), sed's `script` (`:1675`) — read with the same `OptionValueKind` vocabulary the option slots already use, and ONE reader (`suppliesFirstOperandSlot` `:1401`) answers \"did an option supply this slot instead\" for both walks that needed it (the boundary walk `:3441`/`:3459-3466`, the stdin-floor walk `:4007`/`:4012`). Rules: -1 (the verb-named branch and its private predicate are gone; a verb with no row keeps an ordinary first operand). WHO NEEDS IT: `sed -n '/error/p' app.log` — an everyday log-reading line whose script, spelled with slashes because it opens with an address regexp, was read as the absolute path `/error/p`, found outside the roots and mandated; the `-e` spelling of the same script was already exempt, so one invocation had two readings. WHO IS HURT: a probe pinned at `mandated` for a path-shaped sed script, including its deny-listed spelling — `sed <deny row>` and `sed -l <deny row>` now drop their card on the default/off and bypass tiers. COMPENSATION: the token is not a file under EITHER implementation (it is the script where `-l` takes no value and `-l`'s length argument where it does), so the verb-blind reading that recorded it as a read was an over-approximation, not a protection; the narrowing is exactly one operand wide and no other verb grew a row."
+    },
+    {
+      "id": "G2",
+      "source": "criteria.title",
+      "text": "#892 — a verb's first operand can be a slot its grammar fills, and the narrowing is exactly one operand wide"
+    }
+  ],
+  "closedSetMembers": [
+    {
+      "set": "QuoteOpen",
+      "at": [
+        "src/tools/fs/bash-lexer.ts:109"
+      ],
+      "newSet": true,
+      "added": [
+        "\"",
+        "'"
+      ],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    },
+    {
+      "set": "SHELL_SCAN_DECLINES",
+      "at": [
+        "src/tools/fs/bash-program-position.ts:346"
+      ],
+      "newSet": true,
+      "added": [
+        "stream_fed_operands",
+        "unreadable_program_position"
+      ],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": false
+    }
+  ],
+  "closedSetsUnreadable": [],
+  "typeKeys": [],
+  "declarationMoves": [
+    {
+      "name": "NOT_AUTO_ALLOWED",
+      "kind": null,
+      "onSurface": false,
+      "from": [
+        "src/tools/fs/bash-program-position.ts",
+        "src/tools/fs/bash-readonly-classifier.ts"
+      ],
+      "to": [
+        "src/tools/fs/bash-program-position.ts"
+      ]
+    },
+    {
+      "name": "traceHookCrash",
+      "kind": null,
+      "onSurface": false,
+      "from": [
+        "src/core/runner/gate-exit.ts"
+      ],
+      "to": [
+        "src/core/gate-crash-trace.ts"
+      ]
+    }
+  ],
+  "mintMoves": [],
+  "criteriaObserves": [
+    {
+      "kind": "typeMember",
+      "name": "AskRequest.message",
+      "assertions": [
+        "G5.a",
+        "G5.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "AskRequest.origin",
+      "assertions": [
+        "G5.a",
+        "G5.b",
+        "G5.c"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "AskRequest.ruleOffersAbsence",
+      "assertions": [
+        "G1.d",
+        "G3.b",
+        "G3.d",
+        "G4.c"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "AskRequest.toolName",
+      "assertions": [
+        "G5.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "BashReadonlyRootBoundary.denyMatch",
+      "assertions": [
+        "G1.c"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "CompoundReadonlyVerdict.outOfRootPaths",
+      "assertions": [
+        "G1.b",
+        "G2.a",
+        "G2.b",
+        "G2.c",
+        "G2.d"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "CompoundReadonlyVerdict.readDenied",
+      "assertions": [
+        "G1.b",
+        "G2.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "ReadRootGrantCandidate.dir",
+      "assertions": [
+        "G4.e"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "ReversibilityVerdict.mandated",
+      "assertions": [
+        "G1.a",
+        "G1.b",
+        "G1.c",
+        "G2.a",
+        "G2.b",
+        "G2.c",
+        "G2.d",
+        "G3.a",
+        "G3.c",
+        "G3.d",
+        "G3.e",
+        "G4.a",
+        "G4.b",
+        "G4.c",
+        "G4.d",
+        "G6.a",
+        "G6.c",
+        "G7.a",
+        "G7.b",
+        "G7.c"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "ReversibilityVerdict.readRootCandidate",
+      "assertions": [
+        "G4.e"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "ReversibilityVerdict.reversible",
+      "assertions": [
+        "G1.a",
+        "G3.a",
+        "G3.e",
+        "G4.b",
+        "G4.d",
+        "G6.a",
+        "G6.b",
+        "G7.a",
+        "G7.c"
+      ]
+    }
+  ],
+  "consumersHint": {
+    "cli": [],
+    "server": [],
+    "sdk": [],
+    "note": "scanned cli@879f19e9 server@1b232ad6 sdk@6209e5e — a name listed is MENTIONED there today, which is evidence of consumption, not proof of it"
+  },
+  "breakingCount": 0,
+  "breakingItems": [],
+  "toResolvedAt": "29f9c021a132099c91933bd71a58bd4da716bfac"
+}