@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/instance-reaper.js

@@ -66,7 +66,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeFileAtomicAsync } from "./atomic-write.js";
 import { sweepOwnStagingFiles, } from "./atomic-write-staging.js";
-import { spawnCollectStdout, unrefChildAndPipes } from "./child-unref.js";
+import { acquireQuarantinePidFileLock } from "./bounded-pid-file-lock.js";
+import { spawnCollectStdoutResult, unrefChildAndPipes, } from "./child-unref.js";
+import { incrementDegradationCount, recordDegradationOnce, } from "./degradation-ledger.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
 import { isInstanceRegistryEnabled, readInstanceRegistry, } from "./instance-registry.js";
 import { logLatency } from "./latency-logger.js";
@@ -267,8 +269,16 @@ function posixPsPath() {
 function escapeWqlLikeValue(value) {
     return value.replaceAll("'", "''").replaceAll(/[%_]/g, (ch) => `[${ch}]`);
 }
+/** Escape a value for a WQL EQUALITY comparison: only the string delimiter
+ *  needs escaping — `%`/`_` are literal outside `LIKE`. */
+function escapeWqlStringValue(value) {
+    return value.replaceAll("'", "''");
+}
 /** Search running processes whose command line contains `marker` (Windows,
- *  via CIM/WQL). Returns matching pids. Best-effort: any failure ⇒ []. */
+ *  via CIM/WQL). Returns matching pids. Best-effort: any failure ⇒ [], but a
+ *  failure is RECORDED (#1857 class sweep) — "the search found no orphan" and
+ *  "the search never ran" produce the same empty array, and only the record
+ *  tells them apart. */
 async function findPidsByMarkerWindows(marker) {
     if (!isWindows || !marker)
         return [];
@@ -279,8 +289,15 @@ async function findPidsByMarkerWindows(marker) {
         `| Where-Object { $_.ProcessId -ne $PID } ` +
         `| Select-Object -ExpandProperty ProcessId`;
     const powershell = windowsExe("WindowsPowerShell\\v1.0\\powershell.exe");
-    const out = await spawnCollectStdout(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
-    return out
+    const result = await spawnCollectStdoutResult(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, { timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS });
+    if (result.status !== "ok") {
+        recordDegradationOnce({
+            kind: "orphan-backstop-scan-failed",
+            subject: "marker-search",
+            reason: `marker command-line search ${result.status}`,
+        });
+    }
+    return result.stdout
         .split(/\r?\n/)
         .map((line) => Number(line.trim()))
         .filter((n) => Number.isFinite(n) && n > 0);
@@ -288,19 +305,35 @@ async function findPidsByMarkerWindows(marker) {
 /** Fetch command lines for a set of pids in one query (Windows: CIM; POSIX:
  *  `ps`). Returns a pid → command-line map; pids that can't be resolved are
  *  simply absent (the caller treats absent as "identity unverifiable — do not
- *  kill by pid"). Best-effort: any failure ⇒ empty map. */
+ *  kill by pid").
+ *
+ *  Best-effort: any failure ⇒ empty map, RECORDED (#1857 class sweep). An
+ *  errored query makes every recorded child unverifiable at once, which
+ *  suppresses the entire registry-driven reap — and reads exactly like a
+ *  registry whose children have all already exited. Only the record separates
+ *  the two. */
 async function queryCommandLines(pids) {
     const valid = [...new Set(pids.filter((p) => Number.isFinite(p) && p > 0))];
     const map = new Map();
     if (valid.length === 0)
         return map;
+    const noteFailure = (status) => {
+        if (status === "ok")
+            return;
+        recordDegradationOnce({
+            kind: "orphan-backstop-scan-failed",
+            subject: "identity-query",
+            reason: `command-line identity query ${status}; reap suppressed this sweep`,
+        });
+    };
     if (isWindows) {
         const filter = valid.map((p) => `ProcessId=${p}`).join(" OR ");
         const psScript = `Get-CimInstance Win32_Process -Filter "${filter}" ` +
             `| ForEach-Object { "$($_.ProcessId)\t$($_.CommandLine)" }`;
         const powershell = windowsExe("WindowsPowerShell\\v1.0\\powershell.exe");
-        const out = await spawnCollectStdout(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
-        for (const line of out.split(/\r?\n/)) {
+        const result = await spawnCollectStdoutResult(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, { timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS });
+        noteFailure(result.status);
+        for (const line of result.stdout.split(/\r?\n/)) {
             const tab = line.indexOf("\t");
             if (tab <= 0)
                 continue;
@@ -310,8 +343,14 @@ async function queryCommandLines(pids) {
         }
         return map;
     }
-    const out = await spawnCollectStdout(posixPsPath(), ["-p", valid.join(","), "-o", "pid=,args="], { shell: false, stdio: ["ignore", "pipe", "ignore"] });
-    for (const line of out.split(/\r?\n/)) {
+    const result = await spawnCollectStdoutResult(posixPsPath(), ["-p", valid.join(","), "-o", "pid=,args="], { shell: false, stdio: ["ignore", "pipe", "ignore"] }, { timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS });
+    // `ps -p` exits nonzero when NONE of the pids exist, which is a legitimate
+    // clean result here, so only spawn/timeout failures are recorded. The
+    // shared collector calls that an exit failure, but this caller's command
+    // contract makes that status the expected empty-table result.
+    if (result.status !== "exit-error")
+        noteFailure(result.status);
+    for (const line of result.stdout.split(/\r?\n/)) {
         // Linear parse (S8786/S6594: avoid regex backtracking on
         // attacker-lengthenable ps output) — trim leading whitespace,
         // then split on the first whitespace run: "  1234 args here".
@@ -359,12 +398,34 @@ export function buildIdentityMatcher(cmdlines) {
         return cmdline.toLowerCase().includes(basename);
     };
 }
-/** Force-kill a pid's full process tree. Windows: `taskkill /F /T`. POSIX:
- *  mirror killProcessTree's process-group kill, falling back to a direct
- *  signal. Best-effort: swallow all errors. */
-async function killPidTree(pid) {
+/** Post-kill liveness poll budget. `taskkill /F /T` returns before the kernel
+ *  has finished tearing the tree down, so a single immediate check would
+ *  report false `alive`s. */
+export const KILL_VERIFY_ATTEMPTS = 5;
+export const KILL_VERIFY_INTERVAL_MS = 100;
+/** `setTimeout` as an awaitable, with the timer unref'd so a settled one-shot
+ *  `pi --print` never waits on best-effort kill verification. */
+function sleepUnref(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref();
+    });
+}
+/**
+ * Force-kill a pid's full process tree, then VERIFY. Windows: `taskkill /F
+ * /T`. POSIX: mirror killProcessTree's process-group kill, falling back to a
+ * direct signal. The kill itself stays best-effort (all errors swallowed) —
+ * what changed in #1857 is that the caller now learns the outcome, so an
+ * unverified kill can be recorded with identity instead of being counted as
+ * a success.
+ *
+ * Verification direction is conservative in the safe direction: a recycled
+ * pid now belonging to an unrelated live process reports `alive`, so a real
+ * reap can be under-reported, but a failed reap is never reported as done.
+ */
+async function killPidTree(pid, options = {}) {
     if (!Number.isFinite(pid) || pid <= 0)
-        return;
+        return "invalid";
     if (isWindows) {
         try {
             const taskkill = windowsExe("taskkill.exe");
@@ -382,19 +443,42 @@ async function killPidTree(pid) {
         catch {
             // best-effort
         }
-        return;
     }
-    try {
-        process.kill(-pid, "SIGKILL");
+    else {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                // best-effort — process may already be gone
+            }
+        }
     }
-    catch {
+    return await verifyPidGone(pid, options);
+}
+/** Poll `isPidAlive` for a short budget after a kill attempt. */
+async function verifyPidGone(pid, options = {}) {
+    const isPidAlive = options.isPidAlive ?? realIsPidAlive;
+    const attempts = Math.max(1, options.verifyAttempts ?? KILL_VERIFY_ATTEMPTS);
+    const intervalMs = Math.max(0, options.verifyIntervalMs ?? KILL_VERIFY_INTERVAL_MS);
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        let alive;
         try {
-            process.kill(pid, "SIGKILL");
+            alive = isPidAlive(pid);
         }
         catch {
-            // best-effort — process may already be gone
+            // An unreadable liveness probe is not evidence of death.
+            alive = true;
         }
+        if (!alive)
+            return "gone";
+        if (attempt < attempts - 1)
+            await sleepUnref(intervalMs);
     }
+    return "alive";
 }
 /**
  * #658: known pi-lens-managed LSP/scanner binary names (clients/lsp/server.ts
@@ -406,15 +490,29 @@ async function killPidTree(pid) {
  * (script path), not the process image name, exactly like the existing
  * marker-search's WQL LIKE query below.
  */
-export const MANAGED_BINARY_NAMES = [
-    "ast-grep",
-    "opengrep-core",
-    "opengrep",
-    "marksman",
-    "zizmor",
-    "typos-lsp",
-    "yaml-language-server",
-    "typescript-language-server",
+export const MANAGED_BINARIES = [
+    { name: "ast-grep", launcher: "native" },
+    { name: "opengrep-core", launcher: "native" },
+    { name: "opengrep", launcher: "native" },
+    { name: "marksman", launcher: "native" },
+    { name: "zizmor", launcher: "native" },
+    { name: "typos-lsp", launcher: "native" },
+    { name: "yaml-language-server", launcher: "node" },
+    { name: "typescript-language-server", launcher: "node" },
+];
+/** Derived, never hand-written: the command-line substrings every platform
+ *  matches against. */
+export const MANAGED_BINARY_NAMES = MANAGED_BINARIES.map((binary) => binary.name);
+/**
+ * Derived Windows `Win32_Process.Name` values for the enumeration pre-filter
+ * (#1857). Equality on `Name` replaces eight leading-wildcard `CommandLine
+ * LIKE '%…%'` clauses; the node-launched entries collapse to `node.exe`, so
+ * the query returns a SUPERSET that JS then narrows by the same
+ * `MANAGED_BINARY_NAMES` substring test POSIX already uses. Identical
+ * semantics, one filtering rule.
+ */
+export const MANAGED_IMAGE_NAMES = [
+    ...new Set(MANAGED_BINARIES.map((binary) => binary.launcher === "node" ? "node.exe" : `${binary.name}.exe`)),
 ];
 /**
  * PURE decision function for the #658 registry-independent backstop: given a
@@ -441,13 +539,44 @@ export const MANAGED_BINARY_NAMES = [
  * matching only decides which processes are candidates for this check at
  * all); a live parent is never overridden "however unfamiliar" the process.
  */
-export function decideBackstopOrphanReaping(processes, registry, isPidAlive) {
+export function decideBackstopOrphanReaping(processes, registry, isPidAlive, options = {}) {
+    return partitionBackstopCandidates(processes, registry, isPidAlive, options)
+        .eligible;
+}
+/**
+ * Minimum process age before a name-matching, dead-parent process becomes
+ * backstop-kill-eligible (#1857 item 4).
+ *
+ * The hazard: LSP servers launch through `.cmd` shims with `shell: true`, so
+ * the pid registered in `lspChildren[]` is the shim's. Between the real
+ * server's spawn and its registration there is a window in which the server
+ * is name-matching and untracked. The 2026-08-20 session measured that window
+ * at ~890ms (spawn 10:54:00.602, registration 10:54:01.492) with a sweep
+ * ending at 10:53:59.996 — a near miss saved only by the parent-alive guard,
+ * which is a guard about the PARENT and therefore does not cover a shim whose
+ * parent is briefly unresolvable.
+ *
+ * 60s is roughly 67x the observed window and costs nothing against real
+ * orphans, which are minutes-to-hours old by the time any sweep sees them.
+ */
+export const BACKSTOP_SPAWN_GRACE_MS = 60_000;
+/**
+ * The single implementation of the backstop decision. Returns the eligible
+ * set plus the two age-rejected sets, so `sweepUntrackedOrphans` can record
+ * WHY a candidate was spared instead of losing it into an unexplained count.
+ */
+export function partitionBackstopCandidates(processes, registry, isPidAlive, options = {}) {
+    const graceMs = Math.max(0, options.graceMs ?? BACKSTOP_SPAWN_GRACE_MS);
     const trackedPids = new Set();
     for (const instance of registry) {
         for (const child of instance.lspChildren)
             trackedPids.add(child.pid);
     }
-    const out = [];
+    const partition = {
+        eligible: [],
+        tooFresh: [],
+        unknownAge: [],
+    };
     for (const proc of processes) {
         if (trackedPids.has(proc.pid))
             continue; // owned by the registry-driven reaper
@@ -457,45 +586,84 @@ export function decideBackstopOrphanReaping(processes, registry, isPidAlive) {
             continue; // malformed data guard
         if (isPidAlive(proc.parentPid))
             continue; // live parent — never kill
-        out.push(proc);
+        // Spawn-grace guard, applied LAST so the buckets only ever contain
+        // processes that passed every other eligibility test.
+        if (graceMs > 0) {
+            const ageMs = proc.ageMs;
+            if (typeof ageMs !== "number" || !Number.isFinite(ageMs)) {
+                partition.unknownAge.push(proc);
+                continue;
+            }
+            if (ageMs < graceMs) {
+                partition.tooFresh.push(proc);
+                continue;
+            }
+        }
+        partition.eligible.push(proc);
     }
-    return out;
+    return partition;
 }
 /** Enumerate live OS processes whose command line contains one of
  *  `MANAGED_BINARY_NAMES` (#658), independent of the instance registry.
  *  Windows: one batched CIM/WQL query (mirrors `findPidsByMarkerWindows`'s
  *  query pattern). POSIX: `ps -eo pid=,ppid=,args=`, filtered in JS. Returns
  *  `{pid, parentPid, command}` rows. Best-effort: any failure ⇒ []. */
-async function enumerateManagedProcesses() {
+async function enumerateManagedProcesses(options = {}) {
+    const timeoutMs = options.timeoutMs ?? BACKSTOP_SCAN_TIMEOUT_MS;
+    const collect = {
+        timeoutMs,
+        onTimeout: (child) => terminateScannerChild(child, options),
+    };
     if (isWindows) {
-        const clauses = MANAGED_BINARY_NAMES.map((name) => `CommandLine LIKE '%${escapeWqlLikeValue(name)}%'`).join(" OR ");
-        const psScript = `Get-CimInstance Win32_Process -Filter "${clauses}" ` +
-            `| ForEach-Object { "$($_.ProcessId)\t$($_.ParentProcessId)\t$($_.CommandLine)" }`;
+        // #1857: `Name = '…'` equality replaces eight leading-wildcard
+        // `CommandLine LIKE '%…%'` clauses, and the query now also projects
+        // `CreationDate` so the spawn-grace guard has an age to work with. The
+        // image-name set is DERIVED from MANAGED_BINARIES (MANAGED_IMAGE_NAMES),
+        // so adding a managed binary cannot leave a stale parallel list behind.
+        const clauses = MANAGED_IMAGE_NAMES.map((name) => `Name = '${escapeWqlStringValue(name)}'`).join(" OR ");
+        // The age column is computed IN PowerShell as a millisecond delta, not
+        // exported as `CreationDate.Ticks`. `Ticks` is the LOCAL-time
+        // representation, so subtracting the Unix epoch in JS produced an age
+        // wrong by the machine's UTC offset — measured on a UTC+3 host as
+        // -8358s for a process started 40 minutes earlier. A delta computed on
+        // one side of the boundary has no timezone to get wrong. The explicit
+        // `[datetime]` test matters: `(Get-Date) - $null` yields a two-thousand
+        // year TimeSpan, which would read as "ancient" and defeat the grace
+        // guard exactly where the data is missing.
+        const psScript = `Get-CimInstance -Query "SELECT ProcessId,ParentProcessId,CreationDate,CommandLine FROM Win32_Process WHERE ${clauses}" ` +
+            `| ForEach-Object { $age = if ($_.CreationDate -is [datetime]) { [int64]((Get-Date) - $_.CreationDate).TotalMilliseconds } else { '' }; ` +
+            `"$($_.ProcessId)\t$($_.ParentProcessId)\t$age\t$($_.CommandLine)" }`;
         const powershell = windowsExe("WindowsPowerShell\\v1.0\\powershell.exe");
-        const out = await spawnCollectStdout(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
-        const results = [];
-        for (const line of out.split(/\r?\n/)) {
+        const result = await spawnCollectStdoutResult(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, collect);
+        const processes = [];
+        for (const line of result.stdout.split(/\r?\n/)) {
             const firstTab = line.indexOf("\t");
             if (firstTab <= 0)
                 continue;
             const secondTab = line.indexOf("\t", firstTab + 1);
             if (secondTab <= 0)
                 continue;
+            const thirdTab = line.indexOf("\t", secondTab + 1);
+            if (thirdTab <= 0)
+                continue;
             const pid = Number(line.slice(0, firstTab).trim());
             const parentPid = Number(line.slice(firstTab + 1, secondTab).trim());
-            const command = line.slice(secondTab + 1);
-            if (Number.isFinite(pid) && pid > 0) {
-                results.push({ pid, parentPid, command });
-            }
+            const ageMs = parseNonNegativeMs(line.slice(secondTab + 1, thirdTab));
+            const command = line.slice(thirdTab + 1);
+            if (!Number.isFinite(pid) || pid <= 0)
+                continue;
+            processes.push({ pid, parentPid, command, ageMs });
         }
-        return results;
+        return narrowToManagedBinaries(processes, result);
     }
     // POSIX: enumerate everything, filter in JS by managed-name substring —
     // there is no single-query WQL-style server-side filter available.
-    const out = await spawnCollectStdout(posixPsPath(), ["-eo", "pid=,ppid=,args="], { shell: false, stdio: ["ignore", "pipe", "ignore"] });
-    const results = [];
-    for (const line of out.split(/\r?\n/)) {
-        // Linear parse (S8786/S6594): "  pid ppid args here".
+    // `etime` is the POSIX-standard elapsed-time column (Linux and macOS both
+    // support it; `etimes` is Linux-only), and supplies the spawn-grace age.
+    const result = await spawnCollectStdoutResult(posixPsPath(), [...POSIX_PS_ARGS], { shell: false, stdio: ["ignore", "pipe", "ignore"] }, collect);
+    const processes = [];
+    for (const line of result.stdout.split(/\r?\n/)) {
+        // Linear parse (S8786/S6594): "  pid ppid etime args here".
         const trimmed = line.trimStart();
         if (!trimmed)
             continue;
@@ -516,18 +684,118 @@ async function enumerateManagedProcesses() {
         if (j === 0)
             continue;
         const parentPid = Number(rest.slice(0, j));
-        let m = j;
+        rest = rest.slice(j);
+        let m = 0;
         while (m < rest.length && (rest[m] === " " || rest[m] === "\t"))
             m++;
-        const args = rest.slice(m);
+        rest = rest.slice(m);
+        // etime token: a non-whitespace run of digits, ':' and '-'.
+        let e = 0;
+        while (e < rest.length && rest[e] !== " " && rest[e] !== "\t")
+            e++;
+        const ageMs = ageMsFromPosixEtime(rest.slice(0, e));
+        let n = e;
+        while (n < rest.length && (rest[n] === " " || rest[n] === "\t"))
+            n++;
+        const args = rest.slice(n);
         if (!Number.isFinite(pid) || pid <= 0)
             continue;
-        const lowerArgs = args.toLowerCase();
-        if (MANAGED_BINARY_NAMES.some((name) => lowerArgs.includes(name.toLowerCase()))) {
-            results.push({ pid, parentPid, command: args });
-        }
+        processes.push({ pid, parentPid, command: args, ageMs });
+    }
+    return narrowToManagedBinaries(processes, result);
+}
+/**
+ * The ONE place a raw OS-process snapshot is narrowed to managed binaries.
+ * Both platforms over-collect for their own reason — Windows because
+ * `node.exe` is a superset image name covering every node process on the
+ * machine, POSIX because `ps -e` has no server-side filter — so the narrowing
+ * lives at a single call site rather than being repeated per branch, where one
+ * copy could rot or be dropped unnoticed.
+ */
+function narrowToManagedBinaries(processes, result) {
+    return {
+        processes: processes.filter((proc) => matchesManagedBinary(proc.command)),
+        status: result.status,
+        timeoutKill: result.timeoutKill,
+    };
+}
+/**
+ * Terminate a scanner child that blew the scan timeout, using the reaper's
+ * OWN tree-kill-and-verify machinery (#1864 review F3).
+ *
+ * The previous handler sent one bare signal to the direct child and resolved
+ * in the same tick. On Windows that signal reaches only the `powershell.exe`
+ * we spawned, never a CIM worker beneath it, and nothing checked whether it
+ * died. An orphan sweep that leaks its own scanner is the defect the sweep
+ * exists to fix, so the scanner now gets exactly what an orphan gets:
+ * `taskkill /F /T` or a POSIX group kill, then a verified liveness poll. The
+ * escalation is recorded with the scanner's identity, never swallowed.
+ */
+export async function terminateScannerChild(child, options) {
+    const pid = child.pid;
+    const outcome = typeof pid === "number" && pid > 0
+        ? await killPidTree(pid, {
+            verifyAttempts: options.verifyAttempts,
+            verifyIntervalMs: options.verifyIntervalMs,
+        })
+        : "invalid";
+    incrementDegradationCount({
+        kind: "orphan-backstop-scanner-escalated",
+        subject: `${isWindows ? "win32-cim" : "posix-ps"}#${pid ?? "no-pid"}`,
+        reason: `scan exceeded its timeout; tree kill reported ${outcome}`,
+    });
+    return outcome;
+}
+/** Hard bound on the enumeration child. The 2026-08-20 incident measured the
+ *  Windows CIM query at 9344ms under session_start contention; this caps the
+ *  worst case rather than trusting the median. */
+export const BACKSTOP_SCAN_TIMEOUT_MS = 5_000;
+/** The one command-line match rule, shared by both platforms' parsers. */
+function matchesManagedBinary(command) {
+    const lower = command.toLowerCase();
+    return MANAGED_BINARY_NAMES.some((name) => lower.includes(name.toLowerCase()));
+}
+/**
+ * Parse the Windows age column: a non-negative integer millisecond count, or
+ * anything else. A negative or malformed value is `undefined`, not zero and
+ * not a clamp — a nonsensical age means the age is UNKNOWN, and the grace
+ * guard must spare an unknown-age process rather than reason from a number it
+ * cannot trust. That rule is what surfaced the local-time tick bug during the
+ * host probe instead of silently sparing everything.
+ */
+function parseNonNegativeMs(raw) {
+    const token = raw.trim();
+    if (!/^\d+$/.test(token))
+        return undefined;
+    const value = Number(token);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * POSIX enumeration columns. Exported so a real-`ps` test can assert this
+ * exact argument vector is accepted by the host's `ps` — a rejected column
+ * would make the whole backstop silently return zero rows, and this is the
+ * one part of the fix that cannot be checked from a Windows dev machine.
+ */
+export const POSIX_PS_ARGS = ["-eo", "pid=,ppid=,etime=,args="];
+/** Parse `ps -o etime` output: `[[dd-]hh:]mm:ss`. Returns undefined for any
+ *  shape the column did not produce (a `ps` without the column emits the
+ *  command line where the token was expected). */
+export function ageMsFromPosixEtime(raw) {
+    const token = raw.trim();
+    if (!/^(?:\d+-)?(?:\d+:)?\d+:\d+$/.test(token))
+        return undefined;
+    let days = 0;
+    let rest = token;
+    const dash = rest.indexOf("-");
+    if (dash >= 0) {
+        days = Number(rest.slice(0, dash));
+        rest = rest.slice(dash + 1);
     }
-    return results;
+    const parts = rest.split(":").map(Number);
+    if (parts.some((part) => !Number.isFinite(part)))
+        return undefined;
+    const [hours, minutes, seconds] = parts.length === 3 ? parts : [0, parts[0], parts[1]];
+    return (((days * 24 + hours) * 60 * 60 + minutes * 60 + seconds) * 1000);
 }
 /**
  * Fire-and-forget REGISTRY-INDEPENDENT backstop sweep (#658): finds
@@ -539,55 +807,318 @@ async function enumerateManagedProcesses() {
  * layer: `sweepOrphans`'s registry-driven path is untouched and remains the
  * cheap, correct common case.
  *
- * Kill-attempt retry: deliberately NO separate retry-tracking state. If
- * `killPidTree` fails silently, the process stays alive, untracked, and its
- * parent stays dead — so it stays classified as backstop-kill-eligible and
- * this exact sweep simply tries again at the next `session_start`, with zero
- * extra bookkeeping. This only breaks if the orphan's *parent* pid gets
- * reused by a live process in the interim (closes the window), which is the
- * same residual risk `decideOrphanReaping`'s registry path already accepts.
- * A future hardening (making `killPidTree` return a success signal so a
- * failed kill can be logged distinctly from "already gone") is a reasonable
- * follow-up, not required for correctness here.
+ * Kill-attempt retry: deliberately NO separate retry-tracking state. A
+ * process that survives its kill stays alive, untracked, and dead-parented,
+ * so the next sweep re-classifies it as eligible and tries again. #1857 added
+ * the missing half of that story: the survivor is now RECORDED, by identity,
+ * through `incrementDegradationCount`, instead of being counted as a reap.
+ *
+ * Cost and cadence (#1857): the sweep is deferred off the session_start
+ * critical path by `scheduleUntrackedOrphanSweep`, its enumeration child has
+ * a hard `BACKSTOP_SCAN_TIMEOUT_MS` timeout, and a machine-wide wall-clock
+ * cooldown stops every session from paying for it. The cooldown is a
+ * TIMESTAMP FILE, not a process-lifetime latch: it re-arms by the clock, so a
+ * long-lived host whose sessions keep starting keeps reaping, and a session
+ * that outlives the cooldown is no worse off than before, when the sweep ran
+ * exactly once at its start.
+ *
+ * Mutual exclusion (#1864 review F1): the cooldown check and the stamp write
+ * were a read-check-write, and an atomic rename makes each WRITE atomic
+ * without making the PAIR exclusive — two sessions starting together both read
+ * "no stamp", both wrote, and both swept. The claim now runs under
+ * `acquireQuarantinePidFileLock` (clients/bounded-pid-file-lock.ts:179), the
+ * repo's existing async cross-process lock for work that spans awaited I/O.
+ * The lock is taken FIRST and there is exactly ONE cooldown read, inside it,
+ * so check and claim are a single serialized step rather than a pair with a
+ * window between them. A contended sweep skips rather than waits: the loser
+ * has nothing useful to do, and blocking would put a best-effort background
+ * sweep back on somebody's clock.
  *
  * Never throws — every step is wrapped so a reap failure cannot block or
  * crash the caller (session_start).
  */
-export async function sweepUntrackedOrphans() {
-    if (!isInstanceRegistryEnabled())
-        return;
+export async function sweepUntrackedOrphans(options = {}) {
     const startedAt = Date.now();
+    if (!isInstanceRegistryEnabled()) {
+        return logBackstopOutcome("disabled", startedAt, {});
+    }
+    const cooldownMs = Math.max(0, options.cooldownMs ?? BACKSTOP_COOLDOWN_MS);
+    let release = null;
     try {
-        const [registry, processes] = await Promise.all([
+        // LOCK FIRST, then read the stamp. The ORDER is the fix. A cooldown
+        // check outside the lock followed by a stamp write inside it is still a
+        // read-check-write: two processes both pass the outside check before
+        // either acquires. Keeping a second check inside the lock as well would
+        // leave the outside one doing nothing a mutation could detect, so there
+        // is exactly ONE check and it lives inside the lock — check and claim
+        // are one serialized step. Locking before an eventual skip costs one
+        // mkdir, on a timer that already fired 30 seconds after session start.
+        release = await acquireBackstopLock();
+        if (release === null) {
+            // Another process holds the sweep right now. Not an error, and not a
+            // cooldown either — a distinct record, because "somebody else is
+            // sweeping" and "we swept recently" have different causes.
+            return logBackstopOutcome("concurrent", startedAt, {});
+        }
+        const throttled = await isWithinCooldown(Date.now(), cooldownMs, options);
+        if (throttled !== undefined) {
+            return logBackstopOutcome("cooldown", startedAt, {
+                sinceLastMs: throttled,
+            });
+        }
+        // Claim the cooldown slot BEFORE the scan, not after: a sweep that dies
+        // mid-scan must not re-run at full cost on every retry.
+        await writeBackstopStamp(startedAt);
+        const [registry, scan] = await Promise.all([
             readInstanceRegistry(),
-            enumerateManagedProcesses(),
+            enumerateManagedProcesses({
+                timeoutMs: options.scanTimeoutMs,
+                verifyAttempts: options.verifyAttempts,
+                verifyIntervalMs: options.verifyIntervalMs,
+            }),
         ]);
-        if (processes.length === 0)
-            return;
-        const candidates = decideBackstopOrphanReaping(processes, registry, realIsPidAlive);
-        let killedCount = 0;
-        for (const proc of candidates) {
-            await killPidTree(proc.pid);
-            killedCount++;
+        if (scan.status !== "ok") {
+            // An enumeration that errored or timed out produced an EMPTY result
+            // for a reason that is not "nothing to reap" — record it as such.
+            recordDegradationOnce({
+                kind: "orphan-backstop-scan-failed",
+                subject: isWindows ? "win32-cim" : "posix-ps",
+                reason: `process enumeration ${scan.status}`,
+            });
+            return logBackstopOutcome("error", startedAt, {
+                scanStatus: scan.status,
+                scannerKill: scan.timeoutKill,
+                scanned: scan.processes.length,
+            });
         }
-        try {
-            logLatency({
-                type: "phase",
-                phase: "orphan_backstop_reaped",
-                filePath: "",
-                durationMs: Date.now() - startedAt,
-                metadata: {
-                    scanned: processes.length,
-                    killed: killedCount,
-                },
+        const partition = partitionBackstopCandidates(scan.processes, registry, realIsPidAlive, { graceMs: options.graceMs });
+        for (const proc of partition.unknownAge) {
+            // A spared kill must never be silent: without this the guard would
+            // look identical to "found nothing".
+            incrementDegradationCount({
+                kind: "orphan-backstop-age-unknown",
+                subject: describeManagedProcess(proc),
+                reason: "OS snapshot reported no usable process creation time",
             });
         }
-        catch {
-            // best-effort logging only
+        const killed = [];
+        const unverified = [];
+        for (const proc of partition.eligible) {
+            const identity = describeManagedProcess(proc);
+            const outcome = await killPidTree(proc.pid, {
+                verifyAttempts: options.verifyAttempts,
+                verifyIntervalMs: options.verifyIntervalMs,
+            });
+            if (outcome === "gone") {
+                killed.push(identity);
+                continue;
+            }
+            unverified.push(identity);
+            incrementDegradationCount({
+                kind: "orphan-backstop-kill-unverified",
+                subject: identity,
+                reason: `kill attempted, process still ${outcome === "alive" ? "alive" : "unresolvable"}`,
+            });
+        }
+        const retryAt = scheduleGraceRetryIfNeeded(partition, options);
+        return logBackstopOutcome(classifyKillOutcome(killed.length, unverified.length), startedAt, {
+            scanStatus: scan.status,
+            scanned: scan.processes.length,
+            eligible: partition.eligible.length,
+            tooFresh: partition.tooFresh.length,
+            unknownAge: partition.unknownAge.length,
+            killed: killed.length,
+            killUnverified: unverified.length,
+            // Identity of the kill, bounded — #1857 item 3. Counts alone can
+            // never answer "which process did we kill?".
+            killedProcesses: killed.slice(0, BACKSTOP_IDENTITY_LOG_LIMIT),
+            unverifiedProcesses: unverified.slice(0, BACKSTOP_IDENTITY_LOG_LIMIT),
+            graceRetryInMs: retryAt,
+        });
+    }
+    catch (error) {
+        // The sweep must never throw out of session_start — but "threw" is now
+        // a distinguishable record rather than a silent absence.
+        recordDegradationOnce({
+            kind: "orphan-backstop-scan-failed",
+            subject: "sweep",
+            reason: `sweep threw: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return logBackstopOutcome("error", startedAt, { threw: true });
+    }
+    finally {
+        if (release) {
+            await release().catch(() => {
+                // A lock we cannot release goes stale on its own timer.
+            });
         }
     }
+}
+/** Map verified/unverified kill counts onto the outcome. The only place that
+ *  mapping exists. */
+function classifyKillOutcome(killed, unverified) {
+    if (unverified === 0)
+        return killed > 0 ? "reaped" : "clean";
+    return killed > 0 ? "partial" : "unverified";
+}
+/**
+ * Minimum wall-clock gap between backstop sweeps, machine-wide. The backstop
+ * catches processes that are already orphaned and will stay orphaned; it is
+ * not time-critical, so paying its cost once per half hour instead of once
+ * per session_start removes essentially all of its aggregate cost.
+ */
+export const BACKSTOP_COOLDOWN_MS = 30 * 60 * 1000;
+/** How long after session_start the deferred sweep fires. Chosen to clear the
+ *  warmup window it was measured starving: `warmup_total` median 3288ms,
+ *  worst on record 5480ms (#1857). */
+export const BACKSTOP_START_DELAY_MS = 30_000;
+/** Cap on process identities embedded in one latency record. */
+const BACKSTOP_IDENTITY_LOG_LIMIT = 10;
+/**
+ * Extra margin on top of the spawn grace before the follow-up sweep runs, so
+ * a candidate that was 1ms too fresh is comfortably past the grace by the
+ * time the retry looks at it again.
+ */
+export const BACKSTOP_GRACE_RETRY_MARGIN_MS = 30_000;
+/** How long the sweep lock may be held before another process reclaims it.
+ *  Well above the scan timeout plus the kill budget, and irrelevant when the
+ *  holder dies — the lock reclaims immediately on a dead owner pid
+ *  (clients/bounded-pid-file-lock.ts:90). */
+const BACKSTOP_LOCK_STALE_MS = 120_000;
+/**
+ * Schedule the backstop sweep OFF the session_start critical path. The timer
+ * is `unref`'d, so a settled one-shot `pi --print` exits without waiting and
+ * the sweep simply does not happen for that invocation — which is correct: a
+ * process too short-lived to reach the delay is also too short-lived to be
+ * the right place to spend seconds of CIM time.
+ */
+export function scheduleUntrackedOrphanSweep(delayMs = BACKSTOP_START_DELAY_MS, options = {}) {
+    const timer = setTimeout(() => {
+        void sweepUntrackedOrphans(options).catch(() => {
+            // sweepUntrackedOrphans never rejects; belt-and-braces.
+        });
+    }, Math.max(0, delayMs));
+    timer.unref();
+    return timer;
+}
+/**
+ * Arm ONE follow-up sweep when the spawn grace spared a candidate (#1864
+ * review F2).
+ *
+ * Without it, the grace guard could spare an orphan indefinitely: the sweep
+ * runs once per session, a candidate younger than the grace is spared, and a
+ * long-lived session never looks again. That is a regression against the old
+ * always-at-session-start sweep, which at least re-examined the process every
+ * session.
+ *
+ * The retry passes `force` (the cooldown it would otherwise hit is the stamp
+ * this same sweep just wrote) and `allowGraceRetry: false`, so the chain is
+ * exactly one deep. It still takes the lock, so it cannot race a concurrent
+ * sweep. Residual: if the process exits before the timer fires, the spared
+ * candidate waits for the next session's sweep — the retry is unref'd, and a
+ * background reap must never hold a settled one-shot open.
+ *
+ * Returns the delay armed, or undefined when nothing was spared.
+ */
+function scheduleGraceRetryIfNeeded(partition, options) {
+    if (options.allowGraceRetry === false)
+        return undefined;
+    if (partition.tooFresh.length === 0)
+        return undefined;
+    const graceMs = Math.max(0, options.graceMs ?? BACKSTOP_SPAWN_GRACE_MS);
+    const delayMs = Math.max(0, options.graceRetryDelayMs ?? graceMs + BACKSTOP_GRACE_RETRY_MARGIN_MS);
+    scheduleUntrackedOrphanSweep(delayMs, {
+        ...options,
+        force: true,
+        allowGraceRetry: false,
+    });
+    return delayMs;
+}
+/** Serialize the sweep across processes. Returns null when another process
+ *  holds it — the caller skips rather than waits (`waitMs: 0`). */
+async function acquireBackstopLock() {
+    try {
+        return await acquireQuarantinePidFileLock(path.join(getGlobalPiLensDir(), "orphan-backstop.lock"), {
+            waitMs: 0,
+            retryMs: 50,
+            staleMs: BACKSTOP_LOCK_STALE_MS,
+            timeoutMessage: "orphan backstop sweep lock contended",
+            onContention: "skip-log",
+            logContention: () => {
+                // The caller emits the `concurrent` record; nothing to add here.
+            },
+        });
+    }
     catch {
-        // The sweep must never throw out of session_start.
+        // A lock we cannot even attempt (unwritable global dir) must not disable
+        // the backstop — fall through unlocked, exactly as before this fix.
+        return async () => { };
+    }
+}
+/** Milliseconds since the last sweep when the cooldown is in force, else
+ *  undefined. Centralized so the pre-check and the in-lock re-check cannot
+ *  drift apart. */
+async function isWithinCooldown(now, cooldownMs, options) {
+    if (cooldownMs <= 0 || options.force)
+        return undefined;
+    const lastSweepAt = await readBackstopStamp();
+    if (lastSweepAt === undefined)
+        return undefined;
+    const sinceLastMs = now - lastSweepAt;
+    return sinceLastMs < cooldownMs ? sinceLastMs : undefined;
+}
+/** Short, stable identity for one managed process: which binary, which pid.
+ *  Full command lines are user paths and can be long, so the record carries
+ *  the matched managed-binary name plus the pid. */
+function describeManagedProcess(proc) {
+    const lower = proc.command.toLowerCase();
+    const matched = MANAGED_BINARY_NAMES.find((name) => lower.includes(name.toLowerCase()));
+    return `${matched ?? "unknown"}#${proc.pid}`;
+}
+function logBackstopOutcome(outcome, startedAt, metadata) {
+    try {
+        logLatency({
+            type: "phase",
+            phase: "orphan_backstop_reaped",
+            filePath: "",
+            durationMs: Date.now() - startedAt,
+            metadata: { outcome, ...metadata },
+        });
+    }
+    catch {
+        // best-effort logging only
+    }
+    return outcome;
+}
+/** Machine-wide cooldown stamp. A file, not a module-level flag: the sweep is
+ *  machine-scoped (every pi-lens process shares one OS process table), and
+ *  process-lifetime state cannot express "30 minutes have passed". */
+function backstopStampPath() {
+    return path.join(getGlobalPiLensDir(), "orphan-backstop.json");
+}
+async function readBackstopStamp() {
+    try {
+        const raw = await fs.promises.readFile(backstopStampPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        const value = parsed?.lastSweepAt;
+        return typeof value === "number" && Number.isFinite(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        // Absent or unreadable ⇒ no cooldown in force, so the sweep runs. A
+        // corrupt stamp must never be able to disable the backstop permanently.
+        return undefined;
+    }
+}
+async function writeBackstopStamp(at) {
+    try {
+        await fs.promises.mkdir(getGlobalPiLensDir(), { recursive: true });
+        await writeFileAtomicAsync(backstopStampPath(), JSON.stringify({ lastSweepAt: at }));
+    }
+    catch {
+        // best-effort — a stamp we cannot persist just means the next session
+        // pays for another sweep, never a crash.
     }
 }
 /**
@@ -615,20 +1146,34 @@ export async function sweepOrphans() {
         const cmdlines = await queryCommandLines(candidatePids);
         const matchProcess = buildIdentityMatcher(cmdlines);
         const decision = decideOrphanReaping(registry, realIsPidAlive, matchProcess);
+        // #1857 class sweep: the registry-driven path spelled the same
+        // attempt-counted-as-kill defect as the backstop, so it gets the same
+        // verified accounting and the same bounded, identity-carrying record.
         let killedCount = 0;
+        let unverifiedCount = 0;
         const killedServerIds = [];
+        const killAndAccount = async (pid, serverId) => {
+            const outcome = await killPidTree(pid);
+            if (outcome === "gone") {
+                killedCount++;
+                killedServerIds.push(serverId);
+                return;
+            }
+            unverifiedCount++;
+            incrementDegradationCount({
+                kind: "orphan-reap-kill-unverified",
+                subject: `${serverId}#${pid}`,
+                reason: `kill attempted, process still ${outcome === "alive" ? "alive" : "unresolvable"}`,
+            });
+        };
         for (const child of decision.childrenToKill) {
-            await killPidTree(child.pid);
-            killedCount++;
-            killedServerIds.push(child.serverId);
+            await killAndAccount(child.pid, child.serverId);
         }
         for (const search of decision.markerSearches) {
             try {
                 const pids = await findPidsByMarkerWindows(search.marker);
                 for (const pid of pids) {
-                    await killPidTree(pid);
-                    killedCount++;
-                    killedServerIds.push(search.serverId);
+                    await killAndAccount(pid, search.serverId);
                 }
             }
             catch {
@@ -661,6 +1206,7 @@ export async function sweepOrphans() {
                     deadInstances: decision.deadInstances.length,
                     staleInstances: decision.staleInstances.length,
                     killed: killedCount,
+                    killUnverified: unverifiedCount,
                     serverIds: killedServerIds,
                     markerSearches: decision.markerSearches.length,
                 },