@sema-agent/core 7.24.4 → 7.25.1

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

@@ -1,5 +1,4 @@
 import { type SegmentTokens, 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
@@ -314,148 +313,10 @@ export interface BashReadonlyRootBoundary {
  * is the read-only verdict; everything else is a demotion.
  */
 export interface CompoundReadonlyVerdict {
-    /** Demotion reason (the same string {@link classifyCompoundReadonly} returns), or undefined. */
+    /** Demotion reason (the same string {@link classifyCompoundReadonly} returns), or undefined: the
+     *  command's SHAPE is not one the classify doctrine auto-allows. WHERE the command reads is not this
+     *  verdict's business — that is the gate's shell read station (`shell-read-check.ts`). */
     reason?: string;
-    /** Set when a listed reader's statically resolved path operand lies outside the roots. With `reason` the
-     *  containment sentence itself, the roots were the SOLE obstacle (every segment a listed reader, no
-     *  blocking/device/guarded-form arm fired, every operand resolved) and the narrow "allow reading from <dir>"
-     *  approval would make the command auto-allowable; with `reason` a SHAPE refusal (follow mode, a device, a
-     *  blocking stdin read, a guarded verb form, multi-cd) or an UNRESOLVABLE-operand refusal (another operand
-     *  the walk could not read) the finding rides beside the sentence — the read of that path is the same read,
-     *  so the boundary's objection is stated either way, while the command stays refused after any grant. */
-    outOfRootRead?: true;
-    /** The resolved out-of-root paths, de-duplicated, in first-seen order. Present iff `outOfRootRead`. */
-    outOfRootPaths?: readonly string[];
-    /** B-057 — an operand matched the deployment's read deny judge (`BashReadonlyRootBoundary.denyMatch`):
-     *  the demotion was raised by a DECLARED read boundary, not by the classifier's own caution. The probe
-     *  reads it to mint `mandated` — a stored allow rule or the read-only shell arm may retire a classify-
-     *  tier question, never one the read face itself asked. Structural sibling of `outOfRootRead`. */
-    readDenied?: true;
-    /** The matched operand (resolved spelling) and the pattern — present iff {@link readDenied} (the
-     *  `outOfRootRead`/`outOfRootPaths` idiom), so a refusal CARD names the target without parsing prose. */
-    readDeniedPath?: string;
-    readDeniedPattern?: string;
-    /**
-     * The paths this scan resolved INSIDE the roots (de-duplicated, first-seen order), i.e. the
-     * candidates a caller holding a filesystem should re-check with symlinks resolved. Absent when there
-     * are none.
-     *
-     * Why the ALLOW side is reported at all: containment here is LEXICAL (see
-     * {@link resolveOperandLexically}), so "inside the roots" means the written spelling has an in-root
-     * prefix — a symlink inside a root that points out of it (`<root>/vendor` → `/etc`) passes. Closing
-     * that needs `realpath`, which this function deliberately cannot do (synchronous, pure, no
-     * ExecutionEnv). Carrying the candidates is the seam: the ENFORCING caller canonicalizes them and
-     * re-compares (`createBashReadonlyTool` does exactly this — a target that resolves out of root is
-     * refused there). Typically 0-2 entries per command.
-     *
-     * Present on BOTH arms, not only the allow arm: a command can name one out-of-root path AND one
-     * in-root candidate (`cat /etc/passwd inroot.txt`), and a caller that EXEMPTS the out-of-root path
-     * (the engine's own overflow spool, or a non-canonical spelling that resolves back inside) then goes
-     * on to execute — with the other candidate still unverified. The field is what that caller checks
-     * before running, whichever way the lexical verdict came out.
-     *
-     * Includes bare-word operands (`cat linkfile.txt`), which are NOT lexical out-of-root candidates —
-     * the "a name with no separator can only reach the working directory" argument is true lexically and
-     * false under symlinks, so those are exactly the entries a filesystem-holding caller must resolve.
-     * They never affect {@link reason}: a bare word cannot demote and does not here either.
-     */
-    checkedPaths?: readonly string[];
-    /**
-     * Operands whose spelling carries an UNEXPANDED glob (`*`, `?`, `[…]`, unquoted). Lexical
-     * containment is not decidable for them: the shell expands the pattern AFTER this verdict is made, and
-     * inside a root an expansion can land on a symlink that points out of it (`cat *` where the directory
-     * holds a link to an out-of-root file — reproduced end-to-end, not a theoretical shape).
-     *
-     * They are NOT in {@link checkedPaths}: a filesystem-holding resolver answers the unexpanded spelling
-     * with its deepest EXISTING ancestor — the directory itself — and reports nothing escaping, which is
-     * precisely the false "resolved, inside" answer this field exists to prevent.
-     *
-     * CONSUMER CONTRACT. A gate that auto-allows on containment must treat a verdict carrying this field as
-     * UNDECIDED: ask, or expand the patterns itself against the filesystem and judge every match. The
-     * read-only judgement itself is unaffected — `ls *` genuinely writes nothing, and {@link reason} stays
-     * absent — because a hard refusal here would take a routine idiom away from every caller, including the
-     * ones that CAN resolve it. The engine's own `bash_readonly` leg is such a caller: it expands and
-     * resolves each match before executing, so it keeps running these commands unprompted.
-     *
-     * `cd` is the one exception, and it fails closed: a glob there cannot be expanded into the single
-     * directory the compound face must track as the new working directory, so it demotes (see {@link reason}).
-     *
-     * ALSO carries the {@link recursiveReadPaths} entries (a subset): both families are operands whose
-     * real read set is not in the command text, and the consumer contract above ("non-empty ⇒ ask, or
-     * resolve yourself") is stated over this one field so an auto-allow gate cannot honour one family
-     * and miss the other.
-     */
-    undecidedPaths?: readonly string[];
-    /** The KERNEL spellings of the {@link checkedPaths} / {@link undecidedPaths} entries whose operand
-     *  traverses `..`: the same absolute path, `..` UNCOLLAPSED ({@link OperandSpellings.spelled}). A fold
-     *  names a different file whenever a parent step follows a symlink — `<root>/link/../x` is
-     *  `dirname(realpath(link))/x` to the kernel, `<root>/x` to the text. Absent when nothing traverses
-     *  `..`, and never a replacement: a resolving caller judges these BESIDE the folded entries, list for
-     *  list. Containment, deny judgment and every `reason` here stay decided on the FOLDED form — this file
-     *  is zero-I/O, and only a caller holding the filesystem can tell the two apart. */
-    checkedSpellings?: readonly string[];
-    /** The kernel spellings of {@link undecidedPaths} — see {@link checkedSpellings}. */
-    undecidedSpellings?: readonly string[];
-    /** The kernel spellings of {@link outOfRootPaths} — see {@link checkedSpellings}. A caller GRANTING
-     *  anything off a resolved out-of-root path judges this beside it: the two can disagree about whether
-     *  the target is back inside. */
-    outOfRootSpellings?: readonly string[];
-    /**
-     * Operands (written spellings) the walk could NOT resolve at all — a `~user` form, a `~` under no declared
-     * home, an argument the shell rewrites (brace/variable/command expansion), a `cd` target it cannot follow
-     * (`cd -`, bare `cd`, a pattern). The STRUCTURAL form of the unresolvable sentence: `reason` carries the
-     * first one's sentence, this member every one of them, and both survive whatever other sentence (a shape
-     * refusal) takes precedence. CONSUMER CONTRACT: non-empty ⇒ the boundary could not read where the command
-     * reads — a fail-closed ask, never a vouch (plain on the classify seat, whose classifier asks beside it; MANDATED on the
-     * boundary-only seat, where nothing else would ask).
-     */
-    unresolvedOperands?: readonly string[];
-    /**
-     * The grammar gate refused the WHOLE command before the walk ran (an escape, a substitution, a subshell, a
-     * redirection, a line break — see {@link rejectedSansRedirection} and the compound gate): no operand was judged,
-     * and what the shell would run is not knowable from the text (a reader can be spelled `ca\t`, fed by `<`, or hidden
-     * in `$(…)`). CONSUMER CONTRACT: present ⇒ the boundary judged nothing — MANDATED on both probe seats (a name-reading
-     * arm or a stored allow rule must not retire a read nobody judged). Structure, never the sentence.
-     */
-    refusedWhole?: true;
-    /**
-     * Operands of a RECURSIVE/EXPANDING read form (`grep -r`, `ls -R`, `du`, … — see
-     * {@link RECURSIVE_READ_FORMS}) judged with a {@link BashReadonlyRootBoundary.denyMatch} seat wired.
-     * The judge sees only the operand's own resolved spelling, but a recursive verb reads the operand's whole
-     * SUBTREE — `grep -r x /home/user` touches `/home/user/.ssh/*` while the judged spelling matches nothing.
-     * The traversal's reach set is therefore not covered by the lexical check at all, and with zero I/O
-     * "provably not a directory" does not exist — so every such operand is UNDECIDED (no directory guessing,
-     * no bounded pre-check: both would be a false "resolved, inside" of exactly the kind
-     * {@link undecidedPaths} exists to prevent).
-     *
-     * Subset of {@link undecidedPaths} (same consumer contract: ask, never auto-allow); carried separately so
-     * a consumer minting prose can name the recursive-reach cause rather than the glob one. Minted ONLY when
-     * `denyMatch` is wired: without a judge there is nothing the traversal bypasses. EVERY face wiring the
-     * seat sees this field, the `bash_readonly` shell included, and answers it by its OWN rule for a demotion
-     * — that face has no approval channel, so what it cannot establish it REFUSES (an unbounded traversal is
-     * the same "the read set is not in the text" finding as a pattern the expander cannot enumerate).
-     */
-    recursiveReadPaths?: readonly string[];
-    /**
-     * The ONE path whose addition to the declared roots would make every objection THIS WALK raised go away,
-     * MEASURED not argued: the walk runs again with the proposed root in place and the value is offered only
-     * if that walk has no objection left (`..` spellings are excluded on their own account — a folded-vs-kernel
-     * disagreement no replay of the text settles). It rides the containment sentence, and a per-segment NAME
-     * refusal ({@link segmentNameRefusal}), which is not a refusal of the READ; a SHAPE refusal takes it with
-     * it. VALUE: the deepest directory PROPERLY containing every {@link outOfRootPaths} entry, folded (zero
-     * I/O, so a directory contributes its PARENT); where that would contain the declared home or a root, the
-     * single path read is offered VERBATIM instead ({@link outOfRootGrantCoversExactPath}) — `cat
-     * ~/.gitconfig` is one file and the alternative is a card with no way out. Contract:
-     * {@link import("../../core/tool-spec.js").ReadRootGrantCandidate}.
-     */
-    outOfRootGrantCandidate?: string;
-    /** {@link outOfRootGrantCandidate} is the path the command NAMED, offered verbatim, rather than a
-     *  directory containing it — minted where that directory would have handed out the home or the workspace.
-     *  A consumer adds the string ITSELF; expanding it into a directory pattern is what this prevents. */
-    outOfRootGrantCoversExactPath?: true;
-    /** The verdict's {@link reason} is a per-segment NAME refusal (an unlisted program, a path-prefixed name,
-     *  a control word before a reader) rather than the walk's own sentence or a refused SHAPE. */
-    segmentNameRefusal?: true;
 }
 /**
  * The single minting point for the out-of-root-read approval option text, so a gate rendering
@@ -468,18 +329,6 @@ 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;
 /** Programs whose operands are NEVER filesystem paths, so no operand of theirs is checked:
  *  `echo`'s words are literal text, `which`'s are PATH lookups, `tr`'s are character sets, and
  *  `basename`/`dirname` do pure string surgery on a path without ever opening it. Everything else —
@@ -550,27 +399,6 @@ export declare function resolveOperandSpellings(base: string | undefined, operan
  *  exactly as `sh` does, and a deployment that meets one of them meets the whole member. GNU `parallel` is a member
  *  for the reason it is not a launcher: it hands a BUILT command line to a shell. */
 export declare const SHELL_REENTRY_PROGRAM_RE: RegExp;
-/** Whether a command the grammar gate REFUSED WHOLE may READ a file the boundary never judged. The answer is the
- *  complement of a WHITELIST: the command is exempt only when every part of it is a shape the scan fully understands
- *  and none of those shapes reads a file outside the walk's reach — everything else is read evidence, so a token the
- *  scan does not understand mandates rather than passes. Exempt shapes, per segment: a program that reads no path
- *  (`echo`, `python3 -`, `tee out.txt`, an unlisted program); `cat` / `wc` with payload-free flags whose input is a
- *  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 | 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>): RefusedCommandScan;
-/** What ONE scan of a refused command found — TWO facts, because a seat's table answers only the first. `mayRead`
- *  is the whitelist's verdict ("may read a file the boundary never judged"), which a seat turns into a MANDATE.
- *  `declined` is the scan's own report that it could not judge where a segment reads AT ALL
- *  ({@link SHELL_SCAN_DECLINES}), recorded BEFORE the seat's table and so the SAME on every seat: a seat omitting
- *  that decline has ruled only that an ANSWERER may retire the ask, never that nothing happened. */
-export interface RefusedCommandScan {
-    readonly mayRead: boolean;
-    readonly declined: boolean;
-}
 /**
  * Does this RAW token carry a metacharacter the shell EXPANDS, unquoted?
  *
@@ -866,6 +694,9 @@ export interface SedScriptNames {
     readonly writes: readonly string[];
     readonly commands: readonly string[];
     readonly executesPatternSpace: boolean;
+    /** Why the script's names are NOT all here, when they are not: the script is supplied from a FILE whose text is not
+     *  in the command (one reading), or no reading could parse it to its end. Absent when every name is listed. */
+    readonly unread?: string;
 }
 /**
  * Does this verb's SCRIPT SLOT put a file name or a command line somewhere the walk's operand reading
@@ -980,12 +811,14 @@ export declare function inlineProgramClause(model: InlineProgramModel, args: rea
  *  command name. Names-only traversals (`find`, `ls -R`, `du`, `tree`, an archive write) are in the table
  *  and answer `false` here — see {@link RecursiveReadFormModel.discloses}. */
 export declare function segmentSelectsRecursiveRead(name: string, args: readonly string[]): boolean;
-export declare function assignmentWordPayload(word: string): {
+/** `raw` is the word as WRITTEN; it defaults to the folded spelling, which is the reading that expands most. */
+export declare function assignmentWordPayload(word: string, raw?: string): {
     kind: "value";
     value: string;
 } | {
     kind: "unresolved";
     reason: string;
+    value?: string;
 } | undefined;
 /** WHICH programs are DECLARED not to open the value of a `NAME=value` ARGUMENT — an allow-list, because
  *  the other polarity was measured false. `make PREFIX=/usr/local`, `cmake -D…`, `docker run -e HOME=/root`
@@ -1003,9 +836,9 @@ export declare function assignmentWordPayload(word: string): {
 export declare const ASSIGNMENT_VALUE_NOT_PATHS: ReadonlySet<string>;
 /** The program the shell will RUN here and where its OWN argv begins — the two seats
  *  {@link HeadedSegment.argvProgram} / {@link HeadedSegment.argvFrom} carry, from one reader so they cannot
- *  disagree. Both assignment spellings are stripped BEFORE the program-position reader runs: it does not
- *  read `NAME+=value` as an assignment (quoting makes `'A+=x'` a command NAME on folded text), so a leading
- *  append word arrives AS the program and hides any launcher — measured on `A+=x env B=<outside> <prog>`. */
+ *  disagree. The LEADING assignments (both spellings) are the program-position reader's own step, so this
+ *  seat no longer strips them a second time: a second strip read the quoted `'A+=x'` as an assignment the
+ *  one reader calls a program name, which is two readers with two answers. */
 export declare function argvProgramOf(tokens: SegmentTokens): {
     program: string;
     from: number;
@@ -1037,83 +870,12 @@ export declare function foldHomeVariableSpelling(command: string, homeDir: strin
  * out-of-root signal; the boundary scan below only ever converts a would-be READ-ONLY verdict into a
  * demotion, which is why omitting `boundary` reproduces the name-only behaviour exactly.
  */
-export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary, 
-/** The poll-loop face passes `iterated:true` over a body REPLICATED
- *  `beats` times — a single cd repeated per iteration is a legitimate accumulating shift, not the
- *  ">1 cd = ask for clarity" compound CC refuses (a `for` loop is a sema-only face; CC asks for any
- *  loop). It suppresses ONLY that multi-cd refuse; every read is still threaded + boundary-judged
- *  against its real per-iteration base, so the escape a climbing loop opens is still caught. */
-opts?: {
-    readonly iterated?: boolean;
+export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, 
+/** The environment's declared home, so the `$HOME` / `${HOME}` word spellings fold the way the read station
+ *  folds them before the shape is read. Nothing else is read off it: WHERE a command reads is the station's. */
+boundary?: {
+    readonly homeDir?: string;
 }): CompoundReadonlyVerdict;
-/**
- * The read boundary ALONE, for the `bash_readonly` face.
- *
- * `bash_readonly` declares `effect:"read"` and is admitted by {@link coarseReadonlyCheck}, an argv[0]-NAME
- * filter: path operands were invisible to it, so an allowlisted reader could name any file on the host
- * (`cat /etc/passwd`) and — with no approval gate on the read effect — get it. The compound face above
- * answers a different question for a different consumer (a gate that can ASK); this face answers only
- * "does this command read outside the roots", leaving the availability arms (blocking stdin, `tail -f`,
- * device reads) untouched so a caller wiring it gains the boundary and nothing else.
- *
- * PRECONDITION: `command` has already passed {@link coarseReadonlyCheck}, i.e. it is ONE simple command
- * with no connectors, redirects, substitutions or escapes anywhere. That is what makes a whitespace split
- * exact here. Feeding it an unvetted compound is not unsafe (the connector ends up glued to a token, which
- * only ever produces MORE path candidates and a stricter verdict) but the reason text would name a
- * nonsense command, so callers vet first.
- *
- * Returns the same {@link CompoundReadonlyVerdict} the compound face returns: `reason === undefined` means
- * every path operand resolved inside the roots. A caller with no approval channel treats BOTH demotion
- * kinds — resolved-and-outside (`outOfRootRead`, with `outOfRootPaths`) and could-not-resolve (reason
- * only) — as a refusal; there is nowhere to degrade to.
- *
- * SCOPE OF THE GUARANTEE (both directions): "inside the roots" is LEXICAL containment — see
- * {@link resolveOperandLexically}. A symlink inside a root that points out of it reads as in-root here,
- * so this face bounds where a command may NAME a file, not where the kernel will ultimately take it.
- * A deployment that needs filesystem-true containment resolves the operands itself, and this
- * verdict hands it the list to resolve ({@link CompoundReadonlyVerdict.checkedPaths}, on both arms).
- * The engine's own shell legs are that caller on a local env — the read-only face before it runs an
- * allowlisted command, the full face after its gate allowed one.
- */
-export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
-/**
- * What {@link classifyOutOfRootReadGate} answers. Two members and one rule between them:
- * `paths` is EVIDENCE for a `gated` answer, never the answer itself. A caller decides on `gated`.
- */
-export interface OutOfRootReadGateVerdict {
-    /** True ⇔ this command is structurally gated on the read boundary. */
-    readonly gated: boolean;
-    /** The RESOLVED out-of-root paths behind a `gated` answer. EMPTY when the gate fired for a reason
-     *  that resolves none — a working-directory move this walk cannot follow, after which every relative
-     *  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.
-     *
-     *  It carries the FINDING, not a boolean: this is the arm a command the grammar gate refused WHOLE
-     *  (`cat .env > out.txt`, a subshell, a substitution) reaches, and there the compound verdict carries no
-     *  deny fields at all — so a caller disclosing the hit has nowhere else to read the path and the pattern
-     *  from, and said nothing. The second pass already computed both; throwing them away was the whole bug. */
-    readonly denied?: {
-        readonly path: string;
-        readonly pattern: string;
-    };
-    /** The reader operands this pass RESOLVED and placed inside the roots, plus the expansions it parsed but
-     *  cannot enumerate — the candidates an execute-time recheck must canonicalize.
-     *
-     *  Published because this pass reads SHAPES the compound walk hands nothing out for: a launcher whose
-     *  program it cannot name (`env -- cat f`, `sudo -u root cat f`), a stream-fed one (`… | xargs cat f`).
-     *  There the compound verdict carries no candidates at all, so the recheck had nothing to resolve and an
-     *  in-root symlink to a deny-listed target RAN after an approval — while the same read spelled without
-     *  the launcher was refused. Same operands, same judge, one more pass allowed to hand them over.
-     *
-     *  NOT the out-of-root ones: those ride {@link paths}, they are what the boundary RAISED, and a leg that
-     *  re-refused them would be a second adjudicator of a decision already made. */
-    readonly checked: readonly string[];
-    readonly undecided: readonly string[];
-}
 /** Working-directory moves {@link evaluateReadBoundary} does NOT model. `cd` is deliberately absent —
  *  it IS modelled (the walk threads the base through it), which is the whole difference: a move the
  *  walk follows keeps the verdict decidable, and one it cannot follow does not. */
@@ -1124,61 +886,6 @@ export declare const UNMODELLED_BASE_MOVERS: ReadonlySet<string>;
  *  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
- * name a path outside the allowed directories?
- *
- * {@link classifyCompoundReadonlyDetailed} answers a different question — "is this whole command
- * auto-allowable?" — and it stops at the FIRST obstacle. That makes its `outOfRootRead` signal precise
- * for the shape it was built for and silent for three shapes where the containment fact is just as
- * true: a compound whose OTHER segment is not a listed reader (`cat <outside> | curl …` refuses on the
- * unlisted name and never reaches the boundary walk at all), an operand that ALSO matches the
- * sensitive-path deny judge (whose more-specific reason short-circuits the walk), and a recursive form
- * whose traversal root sits outside. This face answers the containment question in all of them, so a
- * consumer that must treat "reads outside the roots" as a STRUCTURAL gate rather than as one possible
- * reason for a demotion has one predicate to read.
- *
- * What it judges and what it does not:
- *  · EVERY segment, under one of two readings. A segment whose PROGRAM is in `allow` — the deployment's
- *    own read-command table, the analogue of the reference implementation's path-restricted command
- *    list — is read with that verb's own slots (a pattern operand, a recursive form). The program is
- *    read after the two decorations the shell itself strips before choosing it (leading `NAME=value`
- *    assignments, a path prefix), so `/bin/cat` is judged as `cat`: recognizing readers by their literal
- *    spelling alone let a rule the persisted grammar admits (`Bash(/bin/cat:*)`) carry the exact read
- *    this gate exists for. Every OTHER segment is judged whole and verb-blind — its tokens are offered
- *    as path candidates under a head with no per-verb behaviour — because a program not on the table is
- *    not a program known to read nothing: skipping it made the gate silent for every reader the
- *    deployment had not enumerated, which is the one thing a name table cannot enumerate.
- *  · `cd` is judged whether or not the deployment listed it, because the walk MODELS it (it threads the
- *    base across segments) and dropping it would place every later relative operand against a base bash
- *    has already left. A move the walk cannot model (`pushd`/`popd`) is not silently tolerated either —
- *    see the `paths`-less gated answer below.
- *  · BOTH halves from ONE extraction, in TWO passes: the CONTAINMENT pass alone is deny-free, because
- *    {@link BashReadonlyRootBoundary.denyMatch} outranks containment inside the walk and returns early,
- *    which would let a deny-listed operand HIDE the fact that it also sits outside the roots. A SECOND
- *    pass over the SAME readers does carry that judge, and is what answers `denied` (see below).
- *  · `face: "open"` is honoured: under the open read face containment is structurally satisfied, an
- *    out-of-roots operand is not a finding, and this gate is silent — a full-read deployment sees no
- *    gate here, by the same one mechanism the face already defines.
- *
- * Answers `gated` with the resolved paths behind it, and NOT gated for every whole-string refusal (an
- * unparseable grammar, a substitution, a redirection) and for an operand that cannot be resolved
- * statically. That silence is the honest answer, not a miss: those shapes name no concrete directory,
- * so there is nothing for a path gate to be about.
- *
- * It deliberately does NOT reuse {@link CompoundReadonlyVerdict}: one arm of this face is gated while
- * resolving no path at all (the unmodelled working-directory move), and that arm cannot fill an
- * `outOfRootPaths` whose contract says the entries ARE resolved out-of-root paths. A result type that
- * can say "gated, and here is nothing" is the one that lets the arm exist without lying.
- *
- * The bounded poll-loop grammar is judged through its BODY, the same text that face re-classifies —
- * without it, the one control structure this file auto-allows would be the one shape whose reads no
- * gate looks at. The body is judged in a single pass (the per-iteration `cd` accumulation the
- * auto-allow face models is not replicated here): a loop that climbs out of the roots over its beats
- * is refused by that face on its own terms, and under-reporting here can only cost a gate, never grant
- * one.
- */
-export declare function classifyOutOfRootReadGate(command: string, allow: ReadonlySet<string>, boundary: BashReadonlyRootBoundary): OutOfRootReadGateVerdict;
 /**
  * Compound read-only classification, reason-only face. Returns the demotion reason, or
  * undefined when the command classifies read-only. ⚠️ `undefined` is NOT "safe to auto-execute":
@@ -1190,7 +897,9 @@ export declare function classifyOutOfRootReadGate(command: string, allow: Readon
  * detailed face when the caller wants to know WHY, e.g. to offer the narrow "allow reading from
  * <dir>" approval); without it the verdict is exactly what it always was.
  */
-export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;
+export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>, boundary?: {
+    readonly homeDir?: string;
+}): string | undefined;
 /**
  * Iteration cap for {@link classifyBoundedReadonlyPollLoop}. The bound must be a LITERAL in the
  * command text (that is what makes "bounded" provable without executing anything); this cap keeps a
@@ -1287,7 +996,9 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  * consequence case by case, the whole command is rejected up front if it carries any such character
  * ({@link NON_ASCII_WHITESPACE}), so the grammar's tokenization and bash's stay identical.
  */
-export declare function classifyBoundedReadonlyPollLoop(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;
+export declare function classifyBoundedReadonlyPollLoop(command: string, allow: ReadonlySet<string>, boundary?: {
+    readonly homeDir?: string;
+}): string | undefined;
 /**
  * The poll-loop face's STRUCTURED verdict — the same {@link CompoundReadonlyVerdict} the compound face
  * returns, so a consumer reads the boundary's structural findings (deny row, containment, recursive or
@@ -1296,4 +1007,6 @@ export declare function classifyBoundedReadonlyPollLoop(command: string, allow:
  * projection. A refusal of the LOOP GRAMMAR itself (not a bounded loop, an unlisted body program, an
  * unvetted sleep) carries no structure: no reader segment was walked.
  */
-export declare function classifyBoundedReadonlyPollLoopDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+export declare function classifyBoundedReadonlyPollLoopDetailed(command: string, allow: ReadonlySet<string>, boundary?: {
+    readonly homeDir?: string;
+}): CompoundReadonlyVerdict;