agent-sanitizer 2.23.2 → 2.24.0

package/src/ansi.mjs

@@ -80,7 +80,7 @@ const ST_C1 = 0x9c;
 const OSC_C1 = 0x9d;
 const BEL = 0x07;
 
-/** The four things an introducer can turn out to be. */
+/** The six things an introducer can turn out to be. */
 export const TOKEN_KIND = Object.freeze({
   /** A display-only `ESC[…m` / `U+009B…m` colour sequence. */
   SGR: "sgr",
@@ -88,10 +88,70 @@ export const TOKEN_KIND = Object.freeze({
   CSI: "csi",
   /** An OSC string: introducer, body and terminator as one unit. */
   OSC: "osc",
-  /** An introducer that starts no sequence the grammar recognizes. */
+  /**
+   * 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, and the
+   * block includes the string introducers DCS/SOS/PM/APC (U+0090/0098/009E/
+   * 009F) — which this grammar does not consume, so an unrecognized one here
+   * means a terminal WOULD have swallowed the following text as a control
+   * payload. 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",
 });
 
+/**
+ * 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) {
+  return (
+    kind === TOKEN_KIND.ORPHAN ||
+    kind === TOKEN_KIND.ORPHAN_CSI ||
+    kind === TOKEN_KIND.ORPHAN_C1
+  );
+}
+
+/**
+ * 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. `ESC ]` is an OSC, which the scanner
+ * consumes to the end of input if unterminated (so it never reaches here), and
+ * every other second byte — `ESC (`, `ESC #`, `ESC P` — 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, next) {
+  if (ch.charCodeAt(0) !== ESC) return TOKEN_KIND.ORPHAN_C1;
+  return next === "[" ? TOKEN_KIND.ORPHAN_CSI : TOKEN_KIND.ORPHAN;
+}
+
 /**
  * @typedef {object} AnsiToken
  * @property {number} start Index of the introducer.
@@ -168,8 +228,9 @@ const INTRODUCER_SCAN_RE = new RegExp(CONTROL_INTRODUCER_SOURCE, "g");
 /**
  * Tokenize every raw control introducer in `text`.
  *
- * Every introducer yields exactly one token — an ORPHAN when it starts nothing
- * the grammar recognizes — so "which introducers are in this text" and "which
+ * 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.
@@ -190,7 +251,7 @@ export function scanAnsi(text) {
     const csiEnd = oscEnd < 0 ? scanCsi(text, start) : -1;
     let end = start + 1;
     /** @type {string} */
-    let kind = TOKEN_KIND.ORPHAN;
+    let kind = orphanKindFor(text[start], text[start + 1]);
     if (oscEnd >= 0) {
       end = oscEnd;
       kind = TOKEN_KIND.OSC;

package/src/index.mjs

@@ -23,7 +23,13 @@ import { sanitizeText } from "./output.mjs";
 // Layer 1 lives in the zero-dependency `./layer1.mjs`, shared verbatim with the
 // tool-output pipeline (`./output`) and the Edit-repair rehydrator
 // (`./rehydrate`) so every consumer derives the identical model-facing view.
-export { applyLayer1, stripAnsiFully, LONE_SURROGATE_RE } from "./layer1.mjs";
+export {
+  applyLayer1,
+  isBenignAnsi,
+  isBenignAnsiKinds,
+  stripAnsiFully,
+  LONE_SURROGATE_RE,
+} from "./layer1.mjs";
 
 export {
   stripInvisible,

package/src/layer1.mjs

@@ -13,7 +13,13 @@
  * point where a lone surrogate would otherwise corrupt a match or a parse.
  */
 import { stripInvisibleWithReport, CATEGORY } from "./invisible.mjs";
-import { CONTROL_INTRODUCER_SOURCE, scanAnsi, TOKEN_KIND } from "./ansi.mjs";
+import {
+  CONTROL_INTRODUCER_SOURCE,
+  isOrphanKind,
+  orphanKindFor,
+  scanAnsi,
+  TOKEN_KIND,
+} from "./ansi.mjs";
 
 // The ANSI grammar and the introducer charset live in ./ansi.mjs so this module
 // and invisible.mjs (which owns the public isSgrOnly / SGR_RE and cannot import
@@ -24,6 +30,23 @@ import { CONTROL_INTRODUCER_SOURCE, scanAnsi, TOKEN_KIND } from "./ansi.mjs";
 // survives Layer 1.
 const CONTROL_INTRODUCER_RE = new RegExp(CONTROL_INTRODUCER_SOURCE, "g");
 
+/**
+ * Run the residual sweep, recording the orphan kind of every introducer it
+ * removes. The sweep sees bare characters rather than tokens, so the kind comes
+ * from {@link orphanKindFor} — the same decision the tokenizer makes, not a
+ * second spelling of it — fed the following character from the text being
+ * swept, which is the context a terminal reading this introducer would have.
+ * @param {string} text
+ * @param {Set<string>} kinds
+ * @returns {string}
+ */
+function sweepIntroducers(text, kinds) {
+  return text.replace(CONTROL_INTRODUCER_RE, (ch, offset) => {
+    kinds.add(orphanKindFor(ch, text[offset + 1]));
+    return "";
+  });
+}
+
 // Unpaired UTF-16 surrogates (high not followed by low, or low not preceded by
 // high). Normalized before any HTML parser, which throws on a stray byte —
 // which would otherwise let a single malformed code unit suppress all output.
@@ -41,13 +64,18 @@ const MAX_ANSI_PASSES = 3;
  * view. Orphans are removed by applyLayer1's residual sweep, once no
  * reconstitution is possible.
  * @param {string} text
+ * @param {Set<string>} [kinds]  collects the {@link TOKEN_KIND} of every
+ *   sequence this pass actually removed, so a caller can tell a display-only
+ *   colour strip from a cursor/erase/OSC one without re-scanning (see
+ *   {@link isBenignAnsiKinds}).
  * @returns {string}
  */
-function stripAnsiOnce(text) {
+function stripAnsiOnce(text, kinds) {
   let out = "";
   let last = 0;
   for (const token of scanAnsi(text)) {
-    if (token.kind === TOKEN_KIND.ORPHAN) continue;
+    if (isOrphanKind(token.kind)) continue;
+    kinds?.add(token.kind);
     out += text.slice(last, token.start);
     last = token.end;
   }
@@ -68,18 +96,71 @@ function stripAnsiOnce(text) {
  * survives here. Past the bound a reconstituted sequence therefore degrades to
  * VISIBLE text rather than a hidden control, which is the fail-open direction.
  * @param {string} input
+ * @param {Set<string>} [kinds]  see {@link stripAnsiOnce}; accumulates across passes
  * @returns {string}
  */
-export function stripAnsiFully(input) {
+export function stripAnsiFully(input, kinds) {
   let prev = input;
-  let out = stripAnsiOnce(prev);
+  let out = stripAnsiOnce(prev, kinds);
   for (let pass = 1; pass < MAX_ANSI_PASSES && out !== prev; pass++) {
     prev = out;
-    out = stripAnsiOnce(prev);
+    out = stripAnsiOnce(prev, kinds);
   }
   return out;
 }
 
+/**
+ * True when the ANSI a Layer-1 strip removed was INERT: every removed sequence
+ * was either a display-only SGR colour token or a LONE 7-bit `ESC` that opened
+ * nothing at all (a stray byte in a file, a truncated write, a log fragment cut
+ * mid-escape).
+ *
+ * The two other orphan kinds are deliberately NOT inert. A raw C1 orphan
+ * (TOKEN_KIND.ORPHAN_C1): legit UTF-8 text does not carry raw C1 bytes, and the
+ * block holds the DCS/SOS/PM/APC string introducers this grammar does not
+ * consume — so an unrecognized one means a terminal would have eaten the
+ * following text as a control payload. An incomplete CSI (TOKEN_KIND.ORPHAN_CSI)
+ * for the same reason at 7 bits: the CSI parser keeps consuming until a final
+ * byte, so `hello ESC[12 world` hides ` w` from the human while the model reads
+ * the whole prompt.
+ *
+ * This draws a severity line, not a presence line: the bytes are stripped
+ * either way, so all that rides on the answer is whether the operator sees a
+ * WARNING or a terse note. An orphan introducer cannot move the cursor, erase
+ * the screen, relabel a window, or open an OSC string — every one of those needs
+ * a COMPLETE token, which {@link scanAnsi} classifies as CSI or OSC and this
+ * rejects. Warning on a lone `ESC` is the false positive that costs the most: one
+ * pre-existing `ESC` in a markdown file, echoed back in an Edit result, raises
+ * the same alarm as a cursor-spoofing payload, and an alarm that fires on inert
+ * bytes is the one operators learn to scroll past.
+ *
+ * It takes the kinds the STRIP recorded, never a fresh scan of the raw text,
+ * and that is the whole point: a scan of the raw text answers about sequences
+ * that have not been reconstituted yet, so `ESC` + `ESC[m` + `[2J` (a bare ESC,
+ * an SGR, then plain text) reads as orphan-only there while the strip's second
+ * pass actually removes a CSI erase. Recording what each pass removed reports
+ * the sequences that really existed at Layer 1's fixed point.
+ * @param {readonly string[] | Set<string>} kinds  {@link TOKEN_KIND} values removed
+ * @returns {boolean}
+ */
+export function isBenignAnsiKinds(kinds) {
+  return [...kinds].every(
+    (kind) => kind === TOKEN_KIND.SGR || kind === TOKEN_KIND.ORPHAN,
+  );
+}
+
+/**
+ * {@link isBenignAnsiKinds} for callers that hold only the text — it runs the
+ * full Layer-1 composition to get the fixed-point view. Callers that already
+ * ran {@link applyLayer1} must read its `ansiKinds` instead of paying for a
+ * second strip.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isBenignAnsi(text) {
+  return isBenignAnsiKinds(applyLayer1(text).ansiKinds);
+}
+
 // How many times the {ANSI strip, invisible strip} composition may re-run before
 // the sweep is forced. Each iteration deletes at least one character, so the
 // loop terminates on its own; the bound is a DoS guard on the same quadratic
@@ -119,19 +200,25 @@ const MAX_LAYER1_PASSES = 4;
  *
  * `deAnsi` is the ANSI strip of the ORIGINAL text (invisible runs intact), the
  * scope a LONG_RUN payload check needs — not an intermediate of the loop.
+ *
+ * `ansiKinds` is the {@link TOKEN_KIND} of every ANSI sequence the composition
+ * removed, deduped — the severity detail `found`'s single ANSI category cannot
+ * carry (see {@link isBenignAnsiKinds}). It is also what DERIVES that category:
+ * a kind is recorded exactly when bytes were removed, so "we reported ANSI" and
+ * "here is what the ANSI was" can no longer disagree.
  * @param {string} text
- * @returns {{ cleaned: string, deAnsi: string, found: string[] }}
+ * @returns {{ cleaned: string, deAnsi: string, found: string[], ansiKinds: string[] }}
  */
 export function applyLayer1(text) {
-  const deAnsi = stripAnsiFully(text);
+  /** @type {Set<string>} TOKEN_KINDs removed by every ANSI pass below. */
+  const ansiKinds = new Set();
+  const deAnsi = stripAnsiFully(text, ansiKinds);
   /** @type {Set<string>} Union of the categories every iteration reported. */
   const found = new Set();
   let cleaned = text;
-  let ansiFound = false;
 
   for (let pass = 0; pass < MAX_LAYER1_PASSES; pass++) {
-    const afterAnsi = pass === 0 ? deAnsi : stripAnsiFully(cleaned);
-    if (afterAnsi !== cleaned) ansiFound = true;
+    const afterAnsi = pass === 0 ? deAnsi : stripAnsiFully(cleaned, ansiKinds);
     // stripInvisibleWithReport returns `found` for exactly the categories it
     // removed — so a ZWNJ/ZWJ the carve-out PRESERVES never registers as a
     // strip. The second argument stays the ORIGINAL `text` on every iteration:
@@ -152,18 +239,16 @@ export function applyLayer1(text) {
     // pass. A sweep that changes the text feeds one more round (removing an
     // introducer can make invisibles adjacent, exactly as removing a sequence
     // can); one that changes nothing means the whole composition has converged.
-    const swept = cleaned.replace(CONTROL_INTRODUCER_RE, "");
+    const swept = sweepIntroducers(cleaned, ansiKinds);
     if (swept === cleaned) break;
     cleaned = swept;
-    ansiFound = true;
   }
 
-  const swept = cleaned.replace(CONTROL_INTRODUCER_RE, "");
-  if (swept !== cleaned) {
-    cleaned = swept;
-    ansiFound = true;
-  }
+  cleaned = sweepIntroducers(cleaned, ansiKinds);
 
-  if (ansiFound) found.add(CATEGORY.ANSI);
-  return { cleaned, deAnsi, found: [...found] };
+  // Derived, not tracked in parallel: a kind is recorded exactly when an ANSI
+  // pass or the sweep removed bytes, so the category and the severity detail
+  // are two readings of one fact.
+  if (ansiKinds.size > 0) found.add(CATEGORY.ANSI);
+  return { cleaned, deAnsi, found: [...found], ansiKinds: [...ansiKinds] };
 }

package/src/output.mjs

@@ -24,9 +24,13 @@
  * actually removes something, so a secret that a deletion reconstitutes is
  * still caught before this function returns.
  */
-import { CATEGORY, describeStripped, isSgrOnly } from "./invisible.mjs";
+import { CATEGORY, describeStripped } from "./invisible.mjs";
 import { needsMarkdownPipeline } from "./gates.mjs";
-import { applyLayer1, LONE_SURROGATE_RE } from "./layer1.mjs";
+import {
+  applyLayer1,
+  isBenignAnsiKinds,
+  LONE_SURROGATE_RE,
+} from "./layer1.mjs";
 import {
   describeExfil,
   describeHtmlSanitized,
@@ -283,9 +287,10 @@ export function deleteVerbatimSpans(text, spans) {
 
 /**
  * Layer 1 + surrogate normalisation: invisible chars, ANSI, lone surrogates.
- * `sgrNote` is true when the ONLY change was display-only SGR color AND the
- * caller opted into the carve-out (`sgrCarveOut`) — the caller reports that
- * with a terse note, not the WARNING prefix.
+ * `sgrNote` is true when the ONLY change was INERT ANSI — display-only SGR
+ * colour and/or a stray orphan introducer that formed no sequence — AND the
+ * caller opted into the carve-out (`sgrCarveOut`); the caller reports that with
+ * a terse note, not the WARNING prefix.
  * @param {string} text
  * @param {boolean} sgrCarveOut
  * @returns {{ cleaned: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean }}
@@ -297,18 +302,24 @@ function processLayer1(text, sgrCarveOut) {
   const found = [];
   let modified = false;
   let sgrNote = false;
-  const { cleaned: layer1, deAnsi, found: invisFound } = applyLayer1(text);
+  const {
+    cleaned: layer1,
+    deAnsi,
+    found: invisFound,
+    ansiKinds,
+  } = applyLayer1(text);
   let cleaned = layer1;
   if (invisFound.length > 0) {
     found.push(...invisFound);
     modified = true;
-    // Display-only color with the carve-out enabled: the strip removed cosmetic
-    // styling and nothing else (found is exactly [ANSI], so zero invisible
-    // chars were present, making isSgrOnly exact). Report it as a note.
+    // Inert ANSI with the carve-out enabled: the strip removed cosmetic styling
+    // and/or a stray escape byte, and nothing else (found is exactly [ANSI], so
+    // zero invisible chars were present). Report it as a note — a cursor-move,
+    // erase or OSC token lands in ansiKinds as CSI/OSC and keeps the WARNING.
     sgrNote =
       invisFound.length === 1 &&
       invisFound[0] === CATEGORY.ANSI &&
-      isSgrOnly(text) &&
+      isBenignAnsiKinds(ansiKinds) &&
       sgrCarveOut;
     if (!sgrNote) warnings.push(describeStripped(invisFound, deAnsi));
   }

package/src/prompt.mjs

@@ -8,12 +8,14 @@
  * the only way to neutralize a payload is to block. This is the pure decision;
  * a host wraps it in whatever its agent's prompt-submission hook expects.
  *
- * One carve-out: a prompt whose only escape content is SGR color/style codes
- * (`ESC [ params m`) passes with a note instead of blocking. Pasting colored
- * terminal output (test runs, build logs) is the single most common debugging
- * action, and SGR is display-only by the ECMA-48 grammar — it cannot move the
- * cursor, erase the screen, or carry an OSC payload. Anything beyond SGR still
- * blocks, as do the invisible-char thresholds.
+ * One carve-out: a prompt whose only escape content is INERT — SGR color/style
+ * codes (`ESC [ params m`) and/or an orphan introducer that completes no
+ * sequence — passes with a note instead of blocking. Pasting colored terminal
+ * output (test runs, build logs) is the single most common debugging action,
+ * and SGR is display-only by the ECMA-48 grammar; an orphan `ESC` is not a
+ * sequence at all. Neither can move the cursor, erase the screen, or carry an
+ * OSC payload. Anything that IS a complete CSI/OSC token still blocks, as do
+ * the invisible-char thresholds.
  */
 import {
   CHECKS,
@@ -24,9 +26,8 @@ import {
   SCATTERED_THRESHOLD,
   countPayloadInvisible,
   stripInvisible,
-  isSgrOnly,
 } from "./invisible.mjs";
-import { stripAnsiFully } from "./layer1.mjs";
+import { isBenignAnsi, stripAnsiFully } from "./layer1.mjs";
 import { CONTROL_INTRODUCER_SOURCE } from "./ansi.mjs";
 
 // Every raw ANSI control a prompt can carry: 7-bit ESC (U+001B) and the entire
@@ -44,21 +45,6 @@ import { CONTROL_INTRODUCER_SOURCE } from "./ansi.mjs";
 // differently, so even a grep-based drift check would have missed a divergence.
 const ANSI_INTRODUCER = new RegExp(CONTROL_INTRODUCER_SOURCE);
 
-/**
- * True when every ANSI introducer in `prompt` belongs to a display-only SGR
- * color sequence -- the note carve-out's precondition. `isSgrOnly` already tests
- * the SGR-stripped prompt against the WHOLE C1 control block (U+0080-U+009F,
- * which includes the C1 OSC introducer U+009D and DCS/SOS/PM/APC) plus the 7-bit
- * ESC, so a residual C1-OSC or any non-SGR escape already denies it — no
- * separate re-check is needed (an earlier `&& !ANSI_INTRODUCER.test(...)` here
- * was an exact duplicate of that gate over the same stripped string).
- * @param {string} prompt
- * @returns {boolean}
- */
-function isSgrColorOnly(prompt) {
-  return isSgrOnly(prompt);
-}
-
 /**
  * Human-facing block reason: what was detected, the thresholds, a code-point
  * sample of the long run (if any), and how to recover.
@@ -139,9 +125,13 @@ export function classifyPrompt(prompt, strip = stripAnsiFully) {
 
   if (!hasAnsi && invisiblesBelowThreshold) return { action: "pass" };
 
-  // Display-only color codes in an otherwise clean prompt: pass with a note
-  // instead of blocking, so pasted colored logs remain usable.
-  if (hasAnsi && invisiblesBelowThreshold && isSgrColorOnly(prompt))
+  // Inert escapes in an otherwise clean prompt — display-only colour and/or an
+  // orphan introducer that forms no sequence: pass with a note instead of
+  // blocking, so pasted colored logs and log fragments cut mid-escape remain
+  // usable. isBenignAnsi judges from what Layer 1's strip actually removed, so
+  // it covers the whole C1 block and any sequence that only reconstitutes
+  // during the strip; a complete CSI/OSC token falls through to the block.
+  if (hasAnsi && invisiblesBelowThreshold && isBenignAnsi(prompt))
     return { action: "note" };
 
   // CHECKS pairs a machine-readable category code with its detector; map each

package/types/ansi.d.mts

@@ -1,8 +1,32 @@
+/**
+ * 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. `ESC ]` is an OSC, which the scanner
+ * consumes to the end of input if unterminated (so it never reaches here), and
+ * every other second byte — `ESC (`, `ESC #`, `ESC P` — 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 when it starts nothing
- * the grammar recognizes — so "which introducers are in this text" and "which
+ * 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.
@@ -39,7 +63,7 @@ export const CONTROL_INTRODUCER_SOURCE: "[\\u001b\\u0080-\\u009f]";
  * and the regex can no longer describe different languages.
  */
 export const SGR_RE: RegExp;
-/** The four things an introducer can turn out to be. */
+/** The six 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";
@@ -47,8 +71,34 @@ export const TOKEN_KIND: Readonly<{
     CSI: "csi";
     /** An OSC string: introducer, body and terminator as one unit. */
     OSC: "osc";
-    /** An introducer that starts no sequence the grammar recognizes. */
+    /**
+     * 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, and the
+     * block includes the string introducers DCS/SOS/PM/APC (U+0090/0098/009E/
+     * 009F) — which this grammar does not consume, so an unrecognized one here
+     * means a terminal WOULD have swallowed the following text as a control
+     * payload. 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 = {
     /**

package/types/claude-hooks/lib/control-plane.d.mts

@@ -43,7 +43,12 @@ export function nativeStdout(response: {
  * unparsable stdin, missing package, a judge error — is reported on stderr and
  * routed to `onError(err, input)` (`input` undefined when stdin never parsed),
  * where the hook applies its declared fail posture.
- * @param {string} hookName  prefix for the stderr diagnostic
+ *
+ * It is also where every judge hook is TIMED: the verdict picks up a
+ * performance note when the judge overran the hook budget (see
+ * lib/hook-timing.mjs), so no hook has to remember to measure itself.
+ * @param {string} hookName  prefix for the stderr diagnostic, and the hook name
+ *   a slow-run notice reports
  * @param {(event: import("agent-control-plane-core").ToolCallEvent) =>
  *   import("agent-control-plane-core").Verdict |
  *   Promise<import("agent-control-plane-core").Verdict>} judge

package/types/claude-hooks/lib/hook-timing.d.mts

@@ -0,0 +1,106 @@
+/**
+ * Run `work`, charging its whole duration to provisioning so no timer running
+ * across it counts that time. Charged in a `finally`, so a provisioning step
+ * that FAILS is still excluded — the wait happened either way, and a hook that
+ * then fails is reported through its fault posture, not as "slow".
+ *
+ * Wrap only genuinely one-time, per-session setup: waiting out a dependency
+ * install, waiting for a cold redactor daemon to bind. Never wrap the hook's
+ * actual work — that is exactly what this measurement is for.
+ * @template T
+ * @param {() => Promise<T>} work
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {Promise<T>}
+ */
+export function excludeProvisioning<T>(work: () => Promise<T>, now?: () => number): Promise<T>;
+/**
+ * Start measuring; the returned function reports the milliseconds elapsed so
+ * far MINUS any provisioning charged in the meantime, and may be called more
+ * than once.
+ *
+ * Only provisioning charged since this timer started is subtracted, so an
+ * earlier run's cold start cannot pay down a later run's real cost. A
+ * provisioning window that straddles the timer's start would otherwise be able
+ * to subtract more than the timer has measured, so the result is floored at 0.
+ * @param {() => number} [now]  injectable clock, for tests
+ * @returns {() => number}
+ */
+export function startHookTimer(now?: () => number): () => number;
+/**
+ * The model-facing line for a hook that overran the budget, or null when it did
+ * not. Addressed to the model because the model is the only party that reliably
+ * reads this channel — stderr from a non-blocking hook is easy to miss — and it
+ * is asked to relay the number, since the operator is the one who can file it.
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {number} [thresholdMs]
+ * @returns {string | null}
+ */
+export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?: number): string | null;
+/**
+ * `verdict` with the slow-hook notice folded into its `additional_context`, or
+ * the verdict untouched when the run was within budget. Also writes the notice
+ * to stderr, so the timing survives in the transcript even for a hook whose
+ * verdict carries no context channel to the model.
+ *
+ * Appended, never substituted: the context slot is how a hook reports a REDACTED
+ * secret or a stripped payload, and a timing note must not displace that.
+ * @template {{ additional_context?: string }} V
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {V} verdict
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {V}
+ */
+export function withSlowHookNotice<V extends {
+    additional_context?: string;
+}>(hookName: string, elapsedMs: number, verdict: V, writeErr?: (chunk: string) => void): V;
+/**
+ * Report a slow run for a hook that answers with a bare `hookSpecificOutput`
+ * envelope rather than a control-plane verdict — SessionStart, which has no
+ * verdict channel at all. A within-budget run emits nothing, so the quiet path
+ * stays quiet (and the hook's silent-success contract is unchanged).
+ * @param {string} hookName
+ * @param {number} elapsedMs
+ * @param {string} hookEventName
+ * @param {(event: string, fields: Record<string, unknown>) => void} emit  the
+ *   stdout envelope writer (hook-io's emitHookResponse); passed in rather than
+ *   imported so this module stays dependency-free — see the module doc
+ * @param {(chunk: string) => void} [writeErr]  injectable stderr sink, for tests
+ * @returns {boolean}  whether a notice was emitted
+ */
+export function reportSlowHook(hookName: string, elapsedMs: number, hookEventName: string, emit: (event: string, fields: Record<string, unknown>) => void, writeErr?: (chunk: string) => void): boolean;
+/**
+ * The one place a hook's own wall-clock cost is measured and reported.
+ *
+ * These hooks sit on the critical path of every tool call, every prompt and
+ * every session start: whatever they spend, the user waits. That cost is also
+ * the hardest kind of bug to notice from inside — a hook that got slow looks
+ * exactly like an agent that got slow, so it goes unreported for weeks (one
+ * SessionStart scan blocked startup for 30 SECONDS before anyone traced it back
+ * here). A hook past the budget therefore says so IN BAND, in the model's
+ * context, where it cannot be missed and can be relayed to the operator.
+ *
+ * One threshold, one message, one merge rule, shared by every hook — the
+ * measurement is worthless if each hook words it differently or picks its own
+ * bar for "slow".
+ *
+ * What it deliberately does NOT count is ONE-TIME PROVISIONING (see
+ * {@link excludeProvisioning}). A dependency-install wait or a cold redactor
+ * spawn is wall-clock the user really waits, but it is not a cost this hook
+ * pays per call and it is not a bug worth a report — charging it would make the
+ * FIRST call of every session cry wolf, which is precisely the alert fatigue
+ * this notice exists to avoid.
+ *
+ * Dependency-free on purpose: everything imports this, including hook-io, so a
+ * back-import would close a cycle. The one emitter it needs is passed in.
+ */
+/**
+ * Wall-clock a single hook invocation may spend before it is reported as slow.
+ *
+ * A second is far above anything these hooks do when healthy (Layer 1 is a few
+ * regex passes; the redactor daemon answers in tens of milliseconds once warm)
+ * and far below the point where a human is merely impatient — so crossing it
+ * means something is actually wrong, not that the machine is busy.
+ */
+export const SLOW_HOOK_THRESHOLD_MS: 1000;

package/types/claude-hooks/lib/redactor-client.d.mts

@@ -100,7 +100,7 @@ export function waitForSocket(socketPath: string, { deadlineMs, stepMs }?: {
  * @param {{map?: boolean, webIngress?: boolean, socketPath?: string,
  *   deadline?: {remainingMs: () => number},
  *   connect?: typeof connectAndRequest, spawn?: typeof spawnDaemon,
- *   waitForSocket?: typeof waitForSocket}} [opts]
+ *   waitForSocket?: typeof waitForSocket, now?: () => number}} [opts]
  * @returns {Promise<RedactResponse|null>}
  */
 export function redactViaDaemon(text: string, opts?: {
@@ -113,6 +113,7 @@ export function redactViaDaemon(text: string, opts?: {
     connect?: typeof connectAndRequest;
     spawn?: typeof spawnDaemon;
     waitForSocket?: typeof waitForSocket;
+    now?: () => number;
 }): Promise<RedactResponse | null>;
 export const FRAME_CAP: number;
 export const DEFAULT_SOCKET_PATH: string;