dsh-context-compression-improved 0.4.0-beta.1 → 0.5.0

package/packages/selector/tests/runtime/tokenpilot/pruner-review.spec.ts

@@ -181,7 +181,6 @@ function reviewSession(ctx: Context, id: string, oldText: string): {
   session: Session
   oldResultSeq: number
 } {
-  const pruner = ctx.toolResultPruner
   const session = Session.create(SessionId(id))
   const old = appendToolTurn(session, 1, oldText, true)
   appendToolTurn(session, 2, 'newest protected result', true)
@@ -311,3 +310,73 @@ describe('tokenpilot review pipeline (host integration)', () => {
     expect(ctx.toolResultPruner.listReviewProposals(session)).toHaveLength(0)
   })
 })
+
+/** Fresh-stage triage must NOT charge the tail-refill penalty: the fresh
+ *  candidate has never been served, so shaping it causes no cache break.
+ *  Fixture keeps historyKeepRecentTokens at the production-like 64,000 so
+ *  history pricing (penalty 57,600) would drop the batch outright — the
+ *  fresh stage must still land it. */
+describe('tokenpilot review pipeline (fresh-stage exemption)', () => {
+  async function freshReviewSetup(ctx: Context): Promise<void> {
+    await ctx.plugin(TestSettings).await()
+    await ctx.plugin(SelectorHost).await()
+    await ctx.settings.update(nsBrand(CONTEXT_COMPRESSION_SETTINGS_NAMESPACE), {
+      profile: 'tokenpilot-inspired',
+      presetOptions: { reviewMode: true, reviewHighImpactTokens: 1_000_000 },
+    })
+    await ctx.plugin(ToolResultPruner, {
+      profile: 'tokenpilot-inspired',
+      freshTriggerTokens: 200,
+      freshTargetTokens: 100,
+      aggregateTriggerTokens: 1_000_000,
+      aggregateTargetTokens: 900_000,
+      historyTriggerTokens: 400,
+      historyKeepRecentToolCalls: 0,
+      historyKeepRecentTokens: 64_000,
+      historyMinReclaimTokens: 1,
+    }).await()
+  }
+
+  function freshSession(ctx: Context, id: string, text: string): Session {
+    const session = Session.create(SessionId(id))
+    appendToolTurn(session, 1, text, true)
+    const total = measureForCompaction(ctx, session).totalTokens
+    session.append('request/context', {
+      provider: 'deepseek',
+      model: MODEL,
+      contextWindow: Math.floor(total / 0.6),
+    })
+    // Fresh landing publishes a surface replacement, which requires an open turn.
+    session.append('turn/start', { turn: 2 })
+    return session
+  }
+
+  it('lands a fresh batch under review mode instead of dropping it', async () => {
+    const ctx = await runtimeContext()
+    await freshReviewSetup(ctx)
+    const audit = captureAudit(ctx)
+    const session = freshSession(ctx, 'fresh-review-exempt', 'fresh reviewable evidence '.repeat(400))
+
+    const result = ctx.toolResultPruner.pruneSession(session, { stage: 'fresh', freshTurn: 1, freshStep: 1 })
+
+    // Without the exemption the 57,600-token refill penalty prices this batch
+    // into the drop band (payback > 3 with Ŝ unknown) and nothing lands.
+    expect(result.pruned).toHaveLength(1)
+    expect(rewrites(audit.records()).some(entry => entry.component === 'fresh')).toBe(true)
+    expect(reviewEvents(audit.records()).filter(entry => entry.event === 'enqueue')).toHaveLength(0)
+  })
+
+  it('keeps the history batch priced with the refill penalty', async () => {
+    const ctx = await runtimeContext()
+    await freshReviewSetup(ctx)
+    const audit = captureAudit(ctx)
+    const { session } = reviewSession(ctx, 'history-review-priced', 'old reviewable evidence '.repeat(600))
+
+    const result = ctx.toolResultPruner.pruneSession(session, { stage: 'pressure' })
+
+    // History content was already served: the refill penalty is real, Ŝ is
+    // unknown, payback > 3 → drop band → nothing lands and nothing queues.
+    expect(result.pruned).toHaveLength(0)
+    expect(reviewEvents(audit.records()).filter(entry => entry.event === 'enqueue')).toHaveLength(0)
+  })
+})

package/packages/selector/tests/runtime/tokenpilot/read-state.spec.ts

@@ -55,4 +55,28 @@ describe('tokenpilot read-state helpers', () => {
     expect(clusterOmittedLines('fine', 1)).toBe('1 lines omitted (1 info)')
     expect(clusterOmittedLines('fine', 0)).toBeUndefined()
   })
+
+  // R8 census: a document's dropped content is described by its section
+  // headings, not by an error/warn/info histogram that is always 0/0/N.
+  it('lists section headings for document content instead of the info census', () => {
+    const doc = [
+      '# User Guide',
+      'Intro paragraph.',
+      '## Installation',
+      'Run the installer.',
+      '## Configuration',
+      'Set the flags.',
+      '## Troubleshooting',
+      'Check the logs.',
+      '## Reference',
+      'Appendix material.',
+    ].join('\n')
+    const census = clusterOmittedLines(doc, 40)
+    expect(census).toBe(
+      '40 lines omitted (sections: User Guide · Installation · Configuration · Troubleshooting · Reference)',
+    )
+    for (const heading of ['Installation', 'Troubleshooting', 'Reference']) {
+      expect(census).toContain(heading)
+    }
+  })
 })

package/packages/selector/tests/runtime/toolclass.spec.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest'
+import { classifyToolSource } from '../../src/runtime/toolclass.ts'
+import { extractCommand, reduceFreshToolResult } from '../../src/runtime/reducers.ts'
+
+/** Checklist C1–C15 against the FOUR-class narrowing (tasks v2 G4): web/memory
+ *  search and research/sql names fall to generic, glob is path-listing, only
+ *  grep/rg/ripgrep are search, and the content fallback never overrides a
+ *  whitelist hit. */
+describe('classifyToolSource — name whitelist', () => {
+  it('keeps web_search out of search (C1)', () => {
+    expect(classifyToolSource('web_search', '')).toBe('generic')
+  })
+
+  it('routes glob to path-listing (C2)', () => {
+    expect(classifyToolSource('glob', '')).toBe('path-listing')
+  })
+
+  it('keeps memory/conversation search generic — four classes only (C3, v2)', () => {
+    expect(classifyToolSource('memory_search', '')).toBe('generic')
+    expect(classifyToolSource('conversation_search', '')).toBe('generic')
+  })
+
+  it('routes grep/rg/ripgrep to search (C4)', () => {
+    expect(classifyToolSource('grep', '')).toBe('search')
+    expect(classifyToolSource('rg', '')).toBe('search')
+    expect(classifyToolSource('ripgrep', '')).toBe('search')
+    expect(classifyToolSource('grep_search', '')).toBe('search')
+  })
+
+  it('routes shell/bash/pwsh/terminal to shell-exec (C5)', () => {
+    expect(classifyToolSource('shell', '')).toBe('shell')
+    expect(classifyToolSource('bash', '')).toBe('shell')
+    expect(classifyToolSource('pwsh', '')).toBe('shell')
+    expect(classifyToolSource('powershell', '')).toBe('shell')
+    expect(classifyToolSource('terminal', '')).toBe('shell')
+  })
+
+  it('routes read/read_file/cat/view/open_file to file-read (C6)', () => {
+    expect(classifyToolSource('read', '')).toBe('read')
+    expect(classifyToolSource('read_file', '')).toBe('read')
+    expect(classifyToolSource('cat', '')).toBe('read')
+    expect(classifyToolSource('view', '')).toBe('read')
+    expect(classifyToolSource('view_file', '')).toBe('read')
+    expect(classifyToolSource('open_file', '')).toBe('read')
+  })
+
+  it('is generic for mutation tools — no file-mutate class in the four-class set (C7, v2)', () => {
+    expect(classifyToolSource('write', '')).toBe('generic')
+    expect(classifyToolSource('edit', '')).toBe('generic')
+    expect(classifyToolSource('apply_patch', '')).toBe('generic')
+  })
+
+  it('returns generic for any name with an mcp token, before content evidence (C8)', () => {
+    expect(classifyToolSource('mcp__server__grep', '', 'src/a.ts:1: x')).toBe('generic')
+    expect(classifyToolSource('mcp-grep', '', 'src/a.ts:1: x')).toBe('generic')
+  })
+
+  it('never misroutes `research` into a search class (C9)', () => {
+    expect(classifyToolSource('research', '')).toBe('generic')
+    expect(classifyToolSource('deep_research', '')).toBe('generic')
+  })
+
+  it('never misroutes `execute_sql` into shell-exec (C10)', () => {
+    expect(classifyToolSource('execute_sql', '')).toBe('generic')
+  })
+
+  it('matches tokens exactly — no substring bleed (task_11)', () => {
+    expect(classifyToolSource('advanced_search', '')).toBe('generic')
+    expect(classifyToolSource('free_search_test', '')).toBe('generic')
+    expect(classifyToolSource('theme_global', '')).toBe('generic')
+  })
+})
+
+describe('classifyToolSource — command and content fallback', () => {
+  it('routes rg/grep commands to search even from an unknown tool name', () => {
+    expect(classifyToolSource('run_tool', 'rg pattern src/')).toBe('search')
+    expect(classifyToolSource('run_tool', 'grep -n TODO .')).toBe('search')
+  })
+
+  it('routes find/fd/ls/tree commands to path-listing, not search', () => {
+    expect(classifyToolSource('run_tool', 'find . -name "*.ts"')).toBe('path-listing')
+    expect(classifyToolSource('run_tool', 'fd config')).toBe('path-listing')
+  })
+
+  it('falls back to search on a path:line:content line (C13)', () => {
+    expect(classifyToolSource('unknown_tool', '', 'src/index.ts:12: export const x')).toBe('search')
+  })
+
+  it('does not let prose colons or URLs masquerade as grep output (C13 guard)', () => {
+    expect(classifyToolSource('unknown_tool', '', 'Note: 2024 - something happened')).toBe('generic')
+    expect(classifyToolSource('unknown_tool', '', 'see https://host.example:8080 - login')).toBe('generic')
+  })
+
+  it('falls back to path-listing when ≥80% of lines are pure paths (C14)', () => {
+    const listing = ['src/index.ts', 'src/main.ts', 'src/util.ts', 'README.md'].join('\n')
+    expect(classifyToolSource('unknown_tool', '', listing)).toBe('path-listing')
+  })
+
+  it('never overrides a whitelist hit with content evidence (C15)', () => {
+    expect(classifyToolSource('bash', '', 'src/index.ts:12: export const x')).toBe('shell')
+    expect(classifyToolSource('glob', '', 'src/index.ts:12: export const x')).toBe('path-listing')
+    expect(classifyToolSource('read', '', 'src/index.ts')).toBe('read')
+  })
+})
+
+describe('extractCommand — input key removed (C11/C12)', () => {
+  it('returns empty for an input-only payload (C11)', () => {
+    expect(extractCommand('{"input":"arbitrary model text"}')).toBe('')
+  })
+
+  it('still reads the command key (C12)', () => {
+    expect(extractCommand('{"command":"npm test"}')).toBe('npm test')
+  })
+
+  it('still reads cmd/script fallbacks', () => {
+    expect(extractCommand('{"cmd":"pnpm build"}')).toBe('pnpm build')
+    expect(extractCommand('{"script":"ls"}')).toBe('ls')
+  })
+})
+
+/** End-to-end dispatch guard for the misroute fixes: a `glob` result and an
+ *  `execute_sql` result must not land on the search reducer even when they
+ *  exceed every form gate. */
+describe('toolclass dispatch integration', () => {
+  const paths = Array.from({ length: 200 }, (_, index) => `pkg/dir${String(index)}/file${String(index)}.ts`)
+  const globText = paths.join('\n')
+
+  it('routes a large glob result away from search-salience (task_11)', () => {
+    const output = reduceFreshToolResult({
+      toolName: 'glob',
+      argumentsText: '{}',
+      text: globText,
+      budgetChars: 4_000,
+      sourceRef: 'session://probe/glob',
+      isError: false,
+    })
+    expect(output).not.toBeNull()
+    expect(output!.reducer).not.toBe('search-by-file')
+    expect(output!.reducer).not.toBe('search-salience')
+  })
+
+  it('routes a large mcp web_search result away from the search reducer (C1/AD1)', () => {
+    const web = Array.from({ length: 60 }, (_, index) =>
+      `- [Result ${String(index)}](https://example.com/${String(index)}) — a summary paragraph of the ${String(index)}th hit.`).join('\n')
+    const output = reduceFreshToolResult({
+      toolName: 'mcp__web__web_search',
+      argumentsText: '{}',
+      text: web,
+      budgetChars: 2_000,
+      sourceRef: 'session://probe/web',
+      isError: false,
+    })
+    expect(output).not.toBeNull()
+    expect(output!.reducer).not.toBe('search-by-file')
+  })
+})

package/scripts/toolclass-corpus-replay.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * toolclass-corpus-replay.mjs — 真实日志离线复算(task_5 / G3)。
+ *
+ * 对 `~/.dsh/sessions/**\/session*.jsonl.zstd` 多帧 zstd 会话日志:
+ *   扫魔数 28 B5 2F FD 逐帧解压(帧去重:并发写入会落重复帧)
+ *   → 配对 tool/call ↔ tool/result(callId)
+ *   → 直调 reduceFreshToolResult(内部无门槛,门槛在 planFresh;本脚本自带
+ *     budgetChars 模拟,不测端到端 —— 必读①:验收必须在 reducer 层)
+ *   → 输出 ToolClass 分发矩阵 / reducer 命中率 / 压缩率 / 误路由对照 /
+ *     freshTriggerTokens 敏感性表。
+ *
+ * 用法:
+ *   node scripts/toolclass-corpus-replay.mjs [--dir <sessionsDir>] [--limit <N>]
+ *        [--session <substring>] [--min-chars <N>] [--budget-ratio <f>] [--out <report.md>]
+ *
+ * 依赖:先 `pnpm build` 生成 packages/selector/lib/pruner.js。
+ * 样本偏差声明(必读⑨/RK-5):--limit 取的是体积最大的会话(偏长会话),
+ * 结论不得外推到全体会话;报告须标注会话数/样本数/时间范围。
+ * ⚠️ 口径标注:自 7a1972a(字符基准闸门)起,运行时决策按字符(characters)执行,
+ * 本脚本输出的压缩率/预算均为 reducer 层字符口径;tokens 字段仅为遥测派生(chars/4.0),
+ * 不得当作运行时决策依据。
+ * ⚠️ --min-chars 默认 14000 只是**本脚本的样本过滤下限**,与运行时
+ * `READ_TOC_MIN_CHARS`(reducers.ts)数值撞值但**毫无派生关系**:运行时的
+ * fresh 门槛是 freshTriggerTokens(8192 tok ≈ 29.5k 字符),恒高于 14k 字符,
+ * 本脚本过滤值从不参与运行时行为(findings §16)。
+ */
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, relative } from 'node:path'
+import { zstdDecompressSync } from 'node:zlib'
+
+const REPO_ROOT = join(import.meta.dirname, '..')
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
+
+function parseArgs(argv) {
+  const args = {
+    dir: join(homedir(), '.dsh', 'sessions'),
+    limit: 20,
+    session: '',
+    minChars: 14_000,
+    budgetRatio: 0.75,
+    out: '',
+  }
+  for (let index = 2; index < argv.length; index++) {
+    const key = argv[index]
+    const value = argv[index + 1]
+    if (key === '--dir') { args.dir = value; index++ }
+    else if (key === '--limit') { args.limit = Number(value); index++ }
+    else if (key === '--session') { args.session = value; index++ }
+    else if (key === '--min-chars') { args.minChars = Number(value); index++ }
+    else if (key === '--budget-ratio') { args.budgetRatio = Number(value); index++ }
+    else if (key === '--out') { args.out = value; index++ }
+    else { console.error(`unknown arg ${key}`); process.exit(2) }
+  }
+  return args
+}
+
+/** 多帧 zstd:扫魔数逐帧解压;对解出的 JSONL 行全局去重(等价于帧去重,
+ *  且对"重复帧但行交错"的场景更稳)。 */
+function decodeMultiFrameZstd(buffer) {
+  const offsets = []
+  let position = 0
+  for (;;) {
+    const index = buffer.indexOf(ZSTD_MAGIC, position)
+    if (index < 0) break
+    offsets.push(index)
+    position = index + 1
+  }
+  const chunks = []
+  let failedFrames = 0
+  for (let index = 0; index < offsets.length; index++) {
+    const chunk = buffer.subarray(offsets[index], index + 1 < offsets.length ? offsets[index + 1] : buffer.length)
+    try {
+      chunks.push(zstdDecompressSync(chunk))
+    } catch {
+      failedFrames += 1
+    }
+  }
+  const seen = new Set()
+  const lines = []
+  for (const chunk of chunks) {
+    for (const line of chunk.toString('utf8').split('\n')) {
+      if (line.trim() === '' || seen.has(line)) continue
+      seen.add(line)
+      lines.push(line)
+    }
+  }
+  return { lines, frames: offsets.length, failedFrames }
+}
+
+function listSessionFiles(dir, sessionFilter) {
+  const files = []
+  const walk = current => {
+    let entries
+    try { entries = readdirSync(current, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      const path = join(current, entry.name)
+      if (entry.isDirectory()) walk(path)
+      else if (entry.name.startsWith('session') && entry.name.endsWith('.jsonl.zstd')) files.push(path)
+    }
+  }
+  walk(dir)
+  return files.filter(path => sessionFilter === '' || path.includes(sessionFilter))
+}
+
+/** tool/call ↔ tool/result 配对;返回 {toolName, arguments, text, isError, seq, time}。 */
+function extractToolResults(lines) {
+  const calls = new Map()
+  const results = []
+  for (const line of lines) {
+    let event
+    try { event = JSON.parse(line) } catch { continue }
+    if (event?.type === 'tool/call') {
+      const callId = event.data?.callId
+      if (typeof callId === 'string') {
+        calls.set(callId, { name: event.data?.name ?? '', arguments: event.data?.arguments ?? '{}' })
+      }
+    } else if (event?.type === 'tool/result') {
+      const message = event.data?.message
+      const callId = message?.source?.callId
+      const block = message?.content?.[0]
+      const text = block?.content?.find(part => part?.type === 'text')?.text
+      if (typeof callId !== 'string' || typeof text !== 'string') continue
+      results.push({
+        callId,
+        toolName: calls.get(callId)?.name ?? '(unknown)',
+        argumentsText: calls.get(callId)?.arguments ?? '{}',
+        text,
+        isError: block?.isError === true,
+        seq: event.seq,
+        time: event.time,
+      })
+    }
+  }
+  return results
+}
+
+/** v1 时代的旧分类(子串正则),仅用于误路由对照,不参与现行为。 */
+function legacyIsSearchTool(name, command) {
+  return /(?:grep|search|glob|find|ripgrep|rg)/.test(name)
+    || /(?:^|\s)(?:rg|grep|find|fd)\s/.test(command)
+}
+function legacyCommandKeys(argumentsText) {
+  try {
+    const parsed = JSON.parse(argumentsText)
+    if (typeof parsed !== 'object' || parsed === null) return ''
+    for (const key of ['command', 'cmd', 'script', 'input']) {
+      if (typeof parsed[key] === 'string') return parsed[key]
+    }
+  } catch { /* ignore */ }
+  return ''
+}
+
+async function main() {
+  const args = parseArgs(process.argv)
+  const lib = await import(new URL(`file://${join(REPO_ROOT, 'packages/selector/lib/pruner.js').replace(/\\/g, '/')}`).href)
+  const { reduceFreshToolResult, resolvePolicy, COMPRESSION_PROFILES } = lib
+  if (typeof reduceFreshToolResult !== 'function') throw new Error('built lib missing reduceFreshToolResult — run `pnpm build` first')
+
+  const policy = resolvePolicy({}, 'balanced')
+  console.log(`[policy] balanced: freshTriggerTokens = ${policy.freshTriggerTokens} | freshTargetTokens = ${policy.freshTargetTokens} | freshEnabled = ${policy.freshEnabled}`)
+
+  const files = listSessionFiles(args.dir, args.session)
+    .map(path => ({ path, size: statSync(path).size }))
+    .sort((a, b) => b.size - a.size)
+    .slice(0, args.limit)
+  console.log(`[corpus] ${files.length} session file(s) (limit=${args.limit}, min-chars=${args.minChars}, dir=${args.dir})`)
+  console.log(`[note] --min-chars is a sample filter for this script only; it is NOT the runtime READ_TOC_MIN_CHARS and does not gate runtime behavior`)
+
+  const dispatch = new Map() // toolName → toolClass → { reducer → count }
+  const reducerHits = new Map()
+  const classTotals = new Map()
+  const misroutes = []
+  let totalIn = 0
+  let totalOut = 0
+  let reduced = 0
+  let failOpen = 0
+  let sessions = 0
+  let minTime = Number.POSITIVE_INFINITY
+  let maxTime = Number.NEGATIVE_INFINITY
+  const readSizes = []
+
+  for (const file of files) {
+    sessions += 1
+    const raw = readFileSync(file.path)
+    const { lines, frames, failedFrames } = decodeMultiFrameZstd(raw)
+    if (failedFrames > 0) console.warn(`  [warn] ${relative(args.dir, file.path)}: ${failedFrames}/${frames} frame(s) failed to decode`)
+    for (const result of extractToolResults(lines)) {
+      if (result.text.length < args.minChars) continue
+      minTime = Math.min(minTime, result.time)
+      maxTime = Math.max(maxTime, result.time)
+      const budgetChars = Math.floor(result.text.length * args.budgetRatio)
+      const output = reduceFreshToolResult({
+        toolName: result.toolName,
+        argumentsText: result.argumentsText,
+        text: result.text,
+        budgetChars,
+        sourceRef: `session://replay/${String(result.seq)}`,
+        isError: result.isError,
+        codeSkeleton: true,
+      })
+      const command = legacyCommandKeys(result.argumentsText)
+      const lowered = result.toolName.toLowerCase()
+      const legacySearch = legacyIsSearchTool(lowered, command)
+      const nowSearchRoute = output?.reducer === 'search-by-file' || output?.reducer === 'search-salience'
+      if (legacySearch && !nowSearchRoute && misroutes.length < 20) {
+        misroutes.push({
+          tool: result.toolName,
+          chars: result.text.length,
+          head: Array.from(result.text.slice(0, 80).replace(/\n/g, '\\n')),
+          now: output?.reducer ?? 'fail-open',
+        })
+      }
+      void legacySearch
+      // 分发矩阵:工具名 → 现派发 reducer → 计数
+      const byTool = dispatch.get(result.toolName) ?? {}
+      const key = output === null ? 'fail-open' : output.reducer
+      byTool[key] = (byTool[key] ?? 0) + 1
+      dispatch.set(result.toolName, byTool)
+      reducerHits.set(key, (reducerHits.get(key) ?? 0) + 1)
+      classTotals.set(result.toolName, (classTotals.get(result.toolName) ?? 0) + 1)
+      totalIn += result.text.length
+      if (output !== null) {
+        reduced += 1
+        totalOut += output.text.length
+      } else {
+        failOpen += 1
+      }
+      if (result.toolName.toLowerCase().match(/read|cat|view/)) readSizes.push(result.text.length)
+    }
+  }
+
+  const lines = []
+  lines.push(`# toolclass corpus replay — ${new Date().toISOString()}`)
+  lines.push(`- sessions: ${sessions} (top by size; BIAS: favors long sessions — do not extrapolate)`)
+  lines.push(`- sample window (event time): ${Number.isFinite(minTime) ? new Date(minTime).toISOString() : 'n/a'} … ${Number.isFinite(maxTime) ? new Date(maxTime).toISOString() : 'n/a'}`)
+  lines.push(`- samples ≥ ${args.minChars} chars: ${reduced + failOpen} (reduced ${reduced}, fail-open ${failOpen})`)
+  lines.push(`- verify pass rate (non-null): ${reduced + failOpen === 0 ? 'n/a' : `${(reduced / (reduced + failOpen) * 100).toFixed(1)}%`}`)
+  lines.push(`- compression: ${totalIn} → ${totalOut} chars (${totalIn === 0 ? 'n/a' : `${(totalOut / totalIn * 100).toFixed(1)}%`})`)
+  lines.push('')
+  lines.push('## reducer hit rate')
+  for (const [key, count] of [...reducerHits.entries()].sort((a, b) => b[1] - a[1])) {
+    lines.push(`- ${key}: ${count}`)
+  }
+  lines.push('')
+  lines.push('## dispatch matrix (toolName → reducer → count)')
+  for (const [toolName, byReducer] of [...dispatch.entries()]
+    .sort((a, b) => Object.values(b[1]).reduce((x, y) => x + y, 0) - Object.values(a[1]).reduce((x, y) => x + y, 0))) {
+    lines.push(`- ${toolName}: ${JSON.stringify(byReducer)}`)
+  }
+  lines.push('')
+  lines.push('## fixed misroutes (legacy substring → search, now dispatched elsewhere)')
+  for (const sample of misroutes) {
+    lines.push(`- ${sample.tool} (${sample.chars} chars) → ${sample.now} | head: ${sample.head.join('')}`)
+  }
+  if (misroutes.length === 0) lines.push('- (none in this sample)')
+  lines.push('')
+  lines.push('## freshTriggerTokens sensitivity (read-class results, chars thresholds)')
+  for (const trigger of [8_192, 6_144, 4_096, 2_048]) {
+    const t36 = trigger * 3.6
+    const t40 = trigger * 4.0
+    const above36 = readSizes.filter(size => size > t36).length
+    const above40 = readSizes.filter(size => size > t40).length
+    lines.push(`- trigger ${trigger}: read samples > ${t40.toFixed(0)} chars (4.0 c/t): ${above40}/${readSizes.length}; > ${t36.toFixed(0)} (3.6 c/t): ${above36}/${readSizes.length}`)
+  }
+  lines.push('')
+  lines.push(`> profiles available: ${COMPRESSION_PROFILES.join(', ')}`)
+  const report = lines.join('\n')
+  console.log('\n' + report)
+  if (args.out !== '') {
+    writeFileSync(args.out, report, 'utf8')
+    console.log(`[written] ${args.out}`)
+  }
+}
+
+main().catch(error => {
+  console.error(error)
+  process.exit(1)
+})