switchroom 0.19.35 → 0.19.36

package/telegram-plugin/secret-detect/kv-scanner.ts

@@ -13,6 +13,7 @@
  * `key=value` match), so the rewriter can preserve the `key=` prefix.
  */
 import { shannonEntropy } from './entropy.js'
+import { isInertValue, stripTrailingPunctuation } from './inert-values.js'
 
 export interface RawHit {
   rule_id: string
@@ -31,6 +32,107 @@ const KV_RE = /\b([A-Za-z_][A-Za-z0-9_-]*(?:password|passwd|token|secret|key|api
 
 export const KV_ENTROPY_THRESHOLD = 4.0
 
+// ─── Human-memorable passwords ────────────────────────────────────────
+//
+// Gap closed (2026-07 hindsight write-path audit): a password a human can
+// remember — family names + a year, a two-word phrase with a digit — has
+// Shannon entropy well under KV_ENTROPY_THRESHOLD, so `scanKeyValue` above
+// skips it and it was stored in agent memory verbatim.
+//
+// Lowering KV_ENTROPY_THRESHOLD is NOT the fix: that threshold guards a
+// wide LHS set (`key`, `token`, `secret`, `api_key`, and any identifier
+// ending in them), where dropping the entropy floor would mask ordinary
+// prose and config chatter wholesale.
+//
+// Instead this is a SEPARATE, much narrower rule:
+//
+//   * the LHS must be the password family specifically — `password`,
+//     `passwd`, `passphrase`, `pwd` (optionally prefixed, e.g.
+//     `db_password`). Not `key`/`token`/`secret`.
+//   * the connector is `:`/`=` or the literal word `is` (so "the wifi
+//     password is <value>" is covered, which is how a human actually
+//     writes one down).
+//   * the value must LOOK like a chosen credential rather than a word:
+//     8..64 bytes, no whitespace, and at least two distinct character
+//     classes of {lower, upper, digit, symbol}.
+//
+// The two-class gate is what keeps ordinary prose out — but ONLY once
+// trailing punctuation has been stripped off the candidate value.
+//
+// #3982 review, BLOCKER 2: the value class is `[^\s"']`, so a sentence
+// swallows its own terminator into the match. "The password is
+// required." captured `required.` — lowercase letters PLUS a `.`, which
+// is two character classes — and redacted as a credential. Same for
+// `incorrect.`, `unchanged.`, and for a list comma in
+// "password: required, minimum twelve characters". Sentence-final is the
+// single most common position for those words, so the original comment
+// here ("single-class lowercase and never match") was not just wrong, it
+// was wrong about the common case: "Ken confirmed the password is
+// unchanged." stored as "…the password is [REDACTED:memorable_password]",
+// which INVERTS the meaning of the sentence it corrupts.
+//
+// `looksLikeMemorablePassword` therefore runs its length / distinct-char
+// / character-class gates against the punctuation-stripped core, while
+// the MASK still covers the whole captured value (a trailing `!` is more
+// likely the last byte of the password than the end of a sentence).
+//
+// The deliberate trade that remains: a single-class credential such as an
+// all-lowercase passphrase still slips through. That is the conservative
+// side of the line — over-redacting prose corrupts stored conversation and
+// is unrecoverable, whereas this rule's misses are the pre-existing
+// behaviour, not a regression.
+const MEMORABLE_PW_RE =
+  /\b([A-Za-z0-9_-]*(?:password|passwd|passphrase|pwd))\b\s*(?:[:=]\s*|\s+is\s+)(["']?)([^\s"']{8,64})\2/gi
+
+export const MEMORABLE_PW_RULE_ID = 'memorable_password'
+
+/** Minimum distinct character classes for a value to look chosen-by-a-human. */
+export const MEMORABLE_PW_MIN_CLASSES = 2
+
+function charClassCount(value: string): number {
+  let n = 0
+  if (/[a-z]/.test(value)) n++
+  if (/[A-Z]/.test(value)) n++
+  if (/[0-9]/.test(value)) n++
+  if (/[^A-Za-z0-9]/.test(value)) n++
+  return n
+}
+
+/** True when `value` looks like a human-chosen password, not prose. */
+export function looksLikeMemorablePassword(value: string): boolean {
+  if (isInertValue(value)) return false
+  // Gate on the value WITHOUT the sentence punctuation it swallowed.
+  const core = stripTrailingPunctuation(value)
+  if (core.length < 8 || core.length > 64) return false
+  if (isInertValue(core)) return false
+  // A single repeated character is a mask, not a password.
+  if (new Set(core).size < 4) return false
+  return charClassCount(core) >= MEMORABLE_PW_MIN_CLASSES
+}
+
+export function scanMemorablePasswords(text: string): RawHit[] {
+  const hits: RawHit[] = []
+  MEMORABLE_PW_RE.lastIndex = 0
+  let m: RegExpExecArray | null
+  while ((m = MEMORABLE_PW_RE.exec(text)) !== null) {
+    const keyName = m[1]!
+    const value = m[3]
+    if (!value || !looksLikeMemorablePassword(value)) continue
+    const valueOffsetInMatch = m[0].indexOf(value, keyName.length)
+    if (valueOffsetInMatch < 0) continue
+    const start = m.index + valueOffsetInMatch
+    hits.push({
+      rule_id: MEMORABLE_PW_RULE_ID,
+      start,
+      end: start + value.length,
+      matched_text: value,
+      key_name: keyName,
+      confidence: 'ambiguous',
+    })
+  }
+  return hits
+}
+
 export function scanKeyValue(text: string): RawHit[] {
   const hits: RawHit[] = []
   KV_RE.lastIndex = 0
@@ -38,6 +140,12 @@ export function scanKeyValue(text: string): RawHit[] {
   while ((m = KV_RE.exec(text)) !== null) {
     const [, keyName, value] = m
     if (!value) continue
+    // Placeholders / references are not credentials — see inert-values.ts.
+    // `ANTHROPIC_API_KEY: vault:anthropic/api_key` and
+    // `const API_KEY = process.env.ANTHROPIC_API_KEY` both land HERE, not
+    // on the ALL_CAPS `env_key_value` pattern, and both were being
+    // destroyed (#3982 review, MAJOR 5).
+    if (isInertValue(value)) continue
     // Shannon entropy gate — only flag values that actually look random.
     const h = shannonEntropy(value)
     if (h < KV_ENTROPY_THRESHOLD) continue

package/telegram-plugin/secret-detect/patterns.ts

@@ -94,20 +94,40 @@ export const STRUCTURED_PATTERNS: PatternDef[] = [
     captureIndex: 2,
     slugHint: 'cli_flag',
   },
-  // Authorization: Bearer token (form 1 — explicit Authorization header)
+  // Authorization: Bearer token (form 1 — explicit Authorization header).
+  //
+  // CASE-INSENSITIVE since #3982's review: HTTP/2 and HTTP/3 lowercase
+  // every header name on the wire, so `authorization: bearer <token>` is
+  // what an agent actually pastes out of a curl trace or a proxy log —
+  // and it sailed through both engines unmasked. RFC 9110 makes the
+  // header name case-insensitive and the auth SCHEME token
+  // case-insensitive too, so matching case-sensitively was simply wrong.
   {
     rule_id: 'bearer_auth_header',
-    regex: /Authorization\s*[:=]\s*Bearer\s+([A-Za-z0-9._\-+=]+)/g,
+    regex: /Authorization\s*[:=]\s*Bearer\s+([A-Za-z0-9._\-+=]+)/gi,
     captureIndex: 1,
     slugHint: 'bearer_token',
   },
-  // Bare "Bearer XYZ" (length-gated to cut false positives on the word "Bearer")
+  // Bare "Bearer XYZ" (length-gated to cut false positives on the word
+  // "Bearer"). The 18-char floor is what keeps the now case-insensitive
+  // match off prose like "the bearer token to use".
   {
     rule_id: 'bearer_loose',
-    regex: /\bBearer\s+([A-Za-z0-9._\-+=]{18,})\b/g,
+    regex: /\bBearer\s+([A-Za-z0-9._\-+=]{18,})\b/gi,
     captureIndex: 1,
     slugHint: 'bearer_token',
   },
+  // Authorization: Basic <base64(user:password)>. Base64 is an encoding,
+  // not a cipher — a Basic header is a plaintext credential with extra
+  // steps, and it reached agent memory unmasked (#3982 review, MAJOR 6).
+  // Anchored on the header + scheme, so a bare base64 blob elsewhere in
+  // the text is untouched (that stays a documented gap).
+  {
+    rule_id: 'basic_auth_header',
+    regex: /Authorization\s*[:=]\s*Basic\s+([A-Za-z0-9+/=]{8,})/gi,
+    captureIndex: 1,
+    slugHint: 'basic_auth',
+  },
   // PEM private key block — single greedy capture, non-overlapping.
   {
     rule_id: 'pem_private_key',

package/telegram-plugin/tests/format-consistency.test.ts

@@ -334,4 +334,97 @@ describe('stripExcessBold', () => {
     const once = stripExcessBold(input)
     expect(stripExcessBold(once)).toBe(once)
   })
+
+  // ── Heading exemption in the GLOBAL (>30%) rule ──────────────────────────
+  // A bold-dense digest tripped the global ratio and lost EVERY bold marker,
+  // including its section headings, with no signal. Short standalone
+  // pseudo-heading blocks must now survive the global strip.
+
+  const boldDenseBody =
+    '**alpha** **bravo** **charlie** **delta** **echo** **foxtrot** **golf** ' +
+    '**hotel** **india** **juliet** **kilo** **lima** plus a short plain tail here.'
+
+  test('global strip keeps a short standalone bold heading, strips the rest', () => {
+    const input = `**Section One**\n\n${boldDenseBody}`
+    const out = stripExcessBold(input)
+    // Heading survives.
+    expect(out).toContain('**Section One**')
+    // Non-heading inline bold is flattened.
+    expect(out).toContain('alpha')
+    expect(out).not.toContain('**alpha**')
+    expect(out).not.toContain('**golf**')
+  })
+
+  test('global strip preserves EVERY heading in a multi-section digest', () => {
+    const input =
+      `**Overview**\n\n${boldDenseBody}\n\n` +
+      `**Next steps:**\n\n**one** **two** **three** **four** **five** **six** ` +
+      'plus a plain closing clause long enough to matter here.'
+    const out = stripExcessBold(input)
+    expect(out).toContain('**Overview**')
+    expect(out).toContain('**Next steps:**')
+    expect(out).not.toContain('**one**')
+    expect(out).not.toContain('**six**')
+  })
+
+  test('regression: global strip with NO headings still fully strips', () => {
+    const input = `${boldDenseBody}`
+    const out = stripExcessBold(input)
+    expect(out).not.toContain('**')
+    expect(out).toContain('alpha')
+  })
+
+  test('regression: under-threshold message keeps all bold (incl. headings)', () => {
+    const input = `**Summary**\n\n${filler} The key fact is **42**.`
+    expect(stripExcessBold(input)).toBe(input)
+  })
+
+  test('48/49-char pseudo-heading boundary honoured under global strip', () => {
+    // Heading length is measured WITH the `**` markers. 44 inner chars → 48
+    // total (exempt); 45 inner chars → 49 total (stripped).
+    const heading48 = '**' + 'H'.repeat(44) + '**' // length 48
+    const heading49 = '**' + 'H'.repeat(45) + '**' // length 49
+    expect(heading48.length).toBe(48)
+    expect(heading49.length).toBe(49)
+
+    const out48 = stripExcessBold(`${heading48}\n\n${boldDenseBody}`)
+    expect(out48).toContain(heading48)
+
+    const out49 = stripExcessBold(`${heading49}\n\n${boldDenseBody}`)
+    expect(out49).not.toContain(heading49)
+    expect(out49).toContain('H'.repeat(45))
+  })
+
+  test('multi-line fully-bolded block is NOT mislabelled a heading (global)', () => {
+    // Two bolded lines in one block must be flattened, not exempted — the
+    // heading exemption is single-line only.
+    const input = `**First bold line here**\n**Second bold line here**\n\n${boldDenseBody}`
+    const out = stripExcessBold(input)
+    expect(out).not.toContain('**First bold line here**')
+    expect(out).toContain('First bold line here')
+  })
+
+  // ── Observability ────────────────────────────────────────────────────────
+  test('onStrip fires with rule=global + ratio when global rule strips', () => {
+    const calls: Array<{ rule: string; ratio: number }> = []
+    stripExcessBold(`**Section One**\n\n${boldDenseBody}`, (d) => calls.push(d))
+    expect(calls).toHaveLength(1)
+    expect(calls[0].rule).toBe('global')
+    expect(calls[0].ratio).toBeGreaterThan(0.3)
+  })
+
+  test('onStrip fires with rule=per-block when only a block is flattened', () => {
+    const calls: Array<{ rule: string; ratio: number }> = []
+    const input = `${filler}\n\n**This whole paragraph is bold.**\n**Every single line of it.**`
+    stripExcessBold(input, (d) => calls.push(d))
+    expect(calls).toHaveLength(1)
+    expect(calls[0].rule).toBe('per-block')
+    expect(calls[0].ratio).toBeLessThanOrEqual(0.3)
+  })
+
+  test('onStrip does NOT fire when nothing is stripped', () => {
+    const calls: Array<{ rule: string; ratio: number }> = []
+    stripExcessBold(`**Summary**\n\n${filler} The key fact is **42**.`, (d) => calls.push(d))
+    expect(calls).toHaveLength(0)
+  })
 })

package/telegram-plugin/tests/gateway-session-model-relaunch.test.ts

@@ -21,6 +21,8 @@ import {
   classifyModelSwitchConfirmation,
   formatModelRelaunchDiagLog,
   resolveModelSwitchBootNotice,
+  resolveSessionModelResolutionTimeoutMs,
+  waitForSessionModelResolution,
 } from '../gateway/model-command.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -147,6 +149,39 @@ describe('gateway: the live callback dispatcher routes every switch tap to the h
 })
 
 describe('gateway boot: session-model re-hydration + confirmation + alert relay', () => {
+  it('does not classify stale previous-boot state before the resolution barrier', async () => {
+    const staleLaunched = 'claude-opus-4-8'
+    const configured = 'claude-opus-4-8'
+    const reason = 'user: /model fable (session-only relaunch, menu)'
+    const resolved = await waitForSessionModelResolution({
+      barrierExists: () => false,
+      timeoutMs: 0,
+    })
+    const confirmation = resolved
+      ? classifyModelSwitchConfirmation({ reason, launched: staleLaunched, configured })
+      : null
+    expect(resolved).toBe(false)
+    expect(confirmation).toBeNull()
+  })
+
+  it('waits asynchronously until the resolution barrier appears', async () => {
+    let checks = 0
+    const resolved = await waitForSessionModelResolution({
+      barrierExists: () => ++checks >= 2,
+      timeoutMs: 1_000,
+      sleep: async () => {},
+    })
+    expect(resolved).toBe(true)
+    expect(checks).toBe(2)
+  })
+
+  it('uses a safe default for absent or invalid barrier timeout overrides', () => {
+    expect(resolveSessionModelResolutionTimeoutMs(undefined)).toBe(180_000)
+    expect(resolveSessionModelResolutionTimeoutMs('not-a-number')).toBe(180_000)
+    expect(resolveSessionModelResolutionTimeoutMs('-1')).toBe(180_000)
+    expect(resolveSessionModelResolutionTimeoutMs('2500')).toBe(2_500)
+  })
+
   it('re-hydrates the override from .active-session-model (launched !== configured)', () => {
     const idx = GATEWAY_SRC.indexOf("join(smAgentDir, '.active-session-model')")
     expect(idx).toBeGreaterThan(0)
@@ -295,9 +330,12 @@ describe('gateway boot: session-model re-hydration + confirmation + alert relay'
   })
 
   it('wires the pipeline into the boot rehydration (gateway calls classify → diag log → notice)', () => {
-    const idx = GATEWAY_SRC.indexOf('const isApplyBoot = launched.length > 0')
+    const idx = GATEWAY_SRC.indexOf('const resolutionTimeoutMs = resolveSessionModelResolutionTimeoutMs(')
     expect(idx).toBeGreaterThan(0)
-    const win = GATEWAY_SRC.slice(idx, idx + 4200)
+    const win = GATEWAY_SRC.slice(idx, idx + 7000)
+    expect(win).toContain('waitForSessionModelResolution({')
+    expect(win).toContain('if (!resolved) {')
+    expect(win).toContain('gw /model relaunch UNRESOLVED')
     expect(win).toContain('classifyModelSwitchConfirmation({')
     expect(win).toContain('formatModelRelaunchDiagLog')
     expect(win).toContain('if (confirmation != null)')

package/telegram-plugin/tests/ipc-server-validate-operator.test.ts

@@ -13,18 +13,13 @@
 
 import { describe, it, expect } from 'vitest'
 import { validateClientMessage } from '../gateway/ipc-server.js'
+import { OPERATOR_EVENT_KINDS } from '../operator-events.js'
 
-const VALID_KINDS = [
-  'credentials-expired',
-  'credentials-invalid',
-  'credit-exhausted',
-  'quota-exhausted',
-  'rate-limited',
-  'agent-crashed',
-  'agent-restarted-unexpectedly',
-  'unknown-4xx',
-  'unknown-5xx',
-]
+// Drift-proof: iterate the CANONICAL taxonomy the validator now derives its
+// allowlist from, not a hand-copied literal. A kind added to
+// OPERATOR_EVENT_KINDS is automatically covered here; a validator that fails
+// to accept any canonical kind fails this test.
+const VALID_KINDS = OPERATOR_EVENT_KINDS
 
 function base() {
   return {
@@ -43,6 +38,20 @@ describe('validateClientMessage — operator_event', () => {
     }
   })
 
+  // Regression for the 2026-07-30 silent-out-of-credits incident: these three
+  // kinds were added to the OperatorEventKind union but NOT to the gateway IPC
+  // validator's hand-maintained allowlist. The bridge forwarded a
+  // `provider-credit-exhausted` operator_event; the validator rejected it as an
+  // "invalid IPC message shape" and dropped it, so an OpenRouter/LiteLLM 402
+  // credit wall produced NO loud Telegram card. Named explicitly (not just via
+  // the canonical-list loop above) so the failure message points straight at
+  // the incident if the allowlist ever regresses to a hand-maintained literal.
+  it('accepts the operator-actionable kinds forwarded by the bridge over IPC', () => {
+    for (const kind of ['provider-credit-exhausted', 'mcp-dependency-blocked', 'proxy-misconfig']) {
+      expect(validateClientMessage({ ...base(), kind }), kind).toBe(true)
+    }
+  })
+
   it('rejects unknown kinds', () => {
     expect(validateClientMessage({ ...base(), kind: 'something-else' })).toBe(false)
     expect(validateClientMessage({ ...base(), kind: '' })).toBe(false)

package/telegram-plugin/tests/outbound-send-path.test.ts

@@ -379,7 +379,7 @@ describe('outbound-send-path — temporal pass wiring (#3501)', () => {
   it('temporal runs AFTER punctuation/bold and BEFORE scrubVoice (structural pin)', () => {
     const src = readFileSync(new URL('../gateway/outbound-send-path.ts', import.meta.url), 'utf8')
     const start = src.indexOf('export function normalizeOutboundBody(')
-    const boldIdx = src.indexOf('stripExcessBold(normalizePunctuation(text))', start)
+    const boldIdx = src.indexOf('stripExcessBold(normalizePunctuation(text),', start)
     const temporalIdx = src.indexOf('normalizeTemporal(text, tz, nowMs)', start)
     const scrubIdx = src.indexOf('scrubVoice(text)', start)
     expect(boldIdx).toBeGreaterThan(start)

package/telegram-plugin/tests/secret-detect-cross-engine.test.ts

@@ -0,0 +1,263 @@
+/**
+ * DIFFERENTIAL test — run BOTH redaction engines over the same corpus and
+ * compare their output byte for byte.
+ *
+ * Why this file exists (#3982 adversarial review, BLOCKER 1 + MAJOR 4):
+ *
+ * The write-path work shipped two anti-fork mechanisms and neither could
+ * see the fork that actually existed.
+ *
+ *   1. `check-secret-pattern-parity` byte-compares the generated table
+ *      against `patterns.ts`. It proves the pattern SOURCES are equal —
+ *      and the sources WERE equal. Identical source is not identical
+ *      behaviour: Python `re` treats `\b` / `\w` / `\d` and `re.I`
+ *      case-folding as UNICODE-aware for `str` patterns, JavaScript
+ *      `RegExp` without the `u` flag treats them as ASCII-only. Every
+ *      generated rule is `\b`-anchored, so a synthetic `sk-ant-`-shaped
+ *      key written next to Japanese, Chinese, Russian or accented-Latin
+ *      text was masked by TypeScript and stored VERBATIM by Python.
+ *      CJK has no word spacing, so "token abutting a non-ASCII letter"
+ *      is the ordinary case, not an exotic one.
+ *   2. `secret_redaction_vectors.json` pins BEHAVIOUR — but every vector
+ *      it shipped with exercised only the two hand-written imperative
+ *      rules. Zero vectors touched any of the ~60 GENERATED patterns, so
+ *      the whole generated table had no behavioural coverage at all.
+ *
+ * Fixed vectors are still the primary contract (they pin what the output
+ * should BE, which a differential test cannot). This file adds the thing
+ * neither mechanism had: a machine-generated corpus, wide enough to cover
+ * combinations nobody thought to write down, run through both engines
+ * with the outputs compared. A future semantic divergence — a new
+ * shorthand class, an `re.I` folding difference, a `\s` definition
+ * mismatch — fails HERE without anyone having predicted it.
+ *
+ * The Python half runs in a real `python3` subprocess importing the
+ * shipped `lib/secret_redact.py`. That is deliberate: an in-process
+ * re-implementation would be a third engine, and a third engine can fork
+ * too.
+ *
+ * Every credential-shaped literal is synthetic, assembled at runtime, and
+ * never echoed into an assertion message — divergences are reported by
+ * family + neighbour codepoint only.
+ */
+import { describe, it, expect } from "vitest";
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { redact } from "../secret-detect/redact.js";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PY_SCRIPTS_DIR = join(repoRoot, "vendor", "hindsight-memory", "scripts");
+
+/**
+ * Read a JSON array of strings on stdin, write the redacted array on
+ * stdout. Nothing is printed to stdout except the JSON, so a stray
+ * warning cannot be mistaken for output.
+ */
+const PY_DRIVER = [
+  "import json,sys",
+  "sys.path.insert(0, sys.argv[1])",
+  "from lib.secret_redact import redact",
+  "data = json.load(sys.stdin)",
+  "sys.stdout.write(json.dumps([redact(s) for s in data]))",
+].join("\n");
+
+function pythonRedactAll(inputs: string[]): string[] {
+  const out = execFileSync("python3", ["-c", PY_DRIVER, PY_SCRIPTS_DIR], {
+    input: JSON.stringify(inputs),
+    encoding: "utf-8",
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  return JSON.parse(out) as string[];
+}
+
+// ─── Corpus ───────────────────────────────────────────────────────────
+
+/** One synthetic credential per family the generated table claims to cover. */
+const FILL = "AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJ";
+const FAMILIES: Record<string, string> = {
+  anthropic_api_key: "sk-" + "ant-" + "api03-" + FILL,
+  openai_api_key: "sk-" + FILL + "KKKK",
+  github_pat: "ghp_" + FILL.slice(0, 36),
+  aws_access_key: "AKIA" + FILL.slice(0, 16),
+  google_api_key: "AIza" + FILL.slice(0, 35),
+  slack_token: "xoxb-" + "111111111111" + "-" + FILL.slice(0, 24),
+  jwt: "eyJ" + "AAAABBBBCCCC" + "." + "DDDDEEEEFFFF" + "." + "GGGGHHHHIIII",
+  telegram_bot_token: "1234567" + ":" + FILL.slice(0, 30),
+  laravel_sanctum_token: "17|" + FILL,
+  env_key_value: "API_TOKEN=" + "zQ7x" + "Vb2n" + "Kd9w" + "Rt4y",
+  bearer_header: "Authorization: Bearer " + FILL.slice(0, 24),
+  basic_header: "Authorization: Basic " + "YWxpY2U6" + "c3VwZXJzZWNyZXQ=",
+  db_uri: "postgres://appuser:" + "LmN0pQrS7t" + "@db.internal:5432/prod",
+  memorable_password: "wifi password: " + "Fluffy" + "Barnaby" + "1998",
+};
+
+/**
+ * Neighbour characters placed immediately before and after the
+ * credential. The non-ASCII entries are the whole point: they are where
+ * `\b` means different things in the two engines. The whitespace entries
+ * cover the OPPOSITE hazard — JS `\s` is Unicode-aware without `/u`, so
+ * a naive `re.ASCII` port would fork on the SEPARATOR instead.
+ */
+const NEIGHBOURS = [
+  "",
+  " ",
+  "\n",
+  "\t",
+  ".",
+  ",",
+  ")",
+  '"',
+  "'",
+  "-",
+  "_",
+  "/",
+  "é", // é  — accented Latin
+  "к", // к  — Cyrillic
+  "中", // 中 — CJK (no word spacing: the ordinary case)
+  "あ", // あ — Japanese kana
+  "ก", // ก — Thai
+  "ω", // ω — Greek
+  " ", // NBSP        — JS \s matches, ASCII \s does not
+  "　", // ideographic space — same
+  "", // BOM         — same
+  "K", // K (Kelvin sign) — re.I folds this to 'k' in Unicode mode
+  "ſ", // ſ (long s)      — re.I folds this to 's' in Unicode mode
+];
+
+/** Prose that must survive both engines untouched. */
+const NEGATIVES = [
+  "The password is required.",
+  "The password is incorrect.",
+  "Ken confirmed the password is unchanged.",
+  "password: required, minimum twelve characters, mixed case",
+  "POSTGRES_PASSWORD: vault:pg/password",
+  "postgres_password: vault:pg/password",
+  "PASSWORD: ${DB_PASSWORD}",
+  "JWT_SECRET=<generate-with-openssl-rand>",
+  "ANTHROPIC_API_KEY: vault:anthropic/api_key",
+  "const API_KEY = process.env.ANTHROPIC_API_KEY",
+  "--token <value>   the API token",
+  '{"token": "the bearer token to use"}',
+  "I told him the answer was probably Gandalf the Grey.",
+  "他のパスワードは安全です。",
+];
+
+interface Case {
+  text: string;
+  family: string;
+  pre: string;
+  post: string;
+  /**
+   * True when the neighbours leave the rule's `\b` anchors intact, i.e.
+   * when a hit is EXPECTED. An empty neighbour glues the credential to
+   * the surrounding `note`/`end` filler and a `_` is itself a word
+   * character, so `noteAKIA…` is legitimately not a token in EITHER
+   * engine — those cases still have to AGREE, but they must not be
+   * asserted to mask.
+   */
+  anchored: boolean;
+}
+
+const isWordChar = (s: string) => /^[A-Za-z0-9_]$/.test(s);
+
+function buildCorpus(): Case[] {
+  const cases: Case[] = [];
+  for (const [family, value] of Object.entries(FAMILIES)) {
+    for (const pre of NEIGHBOURS) {
+      for (const post of NEIGHBOURS) {
+        // `note` / `end` supply the effective neighbour when the slot is
+        // empty.
+        const anchored =
+          !isWordChar(pre === "" ? "e" : pre) &&
+          !isWordChar(post === "" ? "e" : post);
+        cases.push({
+          text: `note${pre}${value}${post}end`,
+          family,
+          pre,
+          post,
+          anchored,
+        });
+      }
+    }
+  }
+  for (const text of NEGATIVES) {
+    cases.push({ text, family: "negative", pre: "", post: "", anchored: false });
+  }
+  return cases;
+}
+
+/** `U+0041` style, so a failure message never carries secret bytes. */
+function cp(s: string): string {
+  if (s === "") return "none";
+  return `U+${s.codePointAt(0)!.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────
+
+describe("TS and Python redactors agree (differential)", () => {
+  const corpus = buildCorpus();
+  const tsOut = corpus.map((c) => redact(c.text));
+  const pyOut = pythonRedactAll(corpus.map((c) => c.text));
+
+  it("covers every credential family across a wide neighbour matrix", () => {
+    // A shrinking corpus would silently weaken the guarantee.
+    expect(corpus.length).toBeGreaterThanOrEqual(1000);
+    expect(Object.keys(FAMILIES).length).toBeGreaterThanOrEqual(14);
+  });
+
+  it("produces byte-identical output for every case", () => {
+    const divergences = corpus
+      .map((c, i) => ({ c, i }))
+      .filter(({ i }) => tsOut[i] !== pyOut[i])
+      .map(({ c, i }) => ({
+        family: c.family,
+        pre: cp(c.pre),
+        post: cp(c.post),
+        // Booleans only — never the text.
+        tsMasked: tsOut[i]!.includes("[REDACTED"),
+        pyMasked: pyOut[i]!.includes("[REDACTED"),
+      }));
+    expect(divergences).toEqual([]);
+  });
+
+  it("never lets one engine store a credential the other masked", () => {
+    // The asymmetric half of the fork, stated as its own outcome: this is
+    // the assertion that would have gone red on the shipped code.
+    const leaks = corpus
+      .map((c, i) => ({ c, i }))
+      .filter(
+        ({ c, i }) =>
+          c.family !== "negative" &&
+          !pyOut[i]!.includes("[REDACTED") &&
+          tsOut[i]!.includes("[REDACTED"),
+      )
+      .map(({ c }) => ({ family: c.family, pre: cp(c.pre), post: cp(c.post) }));
+    expect(leaks).toEqual([]);
+  });
+
+  it("masks the credential in both engines for every anchored case", () => {
+    const anchored = corpus
+      .map((c, i) => ({ c, i }))
+      .filter(({ c }) => c.anchored);
+    // Sanity: the anchored subset must still be the bulk of the matrix,
+    // otherwise the filter above could silently hollow this out.
+    expect(anchored.length).toBeGreaterThanOrEqual(600);
+    const missed = anchored
+      .filter(
+        ({ i }) =>
+          !(tsOut[i]!.includes("[REDACTED") && pyOut[i]!.includes("[REDACTED")),
+      )
+      .map(({ c }) => ({ family: c.family, pre: cp(c.pre), post: cp(c.post) }));
+    expect(missed).toEqual([]);
+  });
+
+  it("leaves prose untouched in both engines", () => {
+    for (const [i, c] of corpus.entries()) {
+      if (c.family !== "negative") continue;
+      expect(tsOut[i]).toBe(c.text);
+      expect(pyOut[i]).toBe(c.text);
+    }
+  });
+});