@sema-agent/core 7.15.0 → 7.16.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
@@ -213,13 +213,13 @@ export interface BashReadonlyRootBoundary {
      *  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,19 +230,19 @@ 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 {
@@ -262,7 +262,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 +287,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).
@@ -333,8 +333,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)
@@ -344,13 +344,13 @@ export interface CompoundReadonlyVerdict {
  */
 export declare function formatOutOfRootReadApprovalOption(directory: string): string;
 /**
- * RB-412 — {@link classifyCompoundReadonly} with the structured verdict. The name/operator/blocking arms
+ * {@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 +359,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 +379,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 +404,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 +435,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 +456,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 +477,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 +497,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 +512,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 +534,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 +547,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

package/dist/tools/fs/encoding.d.ts

@@ -1,25 +1,19 @@
 /**
- * 编码 parity 批(docs/CC-TOOL-PARITY-SWEEP-2026-07.md P0)— file encoding + line-ending detection
- * for the Read/Edit/Write band, ported from CC's `utils/fileRead.ts` mechanism and hardened where CC
- * is lossy:
+ * File encoding + line-ending detection for the Read/Edit/Write band, ported from CC's
+ * `utils/fileRead.ts` mechanism and hardened where CC is lossy:
  *
- *  - BOM detection: `FF FE` → utf16le, `EF BB BF` → utf8-with-BOM, else plain utf8. (CC 88→2.1.187
- *    dynamic-verified: detection is BOM-only; UTF-16BE / heuristic sniffing deliberately NOT done —
- *    a wrong guess silently corrupts, and the BOM-less case stays a refusal at the Read layer.)
+ *  - BOM detection: `FF FE` → utf16le, `EF BB BF` → utf8-with-BOM, else plain utf8. Detection is
+ *    BOM-only; UTF-16BE / heuristic sniffing is deliberately NOT done — a wrong guess silently
+ *    corrupts, and the BOM-less case stays a refusal at the Read layer.
  *  - The MODEL-FACING text is BOM-stripped and CRLF-normalized (what the model quotes in `old_string`
- *    must match what Read showed it).
- *    RB-285 (encoding LOW, 归因收窄 — CC 220 亲核): the blanket "(CC parity)" that used to sit on this
- *    line was half wrong, because CC has TWO read lanes and they disagree with each other.
- *      · CRLF-normalize — parity on both lanes (`Zr_` @276877 and `Mqe` @58197 both `replaceAll`).
- *      · BOM-strip — parity on CC's READ lane only (`Zr_` @276877: `charCodeAt(0) === 65279 → slice(1)`).
- *        CC's EDIT/WRITE lane (`Mqe`) does NOT strip: it hands the model text with the leading U+FEFF
- *        still in it, and only the staleness/hash coordinate (`X9` = `CTe` + CRLF, @365630-365635)
- *        strips. sema strips in ONE shared decoder for every lane, so the model-facing view and the
- *        hash coordinate cannot drift apart — an improvement over CC's split, recorded as such rather
- *        than claimed as parity.
- *  - Write-back re-encodes with the ORIGINAL encoding, PRESERVES the BOM (CC drops it on Write — its
- *    lossy face, dynamic-verified W1; we keep it, recorded as a deliberate improvement), and restores
- *    the file's dominant line endings for Edit (Write keeps the model's endings as-is, CC decision).
+ *    must match what Read showed it). CRLF-normalize is parity on both of CC's read lanes; BOM-strip
+ *    is parity on CC's READ lane only — CC's EDIT/WRITE lane hands the model text with the leading
+ *    U+FEFF still in it and strips only inside its staleness/hash coordinate. sema strips in ONE
+ *    shared decoder for every lane, so the model-facing view and the hash coordinate cannot drift
+ *    apart: a registered delta, not parity.
+ *  - Write-back re-encodes with the ORIGINAL encoding, PRESERVES the BOM (CC drops it on Write — a
+ *    registered deliberate improvement), and restores the file's dominant line endings for Edit
+ *    (Write keeps the model's endings as-is, CC decision).
  */
 /** Detected byte-level encoding of a text file (BOM-driven; utf8 is the no-BOM default). */
 export interface DetectedFileEncoding {
@@ -31,19 +25,17 @@ export interface DecodedTextFile {
     /** Model-facing text: BOM stripped, `\r\n` normalized to `\n`. The staleness-hash coordinate. */
     text: string;
     encoding: DetectedFileEncoding;
-    /** Dominant line ending of the ORIGINAL bytes (majority vote — CC `CKt` @58184 同算法).
+    /** Dominant line ending of the ORIGINAL bytes (majority vote; CC's counting rule).
      *  Deliberately NOT per-line lossless: a mixed-endings file is unified to the dominant ending on
-     *  the first edit (镜头1/2 LOW, accepted non-goal — CC behaves the same way).
-     *  RB-285 (encoding LOW): the COUNTING RULE is CC's; the SAMPLE is not. CC votes on the first 4096
-     *  characters only (`CKt(s.slice(0, 4096))` @58201) while {@link detectLineEndings} below votes on
-     *  the whole file — so a file whose first 4KB is LF and whose bulk is CRLF gets opposite verdicts.
-     *  sema's whole-file vote is kept on purpose: the verdict decides what an Edit WRITES BACK across
-     *  the entire file, so sampling a prefix is exactly the case where the cheap answer flips the
-     *  remaining 99% of the lines. Registered as a deliberate delta, not parity. */
+     *  the first edit (accepted non-goal — CC behaves the same way).
+     *  The SAMPLE is a registered delta: CC votes on the first 4096 characters only, while
+     *  {@link detectLineEndings} below votes on the whole file. The verdict decides what an Edit WRITES
+     *  BACK across the entire file, so sampling a prefix is exactly the case where the cheap answer
+     *  flips the remaining 99% of the lines. */
     endings: DetectedLineEndings;
-    /** 双镜头 MED: a utf16le body with an ODD byte count is TRUNCATED/corrupt — decoding would
-     *  silently drop the dangling byte and a later write-back would destroy it permanently. Flagged so
-     *  the tool layer fails closed instead of "repairing" the file. */
+    /** A utf16le body with an ODD byte count is TRUNCATED/corrupt — decoding would silently drop the
+     *  dangling byte and a later write-back would destroy it permanently. Flagged so the tool layer
+     *  fails closed instead of "repairing" the file. */
     malformed?: true;
 }
 /** BOM-only encoding detection (CC `detectEncodingForResolvedPath` parity — no content heuristics). */
@@ -56,8 +48,8 @@ export declare function decodeTextBytes(bytes: Uint8Array): DecodedTextFile;
  * @param text normalized (`\n`) text when `endings` is CRLF/LF (Edit path — restore the file's
  *   dominant endings); pass `endings:"preserve"` to write the text's OWN line endings untouched
  *   (Write path — CC decision: the model sent explicit endings in `content` and meant them).
- * @returns a plain string for the no-BOM utf8 + LF-or-preserve fast path (byte-compatible with the
- *   pre-batch writer), else the exact bytes (BOM + encoded body).
+ * @returns a plain string for the no-BOM utf8 + LF-or-preserve fast path, else the exact bytes
+ *   (BOM + encoded body).
  */
 export declare function encodeTextForFile(text: string, encoding: DetectedFileEncoding, endings: DetectedLineEndings | "preserve"): string | Uint8Array;
 /** Normalize model-supplied match/replacement text the same way the file text was normalized
@@ -65,16 +57,15 @@ export declare function encodeTextForFile(text: string, encoding: DetectedFileEn
  *  Deliberately does NOT strip a leading U+FEFF: an `old_string` starting with one may be quoting
  *  genuine file content — use {@link normalizeFileText} only where the string stands for a whole file. */
 export declare function normalizeEditText(s: string): string;
-/** RB-222 — split a leading U+FEFF off MODEL-SUPPLIED whole-file text (CC `CTe` parity,
- *  220 @365630). The BOM is a file-level byte marker, not text: decodeTextBytes strips it on the way
- *  in, so it can never live in the normalized coordinate. Only for strings that stand for a WHOLE
- *  file (Write `content`, readFileState seeding) — a decoded file text's leading U+FEFF is genuine
- *  content and must stay. */
+/** Split a leading U+FEFF off MODEL-SUPPLIED whole-file text (CC parity). The BOM is a file-level
+ *  byte marker, not text: decodeTextBytes strips it on the way in, so it can never live in the
+ *  normalized coordinate. Only for strings that stand for a WHOLE file (Write `content`,
+ *  readFileState seeding) — a decoded file text's leading U+FEFF is genuine content and must stay. */
 export declare function splitLeadingBom(text: string): {
     hadBom: boolean;
     text: string;
 };
-/** RB-222 — CC `X9` parity (220 @365635 = BOM-strip + CRLF-normalize): THE coordinate
- *  every readFileState hash lives in (Read/Edit/Write staleness all hash `decodeTextBytes(...).text`).
- *  A hash taken on raw model content with a leading U+FEFF can never agree with any later re-read. */
+/** CC parity (BOM-strip + CRLF-normalize): THE coordinate every readFileState hash lives in
+ *  (Read/Edit/Write staleness all hash `decodeTextBytes(...).text`). A hash taken on raw model content
+ *  with a leading U+FEFF can never agree with any later re-read. */
 export declare function normalizeFileText(s: string): string;

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

@@ -4,11 +4,11 @@ import { type CwdRef } from "./fs-shared.js";
 import type { ReversibilityVerdict } from "../../core/types.js";
 import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
 /**
- * design/80 D-2 (part-1): a parsed-command classifier for the `bash` tool, exposed as a
+ * A parsed-command classifier for the `bash` tool, exposed as a
  * `ToolSpec.reversibilityProbe`. A full shell is treated as egress+irreversible by DEFAULT; this probe is the
- * "real parsed classifier" that lets a deployment safely auto-allow the provably-benign subset (the §4-OQ4
- * doctrine: shell⇒always-gate UNLESS a parsed classifier is wired). design/154 upgraded it from
- * single-command to {@link classifyCompoundReadonly}: a command is reversible ONLY if every `;`/`&&`/`||`/`|`
+ * "real parsed classifier" that lets a deployment safely auto-allow the provably-benign subset (the
+ * doctrine: shell⇒always-gate UNLESS a parsed classifier is wired). It is COMPOUND-aware
+ * ({@link classifyCompoundReadonly}): a command is reversible ONLY if every `;`/`&&`/`||`/`|`
  * connected segment is a bare command (no redirects/substitution/subshells/escapes/`&` anywhere — those
  * whole-string reject, so it can't chain to `curl`/`git push`/`rm` or background past TaskStop) whose
  * `argv[0]` is in the reversible allowlist (default
@@ -23,7 +23,7 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * Wire it on the `bash` tool with `irreversibility: "maybe"` (or via `TaskSpec.shellGate: "classify"`); without
  * a classifier a deployment should mark `bash` `irreversibility: "always"` (`shellGate: "always"`) — fail-closed.
  *
- * RB-412 closed the DATA-side residual named above for the read direction: pass `boundary` and a listed
+ * The DATA-side residual named above is closed for the read direction: pass `boundary` and a listed
  * reader whose path arguments leave the allowed directories stops being reversible, so the gate asks
  * instead of auto-allowing. Pass it as a FUNCTION wherever the working directory is observable (an
  * in-task `cd` moves the base a relative operand resolves against, and the probe is called per command).
@@ -38,7 +38,7 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * safety argument lives on that function). Additive by construction: the plain verdict is tried
  * first and is never overridden.
  *
- * backlog #239 — the RECURSIVE-READ demotion returns a STRUCTURED cause alongside the verdict. That
+ * The RECURSIVE-READ demotion returns a STRUCTURED cause alongside the verdict. That
  * demotion is the one arm whose reason is genuinely unrecoverable downstream: a recursive read is
  * refused for what the traversal REACHES, and the reached set is by definition not in the command text
  * an approval card shows. The cause is minted from the SAME classification pass that produced the
@@ -98,7 +98,7 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  */
 export declare function bashReadBoundaryProbe(boundary: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
- * design/199 D-6 — the FULL shell's contract id, single-sourced: both shell faces share the wire
+ * The FULL shell's contract id, single-sourced: both shell faces share the wire
  * name "Bash", so this id is the ONE structural discriminator between the write-capable shell and
  * the read-only allowlist face (`core.bash_readonly@1`). Consumed by prepare-task's
  * fullShellReachable roster assertion (its first load-bearing consumer).
@@ -107,36 +107,36 @@ export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
 /** The CC-verbatim exit-1 interpretation for `command`, or undefined when exit 1 means a real error.
  *  Conservative parse: last `;`/`&&`/`||`/newline statement → last `|` pipeline segment → leading
  *  command name (env-assignments skipped, path prefix stripped); `git grep`/`git diff` special-cased
- *  (CC cLp). Exported for the 批④ unit tests. */
+ *  (CC `cLp`). Exported for its unit tests. */
 export declare function bashExitOneInterpretation(command: string): string | undefined;
 export declare function canAutoBackground(command: string, depth?: number): boolean;
 /**
  * `bash` (effect:write) — a full shell. ⚠️ It runs with `rootCanonical` as the initial cwd but is NOT
  * sandboxed: a command can `cd` out, read/write/delete any path the process can reach, and use the
- * network. `rootPath` is a file-tool guard rail, NOT a bash sandbox (design/44 §5, DESIGN#6) — real
- * isolation is the deployment's job (inject a chroot/container `ExecutionEnv`). Every call still goes
- * through the design/37 policy gate, which a multi-tenant deployment MUST wire to constrain it. The cwd
- * persists across calls (design/64 §8.1A): a per-task `cwdRef` starts at `rootCanonical` and is updated
+ * network. `rootPath` is a file-tool guard rail, NOT a bash sandbox — real isolation is the
+ * deployment's job (inject a chroot/container `ExecutionEnv`). Every call still goes through the
+ * tool-policy gate, which a multi-tenant deployment MUST wire to constrain it. The cwd
+ * persists across calls: a per-task `cwdRef` starts at `rootCanonical` and is updated
  * from the shell's final pwd after each command.
  */
 export declare function createBashTool(env: ExecutionEnv, rootCanonical: string, coAuthor?: string | false, cwdRef?: CwdRef, taskOpts?: {
     taskRegistry?: TaskRegistry;
     taskOwner?: string;
     taskScope?: string;
-    /** (design/129, mirrors MonitorToolOptions.sessionId): when the task runs INSIDE a session,
+    /** (mirrors MonitorToolOptions.sessionId): when the task runs INSIDE a session,
      *  a background command registers session-resident (owner = sessionId, sessionScoped flag) — it
      *  survives the run teardown like CC's bg shells and is reaped at the session terminal. Absent ⇒
      *  run-scoped registration exactly as before (killed-with-receipt at teardown). */
     sessionId?: string;
-    /** design/116 §7 G2b: completion-notification sink — a finished background command fires ONE
+    /** Completion-notification sink — a finished background command fires ONE
      *  task-notification (priority "next": boundary interrupt, CC LocalShellTask posture). */
     onTaskNotification?: (n: import("../../core/task-notification.js").TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
-    /** design/116 detach: per-tool-call detach hub — a fired signal adopts the running command as background. */
+    /** Per-tool-call detach hub — a fired signal adopts the running command as background. */
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
     /**
-     * RB-198 F1 (CC 220 `Zry`/`WZi.#m` parity) — EXPLICIT deployment opt-in: on this command's own
+     * EXPLICIT deployment opt-in: on this command's own
      * timeout, an eligible foreground command (see `canAutoBackground`'s own docstring — a
      * DELIBERATELY simplified, narrower-than-CC classifier) is adopted as a background task instead
      * of being killed. Defaults to `false` (the pre-existing, unconditional kill-on-timeout behavior)
@@ -151,7 +151,7 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      */
     autoBackgroundOnTimeout?: boolean;
     /**
-     * RB-220 — mirrors {@link import("../../core/types.js").TaskSpec.oneShot}: this run has no later
+     * Mirrors {@link import("../../core/types.js").TaskSpec.oneShot}: this run has no later
      * turn for an async background notification to land in (a headless `-p` process exits once the
      * turn ends). Branches the background-launch receipt's guidance toward an active block-wait
      * instruction instead of "you will be notified — do not poll", the same failure form
@@ -160,18 +160,18 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      */
     oneShot?: boolean;
     /**
-     * RB-371 ②: the EXTRA containment roots of the structured file tools (additionalDirectories,
+     * The EXTRA containment roots of the structured file tools (additionalDirectories,
      * canonical) — combined with `rootCanonical` and consulted ONLY for the post-`cd` disclosure
      * note (a committed cwd outside every root gets one trailer line saying the structured tools'
      * relative paths now resolve there and may be refused). Bash itself stays deliberately
      * unconfined; passing this never gates anything.
      */
     additionalRoots?: readonly string[];
-    /** RB-370 ② (cli): override of the `timeout` parameter's DEFAULT budget, in ms — see
+    /** Override of the `timeout` parameter's DEFAULT budget, in ms — see
      *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} for the resolution
      *  contract (options over env over constant; invalid values discarded). */
     bashDefaultTimeoutMs?: number;
-    /** RB-370 ② (cli): override of the `timeout` parameter's engine CEILING, in ms — only-widen
+    /** Override of the `timeout` parameter's engine CEILING, in ms — only-widen
      *  vs the resolved default; see {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs}. */
     bashMaxTimeoutMs?: number;
     /** Structured sink for this leg's timeout-cap discard announcements — consumed by
@@ -179,36 +179,36 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
      *  {@link import("./index.js").HandsToolkitOptions.onNotice} for the replace-vs-warn contract). */
     onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
     /**
-     * #181-F6 — whether the Monitor tool is on THIS run's roster (the Runner's own mount predicate is
+     * Whether the Monitor tool is on THIS run's roster (the Runner's own mount predicate is
      * `backgroundTaskToolsActive`; it, not this tool, mounts Monitor). Read by the SR-2 gh rate-limit
      * hint, whose closing clause teaches the Monitor tool: `false` ⇒ the clause is dropped (the sleep
      * advice stays), absent/`true` ⇒ historic full wording (a standalone toolkit consumer may well have
      * mounted Monitor itself — the omitted default must not silently rewrite its hint).
      */
     monitorToolActive?: boolean;
-    /** design/319 (A ticket) — the session's reminder provenance mark: stamped on the gh rate-limit
+    /** The session's reminder provenance mark: stamped on the gh rate-limit
      *  hint's open tag by the mint home (see {@link import("./index.js").HandsToolkitOptions.reminderMark}).
      *  Absent ⇒ historic bare tag. */
     reminderMark?: string;
 }): AgentTool;
 /**
- * `bash_readonly` (effect:read) — a restricted shell for the verifier read-only boundary (design/44 M2):
- * a single allowlisted, bare command with no shell operators. effect:read lets it survive the verifier's
- * read-only filter, but it is NOT a policy circumvention — it still goes through the design/37 gate (council #7:
- * a read can still be a side channel, e.g. dumping a secret file). The allowlist is a coarse pre-filter;
+ * `bash_readonly` (effect:read) — a restricted shell for the verifier read-only boundary: a single
+ * allowlisted, bare command with no shell operators. effect:read lets it survive the verifier's
+ * read-only filter, but it is NOT a policy circumvention — it still goes through the tool-policy gate,
+ * because a read can still be a side channel (dumping a secret file). The allowlist is a coarse pre-filter;
  * the policy gate is the authoritative control.
  *
- * RB-413 (安全面, adjudicated: hard refusal) — that allowlist vets argv[0] and nothing else, so until this
- * leg carried a path boundary an allowlisted reader could name ANY file on the host and get it: `cat
- * /etc/passwd` went straight through. RB-412 gave the full `bash` leg the same boundary as a DEMOTION —
- * that leg's verdict feeds an approval gate, so "outside the roots" can become a prompt. This face has no
+ * Hard refusal, not a demotion: the allowlist vets argv[0] and nothing else, so without a path
+ * boundary an allowlisted reader could name ANY file on the host and get it (`cat /etc/passwd` would go
+ * straight through). The full `bash` leg carries the same boundary as a DEMOTION — that leg's verdict
+ * feeds an approval gate, so "outside the roots" can become a prompt. This face has no
  * such channel: `effect:"read"` is precisely what lets it run where the write shell may not (the verifier's
  * read-only band), so an out-of-root read here is not something to escalate, it is outside what the tool
  * is. It is refused, fail-closed, before anything executes — including the conservative direction, where
  * the operand cannot be resolved statically (there is nothing to degrade to).
  */
 export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, opts?: {
-    /** RB-370 ② (cli): same timeout-cap overrides the full `bash` leg takes — see
+    /** Same timeout-cap overrides the full `bash` leg takes — see
      *  {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} /
      *  {@link import("./index.js").HandsToolkitOptions.bashMaxTimeoutMs} (类修完整域: both foreground
      *  legs share runShell's clamp, so both must share the configurable resolution). */
@@ -217,21 +217,21 @@ export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical:
     /** Structured sink for the timeout-cap discard announcements — same seat the full `bash` leg
      *  takes (both foreground legs share the resolver, so both must share the sink). */
     onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
-    /** RB-413: the extra containment roots the structured file tools got (design/119 `--add-dir`,
+    /** The extra containment roots the structured file tools got (the CC `--add-dir` family,
      *  canonical). A read this deployment already sanctions for Read/Grep/Glob is equally sanctioned
      *  here — the two faces must not disagree about which directories exist for this session. */
     additionalRoots?: readonly string[];
 }): AgentTool;
 /**
- * design/115 P0 `TaskOutput` (legacy aliases: BashOutput/AgentOutput*) — read a background shell's NEW output
+ * `TaskOutput` — read a background shell's NEW output
  * since the last call (cursor), by task_id. Optional legacy `filter` regex is applied BEFORE the per-poll truncation so a watched line survives even when it
  * falls in a high-throughput middle window. Untrusted process output is fenced (delimitUntrusted) — observe-only,
  * never re-fed as instructions.
  */
 export declare function createEnvTaskOutputTool(env: ExecutionEnv): AgentTool;
-/** design/115 P0 `TaskStop` (RB-476-A: legacy aliases cleared) — terminate a background shell by task_id.
+/** `TaskStop` — terminate a background shell by task_id.
  *
- *  design/134 KNOWN-ISSUES close-out: this band kills ENV-DIRECT (it mounts precisely when the toolkit has
+ *  This band kills ENV-DIRECT (it mounts precisely when the toolkit has
  *  no registry — the createHandsToolkit ternary routes registry deployments to createTaskStopTool), so a
  *  row for the SAME shell in the process-local {@link defaultTaskRegistry} (a Runner-mounted run sharing
  *  this env) used to settle via the watcher's no-claimant floor as stoppedBy:"system". The tool now marks