claude-code-runrate 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ version is worth upgrading to, and where to read the rest.
 
 Dates are npm publish dates, because that is when a version reached anyone.
 
+## 0.6.0 — 2026-09-01
+
+The remote-session release. Over mosh, two things had been degrading in
+silence — every clipboard copy was dropped in transit, and 24-bit colour was
+quietly flattened to 256 — and the tmux version floor the sidecar had grown
+was written down nowhere. All three were measured at the terminal, reading
+the raw bytes that reach a mosh client, not inferred.
+
+- **The clipboard survives mosh.** tmux's built-in OSC 52 emits an empty
+  selection field and mosh's parser accepts only an explicit `c`, so every
+  copy vanished between the two. The shipped tmux config now spells the
+  selection out — and names `c` explicitly, which is *more* compatible than
+  tmux's default everywhere, not a mosh-only workaround.
+- **True colour survives mosh.** mosh forces `TERM=xterm-256color` and drops
+  `COLORTERM`, which tmux reads as "no RGB" and silently downgrades every
+  24-bit colour to the nearest 256. The config now declares RGB for that
+  TERM, restoring what mosh was carrying fine all along.
+- **The tmux floor is declared: 3.2.** Percentage splits and
+  `terminal-features` need 3.1; the pane-scoped hooks that keep the sidebar
+  out of copy-mode need 3.2. Below the floor each failure is silent and looks
+  like something else, so `ccr doctor` now reports the tmux version and names
+  one that is too old — and an unreadable version is reported as unreadable,
+  never manufactured into a failure.
+- **The sidebar split speaks tmux 3.4's dialect.** `-p 34` was deprecated in
+  3.1 and rejected outright in 3.4; the launcher sizes with `-l 34%`, which
+  every supported tmux accepts.
+- **The Node floor rises to 22.17.** Node 18 and 20 are past their end of
+  life, and the vendored test runner's own floor is 22.17 — testing below it
+  produced a lane that hung rather than failed. `engines`, the CI matrix,
+  `ccr doctor`'s check, and the spec all state the same floor now, and the
+  matrix pins 22.17 exactly so the floor is tested, not just declared.
+- **The acceptance suite hardened underneath.** The vendored Gherkin runner
+  moved to gherkin-node-test 0.11.0, whose step linter enforces a rule the
+  suite now lives by: a negative assertion over a literal needle passes
+  forever once the needle rots, so *absence must be earned* — by a control
+  proving the needle can still find, or a sanction naming what proves it.
+  Every structural refusal in the step layer (the renderer spawns nothing,
+  the launcher reads no blob, the sidecar has no input channel) now carries
+  one or the other, and both of 0.11's linters gate the suite.
+
 ## 0.5.0 — 2026-08-22
 
 The Windows release. The things that could not be reasoned about were measured

package/README.md

@@ -69,8 +69,8 @@ On Linux/macOS the default host is `tmux`. No WSL required.
 
 ## Requirements
 
-- **Node ≥ 18.3** — that's it for the core. **Zero runtime dependencies.**
-- For the optional live `ccr sidecar`: `tmux` on Linux/macOS, or **Windows
+- **Node ≥ 22.17** — that's it for the core. **Zero runtime dependencies.**
+- For the optional live `ccr sidecar`: **`tmux` ≥ 3.2** on Linux/macOS, or **Windows
   Terminal** / **VS Code's integrated terminal** on Windows (no WSL).
 
 ## VS Code (split terminal)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-runrate",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Claude Code run-rate — subscription burn-rate & economy for your Claude Code sessions.",
   "license": "MIT",
   "author": "Bing Ho <reps-attic-riot@duck.com>",
@@ -17,7 +17,7 @@
     "ccr": "bin/ccr.js"
   },
   "engines": {
-    "node": ">=18.3"
+    "node": ">=22.17"
   },
   "files": [
     "bin",

package/scripts/launch.sh

@@ -135,7 +135,14 @@ if [ -n "${CCR_TITLE:-}" ]; then
 fi
 
 # Pane 1: the live economy sidebar. Capture its pane id so we can scope a hook to it.
-SIDEBAR_PANE="$(tmux -L "$SOCKET" split-window -t "$SESSION:0" -h -p "${CCR_SIDEBAR_PCT:-34}" -P -F '#{pane_id}' \
+# The width is `-l <pct>%`, NOT `-p <pct>`. Both spell the same split, but `-p` is the
+# deprecated form and tmux 3.4 — what Ubuntu 24.04 LTS ships, i.e. every stock Ubuntu
+# Server — rejects it with `size missing`. That killed the launcher AFTER new-session
+# had already succeeded, so the failure mode was silent and confusing: a live Claude
+# pane, no sidebar, no error on screen (launch.sh's stderr goes to the terminal it was
+# spawned from, which is gone by then). `-l N%` is accepted by 3.1 through 3.6+ alike
+# and produces an identical split, so there is no version guard to maintain.
+SIDEBAR_PANE="$(tmux -L "$SOCKET" split-window -t "$SESSION:0" -h -l "${CCR_SIDEBAR_PCT:-34}%" -P -F '#{pane_id}' \
   "$ENV_PREAMBLE; \"$NODE\" \"$REPO/bin/ccr.js\" sidecar; read -r -p 'sidebar exited — Enter to close '")"
 
 # The sidebar is a live dashboard — there is nothing to scroll. A stray mouse-wheel

package/sidecar/ccr.tmux.conf

@@ -22,3 +22,41 @@ set -g set-clipboard on
 
 # prefix + P — dump the whole pane scrollback to a file, regardless of length.
 bind-key P command-prompt -p 'save pane to:' 'capture-pane -S - ; save-buffer %1'
+
+# --- Remote sessions: true colour and a clipboard that survives mosh ---------
+#
+# Both lines matter only over a remote transport, and mosh is the case that
+# breaks without them. Measured over mosh -> tmux, reading the raw bytes that
+# reach the client; neither is guesswork.
+#
+# 1. TRUE COLOUR. mosh forces TERM=xterm-256color and DROPS COLORTERM. tmux
+#    infers RGB support from COLORTERM, so with it gone tmux silently
+#    downgrades 24-bit colour to the nearest 256 (38;2;R;G;B -> 38;5;N). mosh
+#    itself carries 24-bit fine; tmux is the one degrading it. Declaring the
+#    feature restores it.
+#
+# 2. CLIPBOARD. tmux's built-in OSC 52 emits an EMPTY selection field
+#    (`\033]52;;<base64>`), and mosh's OSC 52 parser accepts ONLY an explicit
+#    `c`. So every copy is silently dropped in transit. This override spells
+#    the selection out. Three details are load-bearing:
+#      * `%p1%.0s` CONSUMES the selection parameter while printing nothing.
+#        Omitting it leaves p1 unconsumed and the expansion is invalid.
+#      * `\007`, never `\7`. tmux 3.x SILENTLY REJECTS a terminal-overrides
+#        value containing `\7` — the option is discarded whole with no error,
+#        and `tmux show -s terminal-overrides` simply will not list it. Older
+#        guides on the web all use `\7`; that spelling was fine on tmux 2.x.
+#      * terminal-overrides keys on the client's TERM, so this matches when
+#        TERM is xterm-256color — which is exactly what mosh sets.
+#    Emitting an explicit `c` is also strictly more compatible than tmux's
+#    default empty field, so this is not a mosh-only workaround.
+#
+# Both require tmux 3.1+; ccr asks for 3.2+ overall (see `ccr doctor`).
+#
+# RGB is declared unconditionally. 24-bit has been table stakes for years —
+# iTerm2, Ghostty, WezTerm, kitty, Alacritty, Konsole, every libvte terminal
+# (GNOME Terminal et al), Windows Terminal and PuTTY all handle it. The lone
+# holdout that reports TERM=xterm-256color without it is macOS Terminal.app
+# before macOS 26, which degrades rather than breaking. Optimising the default
+# for that shrinking case would cost every other user their colours.
+set -as terminal-features ',xterm-256color:RGB'
+set -as terminal-overrides ",xterm-256color:Ms=\E]52;c%p1%.0s;%p2%s\007"

package/src/doctor.js

@@ -35,8 +35,27 @@ function isExec(/** @type {string} */ f) {
   try { return (fs.statSync(f).mode & 0o111) !== 0; } catch { return false; }
 }
 
+// ccr's tmux dialect has a floor. 3.1 is HARD: percentage splits
+// (`split-window -l 34%`, since `-p` was deprecated there and 3.4+ rejects it)
+// and `terminal-features`, which sidecar/ccr.tmux.conf needs for true colour
+// over mosh. 3.2 adds pane-scoped hooks, which the launcher uses to keep the
+// sidebar out of copy-mode; below that it degrades quietly rather than
+// breaking, so 3.2 is what we ask for and 3.1 is what we tolerate.
+const TMUX_MIN = { major: 3, minor: 2 };
+/** @param {string} bin @returns {{major:number,minor:number}|null} */
+function tmuxVersion(bin) {
+  try {
+    const r = spawnSync(bin, ['-V'], { encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    // "tmux 3.7c", "tmux 3.2a", "tmux next-3.6" — only the numbers matter.
+    const m = /(\d+)\.(\d+)/.exec(r.stdout || '');
+    return m ? { major: Number(m[1]), minor: Number(m[2]) } : null;
+  } catch { return null; }
+}
+
 /**
  * @param {{ platform?: string, has?: (cmd: string) => (string|null),
+ *   tmuxVersion?: (bin: string) => ({major:number,minor:number}|null),
  *   homedir?: string, repo?: string, write?: (s: string) => void,
  *   env?: Record<string, string|undefined> }} [opts]
  *   side effects are injectable for testing; defaults hit the real environment
@@ -45,6 +64,7 @@ function isExec(/** @type {string} */ f) {
 function run(opts = {}) {
   const platform = opts.platform || process.platform;
   const hasFn = opts.has || has;
+  const tmuxVerFn = opts.tmuxVersion || tmuxVersion;
   const homedir = opts.homedir || os.homedir();
   const REPO = opts.repo || path.join(__dirname, '..');
   const write = opts.write || ((s) => { process.stdout.write(s); });
@@ -53,8 +73,8 @@ function run(opts = {}) {
   let problems = 0;
 
   const [maj, min] = process.versions.node.split('.').map(Number);
-  const nodeOk = maj > 18 || (maj === 18 && min >= 3);
-  out.push(nodeOk ? ok(`node ${process.version}`) : bad(`node ${process.version} — need >= 18.3`));
+  const nodeOk = maj > 22 || (maj === 22 && min >= 17);
+  out.push(nodeOk ? ok(`node ${process.version}`) : bad(`node ${process.version} — need >= 22.17`));
   if (!nodeOk) problems++;
 
   const ccr = hasFn('ccr');
@@ -74,8 +94,24 @@ function run(opts = {}) {
     // temp settings file, so there's no shipped shim asset to check on Windows.
   } else {
     const tmux = hasFn('tmux');
-    out.push(tmux ? ok(`tmux (${stripControl(tmux)})`) : warn('tmux missing — needed for the `ccr [profile]` sidebar'));
-    if (!tmux) problems++;
+    if (!tmux) {
+      out.push(warn('tmux missing — needed for the `ccr [profile]` sidebar'));
+      problems++;
+    } else {
+      const v = tmuxVerFn(tmux);
+      // An unreadable version is not evidence of a problem — say so and move on
+      // rather than manufacturing a failure out of a parse miss.
+      if (!v) {
+        out.push(ok(`tmux (${stripControl(tmux)})`) + dim(' — version unreadable'));
+      } else if (v.major < TMUX_MIN.major
+          || (v.major === TMUX_MIN.major && v.minor < TMUX_MIN.minor)) {
+        out.push(warn(`tmux ${v.major}.${v.minor} (${stripControl(tmux)}) — ccr wants `
+          + `${TMUX_MIN.major}.${TMUX_MIN.minor}+; below 3.1 the sidebar split fails outright`));
+        problems++;
+      } else {
+        out.push(ok(`tmux ${v.major}.${v.minor} (${stripControl(tmux)})`));
+      }
+    }
     out.push(hasFn('bash') ? ok('bash') : warn('bash missing — needed for the launcher'));
 
     const sl = path.join(REPO, 'sidecar', 'ccr-statusline');

package/src/history-privacy.js

@@ -1,435 +0,0 @@
-// @ts-check
-'use strict';
-// src/history-privacy.js — what a release would publish that is not published
-// yet, read out of the object store rather than out of the working tree.
-//
-// Why this is not simply `git grep` over the working tree: a scrubbed tip says
-// nothing about the blobs behind it. 0.4.0 made the shape concrete — its tree
-// grepped clean while fourteen of the twenty-three commits behind that tip
-// still carried a string the release had deliberately removed. Invisible to
-// every check anyone ran, because every check ran on the tree.
-//
-// That particular string turned out to be publishable after all (ruled
-// 2026-08-07; the flat squash it prompted cost nothing either way). The
-// arithmetic is the lesson rather than the string: fourteen commits, none of
-// them reachable from an inspection of the tip, and nothing in the release path
-// that would have looked.
-//
-// The disclosures this repository has ACTUALLY had were both mail addresses —
-// an owner address throughout early history, and a contributor's real address
-// on a branch that reached the public remote in 2026-06. Neither was in the tip
-// when it mattered. Both are what the real-inbox detector below is for.
-//
-// So the check reads history, not `HEAD`: every commit reachable from the tip
-// and not from the published ref, every blob in each of their trees.
-//
-// TWO KINDS OF FINDING, deliberately different:
-//
-//   * DETECTORS (below) are generic and live here in the open, because they
-//     describe SHAPES — an email that is not a noreply alias, an absolute home
-//     path — not anyone's actual secrets. They cover both disclosures above.
-//
-//   * The PRIVATE SUPPLEMENT is a list of literal patterns supplied from
-//     OUTSIDE the repository (see loadPrivatePatterns). Whatever belongs on it
-//     is by definition a string this file must not contain: writing it into a
-//     public file in order to scan for it would be the disclosure it prevents.
-//
-// Detector hits are judged against a BASELINE: whatever the published tree
-// already contains is, by definition, already public and not news. That is why
-// there is no allowlist to maintain — the npm contact alias in package.json is
-// silent because it is already out there, and it would start speaking again
-// the moment it appeared somewhere it had not been. Supplement hits ignore the
-// baseline: those strings are never acceptable, published already or not.
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-
-const { readObject, parseTree } = require('./git-objects');
-
-/** Commits walked before the scan gives up rather than grind. */
-const MAX_COMMITS = 2000;
-/** Distinct blobs read per scan. Trees and blobs are deduplicated by oid, so
- *  this counts real content, not path instances. */
-const MAX_BLOBS = 20000;
-/** A blob larger than this is not read. Secrets hide in text, and the object
- *  reader has its own ceiling anyway. */
-const MAX_BLOB_BYTES = 1024 * 1024;
-/** Bytes inspected for NUL before calling a blob binary and skipping it. */
-const BINARY_SNIFF_BYTES = 8192;
-
-/**
- * A generic shape worth refusing to publish. `extract` returns the literal
- * strings found, which is what makes baseline comparison possible: the finding
- * is the STRING, so "already public" is a set membership test.
- *
- * @typedef {object} Detector
- * @property {string} name
- * @property {string} why      Printed to the operator, so it must explain itself.
- * @property {(text: string) => string[]} extract
- */
-
-/**
- * Addresses that are aliases by construction. This is not an allowlist of
- * anyone's real mail — it is the set of names that CANNOT reach an inbox,
- * which is why a fixture is entitled to use them freely.
- *
- * The reserved names are RFC 2606 and RFC 6761: the `.invalid`, `.test`,
- * `.example` and `.localhost` TLDs, and the `example.com/org/net` domains.
- * They are matched as SUFFIXES, so `oracle@ccr.invalid` and
- * `someone@corp.example.com` are covered — an earlier version anchored on
- * `@invalid$` and flagged this repository's own test fixtures.
- */
-const ALIAS_MAIL = /(@users\.noreply\.github\.com|@noreply\.[A-Za-z0-9.-]+|^noreply@|\.(invalid|test|example|localhost)$|(^|@|\.)example\.(com|org|net)$)/i;
-
-const MAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
-
-/**
- * `/home/<user>/`, `/Users/<user>/`, `C:\Users\<user>\` — an absolute path
- * through somebody's home directory. Generic placeholders are not findings.
- */
-const HOME_RE = /(?:\/home\/|\/Users\/|[A-Za-z]:\\Users\\)([A-Za-z0-9._-]+)/g;
-const PLACEHOLDER_USER = /^(user|username|you|me|someone|test|runner|ci|root|foo|bar|example|\$\{?\w+\}?)$/i;
-
-/** @type {Detector[]} */
-const DETECTORS = [
-  {
-    name: 'real-inbox',
-    why: 'an email address that is not a noreply alias',
-    extract: (text) => (text.match(MAIL_RE) || []).filter((m) => !ALIAS_MAIL.test(m)),
-  },
-  {
-    name: 'home-path',
-    why: 'an absolute path naming a home directory',
-    extract: (text) => {
-      /** @type {string[]} */
-      const out = [];
-      for (const m of text.matchAll(HOME_RE)) {
-        if (!PLACEHOLDER_USER.test(m[1])) out.push(m[0]);
-      }
-      return out;
-    },
-  },
-];
-
-/**
- * The private supplement: literal ERE-ish patterns that must never appear,
- * supplied from outside the repository so the repository never states them.
- *
- * Sources, first one that exists wins:
- *   1. $CCR_PRIVATE_PATTERNS       — patterns inline, comma or newline separated
- *   2. $CCR_PRIVATE_PATTERNS_FILE  — a file of them, one per line, `#` comments
- *   3. ~/.config/ccr/private-patterns
- *
- * Absent all three the supplement is empty and `configured` is false, which
- * the gate reports rather than swallows: a check that quietly did not run is
- * worse than one that says so.
- *
- * @param {{ env?: NodeJS.ProcessEnv, homedir?: () => string }} [deps]
- * @returns {{ configured: boolean, source: string|null, patterns: RegExp[], invalid: string[] }}
- */
-function loadPrivatePatterns(deps = {}) {
-  const env = deps.env || process.env;
-  const home = (deps.homedir || os.homedir)();
-
-  /** @type {string|null} */
-  let raw = null;
-  /** @type {string|null} */
-  let source = null;
-
-  if (env.CCR_PRIVATE_PATTERNS && env.CCR_PRIVATE_PATTERNS.trim()) {
-    raw = env.CCR_PRIVATE_PATTERNS;
-    source = '$CCR_PRIVATE_PATTERNS';
-  } else {
-    const file = env.CCR_PRIVATE_PATTERNS_FILE
-      || path.join(home, '.config', 'ccr', 'private-patterns');
-    try {
-      raw = fs.readFileSync(file, 'utf8');
-      source = file;
-    } catch {
-      raw = null;
-    }
-  }
-
-  if (raw === null) return { configured: false, source: null, patterns: [], invalid: [] };
-
-  /** @type {RegExp[]} */
-  const patterns = [];
-  /** @type {string[]} */
-  const invalid = [];
-  for (const line of raw.split(/[\n,]/)) {
-    const s = line.trim();
-    if (!s || s.startsWith('#')) continue;
-    try {
-      patterns.push(new RegExp(s, 'i'));
-    } catch {
-      invalid.push(s);
-    }
-  }
-  return { configured: true, source, patterns, invalid };
-}
-
-/**
- * Commits reachable from `tip` and not from `published`.
- *
- * The exclusion side is walked first and in full, so a commit that is an
- * ancestor of the published ref is never reported no matter which order the
- * tip walk reaches it in.
- *
- * A commit whose object cannot be read is REPORTED, not skipped. Dropping it
- * would shrink the answer silently: an unreadable tip would walk to an empty
- * list, and an empty list of unpublished commits is indistinguishable from
- * having nothing to disclose. The caller must be able to tell those apart.
- *
- * @param {string} gitDir
- * @param {string} tip
- * @param {string|null} published  Null means "nothing is published yet".
- * @returns {{ commits: string[], unreadable: string[], truncated: boolean }}
- */
-function unpublishedCommits(gitDir, tip, published) {
-  const parentsOf = (/** @type {string} */ oid) => {
-    const obj = readObject(gitDir, oid);
-    if (obj === null || obj.type !== 'commit') return null;
-    const header = obj.data.toString('utf8', 0, Math.min(obj.data.length, 8192));
-    const end = header.indexOf('\n\n');
-    const head = end === -1 ? header : header.slice(0, end);
-    return [...head.matchAll(/^parent ([0-9a-f]{40}|[0-9a-f]{64})$/gm)].map((m) => m[1]);
-  };
-
-  /** @type {Set<string>} */
-  const excluded = new Set();
-  if (published !== null) {
-    const stack = [published];
-    while (stack.length > 0 && excluded.size < MAX_COMMITS) {
-      const oid = /** @type {string} */ (stack.pop());
-      if (excluded.has(oid)) continue;
-      excluded.add(oid);
-      const ps = parentsOf(oid);
-      if (ps !== null) stack.push(...ps);
-    }
-  }
-
-  /** @type {string[]} */
-  const commits = [];
-  /** @type {string[]} */
-  const unreadable = [];
-  /** @type {Set<string>} */
-  const seen = new Set();
-  const stack = [tip];
-  let truncated = false;
-  while (stack.length > 0) {
-    const oid = /** @type {string} */ (stack.pop());
-    if (seen.has(oid) || excluded.has(oid)) continue;
-    seen.add(oid);
-    if (commits.length >= MAX_COMMITS) { truncated = true; break; }
-    const ps = parentsOf(oid);
-    if (ps === null) { unreadable.push(oid); continue; }
-    commits.push(oid);
-    stack.push(...ps);
-  }
-  return { commits, unreadable, truncated };
-}
-
-/**
- * Every blob in a commit's tree, as `path -> oid`, following subtrees and
- * skipping gitlinks (mode 0o160000 — a submodule pointer names a commit in
- * another repository, whose contents are not ours to read).
- *
- * @param {string} gitDir
- * @param {string} treeOid
- * @param {Set<string>} treesSeen  Shared across commits: sibling releases share
- *   almost all of their trees, and re-walking them is the whole cost.
- * @param {(path: string, oid: string) => void} onBlob
- */
-function walkTree(gitDir, treeOid, treesSeen, onBlob, prefix = '') {
-  if (treesSeen.has(treeOid)) return;
-  treesSeen.add(treeOid);
-  const obj = readObject(gitDir, treeOid);
-  if (obj === null || obj.type !== 'tree') return;
-  const entries = parseTree(obj.data, treeOid.length / 2);
-  if (entries === null) return;
-  for (const e of entries) {
-    const full = prefix ? `${prefix}/${e.name}` : e.name;
-    if (e.mode === 0o160000) continue;
-    if (e.mode === 0o40000) walkTree(gitDir, e.oid, treesSeen, onBlob, full);
-    else onBlob(full, e.oid);
-  }
-}
-
-/**
- * Read a blob as text, or null when it is missing, oversized or binary.
- * @param {string} gitDir
- * @param {string} oid
- */
-function readTextBlob(gitDir, oid) {
-  const obj = readObject(gitDir, oid);
-  if (obj === null || obj.type !== 'blob') return null;
-  if (obj.data.length > MAX_BLOB_BYTES) return null;
-  if (obj.data.indexOf(0, 0) !== -1
-    && obj.data.indexOf(0, 0) < BINARY_SNIFF_BYTES) return null;
-  return obj.data.toString('utf8');
-}
-
-/**
- * Every literal a detector finds anywhere in a tree — the baseline of what is
- * already public, so the same string appearing again is not a new disclosure.
- *
- * @param {string} gitDir
- * @param {string} treeOid
- * @returns {Set<string>}
- */
-function baselineLiterals(gitDir, treeOid) {
-  /** @type {Set<string>} */
-  const found = new Set();
-  /** @type {Set<string>} */
-  const trees = new Set();
-  /** @type {Set<string>} */
-  const blobs = new Set();
-  walkTree(gitDir, treeOid, trees, (_p, oid) => {
-    if (blobs.has(oid) || blobs.size >= MAX_BLOBS) return;
-    blobs.add(oid);
-    const text = readTextBlob(gitDir, oid);
-    if (text === null) return;
-    for (const d of DETECTORS) for (const lit of d.extract(text)) found.add(lit);
-  });
-  return found;
-}
-
-/**
- * @typedef {object} PrivacyHit
- * @property {string} commit    Oid of the commit whose tree carries it.
- * @property {string} path      Path within that tree.
- * @property {string} kind      Detector name, or 'private-pattern'.
- * @property {string} why       Human sentence for the operator.
- * @property {string} [literal] The offending string, when it is safe to print
- *   (detector hits only — a supplement hit prints its pattern, never its match).
- */
-
-/**
- * Scan the unpublished history.
- *
- * @param {string} gitDir
- * @param {object} opts
- * @param {string} opts.tip            Commit about to be published from.
- * @param {string|null} opts.published Commit currently public, or null.
- * @param {RegExp[]} [opts.privatePatterns]
- * @param {string[]} [opts.allow]      Literals known to be invented, joined to
- *   the baseline. Detector hits only — a private pattern is never waived here.
- * @returns {{ state: 'clean'|'hits'|'unavailable', hits: PrivacyHit[],
- *   commitsScanned: number, blobsScanned: number, truncated: boolean }}
- */
-function scanHistory(gitDir, opts) {
-  const priv = opts.privatePatterns || [];
-  const walk = unpublishedCommits(gitDir, opts.tip, opts.published);
-  const { commits, truncated } = walk;
-
-  // ANY commit the object store could not answer for makes the whole scan
-  // inconclusive, and inconclusive is not clean. A gate that cleared a release
-  // because it failed to read the evidence would be worse than no gate: it
-  // would report success in exactly the situation it exists to catch.
-  if (walk.unreadable.length > 0) {
-    return {
-      state: 'unavailable', hits: [], commitsScanned: 0, blobsScanned: 0, truncated,
-    };
-  }
-
-  if (commits.length === 0) {
-    return { state: 'clean', hits: [], commitsScanned: 0, blobsScanned: 0, truncated };
-  }
-
-  // What the published tree already says. Absent a published ref there is no
-  // baseline and every detector hit is news, which is the correct reading of
-  // a first publication.
-  /** @type {Set<string>} */
-  let baseline = new Set(opts.allow || []);
-  if (opts.published !== null) {
-    const obj = readObject(gitDir, opts.published);
-    if (obj !== null && obj.type === 'commit') {
-      const m = /^tree ([0-9a-f]{40}|[0-9a-f]{64})$/m.exec(
-        obj.data.toString('latin1', 0, Math.min(obj.data.length, 256)));
-      // Merged, not assigned: the allow list must survive the published tree's
-      // own literals being read in on top of it.
-      if (m) for (const lit of baselineLiterals(gitDir, m[1])) baseline.add(lit);
-    }
-  }
-
-  /** @type {PrivacyHit[]} */
-  const hits = [];
-  let unreadable = 0;
-  let blobCeiling = false;
-
-  // Reading and matching a blob is the expensive half and is done ONCE per
-  // oid. Attribution is the cheap half and is done per commit: the same blob
-  // usually survives many commits, and an operator who is told only about the
-  // first one would accept that commit and publish the other nine. The earlier
-  // shape of this function made exactly that mistake.
-  /** @type {Map<string, Array<{ kind: string, why: string, literal?: string }>>} */
-  const verdicts = new Map();
-  const verdictFor = (/** @type {string} */ oid) => {
-    const cached = verdicts.get(oid);
-    if (cached !== undefined) return cached;
-    if (verdicts.size >= MAX_BLOBS) { blobCeiling = true; return []; }
-    /** @type {Array<{ kind: string, why: string, literal?: string }>} */
-    const found = [];
-    const text = readTextBlob(gitDir, oid);
-    if (text !== null) {
-      // One finding per distinct literal per blob. A string repeated forty
-      // times in a file is one disclosure, and forty lines of it would bury
-      // the other findings the operator needs to see.
-      /** @type {Set<string>} */
-      const already = new Set();
-      for (const d of DETECTORS) {
-        for (const lit of d.extract(text)) {
-          if (baseline.has(lit) || already.has(lit)) continue;
-          already.add(lit);
-          found.push({ kind: d.name, why: d.why, literal: lit });
-        }
-      }
-      for (const re of priv) {
-        if (re.test(text)) {
-          found.push({ kind: 'private-pattern', why: `matches the private pattern /${re.source}/` });
-        }
-      }
-    }
-    verdicts.set(oid, found);
-    return found;
-  };
-
-  for (const commit of commits) {
-    const obj = readObject(gitDir, commit);
-    if (obj === null || obj.type !== 'commit') { unreadable += 1; continue; }
-    const m = /^tree ([0-9a-f]{40}|[0-9a-f]{64})$/m.exec(
-      obj.data.toString('latin1', 0, Math.min(obj.data.length, 256)));
-    if (!m) { unreadable += 1; continue; }
-
-    // Per-commit, so a tree shared with an already-walked commit is still
-    // attributed to this one. Within a commit it still collapses duplicates.
-    /** @type {Set<string>} */
-    const treesSeen = new Set();
-    walkTree(gitDir, m[1], treesSeen, (p, oid) => {
-      for (const v of verdictFor(oid)) hits.push({ commit, path: p, ...v });
-    });
-  }
-
-  // Same rule one level down: a commit that resolved but whose tree header did
-  // not parse leaves part of the history unexamined.
-  if (unreadable > 0) {
-    return {
-      state: 'unavailable', hits: [], commitsScanned: 0,
-      blobsScanned: verdicts.size, truncated: truncated || blobCeiling,
-    };
-  }
-
-  return {
-    state: hits.length > 0 ? 'hits' : 'clean',
-    hits,
-    commitsScanned: commits.length,
-    blobsScanned: verdicts.size,
-    truncated: truncated || blobCeiling,
-  };
-}
-
-module.exports = {
-  scanHistory, unpublishedCommits, loadPrivatePatterns, walkTree, baselineLiterals,
-  DETECTORS, MAX_COMMITS, MAX_BLOBS, MAX_BLOB_BYTES,
-};