@sema-agent/core 7.14.0 → 7.16.0

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

@@ -5,18 +5,18 @@ import { type DecodedTextFile } from "./encoding.js";
 import { type ImageDownsampler } from "../../core/mcp.js";
 import { type EngineNotice } from "../../core/types.js";
 /**
- * The "hand" tool band (design/44 §3) — built per task over an injected {@link ExecutionEnv} and a
- * per-task {@link ReadFileState}, closure-captured (design/44 §11 ruling A: the codebase tool idiom; no
- * `ToolExecuteContext` growth). Every edit/write enforces the CC-ported safety invariants (read-before-
- * edit, content-hash staleness, edit uniqueness, write-back) + rootPath containment (§4). The band is
- * the file tools read/edit/write/grep/glob plus a shell: `bash` (effect:write, full shell) for normal
- * tasks, or `bash_readonly` (effect:read, allowlisted) under the verifier read-only boundary (§6).
+ * The "hand" tool band — built per task over an injected {@link ExecutionEnv} and a per-task
+ * {@link ReadFileState}, closure-captured (the codebase tool idiom; no `ToolExecuteContext` growth).
+ * Every edit/write enforces the CC-ported safety invariants (read-before-edit, content-hash staleness,
+ * edit uniqueness, write-back) plus rootPath containment. The band is the file tools
+ * read/edit/write/grep/glob plus a shell: `bash` (effect:write, full shell) for normal tasks, or
+ * `bash_readonly` (effect:read, allowlisted) under the verifier read-only boundary.
  */
-/** Byte cap on a single read (design/64 §7.2(3), CC `MAX_OUTPUT_SIZE = 0.25*1024*1024`). A DEFAULT
- *  whole-file read over this is refused with guidance; an explicit offset/limit slice is served
- *  (fidelity-sweep F3 — keeps read-before-edit satisfiable on large files). */
+/** Byte cap on a single read (CC `MAX_OUTPUT_SIZE = 0.25*1024*1024`). A DEFAULT whole-file read over
+ *  this is refused with guidance; an explicit offset/limit slice is served, which keeps
+ *  read-before-edit satisfiable on large files. */
 export declare const MAX_READ_BYTES: number;
-/** Hard MEMORY upper bound on a sliced (explicit offset/limit) read (fidelity R3-1). The offset/limit
+/** Hard MEMORY upper bound on a sliced (explicit offset/limit) read. The offset/limit
  *  escape hatch bypasses the whole-file byte cap above, but the reader still loads the ENTIRE file into
  *  memory (`readBinaryFile`) before slicing by line — so without this cap, an explicit `offset:1,limit:1`
  *  on a multi-GB file is an OOM lever the model can pull. This bounds the bytes loaded into MEMORY, not
@@ -24,30 +24,27 @@ export declare const MAX_READ_BYTES: number;
  *  explicit slice, with guidance to stream a portion via bash (`sed -n` / `head -c`) instead, which
  *  never loads the whole file. */
 export declare const SLICED_READ_MAX_BYTES: number;
-/** RB-200 F7 (form-one audit, CC 220 @367140-367150, `ned` verbatim): the byte cap Edit refuses ABOVE.
- *  CC stats the target before touching it and refuses with a formatted-size message when it exceeds
- *  this; sema's Edit had no equivalent — it goes straight to a whole-file `readBinaryFile` (twice: the
- *  `old_string:""` full-overwrite branch and the normal find/replace branch), so a multi-GB target was
- *  an unguarded OOM lever the model could pull with an ordinary Edit call. Read solved the identical
- *  problem for its own tool via a pre-read `env.fileInfo` stat + a post-read TOCTOU recheck
- *  ({@link SLICED_READ_MAX_BYTES} above) — same pattern, reused here rather than invented fresh. */
+/** The byte cap Edit refuses ABOVE (CC's own constant, verbatim). CC stats the target before touching
+ *  it and refuses with a formatted-size message when it exceeds this. Without the gate, Edit goes
+ *  straight to a whole-file `readBinaryFile` (twice: the `old_string:""` full-overwrite branch and the
+ *  normal find/replace branch), so a multi-GB target is an unguarded OOM lever an ordinary Edit call
+ *  can pull. The shape is Read's: a pre-read `env.fileInfo` stat plus a post-read TOCTOU recheck
+ *  ({@link SLICED_READ_MAX_BYTES} above). */
 export declare const MAX_EDIT_BYTES: number;
-/** RB-200 F7: `Edit`'s human-readable byte-count formatter (CC `pl()` verbatim: bytes below 1KB, else
+/** `Edit`'s human-readable byte-count formatter (CC `pl()` verbatim: bytes below 1KB, else
  *  KB/MB/GB with one decimal, trailing ".0" stripped). */
 export declare function formatByteSize(n: number): string;
-/** RB-200 F7 (independent-review CONFIRMED bug): Node's own string-length ceiling
- *  (`buffer.constants.MAX_STRING_LENGTH` — ~512MiB on V8/Node 24, verified on this host) sits BELOW
- *  `MAX_EDIT_BYTES` (1GiB, copied from CC's own `ned` constant — 220:367009 — with no cross-check
- *  against the host engine's actual limit). A file whose size lands between the two thresholds passes
- *  Edit's byte-count gate (both the pre-read `fileInfo` stat and the post-read TOCTOU recheck) but
- *  still crashes `decodeTextBytes`'s `Buffer#toString` with an uncaught `RangeError` — reproduced with
- *  a real ~700MB file and NO race, via the `old_string:""` branch's own documented "no read-before-edit
- *  gate" path (no Read call needed first). The model would see a bare, unactionable
- *  "Cannot create a string longer than…" instead of the intended "too large to edit" guidance the byte
- *  gate exists to provide. A numeric threshold pinned to today's engine constant would be fragile
- *  across Node/V8 versions (and does nothing for the ALREADY-shipped Read tool's own decode call if a
- *  future engine ever lowers the ceiling further) — this instead catches ANY decode failure, at
- *  whatever byte count actually broke, and reports it exactly like the byte-count gate would have. */
+/** Node's own string-length ceiling (`buffer.constants.MAX_STRING_LENGTH` — ~512MiB on V8/Node 24)
+ *  sits BELOW `MAX_EDIT_BYTES` (1GiB, CC's constant, which was never cross-checked against a host
+ *  engine's actual limit). A file whose size lands between the two thresholds passes Edit's byte-count
+ *  gate (both the pre-read `fileInfo` stat and the post-read TOCTOU recheck) and still crashes
+ *  `decodeTextBytes`'s `Buffer#toString` with an uncaught `RangeError` — no race needed, reachable
+ *  through the `old_string:""` branch's documented "no read-before-edit gate" path. The model would
+ *  then see a bare, unactionable "Cannot create a string longer than…" instead of the "too large to
+ *  edit" guidance the byte gate exists to provide. A numeric threshold pinned to today's engine
+ *  constant would be fragile across Node/V8 versions (and would do nothing for Read's own decode call
+ *  if a future engine lowered the ceiling further), so this catches ANY decode failure, at whatever
+ *  byte count actually broke, and reports it exactly like the byte-count gate would have. */
 export declare function decodeEditBytes(bytes: Uint8Array, path: string): {
     ok: true;
     value: DecodedTextFile;
@@ -65,7 +62,7 @@ export declare function truncatedUtf16BodyMessage(tool: string, path: string): s
 /** Why a bash_readonly refusal is terminal rather than escalated. Appended by every arm of that refusal
  *  family; the arms differ in what they found, never in what the model can do about it. */
 export declare const BASH_READONLY_CONFINEMENT_NOTE = "bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.";
-/** RB-222 r3 — the readFileState hash coordinate for a file that was JUST WRITTEN via
+/** The readFileState hash coordinate for a file that was JUST WRITTEN via
  *  `encodeTextForFile`: decode the EXACT payload handed to `env.writeFile`, i.e. what the next
  *  re-read's `decodeTextBytes` will produce. A blanket `normalizeFileText` is WRONG on the
  *  encode-preserving Edit lanes: a leading U+FEFF in the new text is stripped by the next read only
@@ -75,7 +72,7 @@ export declare const BASH_READONLY_CONFINEMENT_NOTE = "bash_readonly is confined
  *  and stays correct if the encoding rules ever change. */
 export declare function persistedTextOf(encoded: string | Uint8Array): string;
 /**
- * #483 — one APPLIED edit as the Edit tool's `details` card records it: the RESOLVED old/new strings
+ * One APPLIED edit as the Edit tool's `details` card records it: the RESOLVED old/new strings
  * (post quote/escape resolution, post deletion-newline widening) in the normalized originalFile
  * coordinate. This is the card shape a transcript replay must re-apply, so the application step is a
  * single source shared by the Edit tool's own apply loop and the replay — two spellings of "apply"
@@ -88,14 +85,14 @@ export interface RecordedEdit {
     replaceAll: boolean;
 }
 /**
- * #483 — apply ONE recorded edit mechanically (no matching layers, no validation: the recording site
+ * Apply ONE recorded edit mechanically (no matching layers, no validation: the recording site
  * already resolved and validated the strings; a replay consumer that cannot prove `oldString` is
  * present must fall back to retracting its record, never guess here).
  *
  * Two load-bearing details, both shared with the Edit tool's historical inline apply:
  *  - Function-form replacement: the callback's return value is NOT interpreted as a replacement
- *    pattern, so `$&`/`$$`/`` $` ``/`$'` in `newString` are written literally (S-1; the replaceAll
- *    split/join path was always literal).
+ *    pattern, so `$&`/`$$`/`` $` ``/`$'` in `newString` are written literally (the replaceAll
+ *    split/join path is literal by construction).
  *  - `oldString === ""` is the whole-content OVERWRITE shape: the Edit tool's whitespace-only-file
  *    overwrite lane records `{oldString: "", newString: <full new text>}` after REPLACING the file's
  *    content wholesale (fs-write.ts, the `old_string:""` existing-file branch). The tool's own apply
@@ -103,32 +100,30 @@ export interface RecordedEdit {
  *    it exists for the replay consumer alone — a plain `replace("", ...)` would PREPEND instead.
  */
 export declare function applyRecordedEdit(text: string, edit: RecordedEdit): string;
-/** fidelity-sweep F3 (stopgap wording): render the read-before-edit refusal, appending the slice/bash
- *  escape hatch when the target is over the Read byte cap — a bare "read it first" is un-followable
- *  there (a default whole-file Read refuses such files). Best-effort: an un-stattable file keeps the
- *  bare CC-verbatim refusal.
+/** Render the read-before-edit refusal, appending the slice/bash escape hatch when the target is over
+ *  the Read byte cap — a bare "read it first" is un-followable there (a default whole-file Read
+ *  refuses such files). Best-effort: an un-stattable file keeps the bare CC-verbatim refusal.
  *
- *  RB-264 ⑥W1: `fallbackHint` is a caller-supplied parenthetical for the case NO branch below
- *  diagnosed anything (all three writing tools pass {@link READ_REFUSED_ESCAPE_HINT} — the
- *  Read-refuses-this-file deadlock, which by construction leaves nothing to stat). It is NOT appended
- *  beside a sharper hint: both sharper shapes describe files Read handled successfully, so the
- *  encoding-deadlock sentence would be false there — and stacking two escape routes on one refusal
- *  buries the one that applies. */
+ *  `fallbackHint` is a caller-supplied parenthetical for the case NO branch below diagnosed anything
+ *  (all three writing tools pass {@link READ_REFUSED_ESCAPE_HINT} — the Read-refuses-this-file
+ *  deadlock, which by construction leaves nothing to stat). It is NOT appended beside a sharper hint:
+ *  both sharper shapes describe files Read handled successfully, so the encoding-deadlock sentence
+ *  would be false there — and stacking two escape routes on one refusal buries the one that applies. */
 export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: Pick<FsViolation, "code" | "message" | "partialView">, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
-/** Byte cap on a Read-image WITHOUT a downsampler (batch-C / design/64 §13.4): an image file is returned AS
- *  a visual `ImageContent` block (base64) rather than refused. Bounded so a huge image can't blow the request.
- *  批③: this stat-time cap only bounds the READ; the accept/refuse decision is the base64 gate below (the
- *  Anthropic limit is on base64 LENGTH, so the effective no-sharp accept bound is raw ≤ 3.75MB). */
+/** Byte cap on a Read-image WITHOUT a downsampler: an image file is returned AS a visual
+ *  `ImageContent` block (base64) rather than refused. Bounded so a huge image cannot blow the request.
+ *  This stat-time cap only bounds the READ; the accept/refuse decision is the base64 gate below (the
+ *  provider limit is on base64 LENGTH, so the effective no-sharp accept bound is raw ≤ 3.75MB). */
 export declare const MAX_IMAGE_READ_BYTES: number;
-/** Byte cap on a Read-image WITH a downsampler (批③): sharp can shrink a big photo to the 2000×2000/3.75MB
- *  CC target, so the old 5MB hard refusal is replaced by downsampling (CC readImageWithTokenBudget reads the
- *  file unbounded; we keep an OOM sanity bound — deliberate delta, camera photos fit comfortably). */
+/** Byte cap on a Read-image WITH a downsampler: sharp can shrink a big photo to CC's 2000×2000/3.75MB
+ *  target, so the smaller hard refusal does not apply (CC readImageWithTokenBudget reads the file
+ *  unbounded; we keep an OOM sanity bound — deliberate delta, camera photos fit comfortably). */
 export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
-/** A4-2 (external black-box audit, ruled 2026-08-03): the no-downsampler cap above is a DELIBERATE bound
- *  and does not move — what was wrong is that its refusal read like a hard ceiling. Whether the higher cap
- *  is reachable depends on an OPTIONAL dependency the caller can install, and only this package knew that,
- *  so the refusal now names the move instead of leaving the caller to guess that the limit is negotiable.
- *  Appended ONLY on the no-downsampler branch: with sharp already resolved the hint would be false advice. */
+/** The no-downsampler cap above is a DELIBERATE bound and does not move — but its refusal must not
+ *  read like a hard ceiling. Whether the higher cap is reachable depends on an OPTIONAL dependency the
+ *  caller can install, and only this package knows that, so the refusal names the move instead of
+ *  leaving the caller to guess that the limit is negotiable. Appended ONLY on the no-downsampler
+ *  branch: with sharp already resolved the hint would be false advice. */
 export declare const NO_DOWNSAMPLER_IMAGE_CAP_HINT = "Install the optional \"sharp\" dependency (declared in this package's optionalDependencies) to read images up to 67108864 bytes \u2014 it downsamples them to fit the API image limit.";
 /** Read-image downsampler seam: `undefined` → auto-detect sharp; `false` → force-disabled (deterministic
  *  no-sharp path, used by tests + envs that must not touch native deps); a function → injected. */
@@ -136,28 +131,25 @@ export type ReadImageDownsamplerOption = ImageDownsampler | false | undefined;
 /** Resolve (and memoize) the auto-detected sharp downsampler, process-wide. Shared accessor for the two
  *  consumers of the module-private {@link autoDownsampler} cache. */
 export declare function resolveAutoDownsampler(): Promise<ImageDownsampler | undefined>;
-/** Output-token cap as a char proxy (design/64 §7.2(3), CC `Py_ = 25000` @335039; ~4 chars/token).
- *  Caps the shown body so 2000 very long lines can't blow the context budget.
+/** Output-token cap as a char proxy (CC's 25000, at ~4 chars/token). Caps the shown body so 2000 very
+ *  long lines cannot blow the context budget.
  *
- *  RB-285 M5 (归因收窄, CC 220 亲核): only the 25000 NUMBER is CC's. CC does NOT use a flat chars/4
- *  proxy — `KMu` @279761 pre-filters with a PER-EXTENSION chars-per-token coefficient (json/jsonl = 2,
- *  i.e. half of the 4 assumed here) and then confirms with a REAL tokenizer (`BLd` @518589); the
- *  budget itself is also overridable per call (`fileReadingLimits`) and by the `tengu_amber_wren` gate
- *  (`eze` @335063 (cli250.js:39563)), neither of which has a sema lane. Consequence, stated rather than hidden: on
- *  token-dense text (JSON/CJK/base64) this proxy UNDER-counts, so sema serves a page CC would have cut
- *  further; on token-sparse text it over-counts and paginates earlier than CC. A real tokenizer here
- *  would need a provider-neutral counting seam (BYOM — no single vocabulary), which is why the proxy
- *  stands; the divergence is a fidelity delta, not a correctness one (the partial-view marker always
- *  states the served window truthfully). */
+ *  Only the 25000 NUMBER is CC's. CC does NOT use a flat chars/4 proxy — it pre-filters with a
+ *  PER-EXTENSION chars-per-token coefficient (json/jsonl = 2, half the 4 assumed here) and then
+ *  confirms with a REAL tokenizer; its budget is also overridable per call and by a feature gate,
+ *  neither of which has a sema lane. Consequence, stated rather than hidden: on token-dense text
+ *  (JSON/CJK/base64) this proxy UNDER-counts, so sema serves a page CC would have cut further; on
+ *  token-sparse text it over-counts and paginates earlier than CC. A real tokenizer here would need a
+ *  provider-neutral counting seam (BYOM — no single vocabulary), which is why the proxy stands; the
+ *  divergence is a fidelity delta, not a correctness one (the partial-view marker always states the
+ *  served window truthfully). */
 export declare const MAX_READ_OUTPUT_CHARS = 100000;
-/** Per-read content-safety reminder appended after a text read (design/64 §7.2(7)).
+/** Per-read content-safety reminder appended after a text read.
  *
- *  Attribution, stated precisely because it was previously stated twice and wrongly in both directions.
- *  The upstream 88 source DOES carry the same mechanism — `FileReadTool.ts`'s
- *  `CYBER_RISK_MITIGATION_REMINDER`, appended after every text read, behind a PER-MODEL exemption gate.
- *  The 220 baseline does NOT: the text is gone (`grep -c malware pretty220.js` = 0), retired once the
- *  mitigation moved inside the serving model. So "not an upstream port" is false against 88 and true
- *  against 220, and neither reading alone describes the situation.
+ *  Attribution, stated precisely because either half alone is wrong. The upstream 88 source DOES carry
+ *  the same mechanism — `FileReadTool`'s `CYBER_RISK_MITIGATION_REMINDER`, appended after every text
+ *  read, behind a PER-MODEL exemption gate. The 220 baseline does NOT: the text is gone, retired once
+ *  the mitigation moved inside the serving model.
  *
  *  This engine keeps it because a BYOM deployment cannot assume its serving model carries the
  *  mitigation, and adjacency is the whole mechanism (a reminder in a system prompt hundreds of turns
@@ -169,16 +161,15 @@ export declare const MAX_READ_OUTPUT_CHARS = 100000;
  *  COVERAGE, stated because the switch is easy to over-read: the reminder rides the plain-text read and
  *  the notebook projection. PDF text extraction returns through its own result builder and has never
  *  carried it, so extracted PDF text reaches the model without this mitigation whatever the switch says.
- *  That gap predates the switch; its IMPERSONATION half is now closed — design/319 (B ticket) gave the
- *  PDF text legs the same detect-and-disclose trailer as this lane (reminder-shaped bytes in extracted
- *  PDF text are disclosed at the outlet, fs-pdf.ts), and their bodies were already fenced. The CYBER
- *  half (this malware-alertness sentence) still does not ride PDF text and stays an open item rather
- *  than closed silently — widening it to a third surface is a change to what every PDF read costs,
- *  not a wiring fix.
+ *  That gap predates the switch; its IMPERSONATION half is closed — the PDF text legs carry the same
+ *  detect-and-disclose trailer as this lane (reminder-shaped bytes in extracted PDF text are disclosed
+ *  at the outlet, fs-pdf.ts), and their bodies are fenced. The CYBER half (this malware-alertness
+ *  sentence) still does not ride PDF text and stays an open item rather than closed silently —
+ *  widening it to a third surface is a change to what every PDF read costs, not a wiring fix.
  *
- *  design/319 (A ticket): a FUNCTION over the session mark (formerly the `READ_CYBER_REMINDER`
- *  constant) — the open tag is rendered by the mint home so it carries the run's provenance mark;
- *  the sentence bytes are unchanged, and a markless call renders the historic bare form verbatim. */
+ *  A FUNCTION over the session mark, not a constant: the open tag is rendered by the mint home so it
+ *  carries the run's provenance mark; the sentence bytes are unchanged, and a markless call renders
+ *  the bare form verbatim. */
 export declare function readCyberReminderText(mark: string | undefined): string;
 export declare const BASH_DEFAULT_TIMEOUT_SEC = 120;
 export declare const BASH_MAX_TIMEOUT_SEC = 600;
@@ -238,10 +229,9 @@ export declare function bashTimeoutArgRefusal(timeoutMs: number | undefined, cap
     maxMs: number;
 }): string | undefined;
 /**
- * RB-370 ②/③ — the SINGLE authority for the Bash `timeout` parameter's two numbers:
- * the default budget applied when the model omits `timeout`, and the engine ceiling requests are
- * clamped to. The 120s/600s constants themselves are CC 220-same; what CC additionally has — and this
- * resolver adds — is configurability.
+ * The SINGLE authority for the Bash `timeout` parameter's two numbers: the default budget applied
+ * when the model omits `timeout`, and the engine ceiling requests are clamped to. The 120s/600s
+ * constants themselves are CC-same; what this resolver adds on top is configurability.
  *
  * Resolution, per leg (options over env over constant — the standing sema discipline: "deployments
  * configure the tool, not the process"; env stays as the CC-shaped fallback for process-level tuning):
@@ -252,7 +242,7 @@ export declare function bashTimeoutArgRefusal(timeoutMs: number | undefined, cap
  * default floors the cap. Invalid values (non-finite / <= 0) are discarded at every leg, options
  * included, exactly like CC's env read.
  *
- * ③ Readable seam: a shell/host rendering its OWN copy of the Bash tool description MUST
+ * Readable seam: a shell/host rendering its OWN copy of the Bash tool description MUST
  * read the true values from here instead of holding a sibling constant — the engine's description/param
  * text and its runtime clamp both interpolate this function's output (resolved once per tool instance),
  * so a self-held "600s" only matches by coincidence and forks silently the moment a deployment
@@ -273,8 +263,8 @@ export declare function resolveBashTimeoutCaps(opts?: {
  *  the line must be able to re-arm the ledger. Re-arms BOTH arms (a WeakMap has no clear — it is
  *  re-minted). Never called by production code. */
 export declare function __resetBashTimeoutAnnouncements(): void;
-/** RB-370 ②: the seconds view of a resolved {@link resolveBashTimeoutCaps} pair — the shell's INTERNAL
- *  unit stays seconds while every model-facing surface stays ms (design/64 §8.1C posture). One rounding
+/** The seconds view of a resolved {@link resolveBashTimeoutCaps} pair — the shell's INTERNAL unit
+ *  stays seconds while every model-facing surface stays ms. One rounding
  *  point, same Math.round form as the model-supplied timeout's own ms→s conversion, floored at 1s. */
 export declare function bashTimeoutCapsSec(caps: {
     defaultMs: number;
@@ -287,22 +277,21 @@ export declare function bashMaxOutputChars(): number;
 export declare const FILE_PATH_PARAMS: {
     file_path: Type.TString;
 };
-/** Honest head+tail truncation to {@link bashMaxOutputChars} (the middle is dropped with a real-total marker —
- *  the head AND tail both matter for a shell — deliberately KEPT as the inline shape even after RB-198 F4 added
- *  file-backed recovery below: unlike a background task's poll-for-the-latest-tail interaction, a foreground
- *  command's head can carry status a bare tail-keep would drop, and this shape is already tested/relied on).
- *  Shared by runShell (foreground) and TaskOutput (background poll). Delegates its arithmetic to the shared
- *  {@link clipWithFilePointer} (RB-85/RB-112/RB-122-hardened) but never exercises its pointer arm — no caller
- *  here passes a path. */
+/** Honest head+tail truncation to {@link bashMaxOutputChars}: the middle is dropped with a real-total
+ *  marker, because the head AND tail both matter for a shell. Kept as the inline shape even beside the
+ *  file-backed recovery below — unlike a background task's poll-for-the-latest-tail interaction, a
+ *  foreground command's head can carry status a bare tail-keep would drop. Shared by runShell
+ *  (foreground) and TaskOutput (background poll). Delegates its arithmetic to the shared
+ *  {@link clipWithFilePointer} but never exercises its pointer arm — no caller here passes a path. */
 export declare function clipShellOutput(s: string): string;
 /**
- * RB-198 F4 (form-one audit, "前台大输出落盘回读"): a foreground command's captured stdout/stderr are
- * ALREADY fully in memory here (the env delivered them whole — only `clipShellOutput` above decides how
- * much of that the model's turn actually sees) — the gap this closes is that the omitted middle was
- * simply discarded, forcing a blind full re-run to recover output that was, in fact, captured. "Whole"
- * means whatever THIS layer received, not a guarantee about what the process originally wrote (
- * review P1): the env's own rolling-tail cap (`MAX_EXEC_OUTPUT_BYTES`, exec-output-tail.ts) can already
- * have dropped the head before delivery on a truly enormous single command — this file is a faithful copy
+ * A foreground command's captured stdout/stderr are ALREADY fully in memory here (the env delivered
+ * them whole — only `clipShellOutput` above decides how much of that the model's turn actually sees).
+ * What this closes is that the omitted middle would otherwise be discarded, forcing a blind full
+ * re-run to recover output that was, in fact, captured. "Whole" means whatever THIS layer received,
+ * not a guarantee about what the process originally wrote: the env's own rolling-tail cap
+ * (`MAX_EXEC_OUTPUT_BYTES`, exec-output-tail.ts) can already have dropped the head before delivery on
+ * a truly enormous single command — this file is a faithful copy
  * of the received bytes either way, and still carries that cap's own `markTruncated()` marker when it
  * fired, so nothing here overclaims completeness beyond what the text itself already discloses. Purely
  * ADDITIVE: the inline head+tail framing above is untouched; this only gives the model a second, explicit
@@ -320,20 +309,20 @@ export declare function clipShellOutput(s: string): string;
  * containment on their explicit path arguments), so the model already has a direct route to the file: a
  * later `bash` call — the message text says so explicitly rather than implying Read will work, and picks
  * an example command the CALLING tool variant can actually run (see {@link shellRecoveryHint}: `sed -n`
- * for full `bash`, an allowlisted `tail -c` for `bash_readonly`, independent-review finding B). Creation/
- * write failure degrades silently to no file (the inline clip is unaffected either way), matching A5's
- * own degrade posture.
+ * for full `bash`, an allowlisted `tail -c` for `bash_readonly`). Creation/write failure degrades
+ * silently to no file (the inline clip is unaffected either way), matching the background lane's own
+ * degrade posture.
  */
 export declare function writeShellOverflowFile(env: ExecutionEnv, stdout: string, stderr: string): Promise<string | undefined>;
 /**
- * RB-421 (BB-5) — recognise the engine's OWN shell overflow recovery files, so `bash_readonly` can keep
- * honouring the `tail -c … <file>` command its result trailer advertises.
+ * Recognise the engine's OWN shell overflow recovery files, so `bash_readonly` can keep honouring the
+ * `tail -c … <file>` command its result trailer advertises.
  *
- * The first cut of that exemption was a `Set` of the exact paths ONE tool instance had minted. But the
- * trailer lives in the transcript, not in the instance: the hands toolkit is rebuilt on every task
- * preparation, so a later run replaying the advertised command met a tool with no memory of it and was
- * refused — the engine refusing its own advice, and (in the read-only band, whose Read tool is fenced by
- * the same roots) the only route to the truncated output.
+ * NOT a `Set` of the exact paths one tool instance minted: the trailer lives in the transcript, not in
+ * the instance, and the hands toolkit is rebuilt on every task preparation — a later run replaying the
+ * advertised command would meet a tool with no memory of it and be refused, i.e. the engine refusing
+ * its own advice, and (in the read-only band, whose Read tool is fenced by the same roots) the only
+ * route to the truncated output.
  *
  * Judged by SHAPE instead, which survives any rebuild, with the grant kept pinned to the engine's own
  * temp area on three counts that must ALL hold:
@@ -358,7 +347,7 @@ export declare function writeShellOverflowFile(env: ExecutionEnv, stdout: string
  */
 export declare function createShellOverflowSpoolFence(env: ExecutionEnv): (path: string) => Promise<boolean>;
 /**
- * RB-198 F4 (independent-review finding B): the recovery-file trailer's example command must be one the
+ * The recovery-file trailer's example command must be one the
  * CALLING tool can actually run. `sed` is not in {@link import("./bash-readonly-classifier.js").BASH_READONLY_DEFAULT_ALLOW} and `bash_readonly`
  * forbids the operators a pipe/redirect would need, so a `bash_readonly` command that overflows gets a
  * single-command, allowlisted alternative instead (`tail -c`, byte-bounded so it doesn't depend on line
@@ -366,17 +355,17 @@ export declare function createShellOverflowSpoolFence(env: ExecutionEnv): (path:
  * executable. Full `bash` keeps the precise form.
  */
 export declare function shellRecoveryHint(path: string, readOnly: boolean | undefined): string;
-/** CC 2.1.198 live-verbatim Edit/Write success trailer (all-tools-live-probe 2026-07-08 §2.1/§3.1) —
- *  appended to every Edit/Write success message (NOT NotebookEdit — CC ships it without the trailer). */
+/** CC 2.1.198 live-verbatim Edit/Write success trailer — appended to every Edit/Write success message
+ *  (NOT NotebookEdit — CC ships it without the trailer). */
 export declare const FILE_STATE_TRAILER = " (file state is current in your context \u2014 no need to Read it back)";
 export declare const CWD_SENTINEL = "__cc_cwd_9f2c1b__";
-/** Convert a model-supplied millisecond timeout to our internal seconds, clamped (design/64 §8.1C). Exported
- *  for the cc-parity TC-8.2 unit (model sees ms, internal stays seconds — no ×1000 error).
- *  ⚠️ RB-370: this returns the EFFECTIVE budget, not the request — capping at a call site destroys the
- *  caller's number before it can be disclosed. The Bash legs deliberately do NOT use this anymore (they
- *  pass the uncapped conversion into runShell, which caps once and reports the true request); use this
- *  only where the post-ceiling value is what you mean.
- *  RB-370 ②: the clamp bounds are no longer the bare constants — pass the caller's resolved caps
+/** Convert a model-supplied millisecond timeout to our internal seconds, clamped. Exported for the
+ *  cc-parity unit (model sees ms, internal stays seconds — no ×1000 error).
+ *  ⚠️ This returns the EFFECTIVE budget, not the request — capping at a call site destroys the
+ *  caller's number before it can be disclosed. The Bash legs deliberately do NOT use it (they pass the
+ *  uncapped conversion into runShell, which caps once and reports the true request); use this only
+ *  where the post-ceiling value is what you mean.
+ *  The clamp bounds are not the bare constants — pass the caller's resolved caps
  *  ({@link resolveBashTimeoutCaps}) to clamp against a configured deployment; omitted ⇒ resolve fresh
  *  (zero-config = the historical 120s/600s, byte-compat).
  *  ⚠️ This is the RAW converter and NOT the authority on what the tool accepts: it still folds the whole
@@ -388,7 +377,7 @@ export declare function msTimeoutToSec(timeoutMs: number | undefined, caps?: {
     defaultMs: number;
     maxMs: number;
 }): number;
-/** `.ipynb` redirect (design/64 §7.2(5), CC `FileEditTool:266-270`): a raw text edit/overwrite corrupts the
+/** `.ipynb` redirect (CC FileEditTool parity): a raw text edit/overwrite corrupts the
  *  notebook JSON, so the text-edit face refuses and redirects to the NotebookEdit tool (built in
  *  src/tools/fs/fs-write.ts, mounted with the rest of the hands band). */
 export declare function ipynbRedirect(toolName: string, path: string): string | undefined;
@@ -397,32 +386,29 @@ export declare function ipynbRedirect(toolName: string, path: string): string |
  *  ends in "\n". Behavior is identical for content WITHOUT a trailing newline. Shared by read_file's
  *  `total`, edit_file/write_file's "N lines" report, and the persisted ReadFileState.totalLines. */
 export declare function countLines(s: string): number;
-/** parity-204 — CC 2.1.204 VERBATIM (constants `qfc`+`Wfc`, cc204-bundle @9438179/@9440917; 198 zero
- *  hits): the reminder served when a DEFAULT whole-file Read hits a startup-seeded, unchanged file.
- *  CC: ``Wfc(e) = `${qfc} (see "Contents of ${e}" above) and has not changed on disk. Use that content
- *  instead of re-reading.</system-reminder>``` with `qfc = '<system-reminder>This file is already in
- *  your context'`. `filePath` is the CANONICAL key (CC passes the resolved full path `f`, matching the
+/** CC 2.1.204 VERBATIM: the reminder served when a DEFAULT whole-file Read hits a startup-seeded,
+ *  unchanged file. `filePath` is the CANONICAL key (CC passes the resolved full path, matching the
  *  `Contents of <path>` header its context seeding emits — deployments seeding files should title the
- *  injected block the same way so the back-reference lands). Locked verbatim by test (逐字常量锁) —
- *  design/319: the BODY and close tag stay CC-verbatim; the open tag alone is rendered by the mint
- *  home and carries the session mark when one is threaded (the recorded wire-form divergence). */
+ *  injected block the same way so the back-reference lands). Locked verbatim by test: the BODY and
+ *  close tag stay CC-verbatim; the open tag alone is rendered by the mint home and carries the session
+ *  mark when one is threaded (the recorded wire-form divergence). */
 export declare function seededFileUnchangedReminder(filePath: string, mark?: string): string;
 /**
- * RB-197②(交叉复审命中,已修) — true when `resultText` is one of the Read tool's TWO dedup
- * markers (the ordinary unchanged-since-last-read stub below, or {@link seededFileUnchangedReminder})
- * rather than a genuine content transmission. A consumer deciding "is this file's real content
- * present in THIS message" (e.g. auto-compaction's kept-tail visibility scan) must treat a stub hit
- * as absence — the marker POINTS AT an earlier read that may itself no longer be in context.
+ * True when `resultText` is one of the Read tool's TWO dedup markers (the ordinary
+ * unchanged-since-last-read stub below, or {@link seededFileUnchangedReminder}) rather than a genuine
+ * content transmission. A consumer deciding "is this file's real content present in THIS message"
+ * (e.g. auto-compaction's kept-tail visibility scan) must treat a stub hit as absence — the marker
+ * POINTS AT an earlier read that may itself no longer be in context.
  *
- * RB-373: both emitters now ALSO carry a structured marker (`details.type === "file_unchanged"`,
+ * Both emitters ALSO carry a structured marker (`details.type === "file_unchanged"`,
  * fs-read.ts `fileUnchangedResult`) — consumers with access to the tool result's `details` should
  * branch on that instead of this prose match (which can false-positive on file CONTENT that quotes
  * either sentence). This predicate stays for text-only surfaces (compaction sees rendered text).
  */
 export declare function isReadDedupStubResult(resultText: string): boolean;
-/** parity-204 — pre-seed the hands' read state for a file whose FULL, disk-verbatim text was injected
- *  into the model's context at startup (CC 2.1.204 `seededFromContext:!0` seeding, cc204-bundle
- *  @17917159: CLAUDE.md/nested-memory preload; sema: ProjectMemoryLoad.seededFiles → prepare-task).
+/** Pre-seed the hands' read state for a file whose FULL, disk-verbatim text was injected into the
+ *  model's context at startup (CC 2.1.204 `seededFromContext` seeding of the memory preload; sema:
+ *  ProjectMemoryLoad.seededFiles → prepare-task).
  *  `content` MUST be the file's exact disk text at load time — the Read tool's seeded dedup treats a
  *  hash match as "unchanged"; a truncated/annotated variant must NOT be seeded (CC exempts those via
  *  `isPartialView`; sema's contract is simply "don't seed partials"). `key` is the CANONICAL path
@@ -431,7 +417,7 @@ export declare function isReadDedupStubResult(resultText: string): boolean;
 export declare function seedReadFileStateFromContext(state: ReadFileState, key: string, content: string): void;
 /**
  * Seed the hands' read state from a WHOLE-file content the session transcript recorded on an earlier
- * turn (ruled 2026-08-05; the selection rules live in core/runner/session-file-state-replay.ts).
+ * turn (the selection rules live in core/runner/session-file-state-replay.ts).
  *
  * Same minting as {@link seedReadFileStateFromContext} and the same normalization reason, with three
  * deliberate differences, each of which is a claim this seed cannot honestly make:
@@ -446,7 +432,7 @@ export declare function seedReadFileStateFromContext(state: ReadFileState, key:
  */
 export declare function seedReadFileStateFromTranscript(state: ReadFileState, key: string, content: string, lastReadAt: number): void;
 /**
- * #483 rung-1 — copy a SESSION-inherited read-file state into a new task's map, under the new task's
+ * Copy a SESSION-inherited read-file state into a new task's map, under the new task's
  * own containment judgment (CC parity: readFileState is session-scoped — minted once per REPL session,
  * mutated across turns, with no turn-boundary or abort clear site; sema's per-task map inherits the
  * previous turn's live state instead).
@@ -458,7 +444,7 @@ export declare function seedReadFileStateFromTranscript(state: ReadFileState, ke
  *    replay leg already judges — an unjudged copy would smuggle out-of-face entries into the task
  *    (and into its checkpoints).
  *  - **`seededFromContext` entries do not inherit.** That flag claims the file's text lives in the
- *    system-prompt lane OF THIS TASK — a claim only this task's own startup seeding (T10) can make.
+ *    system-prompt lane OF THIS TASK — a claim only this task's own startup seeding can make.
  *    A still-declared file is re-seeded the same turn (no loss); a no-longer-declared one must not
  *    keep answering reads with an "already in your context" reminder that is no longer true.
  *
@@ -468,8 +454,8 @@ export declare function seedReadFileStateFromTranscript(state: ReadFileState, ke
  */
 export declare function inheritSessionReadFileState(target: ReadFileState, inherited: ReadFileState, judgeKey: (recordedKey: string) => Promise<string | undefined>): Promise<void>;
 /**
- * RB-197 (form-one audit, CC 2.1.220 @388663-388664): a landed compaction summarizes old Read results OUT
- * of the context, so every non-seeded read-state entry must be dropped — CC snapshots then
+ * CC parity: a landed compaction summarizes old Read results OUT of the context, so every non-seeded
+ * read-state entry must be dropped — CC snapshots then
  * `readFileState.clear()`s at the same spot. Without this, the Read dedup stub above answers a re-read of
  * an unchanged file with "content omitted to save context" pointing at content that no longer exists
  * anywhere in the context (the model works from hallucinated memory or has to vary offset/limit to escape).
@@ -482,14 +468,14 @@ export declare function inheritSessionReadFileState(target: ReadFileState, inher
  * The read-before-edit gate tightens as a consequence, matching CC: after a compaction the model must
  * re-Read a summarized-away file before editing it, instead of blind-editing from a stale recollection.
  *
- * RB-197②(独立复审 + 命中,已修): a THIRD category besides seeded/re-attached — a file whose most
- * recent Read is still visible verbatim in the compaction's KEPT tail is deliberately left OUT of
+ * A THIRD category besides seeded/re-attached: a file whose most recent Read is still visible
+ * verbatim in the compaction's KEPT tail is deliberately left OUT of
  * `attachedComplete` (re-attaching it would just duplicate content already in context), but its
  * existing read-state entry must survive unmodified for the SAME reason a seeded entry does: the
- * model's view of it did not change. Wiping it (the pre-fix behavior) broke two things for exactly
- * these files — the read-before-edit gate would reject an Edit the model could visibly justify from
- * its own kept-tail Read, and a next Read would miss the dedup stub and retransmit the whole file,
- * recreating the exact waste RB-197①/② exist to remove. `preserveKeys` is the caller's kept-tail set
+ * model's view of it did not change. Wiping it breaks two things for exactly these files — the
+ * read-before-edit gate would reject an Edit the model could visibly justify from its own kept-tail
+ * Read, and a next Read would miss the dedup stub and retransmit the whole file, recreating the exact
+ * waste this dedup exists to remove. `preserveKeys` is the caller's kept-tail set
  * (see `maybeCompact`'s `candidateFiles` computation) — passed as keys already in `state`'s own
  * coordinate (canonicalized the same way the Read/Edit/Write tools populate it), so a plain lookup
  * suffices; no re-hash/re-register needed since the entry's content genuinely has not changed.
@@ -498,7 +484,7 @@ export declare function applyCompactionToReadFileState(state: ReadFileState, att
     path: string;
     content: string;
 }>, preserveKeys?: ReadonlyArray<string>): void;
-/** 批④ #1 (CC 2.1.198 verbatim skeleton, bundle :48196/:335883/:478419): the ENOENT error body for a
+/** CC 2.1.198 verbatim skeleton: the ENOENT error body for a
  *  missing Read/Edit target — `File does not exist. Note: your current working directory is <cwd>.`
  *  plus a `Did you mean <sibling>?` correction when the parent directory holds a near-name (case
  *  variant / same stem different extension — the high-frequency self-heal path). Best-effort: a
@@ -508,7 +494,7 @@ export declare function enoentMessage(env: ExecutionEnv, key: string, cwd: strin
         pattern: string;
     } | null;
 }): Promise<string>;
-/** Per-task mutable working directory shared by the shell and the path-taking fs tools (design/64 §16.3).
+/** Per-task mutable working directory shared by the shell and the path-taking fs tools.
  *  Holds the RAW path (never canonicalized): bash `cd` updates `current`, and the fs tools resolve relative
  *  paths against it. Containment is still enforced per-op by resolveKey (canonicalize + within), so a `cd`
  *  through a symlink out of root cannot carry across a relative fs path outside. */

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

@@ -3,13 +3,13 @@ import type { BeforeWriteHook, FileEditedHook, TrackFileEditHook } from "../../c
 import { type ReadFileState } from "./safety.js";
 import { type CwdRef } from "./fs-shared.js";
 /**
- * design/138 S2-C — the `beforeWrite` CONTENT hook (C-F2: mounted here, not in ToolPolicy, because
- * only this band sees the FINAL text an Edit/NotebookEdit produces — the applied old→new full text
- * is what actually lands on disk). Called before EVERY `env.writeFile` in Write/Edit/NotebookEdit
- * with the resolved containment key and the exact text about to be written. Returning `{ ok:false }`
- * makes the tool fail with a structured error and NOTHING is written. The Runner wires this to the
- * MemoryEngine's write gate (`MemoryEngine.gateWrite`) — a non-memory path passes with one string
- * prefix comparison there (零开销直通). Absent hook ⇒ byte-identical behavior.
+ * The `beforeWrite` CONTENT hook, mounted here rather than in ToolPolicy because only this band sees
+ * the FINAL text an Edit/NotebookEdit produces — the applied old→new full text is what actually lands
+ * on disk. Called before EVERY `env.writeFile` in Write/Edit/NotebookEdit with the resolved
+ * containment key and the exact text about to be written. Returning `{ ok:false }` makes the tool fail
+ * with a structured error and NOTHING is written. The Runner wires this to the MemoryEngine's write
+ * gate (`MemoryEngine.gateWrite`), where a non-memory path passes on one string prefix comparison.
+ * Absent hook ⇒ byte-identical behavior.
  */
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook } from "../../core/types.js";
 export declare function createEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook): AgentTool;
@@ -18,7 +18,7 @@ export declare function createWriteFileTool(env: ExecutionEnv, state: ReadFileSt
  * design v1.163 — NotebookEdit: replace/insert/delete a single cell in a .ipynb. CC-parity tool over the SAME hand-band
  * safety skeleton as Edit/Write (resolveKey containment → requireRead read-before-edit → checkStale content-hash
  * freshness → mutate → writeFile → state.set), with object ops swapped for ipynb-JSON cell mutation. Read serves
- * .ipynb as the RB-227 cell projection but records read state (hash/totalLines) in the RAW notebook-text
+ * .ipynb as the cell projection but records read state (hash/totalLines) in the RAW notebook-text
  * coordinate — that raw-coordinate read record is what this tool's freshness check depends on.
  */
 export declare function createNotebookEditTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook, trackEdit?: TrackFileEditHook, onEdited?: FileEditedHook): AgentTool;

package/dist/tools/fs/gh-rate-limit.d.ts

@@ -1,27 +1,26 @@
 /**
- * gh rate-limit hint (CC 2.1.198 parity — PARITY-SPOT-REMINDERS SR-2).
+ * gh rate-limit hint (CC 2.1.198 parity).
  *
  * CC appends a one-shot <system-reminder> to a FOREGROUND Bash result when a `gh` invocation hits the
- * GitHub API rate limit, so the model sleeps/schedules instead of hammering retries. Anchors:
- * pretty.js:281399-281404 (`Bxa` — the reminder text), :281472-281473 (`m0p` command gate + `f0p`
- * output gate, both ported verbatim), :281426 (`h0p` = 60s throttle), :335536 (attach point — background
- * tasks are never hinted). sema delta (recorded): CC's closing clause names its ScheduleWakeup tool;
- * sema's wait primitive is the Monitor tool, so the clause is adapted — everything else is verbatim.
+ * GitHub API rate limit, so the model sleeps/schedules instead of hammering retries. The command gate,
+ * output gate and 60s throttle below are ported verbatim; a detached/background task is never hinted.
+ * Registered delta: CC's closing clause names its ScheduleWakeup tool; sema's wait primitive is the
+ * Monitor tool, so that clause is adapted — everything else is verbatim.
  */
-/** Test seam: reset the process-wide throttle window (mirrors CC's module-level `Mxa`). */
+/** Test seam: reset the process-wide throttle window (mirrors CC's module-level timestamp). */
 export declare function resetGhRateLimitHintThrottleForTests(): void;
 /**
  * Returns the rate-limit reminder when `command` is a real gh call AND `output` shows a rate-limit
  * error AND the 60s throttle window is open; otherwise undefined. Callers attach it to FOREGROUND
  * Bash results only (CC gates on `backgroundTaskId` — a detached/background task is never hinted).
  *
- * `monitorToolActive` (#181-F6): the closing clause teaches the Monitor tool, but Monitor is mounted
- * by the Runner (`backgroundTaskToolsActive`), not by the Bash tool — under handsReadOnly or a
- * background-less env the taught tool is not on the roster. `false` drops exactly that clause (the
- * sleep-until-reset advice stays); absent/`true` keeps the historic full wording (RB-374① posture:
- * an uninformed caller gets the byte-identical sentence, never a silent rewrite).
+ * `monitorToolActive`: the closing clause teaches the Monitor tool, but Monitor is mounted by the
+ * Runner (`backgroundTaskToolsActive`), not by the Bash tool — under handsReadOnly or a background-less
+ * env the taught tool is not on the roster. `false` drops exactly that clause (the sleep-until-reset
+ * advice stays); absent/`true` keeps the full wording, so an uninformed caller gets the byte-identical
+ * sentence rather than a silent rewrite.
  *
- * design/319 (A ticket): `mark` — the session's reminder provenance mark, stamped on the open tag
- * by the mint home (body bytes unchanged; absent ⇒ historic bare tag).
+ * `mark`: the session's reminder provenance mark, stamped on the open tag by the mint home (body bytes
+ * unchanged; absent ⇒ bare tag).
  */
 export declare function ghRateLimitHint(command: string, output: string, now?: number, monitorToolActive?: boolean, mark?: string): string | undefined;