agent-sanitizer 2.14.7 → 2.14.9

package/README.md

@@ -47,17 +47,17 @@ Split into subpaths so the heavy HTML dependency stays opt-in. **Seam** names
 the callback you inject for the agent-specific concern; `—` is a pure transform,
 `fs (direct)` does its own file I/O instead of taking one.
 
-| #   | Import          | Purpose                                                                                                                                                    | Seam                        |
-| --- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
-| 1   | `/invisible`    | Strip zero-width, bidi, variation-selector and tag chars + ANSI/SGR escapes. Preserves ZWNJ/ZWJ for Arabic/Indic/emoji. Zero deps.                         | —                           |
-| 2   | `/html`         | Splice out instructions hidden in comments, `display:none`, off-screen, white-on-white, `hidden`. Leaves a placeholder.                                    | —                           |
-| 3   | `/html`         | Detect exfil-shaped URLs (payloads in query/path, embedded creds, `data:`/`javascript:`, off-origin redirects). Reports only.                              | —                           |
-| 4   | `/confusables`  | Fold look-alike glyphs in tool-call input (paths, commands) to ASCII, closing a cross-script deny-rule bypass.                                             | `scan`                      |
-| 5   | `/instructions` | Scan/auto-clean `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, etc., decoding Unicode-tag + zero-width-binary payloads.                                             | `fs` (direct)               |
-| 6   | `/prompt`       | Classify a prompt pass / SGR-note / block on payload-capable invisible/ANSI content.                                                                       | —                           |
-| 7   | `/output`       | Run Layers 1–4 over structured tool output, preserving shape. The Layer-5 slot takes a delete-only filter.                                                 | `redact`, `filterInjection` |
-| 8   | `/rehydrate`    | Re-anchor a model Edit composed from the _sanitized_ view back onto real bytes; deny anything ambiguous or secret-exposing.                                | `io`                        |
-| —   | `/view-map`     | Pure offset/text machinery mapping a file's on-disk bytes ↔ the sanitized view (Layer-1 deletions, Layer-4 redactions). No I/O — consumed by `/rehydrate`. | —                           |
+| #   | Import          | Purpose                                                                                                                                                                     | Seam                        |
+| --- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| 1   | `/invisible`    | Strip zero-width, bidi, variation-selector and tag chars + ANSI/SGR escapes. Preserves ZWNJ/ZWJ for Arabic/Indic/emoji. Zero deps.                                          | —                           |
+| 2   | `/html`         | Splice out instructions hidden in comments, `display:none`, off-screen, white-on-white, `hidden`. Leaves a placeholder.                                                     | —                           |
+| 3   | `/html`         | Detect exfil-shaped URLs (payloads in query/path, embedded creds, `data:`/`javascript:`, off-origin redirects). Reports only.                                               | —                           |
+| 4   | `/confusables`  | Fold look-alike glyphs in tool-call input (paths, commands) to ASCII, closing a cross-script deny-rule bypass. Gated per token, so non-Latin prose passes through unfolded. | `scan`                      |
+| 5   | `/instructions` | Scan/auto-clean `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, etc., decoding Unicode-tag + zero-width-binary payloads.                                                              | `fs` (direct)               |
+| 6   | `/prompt`       | Classify a prompt pass / SGR-note / block on payload-capable invisible/ANSI content.                                                                                        | —                           |
+| 7   | `/output`       | Run Layers 1–4 over structured tool output, preserving shape. The Layer-5 slot takes a delete-only filter.                                                                  | `redact`, `filterInjection` |
+| 8   | `/rehydrate`    | Re-anchor a model Edit composed from the _sanitized_ view back onto real bytes; deny anything ambiguous or secret-exposing.                                                 | `io`                        |
+| —   | `/view-map`     | Pure offset/text machinery mapping a file's on-disk bytes ↔ the sanitized view (Layer-1 deletions, Layer-4 redactions). No I/O — consumed by `/rehydrate`.                  | —                           |
 
 See [`THREAT-MODEL.md`](./THREAT-MODEL.md) for per-vector detail.
 

package/THREAT-MODEL.md

@@ -92,12 +92,50 @@ payload-bearing query/fragment), suitable for a warning shown to the operator.
 `./confusables` folds look-alike glyphs in tool-call **input** fields (paths,
 commands) to their ASCII canon. A denied path/command spelled in homoglyphs (a
 Cyrillic `а` for ASCII `a`) would not match an ASCII deny rule; folding closes
-that cross-script bypass (CVE-2025-54794 class). Folding is per-character and
-context-free, so it also catches an **isolated** confusable with no ASCII anchor
-that a context-sensitive canonicaliser would leave alone. The homoglyph engine
-is **injected** (`{ scan }`)—the package owns no glyph map. An all-ASCII field
-never invokes the scanner. This narrows a steganographic channel; it is not an
-enforcement boundary (distinct code points would not match a deny rule anyway).
+that cross-script bypass (CVE-2025-54794 class).
+
+Folding is gated per **token** — a maximal run of ASCII alphanumerics and
+non-ASCII glyphs, with every other ASCII character a boundary. A token folds only
+when both hold:
+
+1. **Folding leaves it pure ASCII.** The bypass requires the folded token to come
+   out byte-equal to an ASCII deny-rule target, so a token that still holds an
+   unmapped glyph after folding could not match one either way — skipping it
+   forfeits no enforcement.
+2. **It is more than a lone non-ASCII glyph.** A single-code-point token is a
+   one-letter foreign word — Russian `с` (with), `о` (about), `у` (at), `а`
+   (and), all mapped confusables and all among the most frequent words in the
+   language — as readily as it is a disguised argument, and no deny rule targets
+   a single character.
+
+So `/etc/pаsswd` and an all-Cyrillic `раѕѕwd` still fold, while `Привет`,
+`пароль.txt`, and `работа с файлом` pass through untouched. Without this gate the
+layer transliterated ordinary Cyrillic and Greek text — a commit message, an
+issue body, a filename — into garbage, which this repo weighs as the worse
+failure.
+
+The gate is per-token and never per-field: a field-level "any prose here → skip
+the field" rule would let an attacker switch folding off for a whole command by
+appending one foreign word.
+
+**Known false positive:** a multi-letter foreign word composed _entirely_ of
+mapped confusables — the Russian `сор` → `cop`, `со` → `co` — is by construction
+indistinguishable from a disguised ASCII token, and still folds.
+
+**Known false negative:** splicing one unmapped non-ASCII glyph into an otherwise
+all-confusable token switches its fold off. It buys an attacker nothing on its
+own — the unmapped glyph is still in the field, so the token cannot match an
+ASCII deny rule either. A filter reading the raw field is what closes that, not
+folding.
+
+The soundness argument assumes no later layer erases code points from the same
+field, which could remove an unmapped glyph the gate relied on after the decision
+was made. Layer 4 runs before `sanitizeAuthoredContent` on `Bash.command`.
+
+The homoglyph engine is **injected** (`{ scan }`) — the package owns no glyph
+map. An all-ASCII field never invokes the scanner. This narrows a steganographic
+channel; it is not an enforcement boundary (distinct code points would not match
+a deny rule anyway).
 
 ## Instruction-file scanning
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.14.7",
+  "version": "2.14.9",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/src/confusables.mjs

@@ -7,13 +7,42 @@
  * an ASCII deny rule, so an attacker could slip a denied path/command past a
  * filter by spelling it in look-alike code points.
  *
- * Folding is per-character and context-free: every glyph the injected scanner
- * flags is replaced with its ASCII (latin) equivalent regardless of its
- * neighbours. This deliberately catches an ISOLATED confusable with no ASCII
- * anchor (a lone Cyrillic "а" in "/а") that a context-SENSITIVE canonicaliser
- * would leave untouched — exactly the bypass to close — while leaving genuine
- * non-confusable non-ASCII (accented Latin, CJK, emoji) alone, since a faithful
- * scanner does not flag those.
+ * Folding is gated per TOKEN (a maximal run of ASCII alphanumerics and
+ * non-ASCII glyphs — see isTokenBoundary). A token folds only when both hold:
+ *
+ *   1. Folding makes it pure ASCII — every non-ASCII code point in it is
+ *      flagged. The bypass requires the folded token to come out byte-equal to
+ *      an ASCII deny-rule target, so a token left holding an unmapped glyph
+ *      could never match one anyway; skipping it costs no enforcement.
+ *   2. It is more than a lone non-ASCII glyph standing between two boundaries.
+ *      A one-code-point token is a one-letter foreign word — Russian "с", "о",
+ *      "у", "а" are among the most frequent words in the language — as readily
+ *      as it is a disguised argument, and no deny rule targets a single
+ *      character, so the evidence does not support rewriting it.
+ *
+ * That still catches the all-confusable disguise ("раѕѕwd" → "passwd") and the
+ * anchored one ("pаsswd" → "passwd"), which is exactly the bypass to
+ * close, while leaving genuine non-Latin prose intact: "Привет" keeps unmapped
+ * П/и/в/т, so its mapped р/е are not folded and the word survives byte-for-byte.
+ *
+ * WHY THE GATE: without it, folding mangled any Cyrillic/Greek text passing
+ * through a command or path — a Russian commit message, issue body, or filename
+ * came out transliterated into garbage. A false positive here rewrites content
+ * the operator wrote, which this repo weighs as the worse failure.
+ *
+ * RESIDUAL: a multi-letter foreign word composed ENTIRELY of mapped confusables
+ * (the Russian "сор" → "cop") is indistinguishable from a disguised ASCII token
+ * by construction, and still folds. Documented in THREAT-MODEL.md, not worked
+ * around — the alternatives (a field-level gate, a "looks like a path" shape
+ * heuristic) either open a bypass or trade one guess for another.
+ *
+ * ORDERING: the soundness argument assumes no later layer erases code points
+ * from the same field, which would let an unmapped glyph the gate relied on
+ * disappear after the decision. Layer 4 runs before sanitizeAuthoredContent on
+ * Bash.command; keep it there.
+ *
+ * Genuine non-confusable non-ASCII (accented Latin, CJK, emoji) is untouched
+ * regardless, since a faithful scanner does not flag it.
  *
  * The confusable scanner is INJECTED, never imported: the canonical engine
  * (namespace-guard's vision-weighted map) is a heavy, separately-owned peer.
@@ -87,6 +116,157 @@ function describeFolds(findings) {
   return folds.length > MAX_REPORTED_FOLDS ? `${shown}, …` : shown;
 }
 
+/**
+ * Reject a finding that does not describe a real, foldable glyph at its reported
+ * offset in `text`. Every consumer of a scanner finding runs this BEFORE acting
+ * on it, so a buggy or adversarial scanner fails loud instead of silently
+ * corrupting (or silently escaping the fold gate in) a path/command.
+ * @param {string} text
+ * @param {{ index: number, char: string, latinEquivalent: string }} finding
+ * @returns {void}
+ */
+function assertFinding(text, finding) {
+  // Fail loud on a finding that does not match the actual bytes at its offset:
+  // a buggy/adversarial scanner reporting a wrong char/index would otherwise
+  // silently corrupt the path/command, defeating the deny-rule protection.
+  // A negative index is the gap the startsWith guard alone misses: when `char`
+  // is a prefix of the text, `startsWith(char, -1)` is true (the offset is
+  // clamped to 0), and the slice math below then mangles the string instead of
+  // throwing — so range-check the index explicitly first.
+  if (!Number.isInteger(finding.index) || finding.index < 0)
+    throw new Error(
+      `Confusable finding has an out-of-range index ${finding.index}`,
+    );
+  // An empty `char` makes startsWith("", i) vacuously true for ANY index, so
+  // the splice inserts latinEquivalent without consuming a code point — silent
+  // insertion-corruption — and describeFolds then crashes on "".codePointAt(0).
+  // A finding must name a real matched glyph, so reject it loudly rather than
+  // let a buggy/adversarial scanner corrupt the input.
+  if (finding.char === "")
+    throw new Error(
+      `Confusable finding at index ${finding.index} has an empty char`,
+    );
+  // An ASCII `char` is not a confusable — it is already its own canon. Folding
+  // it is a no-op at best, but the fold gate reads a non-ASCII code point's
+  // flagged/unflagged status to decide a token's fate, so a scanner claiming an
+  // ASCII character is confusable is reporting something the contract says
+  // cannot happen. Fail loud rather than act on a finding we cannot interpret.
+  if (!hasNonAscii(finding.char))
+    throw new Error(
+      `Confusable finding at index ${finding.index} names an ASCII char ${JSON.stringify(finding.char)}`,
+    );
+  if (!text.startsWith(finding.char, finding.index))
+    throw new Error(
+      `Confusable finding does not match input at index ${finding.index}: expected ${JSON.stringify(finding.char)}`,
+    );
+  // An empty `latinEquivalent` slips past the ASCII loop below (it never
+  // iterates) and would splice the glyph to nothing — silently DELETING a
+  // character from a path/command. That is the same class of silent corruption
+  // the non-ASCII guard rejects, so fail loud here too rather than let a
+  // buggy/adversarial scanner erase input.
+  if (finding.latinEquivalent === "")
+    throw new Error(
+      `Confusable finding for ${JSON.stringify(
+        finding.char,
+      )} at index ${finding.index} has an empty latinEquivalent`,
+    );
+  // The replacement must be the ASCII canon the contract promises. A non-ASCII
+  // `latinEquivalent` would fold one confusable into ANOTHER look-alike (e.g.
+  // Cyrillic а → Cyrillic е), defeating the whole point — the cross-script
+  // deny-rule bypass would survive — and silently break the fold-to-ASCII
+  // invariant callers rely on, so reject it loudly.
+  for (const ch of finding.latinEquivalent)
+    if (/** @type {number} */ (ch.codePointAt(0)) > 0x7f)
+      throw new Error(
+        `Confusable latinEquivalent ${JSON.stringify(
+          finding.latinEquivalent,
+        )} is not ASCII`,
+      );
+}
+
+/**
+ * True for a code point that ends a token: any ASCII character that is not a
+ * letter or digit (space, `/`, `.`, `-`, `_`, quotes, shell metacharacters). A
+ * token is therefore a maximal run of ASCII alphanumerics and non-ASCII glyphs.
+ * That is not a shell word or a path segment — it is deliberately the SMALLEST
+ * unit that still keeps a word of foreign prose whole, so one such word can
+ * never switch folding off for the tokens around it.
+ * @param {string} ch a single code point
+ * @returns {boolean}
+ */
+function isTokenBoundary(ch) {
+  if (hasNonAscii(ch)) return false;
+  const code = ch.charCodeAt(0);
+  const isDigit = code >= 0x30 && code <= 0x39;
+  const isUpper = code >= 0x41 && code <= 0x5a;
+  const isLower = code >= 0x61 && code <= 0x7a;
+  return !isDigit && !isUpper && !isLower;
+}
+
+/**
+ * Keep only the findings whose TOKEN is foldable — see the module header for the
+ * two conditions (folds to pure ASCII; is not a lone glyph) and THREAT-MODEL.md
+ * for why declining the rest forfeits no enforcement.
+ *
+ * Every finding is validated before it is judged, so an adversarial scanner's
+ * bogus finding throws rather than being quietly dropped by the gate.
+ * @param {string} text
+ * @param {Array<{ index: number, char: string, latinEquivalent: string }>} findings
+ * @returns {Array<{ index: number, char: string, latinEquivalent: string }>}
+ */
+export function selectFoldableFindings(text, findings) {
+  for (const finding of findings) assertFinding(text, finding);
+
+  // Every UTF-16 offset a finding covers, not just its start: a scanner is free
+  // to report a multi-code-point match, and treating only the first offset as
+  // flagged would read the rest as unmapped and reject an otherwise ASCII token.
+  const flagged = new Set();
+  for (const finding of findings)
+    for (let i = 0; i < finding.char.length; i++)
+      flagged.add(finding.index + i);
+
+  // Mark the offsets belonging to a foldable token, so the per-finding lookup
+  // below is O(1). An interval scan per finding would be quadratic on a
+  // glyph-stuffed command — this runs on every tool call.
+  const foldableAt = new Uint8Array(text.length);
+  let start = 0;
+  let foldable = true;
+  let glyphs = 0;
+  let anchored = false;
+  let index = 0;
+  /**
+   * Close the token ending at `end`, marking it foldable when it holds no
+   * unmapped glyph and is more than a lone glyph, then reset for the next one.
+   * @param {number} end
+   */
+  const flushToken = (end) => {
+    if (foldable && (glyphs > 1 || anchored)) foldableAt.fill(1, start, end);
+    foldable = true;
+    glyphs = 0;
+    anchored = false;
+  };
+  for (const ch of text) {
+    if (isTokenBoundary(ch)) {
+      flushToken(index);
+      start = index + ch.length;
+    } else {
+      glyphs++;
+      if (!hasNonAscii(ch)) anchored = true;
+      // An unmapped non-ASCII glyph: this token cannot fold to ASCII.
+      else if (!flagged.has(index)) foldable = false;
+    }
+    index += ch.length;
+  }
+  flushToken(index);
+
+  // Every offset the finding covers, not just its first: `char` may span a
+  // boundary into a token the gate rejected, and folding it would rewrite that
+  // token — the exact mangling this gate exists to prevent.
+  return findings.filter((finding) =>
+    [...finding.char].every((_, i) => foldableAt[finding.index + i] === 1),
+  );
+}
+
 /**
  * Replace every scan-flagged confusable with its ASCII (latin) equivalent.
  * `index` is a UTF-16 offset into `text` and `char` is the matched glyph (which
@@ -101,53 +281,10 @@ export function foldConfusables(text, findings) {
   for (const finding of [...findings].sort(
     (lhs, rhs) => rhs.index - lhs.index,
   )) {
-    // Fail loud on a finding that does not match the actual bytes at its offset:
-    // a buggy/adversarial scanner reporting a wrong char/index would otherwise
-    // silently corrupt the path/command, defeating the deny-rule protection.
-    // A negative index is the gap the startsWith guard alone misses: when `char`
-    // is a prefix of the text, `startsWith(char, -1)` is true (the offset is
-    // clamped to 0), and the slice math below then mangles the string instead of
-    // throwing — so range-check the index explicitly first.
-    if (!Number.isInteger(finding.index) || finding.index < 0)
-      throw new Error(
-        `Confusable finding has an out-of-range index ${finding.index}`,
-      );
-    // An empty `char` makes startsWith("", i) vacuously true for ANY index, so
-    // the slice below inserts latinEquivalent without consuming a code point —
-    // silent insertion-corruption — and describeFolds then crashes on
-    // "".codePointAt(0). A finding must name a real matched glyph, so reject it
-    // loudly rather than let a buggy/adversarial scanner corrupt the input.
-    if (finding.char === "")
-      throw new Error(
-        `Confusable finding at index ${finding.index} has an empty char`,
-      );
-    if (!folded.startsWith(finding.char, finding.index))
-      throw new Error(
-        `Confusable finding does not match input at index ${finding.index}: expected ${JSON.stringify(finding.char)}`,
-      );
-    // An empty `latinEquivalent` slips past the ASCII loop below (it never
-    // iterates) and would splice the glyph to nothing — silently DELETING a
-    // character from a path/command. That is the same class of silent corruption
-    // the non-ASCII guard rejects, so fail loud here too rather than let a
-    // buggy/adversarial scanner erase input.
-    if (finding.latinEquivalent === "")
-      throw new Error(
-        `Confusable finding for ${JSON.stringify(
-          finding.char,
-        )} at index ${finding.index} has an empty latinEquivalent`,
-      );
-    // The replacement must be the ASCII canon the contract promises. A non-ASCII
-    // `latinEquivalent` would fold one confusable into ANOTHER look-alike (e.g.
-    // Cyrillic а → Cyrillic е), defeating the whole point — the cross-script
-    // deny-rule bypass would survive — and silently break the fold-to-ASCII
-    // invariant callers rely on, so reject it loudly.
-    for (const ch of finding.latinEquivalent)
-      if (/** @type {number} */ (ch.codePointAt(0)) > 0x7f)
-        throw new Error(
-          `Confusable latinEquivalent ${JSON.stringify(
-            finding.latinEquivalent,
-          )} is not ASCII`,
-        );
+    // Validate against the partially-folded text: the highest-index-first order
+    // leaves every not-yet-spliced offset byte-identical to `text`, so the
+    // startsWith check still sees the original glyph at the reported index.
+    assertFinding(folded, finding);
     folded =
       folded.slice(0, finding.index) +
       finding.latinEquivalent +
@@ -190,8 +327,13 @@ export function normalizeConfusables(
   for (const k of candidates) {
     const { findings } = scan(toolInput[k]);
     if (findings.length === 0) continue;
-    updatedInput[k] = foldConfusables(toolInput[k], findings);
-    normalized.push(`${k} (${describeFolds(findings)})`);
+    // Precision gate: fold only what a deny rule could actually match (see
+    // selectFoldableFindings). Report the folds APPLIED, not the ones scanned —
+    // naming a glyph the model can still see in the field would be a lie.
+    const foldable = selectFoldableFindings(toolInput[k], findings);
+    if (foldable.length === 0) continue;
+    updatedInput[k] = foldConfusables(toolInput[k], foldable);
+    normalized.push(`${k} (${describeFolds(foldable)})`);
   }
 
   if (normalized.length === 0) return null;

package/types/confusables.d.mts

@@ -12,6 +12,26 @@ export function hasNonAscii(value: string): boolean;
  * @returns {string}
  */
 export function normalizeContext(normalized: string[]): string;
+/**
+ * Keep only the findings whose TOKEN is foldable — see the module header for the
+ * two conditions (folds to pure ASCII; is not a lone glyph) and THREAT-MODEL.md
+ * for why declining the rest forfeits no enforcement.
+ *
+ * Every finding is validated before it is judged, so an adversarial scanner's
+ * bogus finding throws rather than being quietly dropped by the gate.
+ * @param {string} text
+ * @param {Array<{ index: number, char: string, latinEquivalent: string }>} findings
+ * @returns {Array<{ index: number, char: string, latinEquivalent: string }>}
+ */
+export function selectFoldableFindings(text: string, findings: Array<{
+    index: number;
+    char: string;
+    latinEquivalent: string;
+}>): Array<{
+    index: number;
+    char: string;
+    latinEquivalent: string;
+}>;
 /**
  * Replace every scan-flagged confusable with its ASCII (latin) equivalent.
  * `index` is a UTF-16 offset into `text` and `char` is the matched glyph (which
@@ -62,13 +82,42 @@ export function normalizeConfusables(tool: string, toolInput: any, { scan, field
  * an ASCII deny rule, so an attacker could slip a denied path/command past a
  * filter by spelling it in look-alike code points.
  *
- * Folding is per-character and context-free: every glyph the injected scanner
- * flags is replaced with its ASCII (latin) equivalent regardless of its
- * neighbours. This deliberately catches an ISOLATED confusable with no ASCII
- * anchor (a lone Cyrillic "а" in "/а") that a context-SENSITIVE canonicaliser
- * would leave untouched — exactly the bypass to close — while leaving genuine
- * non-confusable non-ASCII (accented Latin, CJK, emoji) alone, since a faithful
- * scanner does not flag those.
+ * Folding is gated per TOKEN (a maximal run of ASCII alphanumerics and
+ * non-ASCII glyphs — see isTokenBoundary). A token folds only when both hold:
+ *
+ *   1. Folding makes it pure ASCII — every non-ASCII code point in it is
+ *      flagged. The bypass requires the folded token to come out byte-equal to
+ *      an ASCII deny-rule target, so a token left holding an unmapped glyph
+ *      could never match one anyway; skipping it costs no enforcement.
+ *   2. It is more than a lone non-ASCII glyph standing between two boundaries.
+ *      A one-code-point token is a one-letter foreign word — Russian "с", "о",
+ *      "у", "а" are among the most frequent words in the language — as readily
+ *      as it is a disguised argument, and no deny rule targets a single
+ *      character, so the evidence does not support rewriting it.
+ *
+ * That still catches the all-confusable disguise ("раѕѕwd" → "passwd") and the
+ * anchored one ("pаsswd" → "passwd"), which is exactly the bypass to
+ * close, while leaving genuine non-Latin prose intact: "Привет" keeps unmapped
+ * П/и/в/т, so its mapped р/е are not folded and the word survives byte-for-byte.
+ *
+ * WHY THE GATE: without it, folding mangled any Cyrillic/Greek text passing
+ * through a command or path — a Russian commit message, issue body, or filename
+ * came out transliterated into garbage. A false positive here rewrites content
+ * the operator wrote, which this repo weighs as the worse failure.
+ *
+ * RESIDUAL: a multi-letter foreign word composed ENTIRELY of mapped confusables
+ * (the Russian "сор" → "cop") is indistinguishable from a disguised ASCII token
+ * by construction, and still folds. Documented in THREAT-MODEL.md, not worked
+ * around — the alternatives (a field-level gate, a "looks like a path" shape
+ * heuristic) either open a bypass or trade one guess for another.
+ *
+ * ORDERING: the soundness argument assumes no later layer erases code points
+ * from the same field, which would let an unmapped glyph the gate relied on
+ * disappear after the decision. Layer 4 runs before sanitizeAuthoredContent on
+ * Bash.command; keep it there.
+ *
+ * Genuine non-confusable non-ASCII (accented Latin, CJK, emoji) is untouched
+ * regardless, since a faithful scanner does not flag it.
  *
  * The confusable scanner is INJECTED, never imported: the canonical engine
  * (namespace-guard's vision-weighted map) is a heavy, separately-owned peer.