@raishin/vanguard-frontier-agentic 3.15.0 → 3.17.0

package/mods/context-burn/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "context-burn",
+  "version": "1.0.0",
+  "description": "Tracks context use per session in a status file and warns at 70% and 90% where the harness reports token use."
+}

package/mods/context-burn/README.md

@@ -0,0 +1,66 @@
+# context-burn
+
+Counts tool calls per session in a small status file. Where the harness reports token use,
+it also warns once at 70% and once at 90% of the context window. It only observes: it never
+blocks a tool and never changes a tool result.
+
+## Reach and declared footprint
+
+**L1 (file writes).** The manifest declares default writes to
+`.claude/context-burn-status/*.json`, `.kiro/context-burn-status/*.json` and
+`.codex/context-burn-status/*.json`, and reads `VANGUARD_CONTEXT_BURN_STATUS_PATH`.
+It declares no subprocess spawns or network egress. This is capability disclosure,
+not isolation; the status-path override can write outside these defaults.
+
+## Status file
+
+Fields (pretty-printed JSON, rewritten in full on every event):
+
+- `session_id`: the session the counts belong to.
+- `tool_call_count`: tool calls seen in that session.
+- `last_updated`: ISO 8601 time of the last event.
+- `threshold_events`: `{ threshold, tokens, window, at }` for each threshold crossed, at most
+  one per threshold per session. Empty where no token data exists.
+
+Default paths, relative to the project:
+
+| Harness | Path |
+|---|---|
+| Claude Code | `.claude/context-burn-status/<session-hash>.json` |
+| Kiro | `.kiro/context-burn-status/<session-hash>.json` |
+| Codex | `.codex/context-burn-status/<session-hash>.json` |
+
+`<session-hash>` is the full lowercase SHA-256 of the UTF-8 `session_id`; raw session IDs
+never appear in the path. Missing or empty Node session IDs use `unsessioned`, so those
+events share one fallback file rather than isolated session state.
+
+`VANGUARD_CONTEXT_BURN_STATUS_PATH` (when non-empty) is an exact path override. Using the
+same override across sessions opts out of default isolation. It can point outside the
+declared `file_writes` globs. Old single-file state is not migrated automatically.
+
+## Per harness
+
+| Harness | Behavior |
+|---|---|
+| Claude Code native | `session.start` resets the file. After each tool call it reads context use from the session, toasts the 70% warning and the 90% critical message once each, and updates the file. |
+| Claude Code classic | Counter only. No token data, so no warnings. |
+| Kiro | Counter only, as above. See `kiro/UNSUPPORTED.md`. |
+| Codex | Counter only, as above. See `codex/UNSUPPORTED.md`. |
+
+Messages: `[context-burn] WARNING: 70% context used (<tokens> / <window> tokens)` and
+`[context-burn] CRITICAL: 90% context used (<tokens> / <window> tokens)`.
+
+## Limitations
+
+- Install either the native or the classic surface, not both: they share
+  the same session status file and would double count.
+- Updates are unlocked read-modify-write operations, so same-session parallel hooks can
+  lose increments. There is no automatic cleanup of old status files.
+- Classic PostToolUse fires only after a tool succeeds, so failed calls are not counted.
+- An unreadable or invalid status file, including malformed threshold event objects or
+  fields, starts a fresh count; the Node hook says so on stderr.
+- The native API was verified against Claude Code 2.1.296. The Node hooks need Node 22+.
+
+## Install
+
+See `mods/README.md`.

package/mods/context-burn/bin/hook.mjs

@@ -0,0 +1,38 @@
+// Command hook for classic Claude Code, Kiro and Codex: counter only, no token data.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { defaultStatusPath, freshStatus, parseStatus, recordCall, serializeStatus } from '../lib/core.mjs'
+import { projectPath, runHook } from '../lib/runtime.mjs'
+
+const target = async (ctx, sessionId) =>
+  projectPath(process.env.VANGUARD_CONTEXT_BURN_STATUS_PATH || await defaultStatusPath(ctx.harness, sessionId), ctx.harness, import.meta.dirname)
+const sessionOf = (p) => (typeof p.session_id === 'string' && p.session_id !== '' ? p.session_id : 'unsessioned')
+
+function save(file, status) {
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, serializeStatus(status))
+}
+
+const handlers = {
+  async SessionStart(payload, ctx) {
+    const sessionId = sessionOf(payload)
+    save(await target(ctx, sessionId), freshStatus(sessionId, new Date().toISOString()))
+  },
+  // ponytail: parallel hooks can lose an increment (read-modify-write, no lock); add the
+  // audit-trail lock if exact counts matter.
+  async PostToolUse(payload, ctx) {
+    const sessionId = sessionOf(payload)
+    const file = await target(ctx, sessionId)
+    const log = []
+    let prev
+    try {
+      prev = parseStatus(readFileSync(file, 'utf8'))
+    } catch (err) {
+      if (err?.code !== 'ENOENT') log.push(`[context-burn] status file unreadable; starting a fresh count: ${err.message}`)
+    }
+    save(file, recordCall(prev, sessionId, new Date().toISOString(), undefined).status)
+    return log.length ? { decision: 'allow', log } : undefined
+  },
+}
+
+process.exitCode = await runHook({ name: 'context-burn', handlers })

package/mods/context-burn/claude-code/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Context Burn on Claude Code
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `classic`: Classic hooks receive no token counts, so only the tool-call counter is kept and no threshold warnings are emitted; PostToolUse fires only after a tool succeeds, so failed calls are not counted.

package/mods/context-burn/claude-code/settings.hooks.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/context-burn/bin/hook.mjs\" --harness claude-code --event PostToolUse"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/context-burn/bin/hook.mjs\" --harness claude-code --event SessionStart"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mods/context-burn/codex/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Context Burn on Codex
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `PostToolUse`: Codex hooks receive no token counts; only the tool-call counter is kept and no threshold warnings are emitted.

package/mods/context-burn/codex/hooks.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .codex/vanguard-mods/context-burn/bin/hook.mjs --harness codex --event PostToolUse"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .codex/vanguard-mods/context-burn/bin/hook.mjs --harness codex --event SessionStart"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mods/context-burn/hooks/hooks.json

@@ -0,0 +1,5 @@
+{
+  "modules": [
+    "./register.ts"
+  ]
+}

package/mods/context-burn/hooks/register.test.ts

@@ -0,0 +1,151 @@
+import { test, expect, mock } from 'claude-code/testing'
+
+const ENV = 'VANGUARD_CONTEXT_BURN_STATUS_PATH'
+const DEFAULT = '.claude/context-burn-status/e8bc163c82eee18733288c7d4ac636db3a6deb013ef2d37b68322be20edc45cc.json'
+const RESULT = { result: { stdout: 'x', stderr: '', interrupted: false } }
+const call = { tool: 'Bash', command: 'echo x' }
+const status = (over: object = {}) => ({
+  session_id: 's1',
+  tool_call_count: 4,
+  last_updated: '1970-01-01T00:00:00.000Z',
+  threshold_events: [],
+  ...over,
+})
+
+// Wires every `$` noun a tool.call touches. Returns what the mod wrote and toasted.
+function rig(on: any, o: { env?: object; prev?: object | null; readFails?: boolean; writeFails?: boolean; context?: object; session?: { id: string }; files?: Map<string, string> } = {}) {
+  const writes: { path: string; text: string }[] = []
+  const toasts: string[] = []
+  mock.env(on, o.env ?? {})
+  mock.clock(on, { now: 0 })
+  on('session.id', () => ({ value: o.session?.id ?? 's1' }))
+  on('session.usage', () => ({
+    value: { startedAt: 0, context: o.context ?? { window: 10000 }, rateLimits: [] },
+  }))
+  on('fs.read', ($: any, e: any) => {
+    if (o.files) {
+      if (!o.files.has(e.path)) throw new Error('ENOENT')
+      return { value: o.files.get(e.path) }
+    }
+    if (o.readFails || !o.prev) throw new Error('ENOENT')
+    return { value: JSON.stringify(o.prev) }
+  })
+  on('fs.write', ($: any, e: any) => {
+    if (o.writeFails) throw new Error('disk full')
+    writes.push({ path: e.path, text: e.text })
+    o.files?.set(e.path, e.text)
+    return { value: undefined }
+  })
+  on('ui.toast', ($: any, e: any) => {
+    toasts.push(e.text)
+    return { value: undefined }
+  })
+  on('tool.call', () => RESULT)
+  on('session.start', ($: any, e: any) => ({ cwd: e.cwd }))
+  return { writes, toasts, last: () => JSON.parse(writes[writes.length - 1].text) }
+}
+
+test('session.start writes a fresh status', async ($, on) => {
+  const r = rig(on)
+  await $.session.start({ cwd: '/w', surface: 'terminal', isInteractive: true })
+  expect(r.writes[0].path.endsWith(DEFAULT)).toBe(true)
+  expect(r.last()).toEqual({ session_id: 's1', tool_call_count: 0, last_updated: '1970-01-01T00:00:00.000Z', threshold_events: [] })
+})
+
+test('session.start honors the env override', async ($, on) => {
+  const r = rig(on, { env: { [ENV]: 'custom/out.json' } })
+  await $.session.start({ cwd: '/w', surface: 'terminal', isInteractive: true })
+  expect(r.writes[0].path.endsWith('custom/out.json')).toBe(true)
+})
+
+test('tool.call passes the result through and increments the count', async ($, on) => {
+  const r = rig(on, { prev: status() })
+  expect(await $.tool.call(call)).toEqual(RESULT)
+  expect(r.last().tool_call_count).toBe(5)
+})
+
+test('a status for another session restarts at 1', async ($, on) => {
+  const r = rig(on, { prev: status({ session_id: 'other' }) })
+  await $.tool.call(call)
+  expect(r.last().session_id).toBe('s1')
+  expect(r.last().tool_call_count).toBe(1)
+})
+
+test('75 percent toasts one warning and records the event', async ($, on) => {
+  const r = rig(on, { prev: status(), context: { tokens: 7500, window: 10000, percent: 75 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual(['[context-burn] WARNING: 70% context used (7500 / 10000 tokens)'])
+  expect(r.last().threshold_events.length).toBe(1)
+  expect(r.last().threshold_events[0].threshold).toBe(70)
+})
+
+test('an already recorded 70 event does not toast again', async ($, on) => {
+  const prev = status({ threshold_events: [{ threshold: 70, tokens: 7500, window: 10000, at: 'x' }] })
+  const r = rig(on, { prev, context: { tokens: 7600, window: 10000, percent: 76 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual([])
+})
+
+test('95 percent toasts warning then critical', async ($, on) => {
+  const r = rig(on, { prev: status(), context: { tokens: 9500, window: 10000, percent: 95 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual([
+    '[context-burn] WARNING: 70% context used (9500 / 10000 tokens)',
+    '[context-burn] CRITICAL: 90% context used (9500 / 10000 tokens)',
+  ])
+})
+
+test('percent without tokens computes and rounds tokens', async ($, on) => {
+  const r = rig(on, { prev: status(), context: { window: 3333, percent: 71.5 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual(['[context-burn] WARNING: 70% context used (2383 / 3333 tokens)'])
+})
+
+test('no token data means no toast but the count still rises', async ($, on) => {
+  const r = rig(on, { prev: status(), context: { window: 10000 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual([])
+  expect(r.last().tool_call_count).toBe(5)
+})
+
+test('a failing read starts a fresh count', async ($, on) => {
+  const r = rig(on, { readFails: true })
+  await $.tool.call(call)
+  expect(r.last().tool_call_count).toBe(1)
+})
+
+test('malformed threshold events restart counting and still toast the threshold', async ($, on) => {
+  const r = rig(on, { prev: status({ threshold_events: [null] }), context: { tokens: 7500, window: 10000 } })
+  expect(await $.tool.call(call)).toEqual(RESULT)
+  expect(r.last().tool_call_count).toBe(1)
+  expect(r.last().threshold_events.length).toBe(1)
+  expect(r.toasts.length).toBe(1)
+})
+
+test('interleaved sessions retain independent counts and warn only once per session', async ($, on) => {
+  const session = { id: '../first' }
+  const files = new Map<string, string>()
+  const r = rig(on, { session, files, context: { tokens: 7500, window: 10000 } })
+  for (const id of ['../first', '..\\second']) {
+    session.id = id
+    await $.session.start({ cwd: '/w', surface: 'terminal', isInteractive: true })
+    expect(await $.tool.call(call)).toEqual(RESULT)
+  }
+  for (const id of ['../first', '..\\second']) {
+    session.id = id
+    expect(await $.tool.call(call)).toEqual(RESULT)
+  }
+  expect(files.size).toBe(2)
+  for (const [path, text] of files) {
+    expect(/\/context-burn-status\/[a-f0-9]{64}\.json$/.test(path)).toBe(true)
+    const saved = JSON.parse(text)
+    expect(saved.tool_call_count).toBe(2)
+    expect(saved.threshold_events.length).toBe(1)
+  }
+  expect(r.toasts.length).toBe(2)
+})
+
+test('a failing write still returns the tool result', async ($, on) => {
+  rig(on, { prev: status(), writeFails: true })
+  expect(await $.tool.call(call)).toEqual(RESULT)
+})

package/mods/context-burn/hooks/register.ts

@@ -0,0 +1,35 @@
+import type { Register } from 'claude-code'
+import { defaultStatusPath, freshStatus, parseStatus, recordCall, serializeStatus } from '../lib/core.mjs'
+
+async function statusPath($: any, sessionId: string): Promise<string> {
+  return (await $.env.get('VANGUARD_CONTEXT_BURN_STATUS_PATH')) || await defaultStatusPath('claude-code', sessionId)
+}
+
+export const register: Register = (on) => {
+  // A new session resets the file; a failure must never block startup.
+  on('session.start', async ($, e, next) => {
+    const at = new Date(await $.clock.now()).toISOString()
+    const sessionId = await $.session.id()
+    await $.fs.write(await statusPath($, sessionId), serializeStatus(freshStatus(sessionId, at)))
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  // Observer: the tool runs first and its result is returned untouched, whatever happens here.
+  on('tool.call', async ($, e, next) => {
+    const r = await next(e)
+    const sessionId = await $.session.id()
+    const path = await statusPath($, sessionId)
+    let prev
+    try {
+      prev = parseStatus(await $.fs.read(path))
+    } catch {
+      prev = undefined
+    }
+    const at = new Date(await $.clock.now()).toISOString()
+    const { context } = await $.session.usage()
+    const { status, messages } = recordCall(prev, sessionId, at, context)
+    for (const m of messages) await $.ui.toast(m)
+    await $.fs.write(path, serializeStatus(status))
+    return r
+  }).catch(($, e, next) => next(e))
+}

package/mods/context-burn/kiro/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Context Burn on Kiro
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `PostToolUse`: Kiro hooks receive no token counts; only the tool-call counter is kept and no threshold warnings are emitted.

package/mods/context-burn/kiro/context-burn-post-tool-use-hook.json

@@ -0,0 +1,14 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "context-burn:PostToolUse",
+      "description": "Tracks context use per session in a status file and warns at 70% and 90% where the harness reports token use.",
+      "trigger": "PostToolUse",
+      "action": {
+        "type": "command",
+        "command": "node .kiro/vanguard-mods/context-burn/bin/hook.mjs --harness kiro --event PostToolUse"
+      }
+    }
+  ]
+}

package/mods/context-burn/kiro/context-burn-session-start-hook.json

@@ -0,0 +1,14 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "context-burn:SessionStart",
+      "description": "Tracks context use per session in a status file and warns at 70% and 90% where the harness reports token use.",
+      "trigger": "SessionStart",
+      "action": {
+        "type": "command",
+        "command": "node .kiro/vanguard-mods/context-burn/bin/hook.mjs --harness kiro --event SessionStart"
+      }
+    }
+  ]
+}

package/mods/context-burn/lib/common.mjs

@@ -0,0 +1,213 @@
+// Shared helpers for the mods under mods/. scripts/generate-mods.mjs copies this file
+// byte-for-byte to mods/<id>/lib/common.mjs, so edit it here and run `npm run mods:write`.
+//
+// Pure on purpose: no imports, no environment, no I/O. Claude Code's native mod runtime
+// imports it and has no Node, and every harness must reach the same verdict on the same
+// input. Regexes compile without the `u` flag so Node and Python `re.ASCII`
+// (tests/validate-mods.py) read them the same way.
+
+export const LIMITS = Object.freeze({
+  // A redaction that still changes after this many passes is withheld as a whole.
+  maxPasses: 8,
+  // A guard candidate longer than this is not evaluated and counts as a hit.
+  maxCandidateChars: 65536,
+  // Guard candidates are not evaluated past this combined length; the call counts as a hit.
+  maxTotalChars: 262144,
+  // Only the tail of a leaf's context (key or previous sibling) is prefixed to it.
+  maxContextChars: 256,
+})
+
+const MARKER_PREFIX = '[REDACTED:'
+export const OVERFLOW_MARKER = '[REDACTED:overflow]'
+const OVERFLOW_HIT = Object.freeze({ id: 'overflow', name: 'redaction did not converge' })
+export const TOO_LARGE_HIT = Object.freeze({ id: 'too-large', name: 'input too large to evaluate' })
+
+const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const PATTERN_KEYS = new Set(['id', 'name', 'description', 'regex', 'flags', 'context', 'severity', 'agents'])
+const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s !== '')
+
+// Parser diagnostics can quote credential-bearing data; never expose it in hook logs.
+export function parseJson(text, source) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`${source}: invalid JSON`)
+  }
+}
+
+// Validates a patterns.json-shaped list and compiles it. Throws on anything malformed so a
+// bad extension file fails closed in the caller instead of silently matching nothing.
+export function compilePatterns(list, source = 'patterns') {
+  if (!Array.isArray(list)) throw new Error(`${source}: expected an array of patterns`)
+  const seen = new Set()
+  return list.map((p, i) => {
+    const where = `${source}[${i}]`
+    if (p === null || typeof p !== 'object' || Array.isArray(p)) throw new Error(`${where}: expected an object`)
+    for (const k of Object.keys(p)) if (!PATTERN_KEYS.has(k)) throw new Error(`${where}: unknown key ${k}`)
+    if (typeof p.id !== 'string' || !ID_RE.test(p.id)) throw new Error(`${where}: id must be kebab-case`)
+    if (seen.has(p.id)) throw new Error(`${where}: duplicate id ${p.id}`)
+    seen.add(p.id)
+    if (typeof p.name !== 'string' || p.name === '') throw new Error(`${where}: name must be a non-empty string`)
+    if (typeof p.regex !== 'string' || p.regex === '') throw new Error(`${where}: regex must be a non-empty string`)
+    if (p.flags !== '' && p.flags !== 'i') throw new Error(`${where}: flags must be "" or "i"`)
+    if (!isStringArray(p.context) || p.context.length === 0) throw new Error(`${where}: context must be a non-empty string array`)
+    for (const k of ['description', 'severity']) {
+      if (p[k] !== undefined && typeof p[k] !== 'string') throw new Error(`${where}: ${k} must be a string`)
+    }
+    if (p.agents !== undefined && !isStringArray(p.agents)) throw new Error(`${where}: agents must be a string array`)
+    let rx, rxg
+    try {
+      rx = new RegExp(p.regex, p.flags)
+      rxg = new RegExp(p.regex, 'g' + p.flags)
+    } catch {
+      throw new Error(`${where}: regex does not compile`)
+    }
+    return Object.freeze({
+      id: p.id,
+      name: p.name,
+      severity: p.severity,
+      context: Object.freeze([...p.context]),
+      agents: p.agents ? Object.freeze([...p.agents]) : undefined,
+      rx,
+      rxg,
+      marker: `${MARKER_PREFIX}${p.id}]`,
+    })
+  })
+}
+
+// Every string value (not key) in depth-first order. The order follows the input, so the
+// same payload always yields the same list.
+export function stringLeaves(value, out = []) {
+  if (typeof value === 'string') out.push(value)
+  else if (Array.isArray(value)) for (const v of value) stringLeaves(v, out)
+  else if (value !== null && typeof value === 'object') for (const v of Object.values(value)) stringLeaves(v, out)
+  return out
+}
+
+// Guard candidates: every string leaf, plus every all-string array joined with spaces so
+// an argv-style command (["rm", "-rf", "/"]) reads like the shell line it runs.
+export function candidates(value) {
+  const out = stringLeaves(value)
+  const joinArrays = (v) => {
+    if (Array.isArray(v)) {
+      if (v.length > 1 && v.every((s) => typeof s === 'string')) out.push(v.join(' '))
+      v.forEach(joinArrays)
+    } else if (v !== null && typeof v === 'object') {
+      Object.values(v).forEach(joinArrays)
+    }
+  }
+  joinArrays(value)
+  return out
+}
+
+// The patterns tagged with `context` that match any text, in catalog order. Oversized input
+// is not evaluated (regex cost is unbounded there) and reports TOO_LARGE_HIT instead.
+export function matchPatterns(patterns, texts, context) {
+  let total = 0
+  for (const t of texts) {
+    total += t.length
+    if (t.length > LIMITS.maxCandidateChars || total > LIMITS.maxTotalChars) return [TOO_LARGE_HIT]
+  }
+  return patterns.filter((p) => p.context.includes(context) && texts.some((t) => p.rx.test(t)))
+}
+
+// One pattern pass after another until the text stops changing. Each pass can expose a new
+// match (password-in-url can swallow an earlier marker), so a single pass is not enough.
+function fixedPoint(text, patterns, hits) {
+  let x = text
+  for (let pass = 0; pass <= LIMITS.maxPasses; pass++) {
+    let y = x
+    for (const p of patterns) {
+      y = y.replace(p.rxg, (m) => {
+        if (m === '') return m
+        hits.add(p)
+        return p.marker
+      })
+    }
+    if (y === x) return x
+    x = y
+  }
+  hits.add(OVERFLOW_HIT)
+  return OVERFLOW_MARKER
+}
+
+// Redacts `s` with `ctx` in front so a secret split across a key and its value, or across
+// argv elements ("Bearer", "<token>"), still matches; then strips the context back off.
+function redactLeaf(s, ctx, patterns, hits) {
+  if (ctx === '') return fixedPoint(s, patterns, hits)
+  const pre = ctx.slice(-LIMITS.maxContextChars) + ' '
+  const y = fixedPoint(pre + s, patterns, hits)
+  if (y === OVERFLOW_MARKER) return y
+  const r = fixedPoint(pre, patterns, new Set())
+  if (y.startsWith(r)) return fixedPoint(y.slice(r.length), patterns, hits)
+  // A match spans the boundary: keep from the marker that covers it. Slicing changes
+  // anchors and boundaries, so also check the standalone leaf after contextual matching.
+  let d = 0
+  while (d < r.length && y[d] === r[d]) d++
+  const i = y.lastIndexOf(MARKER_PREFIX, d)
+  return fixedPoint(i >= 0 ? y.slice(i) : y, patterns, hits)
+}
+
+function walk(v, ctx, patterns, hits) {
+  if (typeof v === 'string') {
+    const local = new Set()
+    const out = redactLeaf(v, ctx, patterns, local)
+    if (out !== v) for (const h of local) hits.add(h)
+    return out
+  }
+  if (Array.isArray(v)) {
+    let prev = null
+    return v.map((el) => {
+      const out = walk(el, typeof prev === 'string' ? prev : ctx, patterns, hits)
+      prev = el
+      return out
+    })
+  }
+  if (v !== null && typeof v === 'object') {
+    const named = typeof v.name === 'string' ? v.name : typeof v.key === 'string' ? v.key : null
+    // fromEntries, not assignment: `out[k] = v` would drop an own "__proto__" key.
+    return Object.fromEntries(
+      Object.entries(v).map(([k, x]) => [
+        walk(k, '', patterns, hits),
+        walk(x, k === 'value' && named !== null ? named : k, patterns, hits),
+      ]),
+    )
+  }
+  return v
+}
+
+// Returns a copy of `value` with every match replaced by `[REDACTED:<id>]`, plus the
+// patterns that fired (catalog order, unique). Keys are redacted too; two keys that redact
+// to the same marker collapse into one, which loses data but never leaks it.
+export function redactValue(value, patterns) {
+  const hits = new Set()
+  const out = walk(value, '', patterns, hits)
+  const order = [...patterns, OVERFLOW_HIT]
+  return { value: out, hits: order.filter((p) => hits.has(p)) }
+}
+
+// Same shape as `value`, every string replaced by `text`. The fallback when redaction
+// itself failed: withhold everything rather than pass anything through.
+export function maskValue(value, text) {
+  if (typeof value === 'string') return text
+  if (Array.isArray(value)) return value.map((v) => maskValue(v, text))
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskValue(v, text)]))
+  }
+  return value
+}
+
+// JSON with object keys sorted at every level, so equal values hash equally.
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return '[' + value.map((v) => (v === undefined ? 'null' : canonicalJson(v))).join(',') + ']'
+  if (value !== null && typeof value === 'object') {
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}'
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+export async function sha256Hex(text) {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('')
+}