greprag 5.43.0 → 5.43.2

package/dist/commands/watcher-registry.js

@@ -1,33 +1,35 @@
 "use strict";
-/** Local watcher process registry + owner-pid orphan reaper.
+/** Local watcher process registry + COUNT-CAP (the post-saga model).
  *
- *  The architectural correction the whole monitor-resilience saga circled but
- *  never landed (see adr/monitor-resilience.md 2026-05-28 "severed-ancestry =
- *  the disarm signal" + the 2026-06-04 entry): a watcher's liveness lives at the
- *  LOCAL process layer, not in a cloud registry. The consumer of a watcher is
- *  the Claude Code Monitor task on THIS machine; the server can't see whether
- *  anyone is still consuming the stream, so a server lease counts an orphan
- *  (consumer dead, process still respawning) as "armed". Two local signals fix
- *  that:
+ *  THE LESSON (adr/monitor-resilience.md, "⭐ The watcher in one pass"): a
+ *  functional watcher and an orphaned-but-alive one are EXTERNALLY
+ *  INDISTINGUISHABLE — same command line, same live PID. Only the watcher itself
+ *  can tell, via its own stdout pipe (EPIPE). So every external reaper that
+ *  *judged* orphan-ness (ancestry, owner-pid, monitor-pid) was guessing, and the
+ *  guesses false-killed live watchers — the 548-kill saga in one line.
  *
- *   1. **pidfile** (`~/.greprag/watchers/<short>.json`) — written by the
- *      supervisor on start, removed on terminal exit. `isLocallyArmed` reads it
- *      to gate re-arming with zero cloud dependency and zero ghost-lease lag.
- *      Paired with EPIPE-terminal in the watcher (a watcher whose consumer pipe
- *      breaks exits and removes its own pidfile), a live pidfile means a live,
- *      *consumed* watcher.
+ *  This module no longer judges. Two reliable facts replace the one unknowable
+ *  one:
  *
- *   2. **owner-pid reap** — `reapOrphanWatchers` kills any `inbox watch` process
- *      whose stamped `--owner-pid` names a `claude.exe` that is no longer alive.
- *      Backstop for the case EPIPE can't catch (a consumer hard-killed without
- *      closing the pipe). A watcher with NO `--owner-pid` is KEPT, never killed:
- *      the old ancestry-walk fallback PROVED to false-kill live backgrounded
- *      watchers (2026-06-05a / 2026-06-13) and was retired. SAFE BY CONSTRUCTION:
- *      the kill set is intersected with "cmdline contains `inbox watch`", so it
- *      can only ever terminate greprag watchers — never claude.exe, an editor, or
- *      an unrelated node server.
+ *   1. **pidfile registry** — `~/.greprag/watchers/<short>.json` is a LIST of every
+ *      supervisor armed for that session (`{short,pid,startedAt,ownerPid}`). A
+ *      supervisor appends on arm and removes its own entry on terminal exit; a
+ *      hard kill leaves a dead entry that the alive-filter sweeps. `isLocallyArmed`
+ *      = "any entry alive". (Multiple live supervisors per session is normal under
+ *      the June-8 spray; the count-cap bounds them.)
  *
- *  adr: adr/monitor-resilience.md */
+ *   2. **count-cap** — `reapOrphanWatchers` keeps the K freshest LIVE watchers per
+ *      session and kills only the surplus, NEVER below K. No death-detection → no
+ *      false-kill; a floor of K → it can never reap to zero, so the bug that broke
+ *      liveness every time is structurally impossible. "Freshest" is a *bias*
+ *      toward the just-armed functional one, not a guarantee — and that's fine:
+ *      EPIPE kills a wrongly-kept orphan in ~30s and the supervisor respawns. It is
+ *      **snapshot-free** (per-session file reads + `pidAlive()` syscalls), so the
+ *      06-05b conhost-OOM engine — a `powershell Get-CimInstance` per SessionStart —
+ *      is gone from the cleanup path entirely.
+ *
+ *  EPIPE-terminal (in the watcher) + the supervisor's programmatic respawn do the
+ *  real liveness work; the count-cap only bounds the pile. adr: adr/monitor-resilience.md */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -62,46 +64,31 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GC_GRACE_MS = exports.DEFAULT_WATCHER_CAP = void 0;
 exports.writeWatcherPidfile = writeWatcherPidfile;
+exports.removeWatcherEntry = removeWatcherEntry;
 exports.removeWatcherPidfile = removeWatcherPidfile;
 exports.watcherAuditLog = watcherAuditLog;
 exports.isLocallyArmed = isLocallyArmed;
 exports.listLocalLiveWatchers = listLocalLiveWatchers;
 exports.resolveClaudeOwnerPid = resolveClaudeOwnerPid;
-exports.severedVerdict = severedVerdict;
+exports.capSurplusVerdict = capSurplusVerdict;
 exports.reapOrphanWatchers = reapOrphanWatchers;
+exports.gcVerdict = gcVerdict;
+exports.gcDeadSessions = gcDeadSessions;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const proc_1 = require("../proc");
+const child_process_1 = require("child_process");
 const WATCHER_DIRNAME = 'watchers';
-// Matches a greprag watcher's command line in every launch shape: the npm shim
-// and the old bash while-loop wrapper (`greprag inbox watch …`), and the
-// supervisor's CreateProcess re-invocation (`node …\dist\index.js inbox watch
-// …`). Anchored on the INVOKED BINARY (`greprag` or `index.js`) immediately
-// followed by the `inbox watch` args — NOT a bare `inbox watch` substring, which
-// would also match an unrelated shell that merely mentions the phrase (a grep, a
-// diagnostic, this very reaper). This is the SAFETY GUARD: only a process whose
-// command line is an actual watcher invocation is ever a kill candidate, so the
-// reaper cannot touch claude.exe, an editor, or an incidental shell.
-const WATCHER_CMD_RE = /(?:index\.js|greprag)["'\s]+inbox\s+watch\b/i;
+// Matches a greprag watcher's command line in every launch shape (npm shim, bash
+// relauncher, the supervisor's CreateProcess re-invocation). Anchored on the
+// INVOKED BINARY (`greprag` or `index.js`) immediately followed by `inbox watch`
+// — never a bare `inbox watch` substring. Retained for the owner-pid resolver's
+// claude.exe match; the cleanup path no longer scans the process table at all.
 const CLAUDE_PROC_RE = /^claude(\.exe)?$/i;
-// The owning claude.exe PID, stamped into the watch command at arm time and
-// inherited by every process in the tree (launcher shell → supervisor → child).
-// The robust replacement for the ancestry walk: the launcher chain collapses
-// within seconds of arming (a backgrounded daemon's parent shell exits by
-// design), so "can I still walk up to a claude.exe?" yields false positives on
-// LIVE watchers. "Is the specific claude.exe that armed me still alive?" does
-// not. adr: adr/monitor-resilience.md
-const OWNER_PID_RE = /--owner-pid[=\s]+(\d+)/;
-// The --monitor-pid monitor-task backstop (ff681bb, 2026-06-10) was reverted
-// 2026-06-11: the arm-time stamp came from /proc/$$/winpid of the transient
-// arm-line bash, not the persistent Monitor task, so a dead stamp under a live
-// owner false-flagged live watchers as orphans. Owner-pid liveness is the test.
-// adr: adr/monitor-resilience.md
-// The ancestry-walk fallback (and its GREPRAG_REAP_BY_OWNER escape hatch) was
-// RETIRED 2026-06-13: it false-killed live backgrounded watchers (see
-// severedVerdict). Owner-pid liveness is now the ONLY reap signal; a flagless
-// watcher is kept. adr: adr/monitor-resilience.md
+/** Default per-session watcher floor: keep this many freshest live watchers, reap
+ *  only the surplus above it, never below it. K=2 = the live one + one margin. */
+exports.DEFAULT_WATCHER_CAP = 2;
 function grepragHome() {
     const home = process.env.HOME || process.env.USERPROFILE || '';
     return home ? path.join(home, '.greprag') : null;
@@ -110,109 +97,139 @@ function watchersDir() {
     const h = grepragHome();
     return h ? path.join(h, WATCHER_DIRNAME) : null;
 }
-/** Write the watcher pidfile (supervisor PID), keyed by the 8-hex session short.
- *  `ownerPid` (the owning claude.exe) is recorded so the reaper can test liveness
- *  without enumerating the process table. Best-effort: a failed write only means
- *  `isLocallyArmed` falls back to re-arming, never a crash. */
-function writeWatcherPidfile(short, pid, ownerPid) {
+function pidfilePath(short) {
+    const dir = watchersDir();
+    return dir ? path.join(dir, `${short}.json`) : null;
+}
+/** True iff `pid` is a live process. `process.kill(pid, 0)` sends no signal — it
+ *  only probes existence. EPERM = exists but another user (alive); ESRCH = gone. */
+function pidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === 'EPERM';
+    }
+}
+/** Read a session's entry LIST. Back-compat: a legacy single-object pidfile reads
+ *  as a 1-element list. */
+function readWatcherEntries(short) {
+    try {
+        const p = pidfilePath(short);
+        if (!p)
+            return [];
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        const arr = Array.isArray(parsed) ? parsed : [parsed];
+        return arr.filter((r) => !!r && typeof r.pid === 'number');
+    }
+    catch {
+        return [];
+    }
+}
+function writeWatcherEntries(short, entries) {
     try {
         const dir = watchersDir();
         if (!dir)
             return;
         fs.mkdirSync(dir, { recursive: true });
-        const rec = { short, pid, startedAt: Date.now(), ownerPid };
-        fs.writeFileSync(path.join(dir, `${short}.json`), JSON.stringify(rec));
+        const p = path.join(dir, `${short}.json`);
+        if (entries.length === 0) {
+            fs.rmSync(p, { force: true });
+            return;
+        }
+        fs.writeFileSync(p, JSON.stringify(entries));
+    }
+    catch { /* best-effort — a failed write only means re-arm, never a crash */ }
+}
+/** APPEND this supervisor's entry to the session's list (pruning dead entries as
+ *  it goes). Best-effort. adr: adr/monitor-resilience.md */
+function writeWatcherPidfile(short, pid, ownerPid) {
+    const entries = readWatcherEntries(short).filter(r => r.pid !== pid && pidAlive(r.pid));
+    entries.push({ short, pid, startedAt: Date.now(), ownerPid });
+    writeWatcherEntries(short, entries);
+}
+/** Remove THIS supervisor's entry (called on a supervisor's terminal exit). */
+function removeWatcherEntry(short, pid) {
+    writeWatcherEntries(short, readWatcherEntries(short).filter(r => r.pid !== pid));
+}
+/** Remove a session's whole pidfile (legacy / full sweep). */
+function removeWatcherPidfile(short) {
+    try {
+        const p = pidfilePath(short);
+        if (p)
+            fs.rmSync(p, { force: true });
     }
     catch { /* best-effort */ }
 }
-/** Every parseable watcher pidfile. The on-disk registry of live watchers — the
- *  reaper's cheap pre-check reads THIS, not a process snapshot. */
-function readAllPidfiles() {
+/** Every session short with a pidfile on disk. */
+function allShorts() {
     try {
         const dir = watchersDir();
         if (!dir || !fs.existsSync(dir))
             return [];
-        const out = [];
-        for (const f of fs.readdirSync(dir)) {
-            if (!f.endsWith('.json'))
-                continue;
-            try {
-                const rec = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
-                if (rec && typeof rec.pid === 'number')
-                    out.push(rec);
-            }
-            catch { /* skip unparseable */ }
-        }
-        return out;
+        return fs.readdirSync(dir).filter(f => f.endsWith('.json')).map(f => f.slice(0, -5));
     }
     catch {
         return [];
     }
 }
-// ---- Owner-PID resolution cache ------------------------------------------
-// The owning claude.exe PID is STABLE for the life of a session — claude.exe
-// stays up across every turn. Resolving it via a process snapshot on every
-// unarmed prompt (the `notify` hook's hot path) was the dominant conhost-leak
-// engine: each call spawned a `powershell Get-CimInstance Win32_Process` whose
-// conhost orphaned under load. Cache the result keyed by session short; the hot
-// path becomes a file read + one `pidAlive()` syscall, no subprocess.
-// adr: adr/monitor-resilience.md
+// ---- Owner-PID cache (vestigial under the count-cap; kept for the arm stamp) ----
+// The `notify` hook still stamps `--owner-pid` into the arm command for audit
+// continuity. The cap never reads it; this cache just keeps the per-prompt resolve
+// cheap (a file read instead of a process snapshot) on the rare cache miss.
 function ownerCachePath(short) {
     const dir = watchersDir();
     return dir ? path.join(dir, `${short}.owner`) : null;
 }
-function readOwnerCache(short) {
+function readSessionOwner(short) {
     try {
         const p = ownerCachePath(short);
         if (!p)
             return null;
-        const n = Number(fs.readFileSync(p, 'utf-8').trim());
-        return Number.isFinite(n) && n > 0 ? n : null;
+        const raw = fs.readFileSync(p, 'utf-8').trim();
+        if (/^\d+$/.test(raw)) {
+            const n = Number(raw);
+            return n > 0 ? { pid: n, ts: 0 } : null;
+        } // legacy bare PID
+        const o = JSON.parse(raw);
+        return (o && typeof o.pid === 'number') ? o : null;
     }
     catch {
         return null;
     }
 }
-function writeOwnerCache(short, ownerPid) {
+function writeSessionOwner(short, o) {
     try {
         const dir = watchersDir();
         if (!dir)
             return;
         fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(path.join(dir, `${short}.owner`), String(ownerPid));
+        fs.writeFileSync(path.join(dir, `${short}.owner`), JSON.stringify(o));
     }
     catch { /* best-effort */ }
 }
-function removeWatcherPidfile(short) {
+function removeSessionOwner(short) {
     try {
-        const dir = watchersDir();
-        if (!dir)
-            return;
-        fs.rmSync(path.join(dir, `${short}.json`), { force: true });
+        const p = ownerCachePath(short);
+        if (p)
+            fs.rmSync(p, { force: true });
     }
     catch { /* best-effort */ }
 }
-function readWatcherPidfile(short) {
-    try {
-        const dir = watchersDir();
-        if (!dir)
-            return null;
-        const raw = fs.readFileSync(path.join(dir, `${short}.json`), 'utf-8');
-        const rec = JSON.parse(raw);
-        if (rec && typeof rec.pid === 'number' && rec.short === short)
-            return rec;
-        return null;
-    }
-    catch {
-        return null;
-    }
+// Thin wrappers for resolveClaudeOwnerPid (unchanged contract): read returns the
+// current owner PID; write refreshes the record fresh (clearing any deadSince).
+function readOwnerCache(short) {
+    return readSessionOwner(short)?.pid ?? null;
+}
+function writeOwnerCache(short, ownerPid) {
+    writeSessionOwner(short, { pid: ownerPid, ts: Date.now() });
 }
-/** Append-only diagnostic audit log at ~/.greprag/watchers/audit.log. ALWAYS ON
- *  (not env-gated) so a watcher killed by a SIBLING session's SessionStart reap
- *  leaves a trail — its own Monitor output file is gone by the time we'd read it,
- *  and the reaper is a different process than the watcher. Behaviour-neutral:
- *  pure observation, never gates a kill or an arm. Cheap (a few lines per
- *  SessionStart + per watcher arm/exit). adr: adr/monitor-resilience.md */
+/** Append-only diagnostic audit log at ~/.greprag/watchers/audit.log. ALWAYS ON so
+ *  every arm / terminal exit / cap-kill leaves a trail. Behaviour-neutral: pure
+ *  observation, never gates a kill or an arm. adr: adr/monitor-resilience.md */
 function watcherAuditLog(event) {
     try {
         const dir = watchersDir();
@@ -223,66 +240,43 @@ function watcherAuditLog(event) {
     }
     catch { /* best-effort — visibility must never break the watcher */ }
 }
-/** True iff `pid` is a live process. `process.kill(pid, 0)` sends no signal —
- *  it only probes existence. EPERM means the process exists but is owned by
- *  another user (still alive); ESRCH means gone. */
-function pidAlive(pid) {
-    if (!Number.isFinite(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        return e?.code === 'EPERM';
-    }
-}
-/** Local-first arm check: is there a live watcher PROCESS for this session on
- *  THIS machine? This is ground truth for "armed" — the consumer (the Monitor
- *  task) is local, so a live local pidfile means a live, consumed watcher.
- *  Replaces the server `isSessionArmed` check, which counts orphans (consumer
- *  dead, socket still open) as armed and so both (a) suppresses re-arm when the
- *  real watcher is gone and (b) lets re-arm stack new watchers on undead
- *  orphans. A dead-PID pidfile is swept here so the next turn re-arms. */
+/** Local-first arm check: does this session have ANY live watcher process on THIS
+ *  machine? Ground truth for "armed" — the consumer (the Monitor task) is local,
+ *  so a live local entry means a live, consumed watcher. Sweeps dead entries as it
+ *  reads, so a hard-killed watcher doesn't read as armed. */
 function isLocallyArmed(short) {
-    const rec = readWatcherPidfile(short);
-    if (!rec)
-        return false;
-    if (!pidAlive(rec.pid)) {
-        removeWatcherPidfile(short);
-        return false;
-    }
-    return true;
+    const entries = readWatcherEntries(short);
+    const alive = entries.filter(r => pidAlive(r.pid));
+    if (alive.length !== entries.length)
+        writeWatcherEntries(short, alive);
+    return alive.length > 0;
 }
-/** The local source of truth: every session whose watcher process is alive on
- *  THIS machine right now. Reads the pidfile registry and confirms each PID with
- *  the OS (`pidAlive`), sweeping any dead-PID leftover as it goes. This is the
- *  answer the desk-line returns when the cloud asks "what's truly active?" — it
- *  is computed on demand from ground truth, never a cached/replicated list, so it
- *  cannot go stale the way the cloud `/attached` registry does. adr:
- *  adr/monitor-resilience.md */
+/** Every session whose watcher process is alive on THIS machine right now —
+ *  computed on demand from the pidfile registry + OS liveness, sweeping dead
+ *  entries. Most-recently-armed first. This is what the desk-line returns when the
+ *  cloud asks "what's truly active?". adr: adr/monitor-resilience.md */
 function listLocalLiveWatchers() {
     const out = [];
-    for (const rec of readAllPidfiles()) {
-        if (pidAlive(rec.pid))
-            out.push(rec);
-        else
-            removeWatcherPidfile(rec.short); // stale leftover — drop it
+    for (const short of allShorts()) {
+        const entries = readWatcherEntries(short);
+        const alive = entries.filter(r => pidAlive(r.pid));
+        if (alive.length !== entries.length)
+            writeWatcherEntries(short, alive);
+        out.push(...alive);
     }
-    // Stable order: most-recently-armed first.
     return out.sort((a, b) => (b.startedAt || 0) - (a.startedAt || 0));
 }
-/** Snapshot (pid, ppid, name, cmdline) for every process. Windows via one CIM
- *  call (a single PowerShell invocation — avoids the per-PID `wmic` calls that
- *  hung historically, see ADR 2026-05-26); POSIX via `ps`. Best-effort: any
- *  failure returns [] and the reaper becomes a no-op. */
+/** Snapshot (pid, ppid, name, cmdline) for every process. Windows via one CIM call;
+ *  POSIX via `ps`. ONLY used by `resolveClaudeOwnerPid` now (the cleanup path is
+ *  snapshot-free); it runs at most once per session (cache miss), never per-tick.
+ *  Best-effort: any failure returns []. */
 function snapshotProcs() {
     try {
         if (process.platform === 'win32') {
             const script = 'Get-CimInstance Win32_Process | ' +
                 'Select-Object ProcessId,ParentProcessId,Name,CommandLine | ' +
                 'ConvertTo-Json -Compress';
-            const out = (0, proc_1.safeExecFileSync)('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { timeout: 12_000, maxBuffer: 64 * 1024 * 1024, windowsHide: true }).toString();
+            const out = (0, child_process_1.execFileSync)('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { timeout: 12_000, maxBuffer: 64 * 1024 * 1024, windowsHide: true }).toString();
             const parsed = JSON.parse(out);
             const arr = Array.isArray(parsed) ? parsed : [parsed];
             return arr
@@ -294,8 +288,7 @@ function snapshotProcs() {
             }))
                 .filter(p => Number.isFinite(p.pid) && p.pid > 0);
         }
-        // POSIX fallback.
-        const out = (0, proc_1.safeExecFileSync)('ps', ['-eo', 'pid=,ppid=,comm=,args='], {
+        const out = (0, child_process_1.execFileSync)('ps', ['-eo', 'pid=,ppid=,comm=,args='], {
             timeout: 12_000, maxBuffer: 64 * 1024 * 1024,
         }).toString();
         const rows = [];
@@ -311,28 +304,11 @@ function snapshotProcs() {
         return [];
     }
 }
-/** Owning claude.exe PID parsed from a watcher's command line (`--owner-pid N`),
- *  or null if absent (a legacy watcher armed before this flag existed). */
-function ownerPidFromCmd(cmd) {
-    const m = OWNER_PID_RE.exec(cmd || '');
-    return m ? Number(m[1]) : null;
-}
-/** Resolve the owning claude.exe PID for the CURRENT process by walking its
- *  parent chain in a fresh snapshot. MUST be called from a hook — a direct, live
- *  descendant of the session's claude.exe whose chain is intact — NOT from the
- *  watcher, whose launcher shell collapses within seconds of arming (proven
- *  2026-06-05: a supervisor's ancestry to claude.exe is already severed at arm
- *  time). The hook stamps the result into the watch command (`--owner-pid`) so
- *  the reaper can later ask "is that exact claude.exe still alive?" instead of
- *  re-walking a chain that no longer exists. Returns null if no claude.exe
- *  ancestor is found (caller omits the flag → the watcher is flagless → the reaper
- *  KEEPS it, since the ancestry fallback that used to reap it was a false-kill).
- *  adr: adr/monitor-resilience.md */
+/** Resolve the owning claude.exe PID for the CURRENT process by walking its parent
+ *  chain. MUST be called from a hook (a live descendant of claude.exe). Stamped
+ *  into the arm command (`--owner-pid`) for audit continuity. Cache hit skips the
+ *  snapshot. Returns null if no claude.exe ancestor. adr: adr/monitor-resilience.md */
 function resolveClaudeOwnerPid(cacheShort) {
-    // Cache hit: the owning claude.exe is still alive (stable for the session) —
-    // skip the snapshot entirely. This is what turns the per-prompt hot path from
-    // "spawn a powershell every turn" into "read a file + one syscall".
-    // adr: adr/monitor-resilience.md
     if (cacheShort) {
         const cached = readOwnerCache(cacheShort);
         if (cached && pidAlive(cached))
@@ -364,106 +340,116 @@ function resolveClaudeOwnerPid(cacheShort) {
         return null;
     }
 }
-/** True iff `pid` is present in the snapshot AND is a claude.exe — i.e. the
- *  owning session is still alive. */
-function isLiveClaude(pid, byPid) {
-    const p = byPid.get(pid);
-    return !!p && CLAUDE_PROC_RE.test(p.name);
+// ---- The count-cap -------------------------------------------------------
+/** Pure verdict (testable): given a session's LIVE entries, keep the K freshest
+ *  (by startedAt), return the older surplus to kill. Never kills when count ≤ K;
+ *  never kills more than count − K; never the K freshest. This is the entire
+ *  liveness-safety guarantee — no death judgment, just a count + a floor. */
+function capSurplusVerdict(entries, K) {
+    if (entries.length <= K)
+        return { keep: entries.slice(), kill: [] };
+    const sorted = [...entries].sort((a, b) => (b.startedAt || 0) - (a.startedAt || 0));
+    return { keep: sorted.slice(0, K), kill: sorted.slice(K) };
 }
-/** Decide whether a watcher candidate is a severed orphan, and why. The ONLY
- *  reap signal is the stamped owner PID: a watcher is severed iff its
- *  `--owner-pid` names a claude.exe that is no longer alive. A watcher with NO
- *  `--owner-pid` is KEPT — never ancestry-walked.
- *
- *  Why the ancestry fallback was retired (2026-06-13): the walk "is a live
- *  claude.exe still my ancestor?" PROVED to false-kill LIVE backgrounded watchers
- *  (adr 2026-06-05a) — a Monitor-armed watcher's launcher shell exits by design,
- *  so within seconds of a healthy arm its chain to claude.exe is already severed,
- *  indistinguishable from a real orphan. It was the dominant false-kill on
- *  flagless watchers, and flagless is not rare: the bare arm form is taught by the
- *  skill docs AND emitted by the hook itself whenever resolveClaudeOwnerPid
- *  returns null on a snapshot miss (so `--owner-pid` cannot be guaranteed at the
- *  arm site). The only safe verdict for a flagless watcher is therefore KEEP.
- *  Genuine death of a flagless watcher is still caught at the right layer: its
- *  consumer pipe breaks on session reload/end → EPIPE-terminal (consumer-gone)
- *  tears it down, and `sweepDeadPidfiles` collects a dead-PID pidfile. The
- *  residual — a flagless watcher orphaned by a TaskStop while claude.exe stays
- *  alive (no pipe break, no owner to die) — is one idle process, the exact blind
- *  spot the 2026-06-11 revert already knowingly left open. This also retires the
- *  GREPRAG_REAP_BY_OWNER escape hatch, whose only effect was to re-enable the
- *  proven-bad pure-ancestry walk. adr: adr/monitor-resilience.md */
-function severedVerdict(w, byPid) {
-    const owner = ownerPidFromCmd(w.cmd);
-    if (owner === null) {
-        return { severed: false, reason: 'no-owner-flag→keep (ancestry retired)' };
+/** Count-cap every session: keep the K freshest LIVE watchers, kill only the
+ *  surplus. NO death-detection, NO process snapshot — per-session file reads +
+ *  `pidAlive()`, and a `taskkill` only when there is genuine surplus. Run at
+ *  SessionStart (via the recap hook) and exposed as `greprag inbox reap`. The name
+ *  is retained for its callers; the behaviour is "cap", not "judge orphans".
+ *  adr: adr/monitor-resilience.md */
+function reapOrphanWatchers(K = exports.DEFAULT_WATCHER_CAP) {
+    let scanned = 0;
+    let surplus = 0;
+    const killedAll = [];
+    for (const short of allShorts()) {
+        const alive = readWatcherEntries(short).filter(r => pidAlive(r.pid));
+        scanned += alive.length;
+        const { keep, kill } = capSurplusVerdict(alive, K);
+        if (kill.length === 0) {
+            writeWatcherEntries(short, alive); // sweep dead entries, nothing to cap
+            continue;
+        }
+        surplus += kill.length;
+        const survivors = keep.slice();
+        for (const w of kill) {
+            watcherAuditLog(`cap-candidate=${w.pid} session=${short} SURPLUS→kill startedAt=${w.startedAt}`);
+            if (killProcessTree(w.pid))
+                killedAll.push(w.pid);
+            else
+                survivors.push(w); // kill failed → keep tracking it so it's retried
+        }
+        writeWatcherEntries(short, survivors);
     }
-    const live = isLiveClaude(owner, byPid);
-    return { severed: !live, reason: `owner=${owner}:${live ? 'live-claude' : 'dead'}` };
+    watcherAuditLog(`cap-summary K=${K} scanned=${scanned} surplus=${surplus} killed=[${killedAll.join(',')}]`);
+    return { scanned, orphans: surplus, killed: killedAll };
 }
-/** Kill every `inbox watch` process whose stamped `--owner-pid` names a dead
- *  claude.exe (= orphan), plus sweep dead-PID pidfiles. Flagless watchers are
- *  kept (see severedVerdict). Returns a summary. Best-effort and bounded: a
- *  snapshot failure yields a zero result; the kill set is guaranteed (by
- *  `WATCHER_CMD_RE`) to contain only greprag watchers. Intended to run at
- *  SessionStart, before this session arms — at that moment a watcher with a dead
- *  owner belongs to a PRIOR incarnation, so reaping it is correct. */
-function reapOrphanWatchers() {
-    sweepDeadPidfiles();
-    // Demand-gate the snapshot. The process-table photograph (a spawned
-    // `powershell Get-CimInstance`) was firing on EVERY SessionStart — and
-    // SessionStart re-fires on every compaction/reload, across every session — so
-    // the snapshot itself, not any watcher, became the conhost-leak engine. The
-    // on-disk pidfile registry already tells us, with zero subprocesses, whether
-    // any watcher's owning claude.exe has died: that is the only condition under
-    // which there is anything to reap. If no pidfile reports a dead owner, there is
-    // nothing severed → skip the snapshot entirely. The snapshot now runs ONLY when
-    // a real orphan exists (where its cost is justified), and still performs the
-    // full cmdline-verified, recycle-safe kill below. Flagless/legacy pidfiles (no
-    // ownerPid) NO LONGER force a snapshot: severedVerdict now KEEPS flagless
-    // watchers (the ancestry walk that used to "collect" them was a false-kill), so
-    // there is nothing to reap for them, and a dead-PID pidfile is already collected
-    // by sweepDeadPidfiles above. Dropping the legacy force-snapshot removes the
-    // bare-pidfile self-trigger that fired a conhost-leaking process snapshot on
-    // every SessionStart (the very leak the demand-gate exists to prevent — a single
-    // bare watcher re-armed it). adr: adr/monitor-resilience.md
-    const pidfiles = readAllPidfiles();
-    const severedByOwner = pidfiles.some(r => typeof r.ownerPid === 'number' && !pidAlive(r.ownerPid));
-    if (!severedByOwner) {
-        watcherAuditLog(`reap-summary gated no-severed-owner pidfiles=${pidfiles.length} (snapshot skipped)`);
-        return { scanned: 0, orphans: 0, killed: [] };
-    }
-    const procs = snapshotProcs();
-    if (procs.length === 0) {
-        watcherAuditLog('reap-summary snapshot-empty no-op');
-        return { scanned: 0, orphans: 0, killed: [] };
-    }
-    const byPid = new Map();
-    for (const p of procs)
-        byPid.set(p.pid, p);
-    // Candidate set — the SAFETY GUARD. Only these are ever eligible to be killed.
-    const watchers = procs.filter(p => WATCHER_CMD_RE.test(p.cmd));
-    const verdicts = watchers.map(w => ({ w, ...severedVerdict(w, byPid) }));
-    const severed = verdicts.filter(v => v.severed).map(v => v.w);
-    // Visibility: record every candidate's verdict + the reason (which signal
-    // decided it) BEFORE any kill, so a false-positive is auditable after the
-    // fact. adr: adr/monitor-resilience.md
-    for (const v of verdicts) {
-        watcherAuditLog(`reap-candidate=${v.w.pid} name=${v.w.name} ppid=${v.w.ppid} ${v.severed ? 'SEVERED→kill' : 'ok→keep'} via=${v.reason} cmd="${(v.w.cmd || '').slice(0, 90)}"`);
-    }
+// ---- Dead-session GC (the re-resolved-owner cleanup) ----------------------
+// The count-cap bounds a LIVE session to K; EPIPE + the relauncher clean a
+// CLEANLY-closed session. This collects the remaining tail: a session whose
+// claude.exe HARD-crashes (half-open pipe, no EPIPE) leaves ≤K watchers nothing
+// else reaps. It asks "is the SESSION alive?" — reliably knowable via the
+// SessionStart-refreshed owner record — NOT "is this WATCHER an orphan?"
+// (unknowable). The grace window + `deadSince` clock make it immune to the restart
+// false-kill that doomed the owner-pid reaper: a model/Fast-mode switch re-resolves
+// the owner well within grace, overwriting the record and clearing deadSince.
+// adr: adr/monitor-resilience.md
+/** Minutes a session's owner must stay CONTINUOUSLY dead before its watchers are
+ *  GC'd. Must exceed the worst-case claude.exe restart→SessionStart window (which
+ *  is seconds), so a restart can never be mistaken for a death. */
+exports.GC_GRACE_MS = 5 * 60 * 1000;
+/** Pure GC decision (testable): given a session's owner record and whether its PID
+ *  is alive right now, decide keep / start-the-grace-clock / reap. */
+function gcVerdict(owner, ownerAlive, now, graceMs) {
+    if (!owner)
+        return 'keep'; // no owner record → the count-cap's job
+    if (ownerAlive)
+        return 'keep'; // session alive (even if idle)
+    if (owner.deadSince === undefined)
+        return 'mark-dead'; // first death sighting → start the clock
+    return (now - owner.deadSince > graceMs) ? 'reap' : 'keep';
+}
+/** Reap every watcher of a session whose owning claude.exe has stayed dead past the
+ *  grace window. Run at SessionStart, AFTER refreshing THIS session's own owner
+ *  (so it is never its own victim). No process snapshot — owner-file reads +
+ *  pidAlive() syscalls. adr: adr/monitor-resilience.md */
+function gcDeadSessions(graceMs = exports.GC_GRACE_MS) {
+    const now = Date.now();
+    const reaped = [];
     const killed = [];
-    for (const p of severed) {
-        if (killProcessTree(p.pid))
-            killed.push(p.pid);
+    for (const short of allShorts()) {
+        const owner = readSessionOwner(short);
+        const verdict = gcVerdict(owner, !!owner && pidAlive(owner.pid), now, graceMs);
+        if (verdict === 'keep') {
+            if (owner && owner.deadSince !== undefined && pidAlive(owner.pid)) {
+                writeSessionOwner(short, { pid: owner.pid, ts: owner.ts }); // recovered → clear the grace clock
+            }
+            continue;
+        }
+        if (verdict === 'mark-dead') {
+            writeSessionOwner(short, { ...owner, deadSince: now }); // start the grace clock
+            continue;
+        }
+        // reap: the owner stayed dead past grace → the session is truly gone.
+        const deadFor = Math.round((now - (owner.deadSince || now)) / 1000);
+        for (const e of readWatcherEntries(short)) {
+            watcherAuditLog(`gc-kill=${e.pid} session=${short} owner=${owner.pid}:dead-${deadFor}s`);
+            if (killProcessTree(e.pid))
+                killed.push(e.pid);
+        }
+        removeWatcherPidfile(short);
+        removeSessionOwner(short);
+        reaped.push(short);
     }
-    watcherAuditLog(`reap-summary mode=owner-pid scanned=${watchers.length} severed=${severed.length} killed=[${killed.join(',')}]`);
-    return { scanned: watchers.length, orphans: severed.length, killed };
+    if (reaped.length)
+        watcherAuditLog(`gc-summary reaped=[${reaped.join(',')}] killed=[${killed.join(',')}]`);
+    return { reaped, killed };
 }
 /** Force-kill a process and its descendants. `taskkill /T` reaps the tree in one
  *  shot so a supervisor can't respawn its child in the race window. */
 function killProcessTree(pid) {
     try {
         if (process.platform === 'win32') {
-            (0, proc_1.safeExecFileSync)('taskkill.exe', ['/PID', String(pid), '/T', '/F'], { timeout: 5_000, stdio: 'ignore', windowsHide: true });
+            (0, child_process_1.execFileSync)('taskkill.exe', ['/PID', String(pid), '/T', '/F'], { timeout: 5_000, stdio: 'ignore', windowsHide: true });
         }
         else {
             try {
@@ -477,27 +463,4 @@ function killProcessTree(pid) {
         return false;
     }
 }
-/** Remove pidfiles whose recorded PID is dead. Keeps `isLocallyArmed` honest
- *  even when a watcher died without removing its own file (hard kill / crash). */
-function sweepDeadPidfiles() {
-    try {
-        const dir = watchersDir();
-        if (!dir || !fs.existsSync(dir))
-            return;
-        for (const f of fs.readdirSync(dir)) {
-            if (!f.endsWith('.json'))
-                continue;
-            try {
-                const rec = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
-                if (!rec || typeof rec.pid !== 'number' || !pidAlive(rec.pid)) {
-                    fs.rmSync(path.join(dir, f), { force: true });
-                }
-            }
-            catch {
-                fs.rmSync(path.join(dir, f), { force: true }); // unparseable → drop
-            }
-        }
-    }
-    catch { /* best-effort */ }
-}
 //# sourceMappingURL=watcher-registry.js.map