@sema-agent/core 7.15.0 → 7.17.0

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

@@ -1,22 +1,22 @@
 /**
  * Bare command names `bash_readonly` permits out of the box, ALSO the default reversible set for the
- * design/80 D-2 {@link import("./fs-bash.js").bashReversibilityProbe} classifier. **Coarse first filter, NOT a security
+ * The {@link import("./fs-bash.js").bashReversibilityProbe} classifier. **Coarse first filter, NOT a security
  * boundary**: {@link coarseReadonlyCheck} matches only the command NAME, so a listed command with a
  * writing flag (e.g. `find -delete`, `sort -o`, `tee`) would still write. Such commands are therefore
  * kept OFF this default — the list is curated to commands with NO write/mutation mode under ANY args, so
  * the `effect:"read"` declaration (relied on by wake/resume reconcile + the verifier read-only boundary)
  * AND the classifier's "reversible" promise both stay truthful. The deployment's tool-policy gate is the
- * authoritative control (design/44 §5, council blocker #1); anything that can mutate state or run arbitrary
+ * authoritative control (council blocker #1); anything that can mutate state or run arbitrary
  * code belongs on the full `bash` (effect:write, gated), not here. A deployment may widen this list,
  * accepting that responsibility.
  *
- * design/80 D-2 final-council MAJOR: `date` (`-s`/`--set` → CLOCK_SETTIME), `hostname` (`<name>` → kernel
+ * Deliberately ABSENT: `date` (`-s`/`--set` → CLOCK_SETTIME), `hostname` (`<name>` → kernel
  * hostname), and `file` (`-C -m` → compiles/writes a magic file) were REMOVED — each is read-only by NAME
  * but state-MUTATING with args, which an argv[0]-only filter cannot tell apart. Leaving them in defeated
  * both the `effect:read` truthfulness here and the classifier's irreversibility promise (a `date -s` would
  * auto-allow an irreversible clock jump under `shellGate:"classify"`).
  *
- * backlog #482 (CC parity): rows 3-4 are the CC-anchored expansion — the members of CC's safe-command
+ * Rows 3-4 are the CC-anchored expansion — the members of CC's safe-command
  * set (pretty223.js:420513-420565 `e6s`; identical in the 220 corpus; the 220→245 campaign diff records
  * no change on this face) that satisfy THIS list's curation bar (no write/mutation mode under any args)
  * without new stdin-floor/option-value modeling: pure status/computation printers (`cal`…`sleep` — none
@@ -27,7 +27,7 @@
  * `uniq` (second positional is an OUTPUT file; CC allows a flags-only regex form this filter cannot
  * express), `printf` (builtin `-v var` assigns), `find` (CC allows only a regex excluding
  * `-delete`/`-exec`/…), and the bare-stdin text filters (`od`/`strings`/`nl`/`tsort`/`pr`/…) whose
- * value-taking options defeat the stdin-floor operand count without a per-verb option-value model (#109)
+ * 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
@@ -35,7 +35,7 @@
 export declare const NOT_AUTO_ALLOWED = "\u2014 not auto-allowed";
 export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
 /**
- * backlog #482 slice 2 — the CLASSIFY face's default allow set: the shared list PLUS the verbs that are
+ * The CLASSIFY face's default allow set: the shared list PLUS the verbs that are
  * admissible only where the compound classifier's per-verb judgment runs, and NOT on the shared list's
  * other consumer faces:
  *  · `find` — read-only only when no CC `aCy` dangerous predicate token is present (guard arm);
@@ -123,13 +123,13 @@ export declare function parseLeadingCommandName(command: string, options?: Leadi
  *  with no shell operators. It validates the NAME only (+ blocks operators/path-prefix/env-assignment); it
  *  does NOT inspect arguments for write flags — keeping the allowlist free of write-capable commands and
  *  the policy gate are what make `effect:"read"` truthful. Returns a reason when rejected, else undefined.
- *  design/154: this `effect:"read"` DECLARATION face deliberately stays strict-single-command; only the
+ *  This `effect:"read"` DECLARATION face deliberately stays strict-single-command; only the
  *  classify face ({@link classifyCompoundReadonly} via {@link import("./fs-bash.js").bashReversibilityProbe}) segments compounds. */
 export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>, options?: LeadingCommandNameOptions): string | undefined;
 /**
  * Does this text carry a bare redirection operator — the ONE metacharacter family
- * {@link splitShellCompoundSegments} can be asked to tolerate at its whole-string gate (#490 修①,
- * `redirection: "tolerate"`)?
+ * {@link splitShellCompoundSegments} can be asked to tolerate at its whole-string gate
+ * (`redirection: "tolerate"`)?
  *
  * Exported because the tolerating caller owes a PER-SEGMENT judgement in its place, and that judgement
  * must read the same character class this module tolerated — two hand-kept lists would drift, and a
@@ -162,7 +162,7 @@ export interface ShellCompoundSegments {
  *     bash's quoted regions and the unquoted connectors are exactly bash's command boundaries. Callers
  *     that tolerate a narrow redirection subset (the read-only classify face and its two data-free
  *     spellings) remove those words BEFORE calling; nothing here restores them. `redirection:
- *     "tolerate"` (#490 修①) narrows this step to {@link rejectedSansRedirection} — the mask argument
+ *     "tolerate"` narrows this step to {@link rejectedSansRedirection} — the mask argument
  *     is untouched (`<`/`>` neither quote nor bound) and the refusal moves to the caller's per-segment
  *     vetting via {@link carriesShellRedirection}. The default refuses the whole string as it always did.
  *  2. one trailing `;` is stripped — a no-op terminator, not an empty command. OPTIONAL, because it is
@@ -189,7 +189,7 @@ export declare function splitShellCompoundSegments(source: string, options?: {
     reject: string;
 };
 /**
- * RB-412 — the READ-BOUNDARY face of the read-only classification (opt-in).
+ * The READ-BOUNDARY face of the read-only classification (opt-in).
  *
  * The allowlist vets `argv[0]` only, so until this face existed every listed reader could name ANY
  * path: `ls /etc` and `cat /etc/passwd` classified read-only, and a deployment whose manual-mode shell
@@ -198,7 +198,7 @@ export declare function splitShellCompoundSegments(source: string, options?: {
  * pretty220 @457568) and renders an approval option naming the directory (@905642 (cli250.js:66007)).
  *
  * Supplying this object turns the check ON; omitting it leaves the classifier byte-identical to its
- * pre-RB-412 behaviour, so a consumer pinned to an older calling convention is unaffected.
+ * name-only behaviour, so a consumer pinned to an older calling convention is unaffected.
  */
 export interface BashReadonlyRootBoundary {
     /** Canonical containment roots — the primary root plus any additional allowed directories. An EMPTY
@@ -209,17 +209,18 @@ export interface BashReadonlyRootBoundary {
     /** Base for resolving relative operands. Defaults to `roots[0]`. Callers tracking an observable `cd`
      *  should pass the LIVE working directory, or a `..` operand will be judged against the wrong base. */
     cwd?: string;
-    /** Expansion for a leading `~`. Without it a `~`-rooted operand is unresolvable and demotes (with no
-     *  out-of-root signal — the classifier does not know where it points, which is a different verdict
-     *  from knowing it points outside). */
+    /** Expansion for a leading `~` — and the value the read faces substitute for the `$HOME` / `${HOME}` word
+     *  spellings before segmenting ({@link foldHomeVariableSpelling}). Without it a `~`-rooted operand is unresolvable
+     *  and demotes (with no out-of-root signal — the classifier does not know where it points, which is a
+     *  different verdict from knowing it points outside). */
     homeDir?: string;
-    /** design/199 件B — the sensitive-path read deny judge over LEXICALLY RESOLVED operands: a hit
+    /** The sensitive-path read deny judge over LEXICALLY RESOLVED operands: a hit
      *  demotes the command (ask, never auto-allow), independently of the roots — in-root operands are
      *  judged too. Returns the matched pattern, or null. TWO named residuals, both inherited from this
-     *  classifier's declared purity (synchronous, zero I/O — RB-448/RB-451 state the same scope for the
+     *  classifier's declared purity (synchronous, zero I/O — the same scope stated for the
      *  containment half): ① operand TARGET matching only — no ancestor intersection: the judge sees
      *  the operand's own resolved spelling, never its subtree. The RECURSIVE-reach half of that
-     *  residual has since been narrowed (backlog #222): a listed recursive/expanding verb's path
+     *  residual has since been narrowed: a listed recursive/expanding verb's path
      *  operand under this wired seat rides {@link CompoundReadonlyVerdict.recursiveReadPaths}
      *  (⊂ undecidedPaths), so `grep -r x ~/` no longer auto-allows — it demotes to ask through the
      *  undecided contract. What REMAINS of ① is the form table's stated open set (see the KNOWN OPEN
@@ -230,29 +231,31 @@ export interface BashReadonlyRootBoundary {
      *  (the enforcing/canonicalizing recheck is the bash_readonly leg's job via checkedPaths; the
      *  classify auto-allow lane has no I/O seat by contract). The structured read faces judge BOTH
      *  views (canonical + lexical) — this seat is the shell lane's honest-friction floor, not its
-     *  security boundary (§3.0). The `bash_readonly` face deliberately does NOT wire this seat (its
+     *  security boundary. The `bash_readonly` face deliberately does NOT wire this seat (its
      *  roots containment + command allowlist double gate is the deployment's own read-safety
      *  declaration — v1 ruling). */
     denyMatch?: (resolvedPath: string) => string | null;
-    /** design/199 件A — the resolved read-face containment state. Under "open" the CONTAINMENT half of
+    /** The resolved read-face containment state. Under "open" the CONTAINMENT half of
      *  this boundary is structurally satisfied (an out-of-roots operand is not a demotion; it reports
-     *  as a checked candidate instead), while the deny half above keeps judging in both faces (§2.0).
+     *  as a checked candidate instead), while the deny half above keeps judging in both faces.
      *  Absent ⇒ "roots" (byte-compat). The `bash_readonly` face never passes this seat — its
      *  containment is load-bearing and never opens. */
     face?: "open" | "roots";
 }
 /**
- * RB-412 — the structured verdict of {@link classifyCompoundReadonlyDetailed}. `reason === undefined`
+ * The structured verdict of {@link classifyCompoundReadonlyDetailed}. `reason === undefined`
  * is the read-only verdict; everything else is a demotion.
  */
 export interface CompoundReadonlyVerdict {
     /** Demotion reason (the same string {@link classifyCompoundReadonly} returns), or undefined. */
     reason?: string;
-    /** Set only when the SOLE obstacle to the read-only verdict was the root boundary: every segment is
-     *  an allowlisted reader, no blocking/device/backgrounding arm fired, and the offending arguments are
-     *  statically resolved paths outside the roots. A gate can therefore offer the narrow "allow reading
-     *  from <dir>" approval instead of a generic shell prompt. Absent for every other demotion — an
-     *  unresolvable path deliberately does NOT carry it (nothing concrete to grant). */
+    /** 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[];
@@ -262,7 +265,7 @@ export interface CompoundReadonlyVerdict {
      *  tier question, never one the read face itself asked. Structural sibling of `outOfRootRead`. */
     readDenied?: true;
     /**
-     * RB-451 — the paths this scan resolved INSIDE the roots (de-duplicated, first-seen order), i.e. the
+     * 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.
      *
@@ -287,7 +290,7 @@ export interface CompoundReadonlyVerdict {
      */
     checkedPaths?: readonly string[];
     /**
-     * RB-474 — operands whose spelling carries an UNEXPANDED glob (`*`, `?`, `[…]`, unquoted). Lexical
+     * 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).
@@ -312,6 +315,15 @@ export interface CompoundReadonlyVerdict {
      * and miss the other.
      */
     undecidedPaths?: 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 (plain: nothing was declared), never a vouch.
+     */
+    unresolvedOperands?: readonly string[];
     /**
      * 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.
@@ -333,8 +345,8 @@ export interface CompoundReadonlyVerdict {
     recursiveReadPaths?: readonly string[];
 }
 /**
- * RB-412 — the single minting point for the out-of-root-read approval option text, so a gate rendering
- * the prompt and any other consumer cannot drift apart. Shape follows CC 2.1.220 (@905642 (cli250.js:66007)): the option
+ * The single minting point for the out-of-root-read approval option text, so a gate rendering
+ * the prompt and any other consumer cannot drift apart. Shape follows CC: the option
  * shows the LAST segment of the grantable directory followed by a separator, not the full path.
  *
  * `directory` is the directory to be granted — a caller holding a filesystem (this classifier does not)
@@ -343,14 +355,59 @@ export interface CompoundReadonlyVerdict {
  * uses the host's native separator.
  */
 export declare function formatOutOfRootReadApprovalOption(directory: string): string;
+/** 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.
+ *
+ *  The resolution is TEXTUAL, and its limitation runs in BOTH directions (only the first shows up as
+ *  a refusal, so only that half tends to get reported):
+ *   · false REFUSAL — a non-canonical spelling of an in-root path (a symlinked `/tmp` → `/private/tmp`
+ *     prefix) does not textually match the canonical roots and is refused;
+ *   · false ALLOW — a symlink INSIDE a root that points outside it (`<root>/vendor` → `/etc`) resolves
+ *     to a textual prefix match, so `cat vendor/passwd` is judged in-root and the real command follows
+ *     the link. This face is therefore lexical containment, NOT filesystem containment: it is weaker
+ *     than the structured Read/Grep tools, which canonicalize through `realpath` before comparing
+ *     (see safety.ts's `canonicalizeAndEnforceRoot`). Closing it means resolving each candidate against
+ *     the live filesystem, which this function deliberately cannot do (it is synchronous, pure, and
+ *     shared with the approval-gate face); the seam for it is the ENFORCING caller, which holds the
+ *     ExecutionEnv.
+ *
+ *  The verdict now carries {@link CompoundReadonlyVerdict.checkedPaths} (the
+ *  candidates that landed inside), and `createBashReadonlyTool` canonicalizes them on a LOCAL env
+ *  before running — closing BOTH directions above for that face (an escaping symlink is refused; a
+ *  non-canonical spelling that resolves back inside is no longer refused). Two residuals stay here by
+ *  construction, and belong to the caller rather than to this function: the compound/approval-gate face
+ *  has no filesystem and stays lexical, and a REMOTE env keeps the lexical behaviour (its
+ *  `canonicalPath` is an RPC per candidate). */
+export declare function resolveOperandLexically(base: string | undefined, operand: string, homeDir: string | undefined): string | undefined;
 /**
- * RB-412 — {@link classifyCompoundReadonly} with the structured verdict. The name/operator/blocking arms
+ * 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
+ * double-quoted, followed by `/` or by the word's end. Those are exactly the words whose expansion is the home
+ * directory and nothing else, so the word is rewritten to what bash hands the program — the value itself, in
+ * place, with the word's quote structure untouched (`"$HOME/x"` → `"/home/u/x"`, `$HOME"/x"` → `/home/u"/x"`)
+ * — and every arm reads an ordinary absolute path; no tilde is minted, so the tilde-prefix rule of
+ * {@link tokenizeSegment} judges only tildes the command actually wrote. Substituted only against a DECLARED
+ * home (`homeDir`): with none declared the child's `$HOME` may differ from what `~` falls back to, so the
+ * spelling is left as written and meets the substitution hard-reject. The value must survive this file's own
+ * reading of the rewritten word: the UNQUOTED spelling only for a value with no `$IFS` whitespace, glob or
+ * shell metacharacter (word splitting / pathname expansion / a connector this file would then split on — none
+ * of which a real expansion is subject to here), the double-quoted one for any value carrying no `"`, `$`,
+ * backtick, backslash or line break (the characters that would change the quote structure or meet the
+ * hard-reject). Everything else is left as written: a single-quoted spelling does not expand, and a mid-word
+ * or suffixed one (`x$HOME`, `$HOME.bak`, `$HOMES`) still meets the substitution hard-reject. Bails whole on
+ * an escape or a backtick in the command (the hard-reject refuses those strings regardless, and the quote
+ * walk below is exact only without them) and on unbalanced quoting.
+ */
+export declare function foldHomeVariableSpelling(command: string, homeDir: string | undefined): string;
+/**
+ * {@link classifyCompoundReadonly} with the structured verdict. The name/operator/blocking arms
  * run FIRST and unchanged, so an existing demotion keeps its exact reason and never acquires the
  * 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 pre-RB-412 behaviour exactly.
+ * demotion, which is why omitting `boundary` reproduces the name-only behaviour exactly.
  */
 export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary, 
-/** backlog #482 slice 3 (C4): the poll-loop face passes `iterated:true` over a body REPLICATED
+/** 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
@@ -359,7 +416,7 @@ opts?: {
     readonly iterated?: boolean;
 }): CompoundReadonlyVerdict;
 /**
- * RB-413 — the read boundary ALONE, for the `bash_readonly` face.
+ * 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
@@ -379,16 +436,16 @@ opts?: {
  * 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 (RB-448, both directions): "inside the roots" is LEXICAL containment — see
+ * 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.
- * RB-451 — a deployment that needs filesystem-true containment resolves the operands itself, and this
+ * A deployment that needs filesystem-true containment resolves the operands itself, and this
  * verdict hands it the list to resolve ({@link CompoundReadonlyVerdict.checkedPaths}, on both arms).
  * `createBashReadonlyTool` is that caller for the `bash_readonly` leg and does it on a local env.
  */
 export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
 /**
- * #502 — what {@link classifyOutOfRootReadGate} answers. Two members and one rule between them:
+ * 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 {
@@ -404,7 +461,7 @@ export interface OutOfRootReadGateVerdict {
  *  Exported for that one assertion — production code reads the constant directly. */
 export declare const COMMAND_LAUNCHERS_FOR_TEST: ReadonlySet<string>;
 /**
- * #502 — the OUT-OF-ROOT READ GATE asked as its OWN question: does any listed reader in this command
+ * 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
@@ -435,7 +492,7 @@ export declare const COMMAND_LAUNCHERS_FOR_TEST: ReadonlySet<string>;
  *    unchanged on the full face, and this one keeps answering its own question underneath it.
  *  · `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 §2.0 already defines.
+ *    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
@@ -456,12 +513,12 @@ export declare const COMMAND_LAUNCHERS_FOR_TEST: ReadonlySet<string>;
  */
 export declare function classifyOutOfRootReadGate(command: string, allow: ReadonlySet<string>, boundary: BashReadonlyRootBoundary): OutOfRootReadGateVerdict;
 /**
- * design/154 — compound read-only classification, reason-only face. Returns the demotion reason, or
+ * 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":
  * the detailed verdict may still carry `undecidedPaths` (operands whose unexpanded spelling — a
  * glob — is what got checked), and this face discards that field. An auto-allow decision must read
  * {@link classifyCompoundReadonlyDetailed} and treat a non-empty `undecidedPaths` as ask — the
- * engine's own probe does exactly that (fs-bash.ts). RB-412 added the optional `boundary`: with it,
+ * engine's own probe does exactly that (fs-bash.ts). The optional `boundary`: with it,
  * an allowlisted reader whose path arguments leave the allowed directories is demoted too (use the
  * 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.
@@ -477,7 +534,7 @@ export declare function classifyCompoundReadonly(command: string, allow: Readonl
 export declare const POLL_LOOP_MAX_BEATS = 120;
 /**
  * Per-`sleep` cap (seconds) for {@link classifyBoundedReadonlyPollLoop}. A literal `sleep 99999999`
- * is technically bounded but practically a hang — the same hazard class the RB-41 availability arms
+ * is technically bounded but practically a hang — the same hazard class the availability arms
  * demote (a green verdict that blocks until the tool timeout is green in name only).
  */
 export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
@@ -497,7 +554,7 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  * maps to a test group in test/poll-loop-classifier.test.ts (G1-G6):
  *  G1 BOUNDED TERMINATION. The loop head must be one of three LITERAL forms with a computable
  *     iteration count ≤ {@link POLL_LOOP_MAX_BEATS} ({@link pollLoopBeatsOf}); `while`/`until` never
- *     match the skeleton. Every body command terminates: non-`sleep` segments inherit the RB-41/84/
+ *     match the skeleton. Every body command terminates: non-`sleep` segments inherit the availability/
  *     108/153 availability arms via {@link classifyCompoundReadonlyDetailed} (blocking stdin, `tail
  *     -f`, unbounded devices all reject), and `sleep` must be a literal ≤
  *     {@link POLL_LOOP_MAX_SLEEP_SECONDS}. Bounded beats × terminating body ⇒ the loop halts.
@@ -512,7 +569,7 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  *     the allowlist. Nothing can chain past the vetted segment heads.
  *  G4 READ BOUNDARY UNCHANGED. The reassembled body goes through the boundary scan of
  *     {@link classifyCompoundReadonlyDetailed} with the caller's boundary — out-of-root operands
- *     reject exactly as on the plain face (RB-412/413, not relaxed by one rule). STRICTER here: a
+ *     reject exactly as on the plain face (not relaxed by one rule). STRICTER here: a
  *     verdict carrying {@link CompoundReadonlyVerdict.undecidedPaths} (an unexpanded glob) rejects,
  *     because the probe face is reason-only and a repeated read of a runtime-decided target must not
  *     auto-allow.
@@ -534,7 +591,7 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  *     so the counter is write-only and inert.
  *
  * ACCEPTED-COST NOTES (the residuals, recorded rather than silently tolerated — same posture as the
- * RB-84 `head` note above):
+ * `head` note above):
  *  · `$(seq …)` RESOLVES A COMMAND. This is the ONE command-substitution form the ruling exempts, and
  *    it does run whatever `seq` resolves to on PATH (or a shell function/alias of that name). Two
  *    facts bound the exposure. FIRST, the trust assumption is ISOMORPHIC to the allowlist itself:
@@ -547,8 +604,8 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  *    no-egress envelope — every beat still runs allowlisted readers + literal `sleep`), and the
  *    walltime axis cascades a hard kill regardless. A deployment wanting NO command-substitution at
  *    all can prefer `{<lo>..<hi>}` or a literal list, which bash expands internally with no command
- *    run. (falsification review flagged the substitution as [high] and recommended dropping it;
- *    kept per the ruling that names `$(seq <int> <int>)` as the one exemption — recorded for a
+ *    run. (The substitution is a flagged, high-severity shape kept per the ruling that names
+ *    `$(seq <int> <int>)` as the one exemption — recorded for a
  *    tightening decision, since the brace form is a drop-in equivalent.)
  *  · 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
@@ -568,3 +625,12 @@ export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
  * ({@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;
+/**
+ * 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
+ * undecided operands) off the loop body exactly as off a plain compound, beside whatever sentence the
+ * loop grammar or the body's shape produced. {@link classifyBoundedReadonlyPollLoop} is its `reason`
+ * 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;