@sema-agent/core 5.20.0 → 5.21.0

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

@@ -1,47 +1,263 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+/**
+ * batch-B (CC 2.1.187 parity): Read/Edit/Write take the file path as `file_path`. Read the target the same way
+ * EVERYWHERE the path is consumed from a tool-call's args — not just the tool body but ALSO every gate that
+ * extracts the write target to confine it (sensitive-path, skill allowPaths, session allowDirs). A gate that only
+ * read `args.path` would see `undefined` for a `file_path` call and either fail-OPEN (bypass the guard — a real
+ * hole) or fail-closed (deny a legitimate write). Single source.
+ *
+ * The `path` arm is deliberately BROADER than what Read/Edit/Write accept (ruled 2026-08-03): their schema requires
+ * `file_path` and rejects the retired `path` alias outright (fs-shared.ts FILE_PATH_PARAMS), but this reader is
+ * shared with gates that judge OTHER tool vocabularies — Glob's real `path` parameter, deployment-authored tools —
+ * and a gate must never see LESS than the tool it is confining might act on. So the asymmetry is the design: the
+ * schema decides what a caller may send, this decides what gets judged, and this side over-reads on purpose.
+ */
 export declare function fileArgPath(args: unknown): string | undefined;
+/**
+ * The WRITE TARGET of a path-confinable write call, tool-aware ([886]①a/b — single source for every
+ * gate that confines a write target, same discipline as {@link fileArgPath} above):
+ *
+ *  · canonical `NotebookEdit` → `notebook_path` FIRST, `file_path`/`path` only as fallback. The tool
+ *    itself writes `notebook_path`; its schema tolerates extra keys, so a stray/decoy `file_path` on a
+ *    NotebookEdit call must never become the judged target while the real write lands elsewhere
+ *    (a gate that read `file_path` first would confine the decoy — the [886]①b hole).
+ *  · every other tool → `file_path`/`path` first ({@link fileArgPath}), `notebook_path` as the
+ *    historical fallback (unchanged behavior for the pre-existing gate callers).
+ *
+ * `canonicalName` is the tool name as mounted (RB-476-A: raw — the legacy normalizer is retired;
+ * this module stays dependency-free of the alias table — "NotebookEdit" is the canonical CC name and
+ * old→new normalization is identity for it).
+ */
 export declare function writeTargetPath(canonicalName: string, args: unknown): string | undefined;
+/**
+ * The "hand" file tools (design/44) — safety invariants ported from CC's `FileEditTool` (design/43 Rule
+ * 7): without these a weak model blind-edits / overwrites files (P0 safety, not polish). This module is
+ * the pure/testable core (path resolution + the three edit invariants + content hashing); the tools in
+ * this dir compose it. Per-task state and the execution env are passed in (factory-closure wiring,
+ * design/44 §11 ruling A), never read from a shared/global.
+ */
+/** What we remember about a file the agent has read (design/44 §4). */
 export interface ReadEntry {
+    /** SHA-256 of the content at read time. Staleness is detected by content hash, NOT mtime — mtime is
+     *  unreliable across containers/volumes/NFS and across a design/45 suspend→resume on another replica. */
     hash: string;
+    /** Total line count at read time, and whether the read was truncated (for the edit truncation hint, S2). */
     totalLines: number;
     truncated: boolean;
+    /** RB-200 F2 — CC `isPartialView` parity (220 @515151 sets it only when the auto-pagination catch branch
+     *  fires, i.e. the model asked for the file by DEFAULT — no explicit offset/limit — and the token cap
+     *  truncated it anyway; an EXPLICIT offset/limit slice that fits under the cap is NEVER marked this way,
+     *  even though it's equally "not the whole file"). Deliberately narrower than {@link truncated} above,
+     *  which also fires for a fully-intentional, successful slice read (`start>1 || end<total`) — folding
+     *  THIS flag into that broader one would make {@link OVERSIZE_READ_ESCAPE_HINT}'s documented promise
+     *  ("read it in slices with explicit offset/limit to satisfy the read-first rule") false: a model paging
+     *  through an oversized file on purpose would never be able to satisfy {@link requireRead} again. Optional/
+     *  additive: undefined on every non-Read write-back (Write/Edit re-record the file they just fully wrote)
+     *  and on every seeded/attachment entry — those are never partial by construction. */
     isPartialView?: boolean;
+    /** The line window actually served to the model on the last read (design/64 §7.2(6) dedup stub). Lets
+     *  read_file return a `file_unchanged` stub when the SAME window is re-requested and the content hash is
+     *  unchanged — saving the re-transmitted body. Optional/additive: undefined (e.g. an entry seeded from an
+     *  older design/45 checkpoint) just means "no dedup", never a false hit. */
     view?: {
         start: number;
         end: number;
     };
+    /** Millisecond timestamp of the last read/write-back that recorded this entry (blackboard
+     *  2026-07-03, compact re-read parity: the post-compaction attachment picks the most RECENTLY
+     *  read files — CC sorts readFileState by timestamp). Optional/additive: undefined (an entry
+     *  seeded from an older checkpoint) sorts last, never breaks. */
     lastReadAt?: number;
+    /** CC 2.1.204 parity (`seededFromContext`, cc204-bundle @17889409 / seeding @17917159; 198 zero
+     *  hits): TRUE when the Runner pre-seeded this entry because the file's FULL disk-verbatim text
+     *  was injected into the model's context at startup (ProjectMemoryLoad.seededFiles — CC's
+     *  CLAUDE.md/nested-memory seeding). A DEFAULT whole-file Read of an UNCHANGED seeded file
+     *  answers with the already-in-context reminder instead of re-transmitting the body. Any real
+     *  Read / edit write-back records a FRESH entry without this flag, so a file that changed on
+     *  disk (hash mismatch) always serves real content and the dedup disarms permanently.
+     *  Optional/additive: absent = normal entry. */
     seededFromContext?: boolean;
 }
+/** Per-task record of which files have been read, keyed by canonical path (design/44 §4, §11 ruling A:
+ *  owned by prepare-task, closure-captured by the tools; serialized into a design/45 Checkpoint later). */
 export type ReadFileState = Map<string, ReadEntry>;
+/** SHA-256 hex of UTF-8 content — the staleness/identity key (design/44 §4 inv 2, jury M1). */
 export declare function sha256(content: string): string;
+/** A failed path resolution / invariant check, surfaced to the model as a self-correctable tool error. */
 export interface FsViolation {
     code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid";
+    /** RB-264 N1: set on the `not_read` violation raised by an AUTO-TRUNCATED read
+     *  ({@link ReadEntry.isPartialView}) rather than by a never-read file. Both carry the same CC-verbatim
+     *  message; only this one needs {@link PARTIAL_VIEW_READ_ESCAPE_HINT} appended, because for it a plain
+     *  re-read is a fixpoint. */
     partialView?: true;
+    /** RB-371 ④: set ONLY on `path_not_in_root` — the CANONICAL key the refused path resolved to
+     *  (symlinks followed, tracked cwd applied), i.e. the value the fence actually judged. Rides into
+     *  the tool result's `details` (see {@link violationDetails}) so a consumer can count/aggregate
+     *  boundary refusals from fields instead of regexing the prose. */
     target?: string;
+    /** RB-371 ④: set ONLY on `path_not_in_root` — the containment roots in effect (primary first,
+     *  then additionalDirectories), canonical form. */
     roots?: readonly string[];
     message: string;
 }
+/**
+ * Absolute in EITHER family: POSIX `/…` or drive-letter `C:\…`/`C:/…`.
+ *
+ * REF-C1 — this is the ONE definition of "already absolute, therefore do not prepend a base". It was
+ * independently re-typed at nine coordinates (search.ts ×4, bash-readonly-classifier.ts,
+ * core/lsp.ts, core/runner/prepare-task.ts, orchestration/run-spec.ts and here), three of which
+ * carried a comment claiming the same philosophy as this file while keeping their own copy. The
+ * failure mode is not the duplication itself but the drift it invites: a family added at one
+ * coordinate leaves the other eight judging the same string differently, and this predicate gates a
+ * security fence (frozen-path deny, readonly-boundary containment) as well as URI key minting.
+ * Callers that need a family the predicate does not cover must widen it HERE, not locally.
+ *
+ * The UNC arm (`\\host\share\…`) was exactly that drift, found already in flight: core/lsp.ts carried it
+ * privately while the other eight coordinates did not, so the LSP tool leg resolved a UNC path as
+ * absolute while the edit-nudge leg prefixed it with the task root — two URI keys for one file. Folding
+ * it in here settles the disagreement in the direction the rest of this file already takes: a literal
+ * `\\host\share\…` is win-form (see {@link isWinFormPath}) and `within()` lands it outside every
+ * POSIX/drive root, i.e. it is a location the working directory does not contain.
+ */
 export declare function isAbsolutePathForm(p: string): boolean;
+/**
+ * Windows-FAMILY spelling of a path (codex 1.237 F6, extracted here so {@link canonicalizeTarget} judges
+ * the UNC family by the same rule): drive-rooted (`C:\…`/`C:/…`), UNC-backslash (`\\host\share`), or a
+ * RELATIVE path using `\` as its separator. Never keyed on `process.platform` — the exec env may be remote
+ * and of the other family than the host. A `/`-rooted path is POSIX-form even when a file NAME inside it
+ * contains a literal backslash (legal on POSIX), and `//host/share` is therefore POSIX-form too — which is
+ * the whole point: on POSIX that spelling is an ordinary absolute path, not a network share.
+ *
+ * REF-C2 — this is the ONE definition of the win-family spelling. core/file-snapshot-store.ts held a
+ * byte-identical private twin (its manifest key/restore-target folds are conditioned on it) and now
+ * imports this one; core/ already depends on this module at seven other coordinates, and this file's own
+ * imports are `node:crypto` plus a type, so there is no layering wall between them.
+ */
 export declare function isWinFormPath(p: string): boolean;
 export declare function isBlockedDevicePath(key: string): boolean;
+/**
+ * RB-153 — purely LEXICAL path normalization: collapse repeated separators, drop `.` segments, and
+ * resolve `..` against the preceding segment. No filesystem access, no cwd: this is a spelling
+ * normalizer, not a resolver. (Deliberately NOT `canonicalizeNewPath`'s job — that one walks the real
+ * filesystem precisely because folding `..` lexically across a SYMLINKED parent is unsound. Use this one
+ * only where the question is "are these two strings the same name", never "which file is this".)
+ *
+ * It exists because {@link isBlockedDevicePath} is an exact-string membership test, and `//dev/zero`,
+ * `/dev/./zero` and `/dev/../dev/zero` all name the device `/dev/zero` to the kernel while spelling it
+ * three different ways. Callers that match a device list against a raw argument must normalize first or
+ * the list is a spelling filter rather than a device filter.
+ *
+ * REF-C3 — coverage, after folding in the two private re-implementations that had grown around this one
+ * (the bash classifier's drive-aware wrapper and prepare-task's `normalizeSegments`). The union they
+ * covered between them is now the contract here:
+ *  · POSIX absolute — `/a/./b` → `/a/b`; `/..` is `/`, matching the kernel.
+ *  · drive-letter (`C:\a\..\b`) and UNC (`\\host\share\..\x`) — prefix preserved, folding applies
+ *    to the tail only, and the REJOIN uses the path's own native separator so one file cannot acquire
+ *    two keys by separator form.
+ *  · RELATIVE — stays relative (`dev/zero` therefore still never matches an absolute device entry:
+ *    `dev/zero` under some other directory is an ordinary file), and a leading `..` is KEPT rather than
+ *    popped into nothing — dropping it would move the path.
+ *
+ * FAMILY-awareness is the one thing none of the three had right. A backslash is a separator only in a
+ * win-form path; in a POSIX path it is an ordinary filename character, and the classifier's old
+ * unconditional `\`→`/` fold rewrote a POSIX file literally named `a\..\b` into a different location
+ * before the boundary check ever saw it (both directions: false refusal and false allow).
+ */
 export declare function normalizeAbsPathLexically(p: string): string;
+/**
+ * The READ-leg fold (REF-C3 receipt, R1 verify ISSUE-1): removes `.` segments and duplicate
+ * separators ONLY — transformations that name the SAME file on every real filesystem, symlinks
+ * included. `..` is deliberately KEPT: `a/../x` and `x` are different files when `a` is a symlink,
+ * and this function's callers go on to OPEN the result (fileInfo/readText), not just to mint a
+ * comparison key. Ask "which file is this" here; ask "are these two strings the same name" with
+ * {@link normalizeAbsPathLexically}.
+ */
 export declare function foldRedundantPathSegments(p: string): string;
+/** True if `path`'s extension is a known binary format (pure check — no I/O). Used by read_file and grep. */
 export declare function hasBinaryExtension(path: string): boolean;
+/** The MIME type to return an image file AS (a visual `ImageContent` block), or `undefined` if `path` is not a
+ *  Read-supported image. Pure — no I/O. */
 export declare function imageMimeForRead(path: string): string | undefined;
+/** Verify the raw bytes actually ARE the image format the extension claims (magic-number sniff). Extension alone
+ *  is forgeable: a `.png` holding text / an empty file / a truncated blob would otherwise become a malformed
+ *  `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. (batch-C, codex review.) */
 export declare function imageMagicMatches(bytes: Uint8Array, mimeType: string): boolean;
+/** One contiguous byte pattern that must appear at a fixed offset for its signature to match. */
 export interface BinaryMagicSegment {
+    /** Byte offset the pattern starts at — 0 for a leading signature, 257 for tar's `ustar`, and so on. */
     readonly offset: number;
+    /** The exact bytes that must appear there. */
     readonly bytes: readonly number[];
 }
+/** A file-format signature: EVERY segment must match for the format to be claimed. */
 export interface BinaryMagicSignature {
+    /** Human-readable format label. It lands verbatim in the Read refusal, so it names what the file IS,
+     *  never the extension it happened to be carrying. */
     readonly format: string;
+    /** All segments must match. A second segment exists only to disambiguate a prefix that also spells
+     *  plausible text (`BM`, `RIFF`, `FORM`): the payload word at the later offset is what decides. */
     readonly segments: readonly BinaryMagicSegment[];
 }
+/**
+ * ANG-5 (external black-box re-review, ruled 2026-08-03) — magic-byte criteria for the formats
+ * {@link hasBinaryExtension} names. That list carries 103 extensions; before this table only PDF
+ * (`pdfMagicMatches`, in the PDF lane) and the four API image formats ({@link imageMagicMatches}) had a
+ * content criterion, so for every other listed format the NAME was the only evidence available. Where the
+ * content IS reachable that left identification to the statistical fallback ({@link isBinaryContent}),
+ * which samples the first 8192 decoded characters and passes anything whose control-character ratio
+ * stays under 10% — a short archive/executable header followed by printable payload clears that bar
+ * and gets delivered as text.
+ *
+ * Shape: pure data, one table, `offset + bytes`. Adding a format is a row; the matcher
+ * ({@link binaryMagicFormat}) never changes. Rows are grouped by family so the next diff stays readable.
+ *
+ * Admission rule — a row exists only where the signature is DECIDABLE. A short ASCII prefix that also
+ * opens ordinary prose is admitted only with a disambiguating second segment (`BM` + the zeroed
+ * reserved fields, `RIFF`/`FORM` + the payload word); formats whose only fixed marker is such a prefix
+ * are deliberately absent, because a false positive here makes a real text file unreadable — the exact
+ * harm the name-only refusal was retired for. Absent on that ground: DOS/PE (`MZ`, with the PE header
+ * at a variable offset), SWF (`FWS`/`CWS` + a wide version byte), Blender (`BLENDER`), `.pyc` (a
+ * per-release magic), and PostScript/EPS (genuinely text). They stay covered by the statistical sniff.
+ *
+ * Converged consumer: the WebFetch lane (`tools/web.ts`'s `sniffBinarySignature`) used to carry its own
+ * private eight-format if-chain for HTTP bodies; it now reads this table via {@link binaryMagicFormat}
+ * (PDF handled the same way this table's own callers handle it — via `pdfMagicMatches`, not a row here).
+ */
 export declare const BINARY_MAGIC_SIGNATURES: readonly BinaryMagicSignature[];
+/**
+ * Identify `bytes` by its file signature — the format label, or `undefined` when no row in
+ * {@link BINARY_MAGIC_SIGNATURES} matches. Pure — no I/O, and name-blind by construction (nothing here
+ * looks at a path), so it can be asked in either direction: a mis-named binary is caught, and a listed
+ * extension holding real text is NOT claimed.
+ */
 export declare function binaryMagicFormat(bytes: Uint8Array): string | undefined;
+/**
+ * Content sniff for binary data (design/64 §17.1, CC `constants/files.ts` `isBinaryContent`): a NUL byte,
+ * or more than 10% non-printable characters in the sample, means binary. Second layer behind
+ * {@link hasBinaryExtension} — catches extension-less or mis-named binaries (a `Dockerfile` that is really
+ * a compiled blob) that would otherwise be read as mojibake. Plain text (incl. UTF-8, tabs/newlines) passes.
+ */
 export declare function isBinaryContent(sample: string): boolean;
+/**
+ * CC's own UNC/network-path predicate, verbatim (220 @515523:
+ * `n.startsWith("\\\\") || n.startsWith("//")`). Pure.
+ *
+ * RB-279: the predicate is CC's, but CC's POLARITY is the opposite of what sema used it for. In CC this
+ * test is an EARLY ALLOW — `return { result: !0 }`, skipping the binary-extension and device checks that
+ * follow it — and CC applies it to the NORMALIZED path (`Li` ⇒ `path.normalize`), not the raw argument.
+ * See {@link canonicalizeTarget} for how sema now mirrors that (and for the two deliberate differences).
+ * This function stays a pure spelling test with no verdict of its own.
+ */
 export declare function isUncPath(path: string): boolean;
+/**
+ * Resolve a model-supplied path to a canonical key AND enforce rootPath containment (design/44 §4
+ * inv 5/6/7). Existing paths use `canonicalPath` (resolves symlinks, so the same file can't get two
+ * keys). New paths canonicalize the **deepest existing ancestor** then rejoin the missing tail — a
+ * symlinked parent therefore cannot land the target outside root. Returns the canonical key, or a
+ * `path_not_in_root` violation. (Defense-in-depth at the tool layer; NOT a substitute for a sandboxed
+ * `executionEnv` — see design/44 §5.)
+ */
 export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean): Promise<{
     ok: true;
     key: string;
@@ -49,6 +265,15 @@ export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, pat
     ok: false;
     violation: FsViolation;
 }>;
+/**
+ * Canonicalize a model-supplied path to its real on-disk target (symlinks resolved; for a path that
+ * doesn't exist yet, the deepest EXISTING ancestor is canonicalized then the missing tail rejoined —
+ * so a symlinked parent cannot land the target elsewhere). NO containment check — this is the pure
+ * canonicalization shared by `resolveKey` (which adds rootPath containment) and
+ * `createSensitivePathPolicy` (design/72 §2.1, which matches the real target against a guarded list).
+ * A single source of truth for symlink resolution: a sensitive-path policy that matched the raw path
+ * instead of the real target would compare against the spelling, not the destination (§2.1).
+ */
 export declare function canonicalizeTarget(env: ExecutionEnv, path: string, signal?: AbortSignal, baseCwd?: string): Promise<{
     ok: true;
     key: string;
@@ -57,30 +282,181 @@ export declare function canonicalizeTarget(env: ExecutionEnv, path: string, sign
     message: string;
     unresolvedSymlink?: true;
 }>;
+/** Render a `FsViolation` as the model-facing tool error text (returned, never thrown — model retries). */
 export declare function violationText(toolName: string, v: FsViolation): string;
+/**
+ * RB-371 ④ — structured `details` for a rendered violation: non-`undefined` ONLY for
+ * `path_not_in_root`, the one code with per-refusal coordinates worth counting (which canonical
+ * target, against which roots). Designed to be passed straight as `errorResult`'s second argument by
+ * every renderer of a {@link resolveKey} violation — `undefined` keeps the pre-existing detail-less
+ * shape for all other violation codes, so nothing else changes byte-wise.
+ *
+ * RB-397-c (回溯复查批): `type` is the WIRE discriminator — `structuredFrom`'s `CC_DETAIL_TYPES` gate
+ * (tool-output-projection.ts) keys on `details.type`, so without it the card never reached
+ * `tool_end.structured` and the "count from fields" promise above held for in-process readers only.
+ * `code` stays as-is for the existing RB-371 consumers — the new key is strictly additive.
+ */
 export declare function violationDetails(v: FsViolation): {
     type: "path_not_in_root";
     code: "path_not_in_root";
     target: string;
     roots: readonly string[];
 } | undefined;
+/**
+ * RB-371 ② — does `p` sit inside ANY of the canonical containment roots? Exposed for the Bash
+ * tool's post-`cd` disclosure note (fs-bash.ts): the note reuses the SAME segment-aware `within`
+ * the fence itself uses, so the disclosure and the fence can never disagree about what counts as
+ * "inside". Pure/lexical — callers own any canonicalization of `p` (the tracked cwd stays raw by
+ * design; fs-bash canonical-confirms before claiming "outside").
+ */
 export declare function withinAnyRoot(rootsCanonical: readonly string[], p: string): boolean;
+/**
+ * RB-371 ① — the escape-hatch tail for the `path_not_in_root` refusal: its three sibling hints
+ * below each name a sanctioned next step; this refusal named none, leaving the model to oscillate
+ * between "the boundary is hard" and discovering by trial that bash is not confined by it. Both
+ * stated ways out are consistent with the Bash tool's own card (the shell is deliberately NOT
+ * sandboxed by this fence — design/44 §5 — and every call still passes the deployment's approval
+ * policy) and with the deployment-side widening knob (`additionalDirectories`, design/119).
+ */
 export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s) and the deployment permits it, use the Bash tool \u2014 it is not confined by this fence, though every call remains subject to the deployment's approval policy. Or ask for the directory to be added to additionalDirectories.)";
+/** inv 1 (read-before-edit): a file must have been read this task before it can be edited/overwritten.
+ *  Message is CC 2.1.198 live-verbatim (all-tools-live-probe 2026-07-08 §2.1/§3.1/§5.1 — one message for
+ *  Edit/Write/NotebookEdit: "before writing to it", not the old sema "before editing").
+ *
+ * RB-200 F2(形态一,CC 220 语料证实,@367198/@367671 — Edit/Write 两处读门的判据字面完全相同,
+ * `!p || p.isPartialView`,两个工具用的是同一个条件): an AUTO-TRUNCATED read (the model asked for the
+ * file by default, no explicit offset/limit, and the token cap cut it anyway — {@link ReadEntry.isPartialView})
+ * used to satisfy this gate exactly like a full read (`state.has(key)` alone was the whole check) — the
+ * model could Write (full overwrite) or Edit a file having genuinely seen only its first page, silently
+ * destroying or blind-editing the unseen remainder. CC's own gate treats "never read" and "auto-truncated
+ * partial view" identically for BOTH tools — no softer rule for Edit (whose old_string match only touches
+ * a small snippet) versus Write (which replaces everything), so this doesn't carve one out either.
+ *
+ * Deliberately checks `isPartialView`, NOT the broader {@link ReadEntry.truncated} (which also fires for a
+ * fully-intentional, successful EXPLICIT offset/limit slice read) — CC's own `isPartialView` is scoped the
+ * same narrow way (only the auto-pagination case, never an explicit range that fit), and gating on the
+ * broader flag would make {@link OVERSIZE_READ_ESCAPE_HINT}'s documented promise false: a model deliberately
+ * paging through an oversized file via offset/limit would never be able to satisfy this gate again. */
 export declare function requireRead(state: ReadFileState, key: string): FsViolation | undefined;
+/**
+ * Escape-hatch parenthetical appended to the read-before-edit refusal when the target file is over
+ * the Read tool's whole-file byte cap: a bare "read it first" would be un-followable there (a default
+ * whole-file Read refuses such files → refusal loop). Same parenthetical pattern as the Write tool's
+ * encoding-deadlock hint; the CC-verbatim sentence stays untouched for the normal-size case.
+ */
 export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused \u2014 read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
+/**
+ * RB-264 N1 ([1963] test AI 复验残留, repro `notebookedit-tool-read-gate-deadlock` assertion A.c2) —
+ * the escape-hatch parenthetical for the OTHER shape of the read-before-edit refusal: the file was read,
+ * but the read was AUTO-PAGINATED by the output token cap ({@link ReadEntry.isPartialView}), so only the
+ * first page was ever seen. The oversize branch above has named its escape route since the fidelity
+ * sweep; this branch named none — and it is the worse of the two, because the refusal's own advice
+ * ("Read it first") is a FIXPOINT here: the file is UNDER the byte cap, so a default Read succeeds and
+ * auto-paginates identically, and Read's unchanged-since-last-read dedup then short-circuits before the
+ * state is rewritten. The gate is `isPartialView`, not the file size, so ANY explicit offset/limit slice
+ * that fits clears it — stated explicitly because nothing else in the transcript says so.
+ */
 export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view \u2014 the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
+/**
+ * RB-264 ⑥W1 ([1963] test AI 复验残留) — the escape-hatch parenthetical for the ONE shape of the
+ * read-first deadlock that nothing observable diagnoses: a file the Read tool REFUSES (binary /
+ * BOM-less UTF-16 / unknown encoding) can never satisfy read-before-write, and — unlike the oversize
+ * and partial-view shapes — leaves no trace the refusal renderer can stat for. It is therefore the
+ * renderer's FALLBACK hint (least specific, appended only when no sharper branch fired); appending it
+ * beside a sharper one would assert something false, since both of those shapes are files Read handled.
+ * Kept byte-identical to the sentence Write rendered inline before it moved here.
+ *
+ * ANG-6 (external black-box re-review, ruled 2026-08-03): the deadlock is a property of the READ GATE,
+ * not of Write — Edit and NotebookEdit hit the identical dead end and used to render the bare sentence
+ * with no way out named. All three now pass this one constant, which is why it is no longer named for
+ * the tool that happened to have it first: one sentence, three call sites, nothing to drift apart.
+ */
 export declare const READ_REFUSED_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
+/**
+ * Edit "no-op" guard (design/64 §7.2(4), CC `FileEditTool:148-153`): refuse an edit whose `old_string`
+ * equals `new_string` — without it the edit passes the match check and writes the file back unchanged (a
+ * silent no-op that wastes a turn and dirties mtime). Verbatim CC message so a CC-trained model recognizes it.
+ */
 export declare function checkNoChange(oldString: string, newString: string): FsViolation | undefined;
+/** inv 2 (staleness): the file's current content hash must match what was recorded at read time.
+ *
+ *  RB-436-g: takes `ReadEntry | undefined` and treats an ABSENT entry as stale (fail-closed). The three
+ *  write-side callers prove the entry exists with `requireRead`, then re-read the file — an `await` — and
+ *  only then reach here, so each was asserting a pre-await invariant across a suspension point with `!`.
+ *  Nothing deletes read state mid-turn today (the compaction sweep runs at a turn boundary), so behaviour
+ *  is unchanged; if that ever stops holding, the caller gets this tool's designed "read it again" refusal
+ *  instead of a TypeError thrown from inside the tool. */
 export declare function checkStale(entry: ReadEntry | undefined, currentHash: string): FsViolation | undefined;
+/** Count non-overlapping occurrences of `needle` in `haystack` (`needle` must be non-empty). */
 export declare function countOccurrences(haystack: string, needle: string): number;
+/**
+ * Suggest a sibling filename for a missing path (CC `File does not exist… Did you mean X?` self-heal
+ * path, bundle :335883/:478419). Honest scope (1.253 双轨终审): this is the FALLBACK tier — an
+ * approximation of CC's Cxe same-directory scan plus a sema-added case-insensitive exact-name match
+ * (the case-typo class CC misses). RB-285 (归因更正): CC's FIRST-tier suggester is `G_e` — a GATED
+ * sibling-tree REBASE (`join(cwd, relative(dirname(cwd), missing))`, only for a path under the cwd's
+ * parent but not under the cwd), NOT the "re-resolve the filename against cwd" this comment used to
+ * claim; the full geometry and the sema delta are recorded at the call site (fs-shared.ts
+ * `enoentMessage`), which is where the env probing lives. This function stays pure over a listed
+ * sibling set and corresponds to CC's SECOND tier (`Yrt`/findSimilarFile). (a) CC's findSimilarFile
+ * rule — same stem, different extension/name in the same directory; (b) the case-insensitive
+ * exact-name match (sema addition). Returns the suggested NAME (not a full path), or undefined.
+ */
 export declare function similarNameSuggestion(siblingNames: readonly string[], missingName: string): string | undefined;
+/** Replace curly single/double quotes with their straight ASCII forms (CC qDa, 1:1 char mapping). */
 export declare function normalizeQuotes(s: string): string;
+/**
+ * Resolve `oldString` against `content` with the CC quote-forgiveness layer: exact match first; on a
+ * miss, match in the curly→straight normalized coordinate and return the ACTUAL file substring at
+ * that span (CC kOe). Returns undefined when even the normalized form does not appear.
+ */
 export declare function resolveQuoteMatch(content: string, oldString: string): string | undefined;
+/**
+ * RB-285 M9 (CC `Pdt` layers 3+4, @366594-366600): resolve `oldString` against `content` across the
+ * escape/literal spelling boundary. Returns the ACTUAL span present in `content` (which is what must be
+ * replaced), or `undefined` when neither spelling is present. Pure — call only after an exact match and
+ * the curly-quote layer have both missed.
+ */
 export declare function resolveEscapeMatch(content: string, oldString: string): string | undefined;
+/**
+ * RB-285 M9 (CC `YZu` verbatim, @366561-366587): rewrite `newString` into the SAME spelling the matched
+ * span uses. Without this, a match found through {@link resolveEscapeMatch} would replace an escaped
+ * span with a literal-character replacement (or vice versa) and silently change the file's encoding
+ * convention at that spot. Hex case follows what the file itself used, per-character where known and by
+ * majority vote otherwise — CC's own rule, and the reason it counts upper/lower while walking the span.
+ */
 export declare function adaptNewStringEscapes(oldString: string, matchedOld: string, newString: string): string;
+/** CC `KZu` (@366558): the old_string shapes for which the escape layers above were even attempted —
+ *  gates the explanatory note appended to a no-match refusal so it is never a false claim. */
 export declare function escapeMatchWasAttempted(oldString: string): boolean;
+/** RB-285 M9 — CC `KZu`'s note (@367245-367248) verbatim. */
 export declare const ESCAPE_MATCH_MISS_NOTE = "\n(note: Edit also tried swapping \\uXXXX escapes and their characters; neither form matched, so the mismatch is likely elsewhere in old_string. Re-read the file and copy the exact surrounding text.)";
+/**
+ * When the quote-forgiving match resolved to a curly-quoted file span, convert the straight quotes in
+ * `newString` to the matching curly forms so the replacement stays style-consistent with the file
+ * (CC Dmt/yPp/TPp: openers vs closers by preceding char; a letter-adjacent single quote is an
+ * apostrophe U+2019). Call ONLY when the matched span differs from the model's old_string.
+ */
 export declare function adaptNewStringQuotes(matchedOld: string, newString: string): string;
+/**
+ * The effective old_string a DELETION should replace: `oldString + "\n"` when new_string is empty,
+ * old_string doesn't already end with a newline, and the newline-suffixed form exists in the content;
+ * otherwise old_string unchanged (CC KDa parity). SINGLE (non-replace_all) edits only: a widened
+ * needle under replace_all would miss occurrences not followed by a newline and desync the
+ * replacement count — the Edit tool restricts the widening to single edits (1.253 双轨终审 MED).
+ */
 export declare function deletionOldString(content: string, oldString: string, newString: string): string;
+/**
+ * inv 3 (edit uniqueness): `oldString` must match exactly once unless `replaceAll`. Zero → not found;
+ * >1 without replaceAll → ambiguous. `truncated` adds a hint that unseen content may hold more matches (S2).
+ * Messages are CC 2.1.198 live-verbatim (all-tools-live-probe 2026-07-08 §2.1): first sentence(s) byte-exact,
+ * then a `String: <needle>` echo line (CC form). The sema truncated-read hint survives as a parenthetical
+ * appended to the sentence (probe verdict: "truncated 提示可并入括注保留").
+ */
+/** How much of the needle a failed-match refusal spells back. The echo identifies WHICH string was
+ *  searched for; the caller still holds the whole thing in the tool call above, so a prefix does the job
+ *  a full copy was doing at any length the caller chose. Both arms use it — the not-found arm is the more
+ *  common failure, so bounding only the multi-match arm would leave the stated bound defeated where it
+ *  matters most (and these refusals return as tool results, which do not pass the loop-level budget). */
 export declare const EDIT_ECHO_MAX_CHARS = 200;
 export declare function checkEditMatch(content: string, oldString: string, replaceAll: boolean, truncated: boolean): FsViolation | undefined;