session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/orphan-reaper/no-follow-append.mjs

@@ -0,0 +1,87 @@
+/**
+ * orphan-reaper/no-follow-append.mjs — the ONE hardened JSONL append the
+ * reaper's two ledgers share: the B5 kill audit (`reaper-audit.mjs`) and the
+ * gate-process ledger (`../process-group.mjs`). It was inline in the audit
+ * writer; the gate ledger still used a plain `appendFileSync(path)` (#1489).
+ *
+ * Imports nothing but `node:fs`, so `process-group.mjs` takes it without
+ * growing its closure. The read-side twin is `readTailWindow(file, n,
+ * { noFollow: true })` in `../tail-window.mjs`.
+ */
+
+import { appendFileSync, closeSync, constants as fsConstants, fstatSync, openSync } from 'node:fs';
+
+/** The one refusal every hardened ledger writer prints — the appends here and
+ *  the atomic prune rewrites (`replaceRegularFile`) in both ledger modules. */
+export const NOT_A_REGULAR_FILE = 'not a regular file (a symlink is never written through) — left untouched';
+
+/**
+ * `open(2)` flags of the append. `O_NOFOLLOW` makes the kernel refuse a
+ * symlink as the last path component (ELOOP) in the same call that opens the
+ * file, so there is no lstat-then-open window; `O_NONBLOCK` turns a planted FIFO
+ * with no reader into ENXIO instead of blocking in `open` (a plain append open
+ * of a FIFO waits for a reader that never comes — reproduced 2026-10-02, #1487).
+ * On a regular file `O_NONBLOCK` changes nothing.
+ * Named ceiling (BV-004): both are POSIX-only — Node leaves them undefined on
+ * Windows, where a linked ledger is still followed; revisit if the reaper or the
+ * gate ledger ever runs there.
+ */
+const APPEND_FLAGS = fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT
+  | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+
+/** @returns {Error & {code: string}} */
+function notARegularFile() {
+  return Object.assign(new Error(NOT_A_REGULAR_FILE), { code: 'ERR_NOT_REGULAR_FILE' });
+}
+
+/**
+ * Append `data` to `target`, creating it if absent — but never THROUGH a link
+ * and never blocked by a FIFO.
+ *
+ * The check is the open itself ({@link APPEND_FLAGS}) plus an `fstat` of the
+ * descriptor that was opened — never a separate lstat. That `fstat` refuses
+ * what the open let through: a FIFO that HAD a reader, a directory, a device,
+ * and a HARD-linked file (`nlink !== 1`): `ln <victim> <ledger>` passes every
+ * symlink check, and each append would then land in the victim (reproduced
+ * 2026-10-02 against the audit).
+ *
+ * THROWS — mapping a failure to a WARN line is the caller's job, as with
+ * `readTailWindow`. A symlink or any non-regular file throws
+ * `code: 'ERR_NOT_REGULAR_FILE'` with message {@link NOT_A_REGULAR_FILE}; a
+ * hard-linked file throws `code: 'ERR_HARD_LINKED'`; a FIFO without a reader
+ * throws the kernel's ENXIO unchanged; every other fs error passes through.
+ *
+ * @param {string} target  Absolute path; its directory must already exist.
+ * @param {string} data
+ * @returns {void}
+ */
+export function appendNoFollow(target, data) {
+  let fd;
+  try {
+    fd = openSync(target, APPEND_FLAGS);
+  } catch (err) {
+    throw err?.code === 'ELOOP' ? notARegularFile() : err;
+  }
+  try {
+    const stats = fstatSync(fd);
+    if (!stats.isFile()) throw notARegularFile();
+    // nlink 0: the name was replaced between open and fstat (a concurrent prune
+    // renames a fresh inode over it). Not a planted link — say so, so the
+    // operator does not go hunting for one.
+    if (stats.nlink === 0) {
+      throw Object.assign(
+        new Error('replaced while being opened (a concurrent rewrite renamed a new file over it) — this record was not written'),
+        { code: 'ERR_UNLINKED' },
+      );
+    }
+    if (stats.nlink !== 1) {
+      throw Object.assign(
+        new Error(`hard-linked (${stats.nlink} names) — an append would write into every one of them; left untouched`),
+        { code: 'ERR_HARD_LINKED' },
+      );
+    }
+    appendFileSync(fd, data, 'utf8');
+  } finally {
+    try { closeSync(fd); } catch { /* nothing left to release */ }
+  }
+}

package/scripts/lib/orphan-reaper/ps-snapshot.mjs

@@ -0,0 +1,181 @@
+/**
+ * orphan-reaper/ps-snapshot.mjs — the binding `ps` format: how the reaper
+ * measures the process table, and how it reads what it measured.
+ */
+
+import { spawn } from 'node:child_process';
+
+import { parseEtimeToSeconds } from '../resource-probe/parsers.mjs';
+
+/**
+ * The binding `ps` invocation (Discovery d-2, 2026-09-21, Darwin 25.6.0).
+ *
+ * Headerless (`=` per field) and six NUMERIC fields before `args`, because on
+ * macOS `comm` is a 16-character-truncated PATH that may contain spaces (68 of
+ * 784 processes carried a space, 13 of them survived the truncation) — appending
+ * `args` after `comm` breaks whitespace splitting outright. `-ww` disables column
+ * truncation; `ps` escapes control characters, so one process is one line.
+ * `rss` is in KiB. Roundtrip measured at ~47 ms for 287 KB / 784 processes.
+ *
+ * `pgid=` is the sixth column and is what lets a row join the ledger as a GROUP
+ * MEMBER rather than only as the recorded leader (see `reaper-decide.mjs`).
+ * Availability measured 2026-09-22 on Darwin 25.6.0 — `ps -Aww -o
+ * pid=,ppid=,pgid=,rss=,etime=,%cpu=,args=` exits 0 and prints the column; it is
+ * POSIX (`pgid` is a standard `-o` keyword) and present on Linux `procps` too.
+ *
+ * A targeted call, NOT the full `probe()` — that one spawns up to five
+ * subprocesses and has no caching (PRD § B4).
+ */
+export const PS_ARGS = Object.freeze(['-Aww', '-o', 'pid=,ppid=,pgid=,rss=,etime=,%cpu=,args=']);
+
+/**
+ * The TARGETED variant of {@link PS_ARGS}: one pid, same seven columns.
+ *
+ * Used immediately before every signal and once after the ladder (B3/B6). It is
+ * a separate call rather than a re-run of the full `-A` scan because the whole
+ * point is freshness at the moment of signalling — a 784-row snapshot taken for
+ * the population is already stale by the time the ladder's 10 s grace elapses,
+ * and re-taking it per signal would cost 287 KB to learn one row.
+ *
+ * @param {number} pid
+ * @returns {string[]}
+ */
+export function psPidArgs(pid) {
+  return ['-ww', '-p', String(pid), '-o', 'pid=,ppid=,pgid=,rss=,etime=,%cpu=,args='];
+}
+
+/** Wall-clock ceiling for one `ps` call. Same 2 s as `runPsDetailed()` in
+ *  `resource-probe/probe-platform.mjs`, whose spawn/timeout shape this mirrors. */
+const PS_TIMEOUT_MS = 2000;
+
+/**
+ * One parsed `ps` row.
+ * @typedef {object} PsRow
+ * @property {number} pid
+ * @property {number} ppid
+ * @property {number} pgid            Process-group id — the ledger's group join key.
+ * @property {number} rssKb           Resident set size in KiB.
+ * @property {number} etimeSeconds    Elapsed seconds since exec.
+ * @property {number} cpuPct
+ * @property {string} args            Full command line.
+ */
+
+/**
+ * Parse `ps` output in the {@link PS_ARGS} format, tolerantly — and COUNT what
+ * it drops.
+ *
+ * A silently skipping parser turns a partial read into a clean verdict, which is
+ * the exact failure mode a reaper must not have; hence the `malformed` count
+ * ({@link parsePsSnapshotDetailed}). A row whose `etime` does not parse is
+ * treated as malformed rather than returned with a null age: every returned row
+ * must carry a usable age, because age is a load-bearing gate here.
+ *
+ * @param {string|null|undefined} text
+ * @returns {{rows: PsRow[], malformed: number}}
+ */
+export function parsePsSnapshotDetailed(text) {
+  if (text === null || text === undefined) return { rows: [], malformed: 0 };
+  /** @type {PsRow[]} */
+  const rows = [];
+  let malformed = 0;
+  // Six whitespace-free fields, then `args` as the ENTIRE rest of the line —
+  // args legitimately contains spaces, so it must never be split.
+  const rowRe = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)(?:\s+(.*))?$/;
+  for (const raw of String(text).split(/\r?\n/)) {
+    if (raw.trim().length === 0) continue;
+    const m = rowRe.exec(raw);
+    if (!m) { malformed += 1; continue; }
+    const etimeSeconds = parseEtimeToSeconds(m[5]);
+    const cpuPct = parseFloat(m[6]);
+    if (etimeSeconds === null || Number.isNaN(cpuPct)) { malformed += 1; continue; }
+    rows.push({
+      pid: parseInt(m[1], 10),
+      ppid: parseInt(m[2], 10),
+      pgid: parseInt(m[3], 10),
+      rssKb: parseInt(m[4], 10),
+      etimeSeconds,
+      cpuPct,
+      args: m[7] ?? '',
+    });
+  }
+  return { rows, malformed };
+}
+
+/**
+ * {@link parsePsSnapshotDetailed} without the drop count.
+ * @param {string|null|undefined} text
+ * @returns {PsRow[]}
+ */
+export function parsePsSnapshot(text) {
+  return parsePsSnapshotDetailed(text).rows;
+}
+
+/**
+ * Default `ps` runner: the {@link PS_ARGS} call with a hard 2 s deadline,
+ * SIGKILL on overrun, and `null` on any failure. Never throws.
+ *
+ * Mirrors `runPsDetailed()` in `resource-probe/probe-platform.mjs` — the same
+ * spawn/settle/timeout shape, a different column set.
+ *
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string|null>}
+ */
+export function runPs(timeoutMs = PS_TIMEOUT_MS) {
+  return runPsArgs([...PS_ARGS], timeoutMs);
+}
+
+/**
+ * Default TARGETED `ps` runner (B3/B6): {@link psPidArgs} with the same hard
+ * deadline and the same `null`-on-any-failure contract as {@link runPs}.
+ *
+ * `ps -p <gone-pid>` exits NON-ZERO with empty stdout on macOS, which
+ * {@link runPsArgs} maps to `null` — so "gone" and "could not measure" arrive
+ * here as the same value. That is why the caller treats a `null` as UNMEASURED
+ * and refuses the signal, rather than reading it as proof of death: refusing on
+ * an absent measurement costs one skipped reap, believing it costs a bystander.
+ *
+ * @param {number} pid
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string|null>}
+ */
+export function runPsPid(pid, timeoutMs = PS_TIMEOUT_MS) {
+  if (!Number.isInteger(pid) || pid <= 0) return Promise.resolve(null);
+  return runPsArgs(psPidArgs(pid), timeoutMs);
+}
+
+/**
+ * Spawn `ps` with `args`, capped at `timeoutMs`, `null` on any failure.
+ * Never throws. Mirrors `runPsDetailed()` in `resource-probe/probe-platform.mjs`.
+ *
+ * @param {string[]} args
+ * @param {number} timeoutMs
+ * @returns {Promise<string|null>}
+ */
+function runPsArgs(args, timeoutMs) {
+  return new Promise((resolve) => {
+    if (process.platform === 'win32') { resolve(null); return; }
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    try {
+      const child = spawn('ps', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+      const chunks = [];
+      child.stdout.on('data', (c) => chunks.push(c));
+      child.on('error', () => finish(null));
+      child.on('close', (code) => {
+        if (code !== 0) return finish(null);
+        finish(Buffer.concat(chunks).toString('utf8'));
+      });
+      const timer = setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch { /* already gone */ }
+        finish(null);
+      }, timeoutMs);
+      timer.unref?.();
+    } catch {
+      finish(null);
+    }
+  });
+}

package/scripts/lib/orphan-reaper/reaper-audit.mjs

@@ -0,0 +1,323 @@
+/**
+ * orphan-reaper/reaper-audit.mjs — the B5 kill audit: its record shape, its
+ * writer, its bounded reader and pruner, and the HR-101 false-alarm rate the
+ * reader exists for.
+ */
+
+import { mkdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { replaceRegularFile } from '../process-group.mjs';
+import { readTailWindow } from '../tail-window.mjs';
+import { REAPER_DEFAULTS, underRepo } from './defaults.mjs';
+import { NOT_A_REGULAR_FILE, appendNoFollow } from './no-follow-append.mjs';
+
+/** Relative path of the JSONL kill audit (B5). Gitignored via `.gitignore:55`
+ *  (`.orchestrator/metrics/*.jsonl`), verified with `git check-ignore --no-index -v`.
+ *  Under the `ledger-delete-protected` policy rule: in-process fs only, never a
+ *  shell `rm`/`mv`. */
+export const REAPER_AUDIT_RELPATH = '.orchestrator/metrics/reaper-audit.jsonl';
+
+/**
+ * HR-101 ceiling: above this false-alarm rate the INSTRUMENT is suspect, and
+ * the answer is to re-aim it — never to raise the threshold it fires on. Surfaced
+ * as `instrumentSuspect` in the scan result; nothing in the reaper acts on it,
+ * because acting on a broken instrument is the failure it names.
+ */
+export const FALSE_ALARM_SUSPECT_RATE = 0.1;
+
+/** Characters of `args` copied into an audit record — and ONLY for a command
+ *  that already matched the read-only allowlist, so a foreign process's command
+ *  line (which may carry paths or tokens) never reaches the audit. */
+const ARGS_HEAD_CHARS = 80;
+
+/**
+ * Size ceiling of the audit file and what a prune keeps. Named ceiling (BV-004):
+ * a `kill` record with `args_head` and `result` serialises to 505 bytes, a
+ * `report` record to 285 (measured on {@link buildAuditRecord} output 2026-10-01;
+ * no real audit file existed on this host), so the kept 512 KiB hold ~1,000-1,800
+ * records against the 50 decisions the false-alarm window reads — fewer
+ * decisions where reports dominate: a scan re-reporting R processes keeps
+ * ~1,800/(R+1) of them, below 50 from R ≈ 35. Revisit if
+ * `reaper.false-alarm-window` is ever configured above ~1,000.
+ */
+const REAPER_AUDIT_MAX_BYTES = 1024 * 1024;
+const REAPER_AUDIT_KEEP_BYTES = 512 * 1024;
+
+/** First tail window {@link readAuditRecords} tries; it grows ×4 only while the
+ *  window holds fewer complete lines, or fewer rate decisions, than requested,
+ *  and never past {@link REAPER_AUDIT_MAX_BYTES}. */
+const AUDIT_TAIL_START_BYTES = 64 * 1024;
+
+/**
+ * Whether an audit record is one of the HR-101 rate's DECISIONS: the reaper
+ * judged a process a reapable orphan (`kill` | `dry-run` | `reject`). The one
+ * definition {@link readAuditRecords} (how far back to read) and
+ * {@link falseAlarmRate} (what to count) share — if they disagreed, the reader
+ * would stop growing at a population the rate does not count.
+ *
+ * @param {{decision?: unknown}|null|undefined} record
+ * @returns {boolean}
+ */
+function isRateDecision(record) {
+  const decision = record?.decision;
+  return decision === 'kill' || decision === 'dry-run' || decision === 'reject';
+}
+
+/** Absolute path of the kill audit for a repo. One constant per path.
+ *  @param {string} repoRoot @returns {string} */
+export function auditPath(repoRoot) {
+  return underRepo(repoRoot, REAPER_AUDIT_RELPATH);
+}
+
+/**
+ * Build one B5 audit record.
+ *
+ * Exactly ONE `trigger` per record, taken from the single verdict
+ * `decideReapCandidates` assigned at its fixed priority — a kill carries
+ * `orphan-ppid1`, a report carries the reason it was reported for. That is what
+ * makes "why exactly was this killed" answerable afterwards; a record listing
+ * two triggers would answer it with a shrug.
+ *
+ * `reason` is separate from `trigger` and present on every WITHDRAWAL: the
+ * trigger says what made this a candidate, the reason says what took it back.
+ * `args_head` is present ONLY for a command that cleared the read-only
+ * allowlist — see {@link ARGS_HEAD_CHARS}.
+ *
+ * @param {object} entry     A candidate or a reported/rejected entry.
+ * @param {'kill'|'report'|'reject'|'dry-run'} decision
+ * @param {object} [extra]
+ * @param {string} extra.timestamp
+ * @param {string|null} [extra.sessionId]
+ * @param {object} [extra.result]
+ * @param {string} [extra.reason]
+ * @returns {object}
+ */
+export function buildAuditRecord(entry, decision, {
+  timestamp, sessionId = null, result, reason,
+} = {}) {
+  /** @type {Record<string, unknown>} */
+  const record = {
+    timestamp,
+    session_id: sessionId,
+    pid: entry.pid,
+    pgid: entry.pgid ?? null,
+    trigger: entry.trigger ?? entry.reason ?? null,
+    threshold: entry.threshold ?? null,
+    actual: entry.actual ?? (typeof entry.ageSeconds === 'number' ? { ageSeconds: entry.ageSeconds } : null),
+    unit: 'seconds',
+    command_signature: entry.commandSignature ?? null,
+    decision,
+  };
+  if (typeof entry.args === 'string' && entry.args.length > 0) {
+    record.args_head = entry.args.slice(0, ARGS_HEAD_CHARS);
+  }
+  if (result !== undefined) record.result = result;
+  const effectiveReason = reason ?? (decision === 'report' ? entry.reason : undefined);
+  if (effectiveReason !== undefined && effectiveReason !== null) record.reason = effectiveReason;
+  return record;
+}
+
+/**
+ * Default audit sink: append one JSONL line to {@link REAPER_AUDIT_RELPATH}.
+ * In-process fs only (the path sits under the `ledger-delete-protected` policy
+ * rule). Best-effort — an audit write must never fail a scan — but a failure
+ * prints one WARN line rather than vanishing.
+ *
+ * Refuses a symlinked or non-regular audit exactly as {@link pruneReaperAudit}
+ * does: `appendFileSync(path)` follows a link, so `ln -s events.jsonl
+ * reaper-audit.jsonl` routed every kill record into the link target (CWE-59,
+ * #1487). The write goes through {@link appendNoFollow} (`no-follow-append.mjs`,
+ * shared with the gate-process ledger): an `O_NOFOLLOW|O_NONBLOCK` open plus an
+ * `fstat` of the opened descriptor, which also refuses a FIFO and a HARD-linked
+ * audit (`ln <victim> reaper-audit.jsonl` passes every symlink check, and each
+ * append then landed in the victim — reproduced 2026-10-02). That protects the
+ * append only: the scan child then READS the same path for the rate and opens
+ * it again to prune — both reads therefore go through `readTailWindow`'s
+ * `noFollow` open, the read-side twin. The prune's rewrite is immune to hard
+ * links — it renames a new inode over the name.
+ *
+ * @param {string} repoRoot
+ * @param {object} record
+ * @returns {void}
+ */
+export function appendAuditRecord(repoRoot, record) {
+  const target = auditPath(repoRoot);
+  try {
+    mkdirSync(path.dirname(target), { recursive: true });
+    appendNoFollow(target, `${JSON.stringify(record)}\n`);
+  } catch (err) {
+    process.stderr.write(`orphan-reaper: could not append to ${REAPER_AUDIT_RELPATH}: ${err?.message ?? String(err)}\n`);
+  }
+}
+
+/**
+ * Default audit READER — the other half of {@link appendAuditRecord}, and the
+ * data source {@link falseAlarmRate} needs (B5: "Dieselbe Datei ist die
+ * Datenquelle für `reaper.false-alarm-window`").
+ *
+ * Returns the parsed records of the newest `limit` non-empty lines, oldest
+ * first, EXTENDED BACKWARDS until they hold the newest `limit` rate decisions
+ * ({@link isRateDecision}) or reach the start of the file. `limit` is
+ * `reaper.false-alarm-window`, which counts DECISIONS; a line window let
+ * `report` records — re-written by every scan for every long-lived foreign or
+ * unattributed process — push the decisions out, so the rate was judged on the
+ * newest handful (measured on HEAD 3479e1bf: 30 scans of 4 reports + 1 decision,
+ * window 50 → n 10, rate 0 against a true 6/30; #1487). Widened, never
+ * narrowed: the newest `limit` lines are always the suffix of the result, so a
+ * caller that wanted lines still finds them there.
+ *
+ * Read from a tail window that grows ×4 only while it holds fewer than `limit`
+ * lines or decisions; the first line of a window that does not start at byte 0
+ * is a fragment and is dropped before anything is parsed. Named ceiling
+ * (BV-004): the window stops at {@link REAPER_AUDIT_MAX_BYTES} (1 MiB, ~3,700
+ * report records of 285 bytes) — the prune's own ceiling, enforced HERE rather
+ * than assumed from the prune, because the prune refuses a linked audit and
+ * runs only after this read (a 40 MB link target was read whole, 64 MB window,
+ * 293 MB RSS per scan — #1487). Decisions older than the newest 1 MiB are not
+ * read; revisit if that ceiling is raised.
+ *
+ * The open is `readTailWindow`'s `noFollow` form: a symlinked, FIFO or other
+ * non-regular audit reads as `[]` — refused like the writers refuse it — and a
+ * planted FIFO can no longer block the scan child in `open`.
+ *
+ * A malformed line is dropped from the rate's population rather than counted,
+ * because an unreadable record carries no decision to classify — and the rate
+ * reports its own `n`, so a shrinking population is visible in the number's
+ * denominator.
+ *
+ * @param {string} repoRoot
+ * @param {number} [limit]
+ * @returns {object[]} parsed records in chronological order; `[]` on any failure
+ */
+export function readAuditRecords(repoRoot, limit = REAPER_DEFAULTS.falseAlarmWindow) {
+  const target = auditPath(repoRoot);
+  const want = Math.max(1, limit);
+  let span;
+  try {
+    let windowBytes = AUDIT_TAIL_START_BYTES;
+    for (;;) {
+      const { text, cut } = readTailWindow(target, windowBytes, { noFollow: true });
+      const all = text.split('\n');
+      if (cut) all.shift();
+      span = newestSpan(all.filter((l) => l.trim().length > 0), want);
+      if (!cut || span.complete || windowBytes >= REAPER_AUDIT_MAX_BYTES) break;
+      windowBytes = Math.min(windowBytes * 4, REAPER_AUDIT_MAX_BYTES);
+    }
+  } catch {
+    return [];
+  }
+  return span.records;
+}
+
+/**
+ * Walk a window's complete lines newest-first until the walk has covered `want`
+ * lines AND `want` rate decisions — the population {@link readAuditRecords}
+ * documents. `complete: false` means the window ran out first.
+ *
+ * @param {string[]} lines  Complete, non-empty lines in file order.
+ * @param {number} want
+ * @returns {{records: object[], complete: boolean}} records in file order
+ */
+function newestSpan(lines, want) {
+  const newestFirst = [];
+  let taken = 0;
+  let decisions = 0;
+  for (let i = lines.length - 1; i >= 0 && (taken < want || decisions < want); i -= 1) {
+    taken += 1;
+    let parsed;
+    try {
+      parsed = JSON.parse(lines[i]);
+    } catch {
+      continue; // an unreadable line carries no decision to classify
+    }
+    if (!parsed || typeof parsed !== 'object') continue;
+    newestFirst.push(parsed);
+    if (isRateDecision(parsed)) decisions += 1;
+  }
+  return { records: newestFirst.reverse(), complete: taken >= want && decisions >= want };
+}
+
+/**
+ * Size-bounded prune of the audit: once the file passes `maxBytes`, rewrite it
+ * atomically with its newest `keepBytes`, cut at a line boundary. The same
+ * rewrite shape as `pruneGateProcessLedger` (`process-group.mjs`), the other
+ * ledger the scan's housekeeping prunes; the audit is pruned by SIZE rather than
+ * age because its population is a rolling window of decisions, not of days.
+ *
+ * Never throws; a failure — including a symlinked or non-regular audit, which
+ * is refused rather than written through — prints one WARN line and leaves the
+ * file as it was.
+ * Named ceiling (BV-004): an append that lands between the read and the write
+ * is lost — a window of one read + one write, once per ~0.5 MB of audit.
+ *
+ * @param {string} repoRoot
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes]
+ * @param {number} [opts.keepBytes]
+ * @returns {number} bytes removed; 0 when nothing was pruned
+ */
+export function pruneReaperAudit(repoRoot, {
+  maxBytes = REAPER_AUDIT_MAX_BYTES,
+  keepBytes = REAPER_AUDIT_KEEP_BYTES,
+} = {}) {
+  const target = auditPath(repoRoot);
+  let size;
+  try {
+    size = statSync(target).size;
+  } catch {
+    return 0;
+  }
+  if (size <= maxBytes) return 0;
+  try {
+    // `noFollow`: `statSync` above follows a link, so without it the prune read
+    // a linked target's tail before `replaceRegularFile` refused the write.
+    const { text, cut } = readTailWindow(target, Math.min(keepBytes, maxBytes), { noFollow: true });
+    // A cut window starts mid-record; with no newline at all it is ONE record
+    // larger than the window, and keeping any part of it would keep a fragment.
+    const newline = text.indexOf('\n');
+    const kept = !cut ? text : (newline === -1 ? '' : text.slice(newline + 1));
+    replaceRegularFile(target, kept);
+    return size - Buffer.byteLength(kept, 'utf8');
+  } catch (err) {
+    const why = err?.code === 'ELOOP' || err?.code === 'ERR_NOT_REGULAR_FILE'
+      ? NOT_A_REGULAR_FILE
+      : (err?.message ?? String(err));
+    process.stderr.write(`orphan-reaper: could not prune ${REAPER_AUDIT_RELPATH}: ${why}\n`);
+    return 0;
+  }
+}
+
+/**
+ * False-alarm rate over the last `windowSize` audit decisions — the HR-101
+ * instrument-health check ("a signal may only warn if it is rare"; above ~10%
+ * the instrument is broken and gets re-aimed, never re-thresholded).
+ *
+ * POPULATION (the number's denominator, stated because a rate without one is a
+ * claim): audit records where the reaper judged a process a reapable orphan —
+ * `decision` in `kill` | `dry-run` | `reject` ({@link isRateDecision}, the same
+ * predicate {@link readAuditRecords} reads back far enough for). `report`
+ * records are excluded: reporting a foreign or non-read-only process is the
+ * correct outcome, not a firing of the kill signal.
+ *
+ * FALSE ALARM: a record where that judgement was refuted afterwards —
+ * `decision: 'reject'` (the identity re-check withdrew the candidate) or a kill
+ * whose `result.ok` is false (the signal did not take effect).
+ *
+ * Returns `{rate: null}` below 10 records: a rate over a handful of decisions
+ * says nothing, and `null` is distinguishable from a measured 0 (a missing
+ * measurement must never look like a zero).
+ *
+ * @param {object[]} auditRecords  In chronological order; the LAST `windowSize` are used.
+ * @param {number} [windowSize]
+ * @returns {{rate: number|null, n: number}}
+ */
+export function falseAlarmRate(auditRecords, windowSize = REAPER_DEFAULTS.falseAlarmWindow) {
+  const all = Array.isArray(auditRecords) ? auditRecords : [];
+  const firings = all.filter(isRateDecision);
+  const window = windowSize > 0 ? firings.slice(-windowSize) : firings;
+  const n = window.length;
+  if (n < 10) return { rate: null, n };
+  const falseAlarms = window.filter((r) => r.decision === 'reject' || r?.result?.ok === false).length;
+  return { rate: falseAlarms / n, n };
+}