session-orchestrator 5.3.0 → 5.5.0

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

@@ -0,0 +1,510 @@
+/**
+ * orphan-reaper/scan.mjs — one orphan scan end to end: `ps` → decide → (unless
+ * `dryRun`) re-verify identity before every signal → kill the group → audit.
+ *
+ * The IMPURE half of the reaper. Everything impure reaches the pure decision
+ * (`reaper-decide.mjs`) through `deps` ({@link resolveDeps}), the
+ * `lock-reaper.mjs` split of `evaluateRepo()` / `archiveLock()`.
+ */
+
+import {
+  killProcessGroup,
+  pruneGateProcessLedger,
+  readGateProcessLedger,
+  verifyProcessIdentity,
+} from '../process-group.mjs';
+import { REAPER_DEFAULTS } from './defaults.mjs';
+import { parsePsSnapshot, parsePsSnapshotDetailed, runPs, runPsPid } from './ps-snapshot.mjs';
+import {
+  FALSE_ALARM_SUSPECT_RATE,
+  appendAuditRecord,
+  buildAuditRecord,
+  falseAlarmRate,
+  pruneReaperAudit,
+  readAuditRecords,
+} from './reaper-audit.mjs';
+import { decideReapCandidates, verifyGroupMemberIdentity } from './reaper-decide.mjs';
+
+/** Name const for the one event this module emits. @see docs/events-schema.md */
+export const REAPER_SCAN_EVENT = 'orchestrator.reaper.scan_completed';
+
+/** Default own-session-id reader. Lazily imported so the static import closure
+ *  of this module stays small — it is destined for a hot-path hook (#1432).
+ *  @param {string} repoRoot @returns {Promise<string|null>} */
+async function defaultReadOwnSessionId(repoRoot) {
+  try {
+    const mod = await import('../session-identity/own-session.mjs');
+    const ids = mod.readOwnSessionIds(repoRoot);
+    for (const id of ids) return id;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Default live-peer probe. Lazily imported for the same reason as
+ * {@link defaultReadOwnSessionId}.
+ *
+ * Returns `null` — never `[]` — when the registry cannot be read. The two mean
+ * opposite things to `decideReapCandidates`: `[]` is a MEASUREMENT ("no
+ * peer is alive", so a foreign session's leftovers are reapable), `null` is the
+ * absence of one ("report it, do not touch it").
+ *
+ * @param {string|null} sessionId
+ * @returns {Promise<string[]|null>}
+ */
+async function defaultDetectPeers(sessionId) {
+  try {
+    const mod = await import('../session-registry.mjs');
+    const peers = await mod.detectPeers({ sessionId: sessionId ?? undefined });
+    if (!Array.isArray(peers)) return null;
+    return peers.map((p) => p?.session_id).filter((v) => typeof v === 'string' && v.length > 0);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Default event emitter. Lazily imported for the same reason as
+ * {@link defaultReadOwnSessionId}: `events.mjs` pulls in the schema validator,
+ * the attribution chain and the webhook client, and this module is destined for
+ * a hot-path hook (#1432) whose static import closure is measured.
+ *
+ * Never throws and never rejects — telemetry that can fail a scan would fail the
+ * hook the scan runs in.
+ *
+ * @param {string} type
+ * @param {object} payload
+ * @param {{repoRoot?: string}} [opts]
+ * @returns {Promise<boolean>} whether the record was written
+ */
+async function defaultEmitEvent(type, payload, opts = {}) {
+  try {
+    const mod = await import('../events.mjs');
+    await mod.emitEvent(type, payload, opts);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** @param {number} ms @returns {Promise<void>} */
+function defaultSleep(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+/**
+ * Resolve the adapter, defaulting every seam to the real implementation — the
+ * `resolveDeps()` pattern from `lock-reaper.mjs:77-100`.
+ *
+ * `killProcessGroup` HAS a real default, and that is safe only because
+ * {@link runOrphanScan} defaults `dryRun: true`. Tests ALWAYS inject it
+ * (`.claude/rules/testing.md`: never a real process as a kill target).
+ *
+ * @param {object} [deps]
+ * @returns {object}
+ */
+export function resolveDeps(deps = {}) {
+  const d = deps ?? {};
+  return {
+    runPs: d.runPs ?? runPs,
+    runPsPid: d.runPsPid ?? runPsPid,
+    readLedger: d.readLedger ?? readGateProcessLedger,
+    verifyIdentity: d.verifyIdentity ?? verifyProcessIdentity,
+    killProcessGroup: d.killProcessGroup ?? killProcessGroup,
+    detectPeers: d.detectPeers ?? defaultDetectPeers,
+    readOwnSessionId: d.readOwnSessionId ?? defaultReadOwnSessionId,
+    appendAudit: d.appendAudit ?? appendAuditRecord,
+    readAuditRecords: d.readAuditRecords ?? readAuditRecords,
+    emitEvent: d.emitEvent ?? defaultEmitEvent,
+    now: d.now ?? Date.now,
+    sleep: d.sleep ?? defaultSleep,
+  };
+}
+
+/**
+ * Map an identity verdict's reason to the audit's `reason` vocabulary.
+ *
+ * Three outcomes, never two: `gone` (measured, the process is not there),
+ * `signature-mismatch` / `identity-mismatch` (measured, it is a DIFFERENT
+ * process) and `unmeasured` (the probe itself could not answer). The third is
+ * the one a two-state mapping loses, and losing it is how an absent measurement
+ * starts reading like a clean verdict.
+ *
+ * @param {string|null|undefined} identityReason
+ * @returns {'gone'|'signature-mismatch'|'identity-mismatch'|'unmeasured'}
+ */
+function rejectReasonFor(identityReason) {
+  if (identityReason === 'gone') return 'gone';
+  if (identityReason === 'unmeasured') return 'unmeasured';
+  if (identityReason === 'signature-mismatch') return 'signature-mismatch';
+  return 'identity-mismatch';
+}
+
+/**
+ * Run one orphan scan: `ps` → decide → (unless `dryRun`) re-verify identity
+ * against a FRESH snapshot → kill the group → audit.
+ *
+ * NO-THROW contract: every failure degrades into `skipped: '<reason>'` or a
+ * `rejected` entry, because this runs from a hook and must never fail it
+ * (PRD FA4: "bei jedem Fehler degradiert er lautlos").
+ *
+ * The pre-signal re-check is the TOCTOU defence and the whole point of FA3: a
+ * PID recycled between decision and signal must NOT be signalled. It runs a
+ * TARGETED `ps` (`psPidArgs`, `ps-snapshot.mjs`) through `deps.runPsPid` and feeds the row to
+ * {@link verifyProcessIdentity} — immediately before SIGTERM **and** immediately
+ * before SIGKILL, via `killProcessGroup`'s `beforeSignal` gate, because the
+ * ladder's 10 s grace is itself a recycling window. On any mismatch no further
+ * signal is sent and the candidate is recorded as `decision: 'reject'` with the
+ * reason that withdrew it. Such a candidate stays in `candidates` (that WAS the
+ * decision) and additionally appears in `rejected` (that is the withdrawal) —
+ * the two arrays answer different questions and collapsing them would lose the
+ * TOCTOU event.
+ *
+ * Success is proven the same way, never from an exit code: after the ladder the
+ * scan waits `verifyWaitMs` and re-measures (B6). `ok` is true only for a
+ * process that is GONE; one that outlived SIGKILL is booked
+ * `survivedSigkill: true`, and one the probe could not measure is `verified:
+ * 'unmeasured'` — neither is ever a success.
+ *
+ * `dryRun` defaults to TRUE: arming happens at the CALL SITE (#1432), so a
+ * caller that forgets the flag scans and reports instead of killing.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot
+ * @param {number} [opts.now]
+ * @param {boolean} [opts.dryRun]
+ * @param {object} [opts.deps]
+ * @param {number} [opts.minAgeSeconds]
+ * @param {number} [opts.killGraceMs]
+ * @param {number} [opts.verifyWaitMs]
+ * @param {number} [opts.falseAlarmWindow]  Rolling window of audit DECISIONS the
+ *   HR-101 rate is judged over (`reaper.false-alarm-window`).
+ * @returns {Promise<{scanned: number, candidates: object[], reported: object[],
+ *   rejected: object[], killed: object[], unattributed: number,
+ *   peerLiveness: 'measured'|'unmeasured'|null, skipped?: string, malformed: number,
+ *   durationMs: number, instrumentSuspect: boolean|null, falseAlarmRate: number|null,
+ *   falseAlarmWindowN: number}>}
+ *   `instrumentSuspect`/`falseAlarmRate` are `null` on a degraded (`skipped`) scan
+ *   and `falseAlarmRate` is `null` below the 10-decision floor — in both cases a
+ *   measurement that does not exist, never a measured zero. `peerLiveness` is the
+ *   same distinction for the peer probe, and `null` only on a degraded scan.
+ */
+export async function runOrphanScan({
+  repoRoot,
+  now,
+  dryRun = true,
+  deps,
+  minAgeSeconds = REAPER_DEFAULTS.minAgeSeconds,
+  killGraceMs = REAPER_DEFAULTS.killGraceMs,
+  verifyWaitMs = REAPER_DEFAULTS.verifyWaitMs,
+  falseAlarmWindow = REAPER_DEFAULTS.falseAlarmWindow,
+} = {}) {
+  const d = resolveDeps(deps);
+  const startedAt = typeof now === 'number' ? now : d.now();
+  // A degraded scan measured NOTHING — including the instrument's own health.
+  // `null` rather than `false`/`0` for both instrument fields: a scan that never
+  // ran must not report a healthy instrument it never looked at.
+  const empty = (skipped, malformed = 0) => ({
+    scanned: 0,
+    candidates: [],
+    reported: [],
+    rejected: [],
+    killed: [],
+    unattributed: 0,
+    // Nothing was measured, so peer liveness was not measured either — `null`
+    // rather than the string, because "unmeasured" is a MEASUREMENT OUTCOME and
+    // a degraded scan never got as far as the probe.
+    peerLiveness: null,
+    skipped,
+    malformed,
+    durationMs: Math.max(0, d.now() - startedAt),
+    instrumentSuspect: null,
+    falseAlarmRate: null,
+    falseAlarmWindowN: 0,
+  });
+
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return empty('no-repo-root');
+
+  let text;
+  try {
+    text = await d.runPs();
+  } catch {
+    return empty('ps-failed');
+  }
+  if (text === null || text === undefined) return empty('ps-failed');
+
+  const { rows, malformed } = parsePsSnapshotDetailed(text);
+
+  let ledger;
+  try {
+    ledger = d.readLedger(repoRoot, { nowMs: startedAt });
+  } 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 {
+    ownSessionId = await d.readOwnSessionId(repoRoot);
+  } catch {
+    ownSessionId = null;
+  }
+
+  /** @type {string[]|null} */
+  let livePeerSessionIds;
+  try {
+    livePeerSessionIds = await d.detectPeers(ownSessionId);
+  } catch {
+    // null = unmeasured, NOT "no peers" — see decideReapCandidates.
+    livePeerSessionIds = null;
+  }
+
+  const { candidates, reported, rejected } = decideReapCandidates(
+    rows,
+    ledger?.records ?? [],
+    startedAt,
+    { ownSessionId, livePeerSessionIds, minAgeSeconds },
+  );
+
+  const timestamp = new Date(startedAt).toISOString();
+  const audit = (entry, decision, extra = {}) => {
+    try {
+      d.appendAudit(repoRoot, buildAuditRecord(entry, decision, {
+        timestamp, sessionId: ownSessionId, ...extra,
+      }));
+    } catch {
+      /* the audit is an aid, never a precondition */
+    }
+  };
+
+  for (const entry of reported) audit(entry, 'report');
+
+  /** @type {object[]} */
+  const killed = [];
+
+  /**
+   * Close the scan: measure the instrument's own health (HR-101), emit at most
+   * one event, return the result. Both real exits go through here so the rate
+   * and the event can never be computed twice or forgotten once.
+   * @returns {Promise<object>}
+   */
+  const complete = async () => {
+    let auditRecords;
+    try {
+      auditRecords = (await d.readAuditRecords(repoRoot, falseAlarmWindow)) ?? [];
+    } catch {
+      auditRecords = [];
+    }
+    const fa = falseAlarmRate(auditRecords, falseAlarmWindow);
+    // HR-101: the rate re-aims the instrument, it never re-thresholds it — so
+    // this flag is REPORTED and nothing here branches on it.
+    const instrumentSuspect = typeof fa.rate === 'number' && fa.rate > FALSE_ALARM_SUSPECT_RATE;
+    const survivedSigkill = killed.filter((k) => k.survivedSigkill === true).length;
+    const durationMs = Math.max(0, d.now() - startedAt);
+    // Two counts that must not hide inside `reported`: an unattributed record is
+    // a PRODUCER defect (the gate runner passed no session id), and an
+    // unmeasured peer probe is an INSTRUMENT gap. Folded into the generic
+    // `reported` number, both are invisible — which is how the foreign-session
+    // guard stayed inert across 377 of 377 records without anything saying so.
+    const unattributed = reported.filter((r) => r.reason === 'unattributed').length;
+    const peerLiveness = livePeerSessionIds === null ? 'unmeasured' : 'measured';
+
+    // HR-101 again, in the other direction: a signal that fires on every hook
+    // is noise nobody reads. A scan that found nothing emits nothing — the
+    // absence of a record IS the healthy state, and `instrumentSuspect` is the
+    // one finding that must surface even from an empty scan.
+    if (candidates.length + reported.length + killed.length > 0 || instrumentSuspect) {
+      try {
+        await d.emitEvent(REAPER_SCAN_EVENT, {
+          scanned: rows.length,
+          candidates: candidates.length,
+          reported: reported.length,
+          rejected: rejected.length,
+          killed: killed.length,
+          unattributed,
+          peer_liveness: peerLiveness,
+          survived_sigkill: survivedSigkill,
+          dry_run: dryRun === true,
+          duration_ms: durationMs,
+          instrument_suspect: instrumentSuspect,
+          // OMITTED below the 10-decision floor, never 0: absence means "no
+          // population yet", and a fabricated zero would read as a clean
+          // instrument (`falseAlarmRate` returns `{rate: null}` there).
+          ...(typeof fa.rate === 'number' ? { false_alarm_rate: fa.rate } : {}),
+        }, { repoRoot });
+      } catch {
+        /* telemetry that can fail a scan would fail the hook the scan runs in */
+      }
+    }
+
+    // Housekeeping, last and best-effort: the ledger is append-only and grew
+    // monotonically (measured 2026-09-22: 369 lines/day) because nothing in
+    // production ever called the pruner.
+    try {
+      pruneGateProcessLedger(repoRoot);
+      // The audit is pruned AFTER it was read for the rate above, so a prune
+      // can never shrink the population this scan judged itself on.
+      pruneReaperAudit(repoRoot);
+    } catch {
+      /* housekeeping, never a precondition of a scan */
+    }
+
+    return {
+      scanned: rows.length,
+      candidates,
+      reported,
+      rejected,
+      killed,
+      unattributed,
+      peerLiveness,
+      malformed,
+      durationMs,
+      instrumentSuspect,
+      falseAlarmRate: fa.rate,
+      falseAlarmWindowN: fa.n,
+    };
+  };
+
+  if (dryRun) {
+    for (const c of candidates) audit(c, 'dry-run');
+    return complete();
+  }
+
+  /**
+   * ONE fresh, targeted identity measurement for one candidate (B3).
+   *
+   * There is deliberately no second, bulk `ps` pass any more: two TOCTOU
+   * instruments measuring the same property at different freshness is how the
+   * stale one silently wins. This is the only pre-signal measurement, and it is
+   * taken immediately before each signal rather than once for the whole pass.
+   *
+   * @param {object} c
+   * @returns {Promise<{match: boolean, reason: string, observed?: object}>}
+   */
+  const freshIdentity = async (c) => {
+    let text;
+    try {
+      text = await d.runPsPid(c.pid);
+    } catch {
+      text = null;
+    }
+    // `ps -p` cannot distinguish "gone" from "could not run"; both must refuse
+    // the signal, and only the second is an instrument gap worth its own reason.
+    if (text === null || text === undefined) return { match: false, reason: 'unmeasured' };
+    const row = parsePsSnapshot(text).find((r) => r.pid === c.pid) ?? null;
+    try {
+      // A group MEMBER is re-verified the way it was decided — by the leader's
+      // seam it would fail every time (its own start time, its own command),
+      // and a pre-signal check that always refuses is a disarmed feature, not a
+      // strict one.
+      if (c.isLeader === false) {
+        return verifyGroupMemberIdentity(row, c.ledgerRecord, { nowMs: d.now() });
+      }
+      return d.verifyIdentity(
+        c.pid,
+        { startTime: c.ledgerRecord.startTime, commandSignature: c.ledgerRecord.commandSignature },
+        { snapshotLine: row, nowMs: d.now() },
+      );
+    } catch {
+      return { match: false, reason: 'gone' };
+    }
+  };
+
+  // ONE ladder per GROUP, not per row: with the pgid join a single group can
+  // contribute several candidate rows (leader + descendants), and they all name
+  // the same kill target. Leaders first, so the target of a group is the process
+  // the ledger actually recorded whenever it is still alive.
+  const killTargets = [];
+  const coveredPgids = new Set();
+  for (const c of [...candidates.filter((x) => x.isLeader), ...candidates.filter((x) => !x.isLeader)]) {
+    if (coveredPgids.has(c.pgid)) continue;
+    coveredPgids.add(c.pgid);
+    killTargets.push(c);
+  }
+
+  for (const c of killTargets) {
+    /** Set by the gate below when it refuses; `null` means every signal was permitted. */
+    let withdrawal = null;
+    const beforeSignal = async (signal) => {
+      const identity = await freshIdentity(c);
+      if (identity?.match === true) return true;
+      withdrawal = { signal, identity, reason: rejectReasonFor(identity?.reason) };
+      return false;
+    };
+
+    let result;
+    try {
+      result = await d.killProcessGroup(c.pgid, {
+        killGraceMs, verifyWaitMs, sleepFn: d.sleep, beforeSignal,
+      });
+    } catch (err) {
+      result = { ok: false, signalsSent: [], survivors: [c.pgid], error: err?.code ?? null, aborted: null };
+    }
+    const signalsSent = Array.isArray(result?.signalsSent) ? result.signalsSent : [];
+
+    if (withdrawal !== null) {
+      // The candidate was withdrawn between decision and signal. It stays in
+      // `candidates` (that WAS the decision) and appears in `rejected` (that is
+      // the withdrawal) — collapsing the two would lose the TOCTOU event.
+      // `signalsSent` is carried even here: a withdrawal before the ESCALATION
+      // still means a SIGTERM went out, and an audit that hid it would
+      // under-report what this reaper did to the host.
+      rejected.push({
+        ...c, reason: withdrawal.reason, identity: withdrawal.identity, signalsSent,
+      });
+      audit(c, 'reject', {
+        reason: withdrawal.reason,
+        result: {
+          ok: false,
+          signalsSent,
+          survivors: [],
+          survivedSigkill: false,
+          verifiedAfterMs: 0,
+          verified: 'withdrawn',
+        },
+      });
+      continue;
+    }
+
+    // B6: prove the EFFECT, after a wait, from a fresh measurement of the
+    // process table. An exit code and a sent signal prove nothing — on
+    // 2026-09-20 a probe with no wait reported "still alive" for dead processes.
+    let verified = 'unverified';
+    if (signalsSent.length > 0) {
+      await d.sleep(verifyWaitMs);
+      const after = await freshIdentity(c);
+      if (after?.match === true) verified = 'alive';
+      else if (after?.reason === 'unmeasured') verified = 'unmeasured';
+      else verified = 'gone';
+    }
+    const ok = verified === 'gone';
+    const survivedSigkill = verified === 'alive' && signalsSent.includes('SIGKILL');
+    const survivors = ok ? [] : [c.pgid];
+    const verifiedAfterMs = signalsSent.length > 0 ? verifyWaitMs : 0;
+
+    killed.push({
+      pid: c.pid,
+      pgid: c.pgid,
+      // Every candidate row this one ladder covers — the group join means one
+      // signal can end several candidates, and a `killed` list that named only
+      // the target would under-report what the reaper did to the host.
+      groupMemberPids: candidates.filter((x) => x.pgid === c.pgid).map((x) => x.pid),
+      ok,
+      signalsSent,
+      survivors,
+      survivedSigkill,
+      verified,
+      verifiedAfterMs,
+    });
+    audit(c, 'kill', {
+      result: { ok, signalsSent, survivors, survivedSigkill, verifiedAfterMs, verified },
+    });
+  }
+
+  return complete();
+}

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' };
+  }
+}