session-orchestrator 5.4.0 → 5.5.0

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

@@ -4,19 +4,13 @@
  * reader exists for.
  */
 
-import {
-  appendFileSync,
-  lstatSync,
-  mkdirSync,
-  renameSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
+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`.
@@ -42,16 +36,34 @@ const ARGS_HEAD_CHARS = 80;
  * 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
- * decisions against the 50 the false-alarm window reads. Revisit if
+ * 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 than requested. */
+ *  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) {
@@ -112,6 +124,19 @@ export function buildAuditRecord(entry, decision, {
  * 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}
@@ -120,11 +145,9 @@ export function appendAuditRecord(repoRoot, record) {
   const target = auditPath(repoRoot);
   try {
     mkdirSync(path.dirname(target), { recursive: true });
-    appendFileSync(target, `${JSON.stringify(record)}\n`, 'utf8');
+    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`,
-    );
+    process.stderr.write(`orphan-reaper: could not append to ${REAPER_AUDIT_RELPATH}: ${err?.message ?? String(err)}\n`);
   }
 }
 
@@ -133,13 +156,30 @@ export function appendAuditRecord(repoRoot, record) {
  * data source {@link falseAlarmRate} needs (B5: "Dieselbe Datei ist die
  * Datenquelle für `reaper.false-alarm-window`").
  *
- * Returns the parsed records among the LAST `limit` non-empty lines, oldest
- * first — the same population a whole-file read sliced to `limit` lines yields,
- * read from a tail window instead. The window grows only while it holds fewer
- * complete lines than `limit`, so records larger than expected cannot shrink the
- * population; {@link pruneReaperAudit} bounds the worst case at the whole file.
- * The first line of a window that does not start at byte 0 is a fragment and is
- * dropped before anything is parsed.
+ * 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
@@ -153,61 +193,49 @@ export function appendAuditRecord(repoRoot, record) {
 export function readAuditRecords(repoRoot, limit = REAPER_DEFAULTS.falseAlarmWindow) {
   const target = auditPath(repoRoot);
   const want = Math.max(1, limit);
-  let lines;
+  let span;
   try {
     let windowBytes = AUDIT_TAIL_START_BYTES;
     for (;;) {
-      const { text, cut } = readTailWindow(target, windowBytes);
+      const { text, cut } = readTailWindow(target, windowBytes, { noFollow: true });
       const all = text.split('\n');
       if (cut) all.shift();
-      lines = all.filter((l) => l.trim().length > 0);
-      if (!cut || lines.length >= want) break;
-      windowBytes *= 4;
+      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 [];
   }
-  const records = [];
-  for (const line of lines.slice(-want)) {
-    try {
-      const parsed = JSON.parse(line);
-      if (parsed && typeof parsed === 'object') records.push(parsed);
-    } catch {
-      /* an unreadable line carries no decision to classify */
-    }
-  }
-  return records;
+  return span.records;
 }
 
 /**
- * Replace the audit atomically: write `<target>.tmp-<pid>` beside it, then
- * rename over it. Throws instead of writing when the target is a symlink or not
- * a regular file. `writeFileSync(target)` would truncate first — a scan child
- * killed between truncate and write left the "why was this killed" record empty
- * — and would write THROUGH a symlink, cutting e.g. a linked `events.jsonl` to
- * 512 KiB (CWE-59, reproduced 2026-10-01). `rename` replaces the link itself,
- * and `wx` refuses a pre-planted file or link at the tmp name. The same few
- * lines as `process-group.mjs`'s `replaceRegularFile`, kept local because that
- * module is not this one's to depend on for a file write.
+ * 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} target
- * @param {string} body
+ * @param {string[]} lines  Complete, non-empty lines in file order.
+ * @param {number} want
+ * @returns {{records: object[], complete: boolean}} records in file order
  */
-function replaceRegularFile(target, body) {
-  if (!lstatSync(target).isFile()) {
-    throw new Error('not a regular file (a symlink is never written through) — left untouched');
-  }
-  const tmp = `${target}.tmp-${process.pid}`;
-  try {
-    writeFileSync(tmp, body, { encoding: 'utf8', flag: 'wx' });
-    renameSync(tmp, target);
-  } catch (err) {
-    // EEXIST: the tmp name belongs to someone else — never remove it.
-    if (err?.code !== 'EEXIST') {
-      try { unlinkSync(tmp); } catch { /* nothing was created */ }
+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
     }
-    throw err;
+    if (!parsed || typeof parsed !== 'object') continue;
+    newestFirst.push(parsed);
+    if (isRateDecision(parsed)) decisions += 1;
   }
+  return { records: newestFirst.reverse(), complete: taken >= want && decisions >= want };
 }
 
 /**
@@ -242,7 +270,9 @@ export function pruneReaperAudit(repoRoot, {
   }
   if (size <= maxBytes) return 0;
   try {
-    const { text, cut } = readTailWindow(target, Math.min(keepBytes, maxBytes));
+    // `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');
@@ -250,9 +280,10 @@ export function pruneReaperAudit(repoRoot, {
     replaceRegularFile(target, kept);
     return size - Buffer.byteLength(kept, 'utf8');
   } catch (err) {
-    process.stderr.write(
-      `orphan-reaper: could not prune ${REAPER_AUDIT_RELPATH}: ${err?.message ?? String(err)}\n`,
-    );
+    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;
   }
 }
@@ -264,9 +295,10 @@ export function pruneReaperAudit(repoRoot, {
  *
  * 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`. `report` records are excluded:
- * reporting a foreign or non-read-only process is the correct outcome, not a
- * firing of the kill signal.
+ * `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
@@ -282,7 +314,7 @@ export function pruneReaperAudit(repoRoot, {
  */
 export function falseAlarmRate(auditRecords, windowSize = REAPER_DEFAULTS.falseAlarmWindow) {
   const all = Array.isArray(auditRecords) ? auditRecords : [];
-  const firings = all.filter((r) => r && (r.decision === 'kill' || r.decision === 'dry-run' || r.decision === 'reject'));
+  const firings = all.filter(isRateDecision);
   const window = windowSize > 0 ? firings.slice(-windowSize) : firings;
   const n = window.length;
   if (n < 10) return { rate: null, n };

package/scripts/lib/orphan-reaper/scan-throttle.mjs

@@ -1,13 +1,15 @@
 /**
- * orphan-reaper/scan-throttle.mjs — the B4 throttle the two trigger hooks call.
+ * orphan-reaper/scan-throttle.mjs — the B4 throttle the trigger calls.
  *
- * This is the reaper's only hot-path surface: `hooks/on-stop.mjs` and
- * `hooks/post-tool-batch-wave-signal.mjs` import THIS module, not the scan, so a
- * tool batch pays for one `stat` and two tiny modules — never for the ledger,
- * `ps` or kill-ladder code the detached scan child loads.
+ * Together with `trigger.mjs` this is the reaper's only hot-path surface:
+ * `hooks/on-stop.mjs` and `hooks/post-tool-batch-wave-signal.mjs` reach THIS
+ * module (lazily, via `trigger.mjs`), not the scan, so a tool batch pays for one
+ * `stat` and a few tiny modules — never for the ledger, `ps` or kill-ladder code
+ * the detached scan child loads.
  */
 
-import { lstatSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { lstatSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { REAPER_DEFAULTS, underRepo } from './defaults.mjs';
@@ -24,40 +26,78 @@ export const SCAN_MARKER_RELPATH = '.orchestrator/tmp/reaper-last-scan';
  * file. Writing the marker is the CALLER's job ({@link touchScanMarker}), so
  * this stays a read-only predicate a hook can call cheaply.
  *
+ * `lstat`, never `stat`: a symlinked (or otherwise non-regular) marker is not
+ * one {@link touchScanMarker} wrote, and `stat` read the TARGET's mtime — so a
+ * link to any often-written file (`events.jsonl`) throttled every scan for good
+ * (#1487). Such a marker counts as absent, i.e. "scan" — and that scan's stamp
+ * replaces a link with a regular marker, so the next fire throttles again
+ * ({@link touchScanMarker}). Counting it as absent is the fail-safe
+ * direction for this throttle: too many scans cost one detached child per hook
+ * fire — visible in the process table, and in the `scan_completed` rate
+ * whenever a scan finds anything — in an opt-in state (`reaper.enabled`
+ * defaults false); too few silently disable the reaper, whose
+ * orphans were measured at 86-588 % CPU and up to 8 GB RSS (HR-107), and a
+ * disabled reaper is a state nothing can falsify (HR-105).
+ *
  * @param {string} markerPath   Absolute path — build it with {@link scanMarkerPath}.
  * @param {number} nowMs
  * @param {number} [minIntervalSeconds]
  * @param {object} [opts]
- * @param {(p: string) => {mtimeMs: number}} [opts.statFn]
+ * @param {(p: string) => {mtimeMs: number, isFile?: () => boolean}} [opts.statFn]
+ *   Defaults to `lstatSync`; an injected stat without `isFile` skips the
+ *   regular-file check (test seam).
  * @returns {boolean}
  */
 export function shouldScanNow(markerPath, nowMs, minIntervalSeconds = REAPER_DEFAULTS.minScanIntervalSeconds, {
-  statFn = statSync,
+  statFn = lstatSync,
 } = {}) {
   if (typeof markerPath !== 'string' || markerPath.length === 0) return false;
-  let mtimeMs;
+  let stats;
   try {
-    mtimeMs = statFn(markerPath)?.mtimeMs;
+    stats = statFn(markerPath);
   } catch {
     return true; // no marker yet → first scan
   }
+  if (typeof stats?.isFile === 'function' && !stats.isFile()) return true;
+  const mtimeMs = stats?.mtimeMs;
   if (typeof mtimeMs !== 'number' || Number.isNaN(mtimeMs)) return true;
+  // A marker stamped in the future (`touch -t`, a clock stepped backwards) made
+  // the age negative, so every fire read "too soon" — and the marker is only
+  // re-stamped AFTER a scan, so the reaper never scanned again (#1487). Fail
+  // toward a scan, the same direction as every other unreadable marker here.
+  if (mtimeMs > nowMs) return true;
   return (nowMs - mtimeMs) >= minIntervalSeconds * 1000;
 }
 
 /**
  * Stamp the throttle marker. Best-effort and never throws — a marker that could
  * not be written means the next scan runs, which is the safe direction for a
- * read-only probe.
+ * read-only probe (the reasoning is on {@link shouldScanNow}). Callers must not
+ * read a `false` as a stamped throttle: `maybeTriggerOrphanScan`
+ * (`trigger.mjs`) returns it as `reason: 'spawned-unthrottled'`, and
+ * `hooks/on-stop.mjs` records that reason as `reaper_trigger` on its
+ * Stop/SubagentStop records — so an unwritable marker is countable in
+ * events.jsonl, not only visible as one detached scan child per hook fire.
+ *
+ * Written to a sibling tmp file, then renamed over the marker path. A rename
+ * replaces the directory ENTRY and never follows a symlink sitting there, so a
+ * planted or accidental link is healed by the next stamp — not written through
+ * (CWE-59: `writeFileSync` on the marker replaced the link's target), and not
+ * refused either: refusing it returned `false` on every fire, which switched the
+ * throttle off for good (#1489 Pkt 9). With no lstat-then-write step there is no
+ * check-to-use window left. The tmp name carries pid + random bytes and is
+ * opened `wx` (O_EXCL), so anything already at that name fails the stamp
+ * instead of being written through; a tmp this call created is removed again
+ * when the rename fails, or every failed fire would leave one behind.
  *
- * A marker path that is a symlink or not a regular file is left alone and
- * reported as not written: `writeFileSync` follows a link, so a marker linked to
- * any file would overwrite that file on every hook (CWE-59). Silent, like every
- * other failure here — this runs inside a 50 ms hook budget.
- * Named ceiling (BV-004): lstat-then-write leaves a check-to-use window of one
- * syscall; a link planted inside it is still written through. Acceptable for a
- * gitignored throttle stamp; revisit (O_NOFOLLOW open) if the marker ever
- * carries data.
+ * A DIRECTORY at the marker path is the one shape that stays unhealed: a rename
+ * cannot replace it (EISDIR), and removing it would delete content this module
+ * never wrote. It stays `false`. Silent, like every other failure here — this
+ * runs inside a 50 ms hook budget.
+ * Named ceiling (BV-004): the PARENT path is resolved normally, so a symlinked
+ * `.orchestrator/tmp/` puts the marker into the link's target directory, where
+ * it can replace only an entry of its own name. Acceptable for a gitignored
+ * throttle stamp; revisit if the marker ever carries data.
  *
  * @param {string} markerPath
  * @param {object} [opts]
@@ -66,25 +106,37 @@ export function shouldScanNow(markerPath, nowMs, minIntervalSeconds = REAPER_DEF
  */
 export function touchScanMarker(markerPath, { writeFn } = {}) {
   try {
+    const stamp = `${new Date().toISOString()}\n`;
     if (writeFn) {
-      writeFn(markerPath, `${new Date().toISOString()}\n`);
+      writeFn(markerPath, stamp);
       return true;
     }
-    let existing = null;
+    mkdirSync(path.dirname(markerPath), { recursive: true });
+    const tmp = `${markerPath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+      writeFileSync(tmp, stamp, { encoding: 'utf8', flag: 'wx' });
+    } catch (err) {
+      // EEXIST: the `wx` open was refused, so the entry at `tmp` is not ours.
+      if (err?.code !== 'EEXIST') removeOwnTmp(tmp);
+      return false;
+    }
     try {
-      existing = lstatSync(markerPath);
+      renameSync(tmp, markerPath);
+      return true;
     } catch {
-      /* no marker yet — the first stamp creates it */
+      removeOwnTmp(tmp);
+      return false;
     }
-    if (existing && !existing.isFile()) return false;
-    mkdirSync(path.dirname(markerPath), { recursive: true });
-    writeFileSync(markerPath, `${new Date().toISOString()}\n`, 'utf8');
-    return true;
   } catch {
     return false;
   }
 }
 
+/** Best-effort removal of a tmp file {@link touchScanMarker} created. @param {string} tmp */
+function removeOwnTmp(tmp) {
+  try { unlinkSync(tmp); } catch { /* never created, or already gone */ }
+}
+
 /** Absolute path of the throttle marker for a repo. One constant per path.
  *  @param {string} repoRoot @returns {string} */
 export function scanMarkerPath(repoRoot) {

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

@@ -243,6 +243,10 @@ export async function runOrphanScan({
   } catch {
     return empty('ledger-unreadable', malformed);
   }
+  // The default reader never throws: a refused or unreadable ledger comes back
+  // as no records with `state: 'unreadable'` (#1498). Read as "no register
+  // hits" it ran a clean-looking scan that measured nothing.
+  if (ledger?.state === 'unreadable') return empty('ledger-unreadable', malformed);
 
   let ownSessionId = null;
   try {

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

@@ -0,0 +1,173 @@
+/**
+ * orphan-reaper/trigger.mjs — the B4 trigger both hooks call (#1432 B4).
+ *
+ * `hooks/on-stop.mjs` (Stop + SubagentStop) and
+ * `hooks/post-tool-batch-wave-signal.mjs` (PostToolBatch) are the two trigger
+ * points the PRD declares. Until 2026-10-02 each carried its own verbatim copy
+ * of this code (138 identical lines, one comment apart, measured by diffing the
+ * blocks); the copies are now this one module (#1489).
+ *
+ * Its own file rather than part of `scan-throttle.mjs`, for two closures:
+ *  - `scan-throttle.mjs` is re-exported by the detached scan CLI
+ *    (`scripts/lib/orphan-reaper.mjs`); putting the trigger there would load the
+ *    config parser and `platform.mjs` into every scan child for nothing.
+ *  - The throttle stays a LAZY import below, so a host with the reaper disabled
+ *    (the default) pays for one config read and no throttle module at all.
+ */
+
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
+
+import { _parseReaper } from '../config/reaper.mjs';
+import { getProjectDir } from '../platform.mjs';
+
+/**
+ * Filesystem path of the scan CLI, spawned as a PLAIN argv call.
+ *
+ * It used to be a `file://` URL handed to `node --input-type=module -e
+ * <program>`, because `scripts/lib/orphan-reaper.mjs` had no entry guard. It
+ * has one now (`parseReaperCliArgs` + the `isMainModule` tail), so the child's
+ * contract lives in that module instead of as source text duplicated here —
+ * and nothing this trigger builds is a program any more: every variable part is
+ * an argv value, which cannot become code whatever the checkout path contains.
+ *
+ * `fileURLToPath`, not `new URL(...).pathname`: the latter leaves a
+ * percent-encoded path for any checkout directory containing a space.
+ */
+const ORPHAN_REAPER_SCRIPT = fileURLToPath(new URL('../orphan-reaper.mjs', import.meta.url));
+
+/**
+ * Read the `reaper:` block from the project's Session Config host file.
+ * Sync + inline, mirroring `hooks/loop-guard.mjs` `loadConfig()` — a hot hook
+ * path must not import the full config orchestrator. A missing or unreadable
+ * file yields the parser defaults, i.e. DISABLED.
+ *
+ * @param {string} projectDir
+ * @returns {ReturnType<typeof _parseReaper>}
+ */
+function loadReaperConfig(projectDir) {
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    try {
+      return _parseReaper(readFileSync(path.join(projectDir, name), 'utf8'));
+    } catch {
+      // missing or unreadable — try the next candidate
+    }
+  }
+  return _parseReaper('');
+}
+
+/**
+ * Trigger the orphan scan, throttled and NON-BLOCKING (PRD FA4).
+ *
+ * The hook itself does exactly two pieces of I/O — one config read and one
+ * `stat` of the throttle marker — and then hands the work to a DETACHED,
+ * unref'd child. The scan is never run inline: one `ps` round-trip out of Node
+ * was measured at ~47 ms over 287 KB of output, which alone would blow the
+ * 50 ms `reaper.max-hook-latency-ms` budget this hook has to stay inside.
+ *
+ * The marker is stamped BEFORE the spawn, so a spawn that fails still consumes
+ * the throttle window — otherwise a broken spawn would be retried on every
+ * single tool batch.
+ *
+ * `reaper.max-hook-latency-ms` is the ceiling on the work above — measured here
+ * with `performance.now()` and reported as ONE stderr WARN line when exceeded.
+ * A WARN and not an event: this fires from a `PostToolBatch`-class hook, and a
+ * per-fire telemetry record is exactly the always-on signal
+ * `.claude/rules/host-resources.md` HR-101 calls a broken instrument. The
+ * measurement covers preparation only — the scan itself runs detached, which is
+ * the whole reason the budget can be held.
+ *
+ * Never throws: any failure degrades silently (PRD FA4 "lautlos degradieren").
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir]  Repo root; defaults to `getProjectDir()`.
+ * @param {number} [opts.now]         Injected clock (ms).
+ * @param {Function} [opts.spawnFn]   Injected `spawn` (tests).
+ * @param {Function} [opts.statFn]    Injected marker `lstatSync` (tests).
+ * @param {Function} [opts.writeFn]   Injected marker writer (tests).
+ * @param {() => number} [opts.clockFn]  Injected monotonic clock for the latency
+ *   budget (tests); defaults to `performance.now`.
+ * @returns {Promise<{spawned: boolean, reason: string}>} `reason` is one of
+ *   `'disabled' | 'throttled' | 'spawned' | 'spawned-unthrottled' | 'error'`.
+ *   `'spawned-unthrottled'` means the scan ran but the marker could not be
+ *   stamped — the next fire will scan again, and the result must not read like
+ *   a throttled spawn. `hooks/on-stop.mjs` records `reason` as `reaper_trigger`
+ *   on its per-turn and per-agent records (HR-105: a signal nothing records is
+ *   unfalsifiable); the PostToolBatch hook does not, because the marker is one
+ *   file per repo — a defeated marker shows on the very next Stop record, and a
+ *   per-batch record is the HR-101 shape the WARN above already refuses.
+ */
+export async function maybeTriggerOrphanScan({
+  projectDir,
+  now,
+  spawnFn = spawn,
+  statFn,
+  writeFn,
+  clockFn = () => performance.now(),
+} = {}) {
+  const startedAt = clockFn();
+  /** One WARN line when the preparation overran `reaper.max-hook-latency-ms`. */
+  const checkLatency = (budgetMs) => {
+    const elapsed = clockFn() - startedAt;
+    if (Number.isFinite(budgetMs) && budgetMs > 0 && elapsed > budgetMs) {
+      process.stderr.write(
+        `orphan-reaper trigger: hook latency ${elapsed.toFixed(1)} ms exceeded `
+        + `reaper.max-hook-latency-ms (${budgetMs} ms)\n`,
+      );
+    }
+  };
+  let root;
+  try {
+    root = typeof projectDir === 'string' && projectDir ? projectDir : getProjectDir();
+  } catch {
+    // No project dir, no config to read (#1498): `process.cwd()` throws ENOENT
+    // when the hook starts in a deleted directory with no `*_PROJECT_DIR` set.
+    // That is an unreadable config — the parser defaults, DISABLED — and not a
+    // failure of an armed reaper, so it must not surface as `error`: on-stop
+    // stamps `reaper_trigger` only for a reaper that is enabled.
+    return { spawned: false, reason: 'disabled' };
+  }
+  try {
+    const cfg = loadReaperConfig(root);
+    // Cheapest gate first: disabled means no stat, no spawn, no module load.
+    if (cfg.enabled !== true) return { spawned: false, reason: 'disabled' };
+
+    // The throttle module only — the scan's ledger, `ps` and kill-ladder code
+    // load in the detached child, never on this hook path (#1437).
+    const reaper = await import('./scan-throttle.mjs');
+    const markerPath = reaper.scanMarkerPath(root);
+    const nowMs = typeof now === 'number' ? now : Date.now();
+
+    if (!reaper.shouldScanNow(markerPath, nowMs, cfg['min-scan-interval-seconds'], { statFn })) {
+      checkLatency(cfg['max-hook-latency-ms']);
+      return { spawned: false, reason: 'throttled' };
+    }
+    // An unwritable marker does not cancel the scan — the throttle fails toward
+    // scanning (see shouldScanNow) — but the result says the throttle is off.
+    // No output: this runs on every hook fire (each tool batch, each Stop) in
+    // every session on the host.
+    const stamped = reaper.touchScanMarker(markerPath, { writeFn });
+
+    const child = spawnFn(
+      process.execPath,
+      [
+        ORPHAN_REAPER_SCRIPT,
+        '--repo-root', root,
+        '--mode', cfg.mode,
+        '--min-age-seconds', String(cfg['min-age-seconds']),
+        '--kill-grace-ms', String(cfg['kill-grace-ms']),
+        '--verify-wait-ms', String(cfg['verify-wait-ms']),
+        '--false-alarm-window', String(cfg['false-alarm-window']),
+      ],
+      { detached: true, stdio: 'ignore' },
+    );
+    if (child && typeof child.unref === 'function') child.unref();
+    checkLatency(cfg['max-hook-latency-ms']);
+    return { spawned: true, reason: stamped ? 'spawned' : 'spawned-unthrottled' };
+  } catch {
+    return { spawned: false, reason: 'error' };
+  }
+}

package/scripts/lib/orphan-reaper.mjs

@@ -25,7 +25,11 @@
  * trigger hooks spawn. The implementation lives in `orphan-reaper/`:
  *
  *   defaults.mjs       `REAPER_DEFAULTS` + the repo-path join (node:path only)
- *   scan-throttle.mjs  B4 throttle marker — the trigger hooks import THIS
+ *   trigger.mjs        `maybeTriggerOrphanScan` — the ONE trigger both hooks
+ *                      import; deliberately NOT re-exported here, so this CLI's
+ *                      closure stays free of the config parser and platform.mjs
+ *   scan-throttle.mjs  B4 throttle marker — loaded lazily by trigger.mjs
+ *   no-follow-append.mjs  the O_NOFOLLOW|O_NONBLOCK append both ledgers share
  *   ps-snapshot.mjs    the binding `ps` format, its parser and runners
  *   reaper-decide.mjs  the PURE candidate decision and its identity checks
  *   reaper-audit.mjs   B5 audit record, writer, bounded reader, pruner, HR-101 rate