agent-sanitizer 2.57.4 → 2.58.0

package/types/repo-scope.d.mts

@@ -0,0 +1,58 @@
+/**
+ * The linked worktrees in a `git worktree list --porcelain -z` dump, main and
+ * bare ones excluded — those are not removable, so their state is never at risk
+ * from a teardown command, and the main one is the scan root a prune must never
+ * swallow.
+ * @param {string} porcelain
+ * @returns {string[]} absolute worktree paths
+ */
+export function parseWorktreeList(porcelain: string): string[];
+/**
+ * The linked worktrees of the repo at `cwd`. The guard on `git worktree remove`
+ * asks this the same way the prune below does, so one parser answers for both.
+ * @param {string} cwd
+ * @param {GitRun} run
+ * @returns {string[]} absolute worktree paths
+ */
+export function linkedWorktrees(cwd: string, run: GitRun): string[];
+/**
+ * Directory paths a context scan of `dir` must not walk, relative to it and
+ * `/`-separated: every wholly-ignored directory (unless `ignoredDirs` is off)
+ * and every linked worktree nested inside it.
+ * @param {string} dir
+ * @param {{ ignoredDirs?: boolean, run?: GitRun }} [options]
+ * @returns {Set<string>}
+ */
+export function repoPrunedDirs(dir: string, { ignoredDirs, run }?: {
+    ignoredDirs?: boolean;
+    run?: GitRun;
+}): Set<string>;
+/**
+ * The `exclude` predicate for an instruction-file walk of `dir`: the static
+ * context-scope prune, plus {@link repoPrunedDirs}.
+ *
+ * `ignoredDirs: false` is the LAUNCH scan's posture, and it is a security
+ * choice rather than a performance one: `.gitignore` is repo-controlled, so
+ * honouring it in the one scan that covers launch-time ingress would let a
+ * hostile repo hide a planted `.claude/skills/…/SKILL.md` from it by ignoring
+ * that directory. The whole-tree scan can honour it because anything it prunes
+ * is still scanned by scan-loaded-instructions at the moment the host loads it.
+ *
+ * The lookup is EXACT, so the walk must hand it the same spelling
+ * {@link repoPrunedDirs} uses — one root-relative, `/`-separated path per entry,
+ * which is what walkContextGlobs normalizes to. A predicate that accepted a bare
+ * name as well would prune a tracked `src/build/` for a top-level ignored
+ * `build/`, splicing real instruction files out of the scan.
+ * @param {string} dir
+ * @param {{ ignoredDirs?: boolean, run?: GitRun }} [options]
+ * @returns {(entry: string) => boolean}
+ */
+export function contextScanExclude(dir: string, options?: {
+    ignoredDirs?: boolean;
+    run?: GitRun;
+}): (entry: string) => boolean;
+/**
+ * How git is asked. Injectable so a test can drive the failure paths, which no
+ * filesystem state can force.
+ */
+export type GitRun = (file: string, args: string[], cwd: string) => string;

package/types/src/ansi.d.mts

@@ -0,0 +1,176 @@
+/**
+ * True for either orphan kind — the tokens {@link scanAnsi} emits for an
+ * introducer that completes no sequence, which the stripper must leave in place
+ * for the residual sweep rather than splice (see stripAnsiOnce).
+ * @param {string} kind one of {@link TOKEN_KIND}
+ * @returns {boolean}
+ */
+export function isOrphanKind(kind: string): boolean;
+/**
+ * The orphan kind for the introducer character `ch`, given the character `next`
+ * that follows it: a raw C1 byte, an `ESC` that opened an incomplete CSI, or a
+ * lone `ESC`. The one place that split is decided, shared by the tokenizer and
+ * by Layer 1's residual sweep (which sees bare characters, not tokens).
+ *
+ * `[` is the only lookahead that matters. The five string introducers — `ESC ]`,
+ * `ESC P`, `ESC X`, `ESC ^`, `ESC _` — are consumed whole by
+ * {@link scanControlString}, to the end of input if unterminated, so they never
+ * reach here; every other second byte (`ESC (`, `ESC #`) bounds what a terminal
+ * swallows to a byte or two rather than running until a final byte arrives.
+ * @param {string} ch
+ * @param {string} [next]  the following character, or undefined at end of input
+ * @returns {string}
+ */
+export function orphanKindFor(ch: string, next?: string): string;
+/**
+ * Tokenize every raw control introducer in `text`.
+ *
+ * Every introducer yields exactly one token — an orphan kind (see
+ * {@link orphanKindFor}) when it starts nothing the grammar recognizes — so
+ * "which introducers are in this text" and "which
+ * sequences are in this text" are answered by the same scan. That is what lets
+ * the stripper (splice every non-orphan token, then sweep) and the SGR-only
+ * predicate (every token is SGR) agree by construction.
+ *
+ * Tokens are disjoint and ordered by `start`; each `end` is strictly greater
+ * than its `start`, so the scan always advances.
+ * @param {string} text
+ * @returns {AnsiToken[]}
+ */
+export function scanAnsi(text: string): AnsiToken[];
+/**
+ * The CONCEAL state after the SGR token `token` is applied to a terminal already
+ * in state `concealed` — the state in which a terminal renders what follows as
+ * blank while its bytes stay readable to anything reading the file.
+ *
+ * A TRANSITION, not a property of the token: conceal is terminal state that
+ * outlives the sequence that set it, so `ESC[8m` followed by `ESC[31m` is still
+ * concealed — a per-token predicate would read the second token as "no conceal
+ * here" and lose the state. Only `8` (set), `28` (reveal) and `0` (reset all)
+ * move it, and the token's parameters are applied in order, so a later reveal or
+ * reset in the SAME token cancels an earlier `8`: `ESC[8;28;31m` renders red and
+ * visible.
+ *
+ * The parameters are read the way a terminal reads them rather than scanned for
+ * the digit. `38`/`48`/`58` take their colour arguments from the parameters that
+ * FOLLOW them in the semicolon form, so `ESC[38;5;8m` is bright-black foreground
+ * and its `8` is a palette index; a parameter carrying its arguments as ITU T.416
+ * sub-parameters (`38:5:8`) is self-contained, so only its head counts and
+ * nothing after it is consumed. A colour-space selector T.416 gives no argument
+ * count for is malformed, and a terminal that ignores the colour form still
+ * applies what follows it, so the scan CONTINUES from the next parameter rather
+ * than consuming arguments it cannot size — reading one parameter too many costs
+ * a token shape no emitter produces, while stopping there would hand
+ * `ESC[38;9;8m` a pass.
+ * @param {string} token  a token {@link scanAnsi} classified {@link TOKEN_KIND.SGR}
+ * @param {boolean} concealed  the state before this token
+ * @returns {boolean}
+ */
+export function sgrConcealState(token: string, concealed: boolean): boolean;
+/**
+ * The ONE ANSI grammar: the raw control-introducer charset and the tokenizer
+ * every consumer scans with.
+ *
+ * Two modules need this grammar and they cannot import each other —
+ * `layer1.mjs` imports `invisible.mjs`, so `invisible.mjs` (which owns the
+ * public `isSgrOnly` / `SGR_RE`) must not import back. Before this module the
+ * grammar was therefore written out twice with DIFFERENT param rules
+ * (`invisible.mjs`'s SGR regex accepted any digit run, `layer1.mjs`'s CSI
+ * branch capped each parameter at four digits), and the introducer charset
+ * three times. The looser copy suppressed the operator warning for a sequence
+ * the stripper could not match: `ESC[12345m` read as "display-only colour"
+ * while `[12345m` was spliced into the model's view as visible text. One
+ * tokenizer, one charset, consumed by both — the disagreement cannot recur.
+ *
+ * Same precedent (and same reason) as `cf-charset.mjs`: a dependency-free leaf
+ * module both layers read from.
+ */
+export const CONTROL_INTRODUCER_CODEPOINTS: readonly number[];
+export const CONTROL_INTRODUCER_SOURCE: string;
+/**
+ * Public alias kept for compatibility (re-exported by `invisible.mjs` and the
+ * package root). It is now DERIVED: {@link scanAnsi} classifies a token as SGR
+ * by testing the token's own text against this exact source, so the predicate
+ * and the regex can no longer describe different languages.
+ */
+export const SGR_RE: RegExp;
+/**
+ * The same grammar {@link scanAnsi} implements, as a REGEX SOURCE — the shipped
+ * artifact for a consumer that cannot run this module.
+ *
+ * The scanner below is AUTHORITATIVE and this is derived from its own constants,
+ * never the other way round: the scanner emits token KINDS a regex cannot, and
+ * it is linear by construction where the regex form has to carry an explicit
+ * guard to stay linear (see the CSI arm's lookahead). What a regex CAN be is data —
+ * a stdlib-only Python filter on an uncontrolled host, with no install path for
+ * this package, can read a pattern string but cannot import a tokenizer. So the
+ * generator pins this into `data/invisible-charset.json` beside the introducer
+ * set, `agent_sanitizer.textstrip` compiles it, and the two ports stop being two
+ * hand-written spellings of one grammar.
+ *
+ * Every construct here is common to JS and Python `re` with NO flags —
+ * `\uXXXX`, `(?:)`, `(?=)`, `(?!)`, and `(?![\s\S])` for end-of-input (Python's
+ * `$` also matches before a trailing newline, JS's does not; `\Z` is Python-only)
+ * — so ONE pattern string is what both engines read.
+ * `test/ansi-pattern-parity.test.mjs` runs it against the scanner over a fuzz
+ * corpus; `tests/test_textstrip.py` asserts it compiles under plain `re`.
+ */
+export const ESCAPE_SEQUENCE_SOURCE: string;
+/** The seven things an introducer can turn out to be. */
+export const TOKEN_KIND: Readonly<{
+    /** A display-only `ESC[…m` / `U+009B…m` colour sequence. */
+    SGR: "sgr";
+    /** Any other complete CSI / two-byte escape (cursor move, erase, charset). */
+    CSI: "csi";
+    /** An OSC string: introducer, body and terminator as one unit. */
+    OSC: "osc";
+    /**
+     * One of the other four ECMA-48 control strings — DCS, SOS, PM or APC —
+     * introducer, body and terminator as one unit, exactly like
+     * {@link TOKEN_KIND.OSC}. Split from it only so a warning can name what it
+     * found; both are payload-carrying strings and neither is benign.
+     */
+    CONTROL_STRING: "control-string";
+    /**
+     * A 7-bit `ESC` that starts no sequence the grammar recognizes — a truncated
+     * write, a log fragment cut mid-escape, a stray byte living in a file.
+     */
+    ORPHAN: "orphan-introducer";
+    /**
+     * A 7-bit `ESC` that OPENS a CSI (`ESC [`) it never completes. Split from
+     * {@link TOKEN_KIND.ORPHAN} because a terminal's CSI parser is STATEFUL: it
+     * keeps consuming what follows as parameters and intermediates until a final
+     * byte (0x40-0x7E) arrives, so `hello ESC[12 world` renders as `hello orld`
+     * — the ` w` is eaten as the sequence's intermediate and final. That is the
+     * model-sees/human-sees divergence the gate exists for, so consumers that
+     * downgrade an inert strip to a note must keep warning on this one; only a
+     * lone `ESC` that opens nothing is inert.
+     */
+    ORPHAN_CSI: "orphan-csi-introducer";
+    /**
+     * A RAW C1 byte (U+0080-U+009F) that starts no sequence the grammar
+     * recognizes. Split from {@link TOKEN_KIND.ORPHAN} because the two carry very
+     * different weight: a lone `ESC` is ordinary debris in terminal output, while
+     * a raw C1 byte is not something legitimate UTF-8 text produces. The five
+     * string introducers in the block open a {@link TOKEN_KIND.OSC} or
+     * {@link TOKEN_KIND.CONTROL_STRING} token instead, so a byte that reaches
+     * here is one the grammar recognizes no sequence for at all — and a terminal
+     * may still act on it. Consumers that downgrade an inert strip to a note (see
+     * `isBenignAnsiKinds` in ./layer1.mjs) must keep warning on this one.
+     */
+    ORPHAN_C1: "orphan-c1-introducer";
+}>;
+export type AnsiToken = {
+    /**
+     * Index of the introducer.
+     */
+    start: number;
+    /**
+     * Index one past the last character of the token.
+     */
+    end: number;
+    /**
+     * One of {@link TOKEN_KIND}.
+     */
+    kind: string;
+};

package/types/src/cf-charset.d.mts

@@ -0,0 +1,14 @@
+/**
+ * GENERATED by scripts/gen-invisible-charset.mjs from Node's Unicode data
+ * (\p{Cf}, Unicode 17.0) — DO NOT EDIT.
+ *
+ * The general-category Cf code points, PINNED at generation time. invisible.mjs
+ * strips exactly this set instead of testing \p{Cf} live, and the Python port
+ * reads the SAME set from data/invisible-charset.json's `cf_codepoints`, so both
+ * layers strip an identical Cf set regardless of each runtime's own Unicode
+ * version. Regenerate with `node scripts/gen-invisible-charset.mjs`;
+ * test/invisible-charset.test.mjs fails if this drifts from Node's \p{Cf}.
+ */
+export const UNICODE_VERSION: "17.0";
+/** @type {readonly number[]} Sorted ascending. */
+export const CF_CODEPOINTS: readonly number[];

package/types/src/claude-context.d.mts

@@ -33,7 +33,11 @@ export function isInsideDir(dir: string, file: string): boolean;
  * The one directory no instruction-file walk ever descends into. Its own
  * function so the name is spelled once, and so the two predicates that need it
  * (a plain glob walk, and {@link excludeFromContextScan}) cannot disagree.
- * @param {string} entry  a bare entry name or a path relative to the scan root
+ *
+ * The LAST segment is what it reads: a dependency tree nested under a workspace
+ * package is the same dependency tree, and an entry naming one arrives as the
+ * path `packages/a/node_modules`, never as a bare name.
+ * @param {string} entry  a path relative to the scan root, `/`-separated
  * @returns {boolean}
  */
 export function excludeNodeModules(entry: string): boolean;
@@ -49,10 +53,10 @@ export function excludeNodeModules(entry: string): boolean;
  * context: a doubled-star segment does cross into a dot directory when the
  * pattern names one.
  *
- * A walker calls this with both bare names and root-relative paths, so it must
- * answer for either; a bare name carries no `.claude` context and is judged only
- * against `node_modules`.
- * @param {string} entry  a bare entry name or a path relative to the scan root
+ * Entries are paths relative to the scan root, so a top-level one is a bare
+ * name: it carries no `.claude` context and is judged only against
+ * `node_modules`.
+ * @param {string} entry  a path relative to the scan root, `/`-separated
  * @returns {boolean}
  */
 export function excludeFromContextScan(entry: string): boolean;

package/types/src/instructions.d.mts

@@ -0,0 +1,170 @@
+/**
+ * Decode a run of invisible characters to its likely payload. Recognizes the
+ * two common smuggling encodings — Unicode tag characters (U+E0001–U+E007F map
+ * directly to ASCII) and zero-width binary (ZWSP=0, ZWNJ=1, ZWJ=separator) —
+ * and otherwise reports the raw code points. The tag-character payload is
+ * rendered as a neutral, quoted/escaped `untrusted data, not instructions: "…"`
+ * string (see {@link neutralizeTagBytes}) so the report can never re-inject the
+ * hidden instruction, and only U+E0020–U+E007E map to raw printable ASCII.
+ * @param {string} run
+ * @returns {{ method: string, decoded: string }}
+ */
+export function decodeRun(run: string): {
+    method: string;
+    decoded: string;
+};
+/**
+ * Scan a file's text for hidden-Unicode injection. Reports each long invisible
+ * run (with its decoded payload) plus a single scattered-chars finding when the
+ * non-run invisible count crosses the threshold-evasion floor.
+ * @param {string} content
+ * @returns {Array<{ line: number | null, charCount: number, method: string, decoded: string }>}
+ *   `line` is the 1-based line of a long-run finding, or `null` for the
+ *   whole-file scattered-chars finding (not tied to a single line).
+ */
+export function scanText(content: string): Array<{
+    line: number | null;
+    charCount: number;
+    method: string;
+    decoded: string;
+}>;
+/**
+ * Every `globs` match under `cwd`, as an absolute path, with `node_modules` and
+ * whatever `exclude` rejects pruned from the WALK rather than filtered from its
+ * results — which is where a wide glob's cost actually is.
+ *
+ * `withFileTypes` is what makes the prune ANSWERABLE. Without it the walker
+ * calls `exclude` once with an entry's bare name and again with its
+ * root-relative path, so a predicate holding `build` cannot tell a top-level
+ * `build/` from a tracked `src/build/` and prunes both; under an absolute
+ * pattern it is handed absolute paths and matches neither. A Dirent carries an
+ * absolute `parentPath`, which normalizes to exactly one root-relative,
+ * `/`-separated entry per walked directory whatever shape the pattern has.
+ * @param {string[]} globs
+ * @param {string} cwd
+ * @param {(entry: string) => boolean} [exclude]
+ * @returns {string[]} absolute paths, one match per element
+ */
+export function walkContextGlobs(globs: string[], cwd: string, exclude?: (entry: string) => boolean): string[];
+/**
+ * Expand `globs` (relative to `cwd`) to absolute file paths, skipping
+ * `node_modules`. The glob set is the caller's instruction-file convention.
+ *
+ * Containment is enforced per match (see {@link keepContained}): a match whose
+ * glob pattern itself escapes `cwd` — via `..` or an absolute-path glob
+ * outside the tree — THROWS, since reaching outside the tree is a caller
+ * misconfiguration. A match that lexically stays inside `cwd` but resolves
+ * (via an in-tree symlink) to a target outside the tree, or that simply
+ * cannot be resolved (a dangling symlink or unreadable entry inside the
+ * tree), is SKIPPED, so one bad symlink never aborts scanning the rest of the
+ * project.
+ *
+ * `exclude` prunes the walk via {@link walkContextGlobs}, so it is handed one
+ * root-relative, `/`-separated path per entry. It is composed with, never
+ * replaces, the unconditional `node_modules` prune: a caller narrowing the scan
+ * must not be able to widen it into a dependency tree. Pass
+ * {@link excludeFromContextScan} to take Claude Code's own scope.
+ * @param {string[]} globs
+ * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
+ * @returns {string[]}
+ */
+export function findInstructionFiles(globs: string[], { cwd, exclude }?: {
+    cwd?: string;
+    exclude?: (entry: string) => boolean;
+}): string[];
+/**
+ * Scan every instruction file matched by `globs` and return only those with
+ * findings, each path reported relative to `cwd`. Unreadable/missing files are
+ * skipped. Pure scan — no mutation; pair with {@link cleanFile} to strip.
+ * @param {string[]} globs
+ * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
+ *   `exclude` is forwarded to {@link findInstructionFiles}
+ * @returns {Array<{ file: string, findings: ReturnType<typeof scanText> }>}
+ */
+export function scanInstructionFiles(globs: string[], { cwd, exclude }?: {
+    cwd?: string;
+    exclude?: (entry: string) => boolean;
+}): Array<{
+    file: string;
+    findings: ReturnType<typeof scanText>;
+}>;
+/**
+ * Atomically replace `absPath`'s contents with `data`, preserving `mode`.
+ *
+ * Writes to a sibling temp in the same directory, then `rename`s it over the
+ * original (same dir => same filesystem => the rename is atomic, not a
+ * cross-device copy). The temp name is UNPREDICTABLE (`tmpName()` defaults to
+ * crypto-random) and the temp is created exclusively (O_CREAT|O_EXCL): if the
+ * path already exists — including an attacker-planted symlink at a guessable
+ * temp name — the open fails (EEXIST) and does NOT follow the link to clobber
+ * its target. On the rare collision we fail loud rather than retry into a
+ * different attacker-controlled path.
+ *
+ * Crash-safety (matching the doc claim): the temp fd is `fsync`ed before the
+ * rename and the directory fd is `fsync`ed after it, so a power loss can't leave
+ * the renamed name pointing at unflushed/empty data or lose the rename itself.
+ * The EXACT `mode` is applied with `fchmod` (openSync's create mode is
+ * umask-masked, so it alone would drop bits), and a failed write/sync `unlink`s
+ * the temp before rethrowing so no partial temp leaks. `tmpName` and `remove`
+ * are injectable fault-injection seams for tests (force a known temp path; drive
+ * a cleanup-unlink failure); production callers never pass them.
+ * @param {string} absPath
+ * @param {string} data
+ * @param {number} mode
+ * @param {() => string} [tmpName]
+ * @param {(path: string) => void} [remove]
+ */
+export function atomicReplaceFile(absPath: string, data: string, mode: number, tmpName?: () => string, remove?: (path: string) => void): void;
+/**
+ * Strip payload-capable invisible characters from `absPath` in place. Returns
+ * `true` when the file's bytes actually changed (a payload {@link scanText}
+ * flags was removed) and `false` when {@link scanText} reports nothing to
+ * strip. `true` means and only means "bytes changed", so a caller that flagged
+ * this file and gets `false` back must NOT record it as cleaned — the file
+ * changed under it, or the flagged run is one {@link stripInvisible}
+ * preserves (a well-formed emoji-tag sequence), and either way the payload it
+ * flagged is still there. There is no third return value: the `null` arm this
+ * doc once described was dropped as dead (`stripInvisible` cannot leave the
+ * bytes identical for anything `scanText` flags), and callers must branch on
+ * the boolean rather than testing against `null`, which is vacuously true.
+ *
+ * Contract (scan/clean coherence): clean strips exactly what scan flags. A
+ * write happens ONLY when `scanText` reports a finding, so the "scan, then
+ * clean what scan flagged" workflow never silently rewrites a file scan called
+ * clean. A handful of sub-threshold invisible chars (which scan ignores) are
+ * left untouched — by design, the scanner's definition of a payload is the
+ * single source of truth for what gets removed.
+ *
+ * Refuses to follow symlinks: instruction files must be regular files. The read
+ * fd is opened with `O_NOFOLLOW`, so a symlinked path (which could redirect the
+ * read/write to a target outside the tree) makes the OPEN itself fail — closing
+ * the lstat→open TOCTOU window a separate stat would leave, in which the path
+ * could be swapped to a symlink between the check and the read.
+ *
+ * Non-UTF-8 safety (O9): the file is read as raw BYTES and required to round-trip
+ * losslessly through UTF-8 before any rewrite. `readFileSync(…, "utf-8")`
+ * silently maps invalid bytes to U+FFFD, which a naive strip-and-rewrite would
+ * then persist file-wide — so a non-UTF-8 file fails loud and is left untouched.
+ *
+ * Lost-update / TOCTOU guard: the on-path file is re-checked against the fstat
+ * snapshot taken right after open (inode, size, mtime, and not-a-symlink) before
+ * the rename; a concurrent write or symlink swap between our read and our write
+ * fails loud rather than silently clobbering the other writer.
+ *
+ * The write is atomic (see {@link atomicReplaceFile}): stripped content goes to
+ * a temp file in the same directory which is then `rename`d over the original
+ * (preserving the original file mode), fsync'd for crash-safety.
+ *
+ * Throws if the file cannot be read or written (the caller decides whether an
+ * unwritable contaminated file is fatal or falls back to alerting).
+ * @param {string} absPath
+ * @param {(path: string) => import("node:fs").Stats} [lstat] injectable
+ *   pre-rename recheck stat (fault-injection seam, mirrors
+ *   {@link atomicReplaceFile}'s `tmpName`): lets a test drive the concurrent
+ *   write/symlink-swap that the TOCTOU guard exists to catch, which is otherwise
+ *   unreachable from this fully-synchronous path. Defaults to `lstatSync`.
+ * @returns {boolean}
+ */
+export function cleanFile(absPath: string, lstat?: (path: string) => import("node:fs").Stats): boolean;
+export { contextScanExclude } from "./repo-scope.mjs";
+export { ancestorInstructionFiles, announcedByInstructionsLoaded, CLAUDE_CONTEXT_KINDS, CLAUDE_CONTEXT_SUBDIRS, CLAUDE_DIR_INSTRUCTION_FILES, CLAUDE_INSTRUCTION_GLOBS, CLAUDE_LAUNCH_GLOBS, CLAUDE_MEMORY_FILES, contextScopeContradiction, excludeFromContextScan, USER_GLOBAL_EVENT_NAMED_GLOBS } from "./claude-context.mjs";

package/types/src/invisible.d.mts

@@ -0,0 +1,217 @@
+/**
+ * True when every ANSI control introducer in `text` belongs to a display-only
+ * SGR color sequence (so stripping the ANSI removes only cosmetic styling,
+ * nothing that could move the cursor, erase, or carry a payload). Recognizes
+ * both the 7-bit `ESC[…m` and 8-bit C1 (`U+009B…m`) SGR encodings.
+ *
+ * Answered by the STRIPPER'S OWN tokenizer: scanAnsi emits one token per raw
+ * introducer — 7-bit ESC and the whole C1 block, so a C1 cursor-move
+ * (`U+009B 2J`), a C1-OSC string (`U+009D … BEL`), a C1-DCS/APC payload and a
+ * lone or partial escape each yield a non-SGR token — and the predicate is
+ * "every token is SGR". Because the same scan decides what Layer 1 splices,
+ * this can no longer report "colour only" for bytes the stripper leaves behind.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isSgrOnly(text: string): boolean;
+/**
+ * Every maximal run of at least {@link LONG_RUN_THRESHOLD} consecutive
+ * payload-capable invisible code points in `text`, in order: `index` is the
+ * run's UTF-16 offset, `text` its verbatim slice, `charCount` its length in
+ * code points.
+ *
+ * What {@link LONG_RUN_RE} means, in the form every scanner in this package
+ * uses — because that regex cannot answer for a large document, and an 8 MB
+ * paste of zero-widths (the exact payload the scan exists to catch) is what
+ * took out the SessionStart scanner, the prompt gate and the tool-output tier
+ * alike. Bounding the quantifier bounds the backtrack stack per `exec`; a run
+ * that hits the bound is continued by {@link RUN_TAIL_RE} until it ends, so the
+ * runs reported are maximal at any length.
+ * @param {string} text
+ * @returns {Generator<{ index: number, text: string, charCount: number }>}
+ */
+export function findLongRuns(text: string): Generator<{
+    index: number;
+    text: string;
+    charCount: number;
+}>;
+/**
+ * True when `text` carries at least one {@link findLongRuns} run.
+ *
+ * The bounded pattern answers this on its own: a run long enough to be reported
+ * is long enough to match, whether or not the match reaches the run's end — so
+ * the yes/no costs one anchored scan and never measures the run.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function hasLongRun(text: string): boolean;
+/**
+ * The agent-facing "Stripped: …" note for a Layer-1 strip: the removed category
+ * labels, the LONG RUN marker when the de-ANSI'd text still holds a
+ * payload-length invisible run, and a pointer to recover the bytes — a hex dump
+ * is ASCII, so it passes through sanitization untouched. The single source of
+ * this note, shared by the `sanitize` convenience entry and the tool-output
+ * pipeline.
+ * @param {string[]} invisFound CATEGORY codes applyLayer1 reported removing
+ * @param {string} deAnsi ANSI-stripped text (invisible runs intact), for the LONG_RUN probe
+ * @returns {string}
+ */
+export function describeStripped(invisFound: string[], deAnsi: string): string;
+/**
+ * Count the PAYLOAD invisible code points in `text`: those the carve-out would
+ * strip, excluding ZWNJ/ZWJ (and emoji VS16) that do real rendering work.
+ * Consumers that gate on invisible density (e.g. the prompt classifier's scatter
+ * threshold) use this so legitimate dense multilingual prose is not mistaken for
+ * a hidden channel.
+ * @param {string} text
+ * @returns {number}
+ */
+export function countPayloadInvisible(text: string): number;
+/**
+ * The `text` with every carve-out-PRESERVABLE invisible (joiners/selectors/tags/
+ * blank fillers doing real rendering work) replaced by a space, leaving only the
+ * PAYLOAD invisibles in place. The LONG_RUN injection probe runs over this so a
+ * legitimate emoji/flag/variation sequence never trips the "possible injection
+ * payload" marker (alert fatigue), while a genuine hidden run still surfaces.
+ * @param {string} text
+ * @returns {string}
+ */
+export function payloadInvisibleView(text: string): string;
+/**
+ * The first payload-invisible LONG RUN in `text`, or null when there is none.
+ *
+ * THE definition of "this text carries a hidden run", shared by every consumer
+ * that has an opinion about one: the strip's `[LONG RUN — possible injection
+ * payload]` marker, the prompt gate's block decision, and the tool-output
+ * severity tier. They used to spell it twice, and differently — the marker
+ * probed the PAYLOAD view while the prompt gate probed the raw text, so a
+ * legitimate ten-emoji flag sequence (carve-out-preserved, never stripped) was
+ * quietly enough to BLOCK a prompt while the strip that saw the same text
+ * declined to even flag it. Masking the preserved invisibles is the right half
+ * of that disagreement: a run the carve-out keeps is rendering work, not a
+ * channel, and the joiners it does NOT keep are counted as payload anyway (see
+ * {@link countEffectiveInvisible}).
+ *
+ * Because the view replaces only PRESERVED invisibles (and visible characters)
+ * with spaces, a match consists solely of payload code points and is therefore
+ * byte-identical to the corresponding span of `text` — so a caller may report
+ * the sample verbatim.
+ * @param {string} text
+ * @returns {string | null}
+ */
+export function payloadLongRunSample(text: string): string | null;
+/**
+ * How many invisible code points in `text` the strip layer treats as PAYLOAD:
+ * the ones {@link countPayloadInvisible} counts, plus the joiners that sit in a
+ * genuine linguistic context but exceed the carve-out's preservation budget.
+ *
+ * The surplus term closes the preserved-joiner covert channel (O3):
+ * `countPayloadInvisible` excludes every ZWNJ/ZWJ doing real rendering work, so
+ * an attacker who alternates `letter joiner letter joiner …` — every joiner
+ * legitimately between two cursive letters — counts as ZERO there. The strip
+ * layer already refuses that (it preserves joiners only up to
+ * TOTAL_PRESERVED_JOINER_BUDGET / CONSECUTIVE_JOINER_CAP and strips the rest),
+ * so the surplus is read back OFF the strip — the SSOT — rather than by
+ * re-deriving the budget here, which is what would drift.
+ *
+ * A leading BOM is preserved by the strip but counted by
+ * {@link countPayloadInvisible}, so the difference can go slightly negative;
+ * hence the clamp.
+ * @param {string} text  ANSI-stripped text (an escape sequence can hide invisibles)
+ * @returns {number}
+ */
+export function countEffectiveInvisible(text: string): number;
+/**
+ * True when the invisible characters in `text` are INCIDENTAL: no hidden run,
+ * and too few of them in total to carry an instruction.
+ *
+ * This is a severity line, not a strip line — the bytes are removed either way
+ * (see ../src/severity.mjs). It exists because a single soft hyphen in a
+ * pasted paragraph, or one variation selector a font demanded, raised the exact
+ * `WARNING: Tool output sanitized` an encoded payload does, and a warning that
+ * fires on a stray character in ordinary prose is one operators learn to skip.
+ *
+ * The bar is {@link LONG_RUN_THRESHOLD} — the count this module already calls
+ * "payload length" — applied to the WHOLE text rather than to one run, so it is
+ * strictly stronger than the run probe: fewer than ten payload-invisible code
+ * points, however they are distributed, cannot spell a smuggled instruction (ten
+ * tag characters are ten ASCII letters). Deliberately NOT the far looser
+ * {@link SCATTERED_THRESHOLD} of 30, which is the prompt gate's BLOCK bar: 29
+ * tag characters is a short sentence, and staying quiet about a short sentence
+ * hidden in a tool result is not a trade worth making.
+ * @param {string} text  ANSI-stripped text, invisible runs intact
+ * @returns {boolean}
+ */
+export function isIncidentalInvisible(text: string): boolean;
+/**
+ * Strip payload-capable invisible chars and report which categories were
+ * removed. A single leading U+FEFF (BOM) is preserved as a legitimate marker;
+ * interior BOMs and all soft hyphens (U+00AD) are stripped, since either can
+ * encode hidden instructions. ZWNJ/ZWJ survive only in a linguistic context
+ * (see the carve-out above). `found` names exactly the categories stripped, so
+ * a caller never warns about a strip the carve-out skipped.
+ *
+ * `originalText` is the pre-processing text (before any ANSI strip) used ONLY to
+ * decide whether a leading BOM is genuinely leading: an interior BOM that an
+ * ANSI-strip left at index 0 of `text` (e.g. `ESC[m + interior U+FEFF`) must NOT be treated as a
+ * legitimate leading marker. Defaults to `text` for the common single-arg call.
+ * @param {string} text
+ * @param {string} [originalText]
+ * @returns {{ cleaned: string, found: string[] }}
+ */
+export function stripInvisibleWithReport(text: string, originalText?: string): {
+    cleaned: string;
+    found: string[];
+};
+/**
+ * Strip payload-capable invisible chars (cleaned text only). See
+ * stripInvisibleWithReport for the BOM and ZWNJ/ZWJ carve-out semantics.
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripInvisible(text: string): string;
+export const VS: string;
+export const ZERO_WIDTH_MN: "\u034F\u17B4\u17B5";
+export const BLANK_NON_CF: string;
+export const CATEGORY: Readonly<{
+    CF: "cf-format";
+    VARIATION_SELECTORS: "variation-selectors";
+    BLANK_FILLERS: "blank-fillers";
+    ANSI: "ansi";
+    LONE_SURROGATES: "lone-surrogates";
+    HTML_COMMENTS: "html-comments";
+    HIDDEN_HTML: "hidden-html";
+    EXFIL_URLS: "exfil-urls";
+    CONFUSABLE_HOST: "confusable-host";
+}>;
+/** @type {Readonly<Record<string, string>>} */
+export const CATEGORY_LABELS: Readonly<Record<string, string>>;
+/** @type {Array<[string, RegExp]>} Each entry pairs a CATEGORY code with its detector. */
+export const CHECKS: Array<[string, RegExp]>;
+export const STRIP: RegExp;
+export { SGR_RE } from "./ansi.mjs";
+export const LONG_RUN_THRESHOLD: 10;
+/** Total invisible-char count above which a file/prompt is treated as
+ * payload-capable even without a long run (threshold-evasion catch). */
+export const SCATTERED_THRESHOLD: 30;
+/**
+ * The long-run pattern, declaratively: {@link LONG_RUN_THRESHOLD} or more
+ * consecutive {@link STRIP} code points.
+ *
+ * Scan a document with {@link findLongRuns}, not with this: `exec`/`test`
+ * throw `RangeError: Maximum call stack size exceeded` once a run passes
+ * ~8.4 M code points, because V8 pushes one backtrack entry per iteration of
+ * an unbounded quantifier onto a stack capped at 64 MB. This stays public as
+ * the pattern itself, and as the independent oracle the scan is differenced
+ * against (test/invisible-fast-path.test.mjs).
+ */
+export const LONG_RUN_RE: RegExp;
+export const CONSECUTIVE_JOINER_CAP: 8;
+export const CONSECUTIVE_SELECTOR_CAP: 8;
+export const TOTAL_PRESERVED_JOINER_BUDGET: 16;
+export const PRESERVED_JOINER_PER_VISIBLE: 8;
+export const PRESERVE_HARD_CAP: 64;
+export const TOTAL_PRESERVED_BLANK_BUDGET: 16;
+export const PRESERVED_BLANK_PER_ANCHOR: 2;
+export const LINGUISTIC_SCRIPTS: string[];
+export { BRAHMIC_CONSONANT_RANGES } from "./joining-type.mjs";