@sema-agent/core 7.17.7 → 7.19.0

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

@@ -0,0 +1,142 @@
+/**
+ * The ONE reader of a segment's PROGRAM POSITION: which argv word names the program bash runs, and what stands in
+ * front of it — bare control words with their declared options, environment assignments, a launcher chain.
+ *
+ * Every face that judges a command by its program (the compound walk, the single-command boundary face, the
+ * refused-command whitelist, the poll loop's base-move check) reads this ONE function. A face that needs the
+ * answer it cannot give reads {@link ProgramPosition.refusal}: a declarative record of why the program is not
+ * readable, minted into one sentence by {@link programPositionRefusalSentence}. Reading less than this reader
+ * does (an option skipped, a chain member missed) is how one face used to vouch for a program another refused.
+ */
+import type { SegmentTokens } from "./bash-lexer.js";
+/** The verdict every unresolvable / out-of-root / unbounded finding ends on. The findings differ in what
+ *  they found; the consequence is one consequence, and a copy that drifts reads as a second rule. */
+export declare const NOT_AUTO_ALLOWED = "\u2014 not auto-allowed";
+/** argv[0] as the program bash will resolve it: `/usr/bin/cat` and `cat` are one name. */
+export declare function programBasename(word: string): string;
+/** A leading `NAME=value` word: an assignment bash applies to the command's environment rather than a
+ *  program name. Same shape the exit-code reader in `fs-bash.ts` skips for the same reason. */
+export declare const ASSIGNMENT_WORD: RegExp;
+/** Shell control words that stand BEFORE a command: transparent for the boundary walk (the command behind them is
+ *  judged). */
+export declare const SHELL_CONTROL_PREFIXES: ReadonlySet<string>;
+/** Shell block words that name no command of their own (a loop head, a block close, a case head). */
+export declare const SHELL_BLOCK_WORDS: ReadonlySet<string>;
+/** A control word is a keyword only when bash sees it BARE: `'if'` / `"do"` / `\\!` are command names (a program
+ *  looked up on PATH, whose failure changes nothing), so a quoted or escaped spelling never counts as one. */
+export declare function isBareControlWord(toks: SegmentTokens, i: number, words: ReadonlySet<string>): boolean;
+/**
+ * Programs that turn their STANDARD INPUT into the OPERANDS of another program, and EXEC that program directly.
+ *
+ * The same class as the shell re-entry programs, one level down: there the unseen text is COMMANDS; here the
+ * command's name IS visible and its argv is not — `echo <path> | xargs cat` opens a file no token of this walk
+ * ever named, because the operand arrives on a stream. The membership criterion is that behaviour and only that
+ * behaviour; a program that consumes stdin as DATA (`sort`, `wc`, a reader the deployment never listed) is NOT a
+ * member, because its stdin never becomes a filename. Spelled as a pattern — these are program names, never tool
+ * names.
+ *
+ * "EXECS DIRECTLY" is what separates this class from the shell re-entry class, and it is why GNU `parallel` is
+ * NOT a member: parallel BUILDS A COMMAND LINE and hands it to a shell, and with no command word at all it runs
+ * each input line as a command — so parallel belongs to the shell re-entry class and is refused whole with no
+ * exemption at all. A spelling this file has no name for (an aliased or wrapped `xargs`) is judged as any other
+ * unlisted program is — the name-table floor the re-entry class records for itself.
+ */
+export declare const ARGV_REENTRY_PROGRAM_RE: RegExp;
+/** The program an {@link ARGV_REENTRY_PROGRAM_RE} launcher runs when the chain names none: `xargs` defaults to
+ *  `echo`, which is why a bare one reads nothing. */
+export declare const ARGV_REENTRY_DEFAULT_PROGRAM = "echo";
+/**
+ * What a launcher declares about its OWN options: each exact spelling with its ARITY — `0` for a switch, `1` for an
+ * option whose value is the next token. A fused `--name=value` and every spelling not in the map fall to the refusal
+ * (the conservative side, and the verdict those spellings always had); a `1` with no token left to take is not
+ * readable either.
+ */
+export interface LauncherRow {
+    /** Consulted ONLY for the launcher the command line itself names — a bare keyword in front of the command
+     *  (`time -p …`) or the written command word (`"time" -p …`, `X=1 time -p …`, `/usr/bin/time -p …`). A launcher
+     *  nested behind another (`env time -p …`) is that launcher's operand, and its options refuse: resolving past
+     *  them would turn a whole refusal into an ordinary walked segment — a widening, where every other read of this
+     *  table only ever finds MORE program to judge. */
+    readonly optionArity: ReadonlyMap<string, 0 | 1>;
+}
+/**
+ * The ONE launcher truth: programs that RUN ANOTHER PROGRAM named in ordinary argv tokens, so a declared reader can
+ * sit behind one (`env cat <path>`, `sudo cat <path>`, `timeout 5 cat <path>`), each with the option grammar this
+ * file reads for it.
+ *
+ * Membership is the key set. A row with no declared options means every option-shaped word after that launcher
+ * refuses ("which program runs is not readable without the launcher's option table") — the answer every launcher
+ * but `time` has always had, now stated per row rather than by omission. Declaring a row's options is a behaviour
+ * decision with its own criteria; adding a launcher is a row.
+ *
+ * `time` carries both spellings a deployment can meet: the shell builtin takes `-p` alone, and the standalone
+ * program adds a format, an output file, and three switches.
+ *
+ * A deliberate SUBSET of the rule lane's own `BARE_INTERPRETER_NAMES`, mirrored rather than imported because that
+ * module imports the classifier — the dependency runs that way, and a cycle is a worse problem than a mirror whose
+ * subset relation is pinned by test. GNU `parallel` is absent for the reason the shells are absent: it does not run
+ * a program named in token-visible argv — it BUILDS a command line and hands it to a shell — so it is a shell
+ * re-entry member instead. Language interpreters and shells are excluded as a scope statement: their program
+ * argument is a script path or a quoted code string, not a token-visible program with token-visible operands.
+ */
+export declare const LAUNCHER_TABLE: ReadonlyMap<string, LauncherRow>;
+/** The launcher names — derived from the table, never kept beside it. */
+export declare const COMMAND_LAUNCHERS: ReadonlySet<string>;
+export declare const PROGRAM_POSITION_REFUSAL_KINDS: readonly ["option_at_program_position", "control_syntax_at_program_position"];
+export type ProgramPositionRefusalKind = (typeof PROGRAM_POSITION_REFUSAL_KINDS)[number];
+/** Why the program could not be read — a closed set, each member minted into one sentence. `owner` is the word
+ *  that took the offending token: the control word or the first launcher of the chain. */
+export type ProgramPositionRefusal = {
+    readonly kind: "option_at_program_position";
+    readonly owner: string;
+    readonly option: string;
+} | {
+    readonly kind: "control_syntax_at_program_position";
+    readonly owner: string;
+    readonly word: string;
+};
+export interface ProgramPosition {
+    /** Indices of the bare control words stripped in front (`!`, `if`, `time`, …), in order; their declared options
+     *  are skipped with them. */
+    readonly controlWords: readonly number[];
+    /** The first index past the control words and their options — the WRITTEN command word: an assignment, a
+     *  launcher, or the program itself. `undefined` when nothing stands there. */
+    readonly written: number | undefined;
+    /** The leading `NAME=value` words at `written`. */
+    readonly assignments: readonly number[];
+    /** The launcher chain past the assignments, in order (basenames); empty when the written word is not a launcher. */
+    readonly launchers: readonly {
+        readonly index: number;
+        readonly name: string;
+    }[];
+    /** Some chain member is an argv re-entry program: the program's operands arrive on a stream. */
+    readonly argvFromStdin: boolean;
+    /** The chain ends ON the re-entry program (nothing follows it), so it runs its default program. */
+    readonly runsDefaultProgram: boolean;
+    /** The program bash RUNS: the first word past the chain. `name` is the folded word as written, `basename` what
+     *  bash resolves (`/usr/bin/cat` is `cat`). `undefined` when the chain names none or the read was refused. */
+    readonly program: {
+        readonly index: number;
+        readonly name: string;
+        readonly basename: string;
+    } | undefined;
+    /** Why no program could be read; `undefined` beside `program: undefined` means the chain simply names none. */
+    readonly refusal: ProgramPositionRefusal | undefined;
+}
+/**
+ * Read the program position of one segment's argv words.
+ *
+ * In order: bare control words and the options their launcher rows declare; the written word; its leading
+ * assignments; then either the program itself or a launcher chain — whose first member's declared options are read
+ * too (it is the launcher the line names), and inside which an assignment, a bare number, a nested launcher and an
+ * argv re-entry program are stepped over, an option-shaped word (a lone `-` included — `env - <program>` clears
+ * the environment and the table does not say so) refuses, and shell control syntax refuses. An option-shaped
+ * WRITTEN word (judged on its basename, as the program it names) refuses the same way: it is where the program
+ * would be, and the word in front took an option no row explains.
+ */
+export declare function readProgramPosition(toks: SegmentTokens): ProgramPosition;
+/** Does this program position hand a program operands the walk cannot see? True when the chain re-enters through
+ *  stdin AND the program it runs is not declared no-path. ONE reading, shared by every consumer. */
+export declare function argvReentryUnjudged(pos: ProgramPosition, noPathPrograms: ReadonlySet<string>): boolean;
+/** 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

@@ -0,0 +1,125 @@
+export const NOT_AUTO_ALLOWED = "— not auto-allowed";
+export function programBasename(word) {
+    return word.includes("/") ? (word.split("/").pop() ?? word) : word;
+}
+export const ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
+export const SHELL_CONTROL_PREFIXES = new Set(["!", "if", "then", "elif", "else", "while", "until", "do", "time"]);
+export const SHELL_BLOCK_WORDS = new Set(["for", "select", "case", "esac", "fi", "done", "function", "coproc", "[[", "]]", "in"]);
+export function isBareControlWord(toks, i, words) {
+    const word = toks.folded[i];
+    return word !== undefined && toks.raw[i] === word && words.has(word);
+}
+export const ARGV_REENTRY_PROGRAM_RE = /^xargs$/;
+export const ARGV_REENTRY_DEFAULT_PROGRAM = "echo";
+const NO_DECLARED_OPTIONS = { optionArity: new Map() };
+export const LAUNCHER_TABLE = new Map([
+    ["env", NO_DECLARED_OPTIONS], ["command", NO_DECLARED_OPTIONS], ["builtin", NO_DECLARED_OPTIONS], ["exec", NO_DECLARED_OPTIONS],
+    ["noglob", NO_DECLARED_OPTIONS], ["xargs", NO_DECLARED_OPTIONS], ["busybox", NO_DECLARED_OPTIONS],
+    ["sudo", NO_DECLARED_OPTIONS], ["doas", NO_DECLARED_OPTIONS], ["pkexec", NO_DECLARED_OPTIONS], ["su", NO_DECLARED_OPTIONS],
+    ["runuser", NO_DECLARED_OPTIONS], ["chroot", NO_DECLARED_OPTIONS], ["setpriv", NO_DECLARED_OPTIONS],
+    ["nohup", NO_DECLARED_OPTIONS], ["nice", NO_DECLARED_OPTIONS], ["ionice", NO_DECLARED_OPTIONS], ["chrt", NO_DECLARED_OPTIONS],
+    ["taskset", NO_DECLARED_OPTIONS], ["stdbuf", NO_DECLARED_OPTIONS], ["timeout", NO_DECLARED_OPTIONS],
+    ["time", {
+            optionArity: new Map([
+                ["-p", 0], ["-a", 0], ["-v", 0], ["-q", 0], ["--portability", 0], ["--append", 0], ["--verbose", 0], ["--quiet", 0], ["--help", 0], ["--version", 0],
+                ["-f", 1], ["-o", 1], ["--format", 1], ["--output", 1],
+            ]),
+        }],
+    ["watch", NO_DECLARED_OPTIONS], ["setsid", NO_DECLARED_OPTIONS], ["flock", NO_DECLARED_OPTIONS], ["unshare", NO_DECLARED_OPTIONS],
+    ["nsenter", NO_DECLARED_OPTIONS], ["script", NO_DECLARED_OPTIONS], ["numactl", NO_DECLARED_OPTIONS], ["prlimit", NO_DECLARED_OPTIONS],
+    ["systemd-run", NO_DECLARED_OPTIONS],
+    ["strace", NO_DECLARED_OPTIONS], ["ltrace", NO_DECLARED_OPTIONS], ["valgrind", NO_DECLARED_OPTIONS], ["firejail", NO_DECLARED_OPTIONS],
+    ["bwrap", NO_DECLARED_OPTIONS],
+]);
+export const COMMAND_LAUNCHERS = new Set(LAUNCHER_TABLE.keys());
+function pastLauncherOptions(launcher, folded, i) {
+    const row = LAUNCHER_TABLE.get(launcher);
+    if (row === undefined)
+        return i;
+    for (;;) {
+        const tok = folded[i];
+        const arity = tok === undefined ? undefined : row.optionArity.get(tok);
+        if (arity === undefined)
+            return i;
+        if (arity === 1 && folded[i + 1] === undefined)
+            return i;
+        i += arity + 1;
+    }
+}
+const LAUNCHER_BARE_NUMBER = /^\d+[smhd]?$/;
+export const PROGRAM_POSITION_REFUSAL_KINDS = ["option_at_program_position", "control_syntax_at_program_position"];
+export function readProgramPosition(toks) {
+    const { folded } = toks;
+    const controlWords = [];
+    let i = 0;
+    while (i < folded.length && isBareControlWord(toks, i, SHELL_CONTROL_PREFIXES)) {
+        const controlWord = folded[i];
+        controlWords.push(i);
+        i = pastLauncherOptions(controlWord, folded, i + 1);
+    }
+    const none = (written, assignments, refusal) => ({ controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: undefined, refusal });
+    if (i >= folded.length)
+        return none(undefined, []);
+    const written = i;
+    const assignments = [];
+    while (i < folded.length && ASSIGNMENT_WORD.test(folded[i])) {
+        assignments.push(i);
+        i++;
+    }
+    const head = folded[i];
+    if (head === undefined)
+        return none(written, assignments);
+    const basename = programBasename(head);
+    if (basename.startsWith("-") && basename !== "-") {
+        const owner = controlWords.length > 0 ? folded[controlWords[controlWords.length - 1]] : head;
+        return none(written, assignments, { kind: "option_at_program_position", owner, option: head });
+    }
+    if (!COMMAND_LAUNCHERS.has(basename)) {
+        return { controlWords, written, assignments, launchers: [], argvFromStdin: false, runsDefaultProgram: false, program: { index: i, name: head, basename }, refusal: undefined };
+    }
+    const launchers = [{ index: i, name: basename }];
+    const owner = head;
+    let argvFromStdin = ARGV_REENTRY_PROGRAM_RE.test(basename);
+    let lastReentry = argvFromStdin ? i : -1;
+    const chain = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram: lastReentry === folded.length - 1, program, refusal });
+    for (let j = pastLauncherOptions(basename, folded, i + 1); j < folded.length; j++) {
+        const t = folded[j];
+        if (ASSIGNMENT_WORD.test(t) || LAUNCHER_BARE_NUMBER.test(t))
+            continue;
+        const wordBasename = programBasename(t);
+        if (ARGV_REENTRY_PROGRAM_RE.test(wordBasename)) {
+            argvFromStdin = true;
+            lastReentry = j;
+            continue;
+        }
+        if (COMMAND_LAUNCHERS.has(wordBasename)) {
+            launchers.push({ index: j, name: wordBasename });
+            continue;
+        }
+        if (t.startsWith("-"))
+            return chain(undefined, { kind: "option_at_program_position", owner, option: t });
+        if (SHELL_CONTROL_PREFIXES.has(wordBasename) || SHELL_BLOCK_WORDS.has(wordBasename)) {
+            return chain(undefined, { kind: "control_syntax_at_program_position", owner, word: wordBasename });
+        }
+        return chain({ index: j, name: t, basename: wordBasename });
+    }
+    return chain(undefined);
+}
+export function argvReentryUnjudged(pos, noPathPrograms) {
+    if (!pos.argvFromStdin)
+        return false;
+    const runs = pos.program?.basename ?? (pos.runsDefaultProgram ? ARGV_REENTRY_DEFAULT_PROGRAM : undefined);
+    return runs === undefined || !noPathPrograms.has(runs);
+}
+export function programPositionRefusalSentence(refusal) {
+    switch (refusal.kind) {
+        case "option_at_program_position":
+            return `"${refusal.owner}" is given the option "${refusal.option}" where the program it runs would be — which program runs is not readable without that word's option table ${NOT_AUTO_ALLOWED}`;
+        case "control_syntax_at_program_position":
+            return `"${refusal.owner}" is given shell control syntax ("${refusal.word}") where the program it runs would be ${NOT_AUTO_ALLOWED}`;
+        default: {
+            const exhaustive = refusal;
+            return exhaustive;
+        }
+    }
+}

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

@@ -1,3 +1,4 @@
+import { type ShellSegmentConnector } from "./bash-lexer.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
@@ -30,9 +31,8 @@
  * 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.
  */
-/** The verdict every unresolvable / out-of-root / unbounded finding ends on. The findings differ in what
- *  they found; the consequence is one consequence, and a copy that drifts reads as a second rule. */
-export declare const NOT_AUTO_ALLOWED = "\u2014 not auto-allowed";
+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[];
 /**
  * The CLASSIFY face's default allow set: the shared list PLUS the verbs that are
@@ -140,11 +140,6 @@ 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)?
@@ -184,11 +179,11 @@ export interface ShellCompoundSegments {
  *     own empty-command rule puts the whole string outside its lane — which is what keeps a statement
  *     like "this rule form never matches a command containing a connector" literally true instead of
  *     true-except-for-one-spelling.
- *  3. the quote-aware connector scan over `;` `&&` `||` `|`. A lone `&` is REFUSED rather than split
- *     on: it backgrounds a process that outlives the command, which is not a combinator any face here
- *     is willing to reason about. Unbalanced quoting disables the mask, which degrades to the
- *     quote-blind scan — strictly MORE segments, each of which the caller must still vet, i.e. the
- *     fail-closed direction.
+ *  3. the quote-aware connector scan over `;` `&&` `||` `|` — the strict mode of the ONE lexer
+ *     ({@link lexShellText}). A lone `&` is REFUSED rather than split on: it backgrounds a process that
+ *     outlives the command, which is not a combinator any face here is willing to reason about.
+ *     Unbalanced quoting falls back to the quote-blind scan — strictly MORE segments, each of which the
+ *     caller must still vet, i.e. the fail-closed direction.
  *
  * Empty segments are NOT refused here (`;;`, a leading `;`, a trailing `&&`) — they come back as empty
  * strings, and every caller's per-segment vetting rejects them through its own empty-command rule. The
@@ -200,6 +195,46 @@ export declare function splitShellCompoundSegments(source: string, options?: {
 }): ShellCompoundSegments | {
     reject: string;
 };
+/**
+ * Compound read-only classification for the `bash` CLASSIFY face (shellGate:"classify").
+ * Splits a command on the connector set `;` `&&` `||` `|` and passes every segment through
+ * {@link coarseReadonlyCheck} (the single {@link parseLeadingCommandName} parser + bare-name allowlist).
+ * All segments green ⇒ read-only. Returns a reason when rejected, else undefined.
+ *
+ * G2 — the split CARRIES QUOTE STATE ({@link quoteMask}): a connector character inside a quoted region is
+ * argument text, not a boundary, so `grep -E "error:|BUILD FAILED" x.log | tail -10` is two segments
+ * (`grep …` and `tail -10`) rather than four, and the phantom head `BUILD` no longer decides the verdict.
+ * The whole compound face is what this fixes: a report of an every-command approval prompt on a read-only
+ * monitoring pipeline traced to exactly this — a quoted alternation in a `grep -E` pattern, which is the
+ * ordinary spelling of that idiom.
+ *
+ * Soundness — why the quote-aware split is NOT a relaxation. Backslash/`$`/backtick/subshells/redirection/
+ * line breaks are whole-string rejected first (the two neutral forms in {@link EXEMPT_REDIRECTION} are
+ * removed beforehand, and they move no data into any file), so in the residual space `'`/`"` pairing is
+ * the ENTIRETY of quoting and the mask's regions are exactly bash's quoted regions. The unquoted connectors it splits on are therefore exactly bash's command boundaries:
+ * every program bash runs still starts at the head of some segment this classifier vetted, and its argv[0]
+ * is the head token (a token carrying a quote/brace/glob/tilde character is rejected by the parser's
+ * argv[0] metachar rule, and a clean token equals the executed program name). What changes versus the
+ * older quote-blind scan is only that PHANTOM segments — heads manufactured out of quoted text, which no
+ * program was ever going to run — are gone. Those could only ever ADD a rejection, so removing them
+ * removes false demotions and admits no additional program.
+ *
+ * UNBALANCED QUOTING falls back to the quote-blind scan (fail-closed). A string with an unterminated quote
+ * is one bash cannot parse into commands at all, so there is no "true" segmentation to be accurate about;
+ * the blind scan yields strictly MORE segments, each of which must still pass the allowlist.
+ *
+ * A LONE `&` is hard-rejected (not a connector): it backgrounds a process that survives the shell — the node
+ * execution env spools stdio and deliberately leaves descendants alive on completion — escaping TaskStop and
+ * background-lifecycle governance entirely. Backgrounding is not a read-only combinator, even for a listed
+ * reader (`tail -f x &` outlives the call). `|&` falls out of the same scan (its `&` reads as lone → reject).
+ * One TRAILING `;` is stripped (a no-op terminator); any other empty segment (`;;`, leading `;`, trailing
+ * `&&`/`|`) rejects via the parser's empty-command rule.
+ *
+ * NOT here by design: no git/subcommand allowlist — "zero-flag" vetting operates
+ * on pre-expansion text while the shell expands quotes/braces/globs into argv, and the candidate subcommands
+ * are not provably read-only under repo config anyway. Deployments needing those forms must widen via a
+ * dedicated widening decision, not this classifier.
+ */
 /**
  * The READ-BOUNDARY face of the read-only classification (opt-in).
  *
@@ -378,6 +413,21 @@ export interface CompoundReadonlyVerdict {
      * path is unchanged.
      */
     recursiveReadPaths?: readonly string[];
+    /**
+     * The ONE directory whose addition to the declared roots would make every objection this walk raised go
+     * away. It rides the SAME arm as the containment sentence and is dropped wherever that sentence is (a
+     * SHAPE refusal takes both — `tail -f <out-of-root>` stays refused after any grant), and on that arm the
+     * claim is MEASURED, not argued: the walk runs again with the proposed root in place and the directory is
+     * offered only if that walk has no objection left. `..`-traversing spellings are excluded on their own
+     * account ({@link outOfRootSpellings}): that is a disagreement between the folded text and the kernel,
+     * which no replay of the text can settle. VALUE: the deepest directory PROPERLY
+     * containing every {@link outOfRootPaths} entry, folded lexically — zero I/O, so a path that is itself a
+     * directory contributes its PARENT (`ls /etc/ssl` ⇒ `/etc`) where the reference implementation narrows
+     * with a stat; refused rather than widened when the result would be a family root or would contain the
+     * declared home or a declared {@link BashReadonlyRootBoundary.roots} entry. Meaning and spelling
+     * contract: {@link import("../../core/tool-spec.js").ReadRootGrantCandidate}.
+     */
+    outOfRootGrantCandidate?: string;
 }
 /**
  * The single minting point for the out-of-root-read approval option text, so a gate rendering
@@ -390,6 +440,18 @@ export interface CompoundReadonlyVerdict {
  * uses the host's native separator.
  */
 export declare function formatOutOfRootReadApprovalOption(directory: string): string;
+/**
+ * The deepest directory containing both, or `undefined` when they share none (two path families).
+ *
+ * LINEAR, and that is the point: both paths are already folded, so the answer is their common prefix cut
+ * at a separator. Climbing one directory at a time re-folds the whole remaining path each step — the same
+ * answer at quadratic cost, measured at 4.9 s of synchronous work for one 32 KB command naming a
+ * 16 000-segment operand, on a walk that runs BEFORE the gate arms its probe deadline. The family-aware
+ * comparator keeps the last word: a prefix it cannot confirm contains both paths yields no candidate.
+ * Exported for its unit tests — the family confirmation is reachable from a command only through shapes
+ * the compound grammar refuses first, so a command-level pin cannot tell a live guard from an absent one.
+ */
+export declare function deepestCommonDir(a: string, b: string): string | undefined;
 /** Resolve one operand against the boundary's base, WITHOUT touching the filesystem. Returns undefined
  *  when the token cannot be resolved statically — the fail-closed direction, reported as its own
  *  demotion rather than silently treated as in-root.
@@ -516,8 +578,11 @@ export interface OutOfRootReadGateVerdict {
      *  as display/triage evidence; emptiness is not "not gated". */
     readonly paths: readonly string[];
 }
-/** Test seam for the lockstep pin that this mirror stays a SUBSET of the rule lane's curated table.
- *  Exported for that one assertion — production code reads the constant directly. */
+/** 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
+ *  assertion — production code reads the table directly. The containment face ({@link classifyOutOfRootReadGate})
+ *  does NOT look through a launcher: there every segment whose program is not a listed reader is judged whole,
+ *  launcher or not, so looking through one would only narrow what it reads. */
 export declare const COMMAND_LAUNCHERS_FOR_TEST: ReadonlySet<string>;
 /**
  * The OUT-OF-ROOT READ GATE asked as its OWN question: does any listed reader in this command
@@ -672,7 +737,7 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  *  · STDIN-BLOCKING BODY (an availability residual, not a safety one). CLOSED for the shape this note
  *    used to record: a quoted multiword operand like `grep "x y"` read, to the then whitespace-blind
  *    tokenizer, as two operands meeting grep's file floor, while bash passes ONE pattern and no file and
- *    grep blocks on stdin. {@link splitWordsQuoteAware} now counts the operand bash actually passes, so
+ *    grep blocks on stdin. the lexer now counts the operand bash actually passes, so
  *    that command demotes on both this arm and the plain face. What REMAINS residual is the general
  *    statement: this arm inherits whatever the shared availability arms can see, they are best-effort
  *    (an operand that only turns out to be unreadable at run time is not in the text), and a hang is