@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/dist/lib/secrets/index.js

@@ -36,6 +36,57 @@ import { deriveShortId } from '../session/short-id.js';
 const SERVICE_PREFIX = 'agents-cli';
 export const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
 const BUNDLES_ITEM_PREFIX = `${SERVICE_PREFIX}.bundles.`;
+/** Timeout for keychain-helper verbs that never raise a user prompt. */
+const KEYCHAIN_SILENT_TIMEOUT_MS = 8_000;
+/** Timeout for verbs that may raise Touch ID / password auth UI. */
+const KEYCHAIN_INTERACTIVE_TIMEOUT_MS = 60_000;
+/**
+ * Thrown when a keychain helper / security spawnSync is killed because it
+ * exceeded its timeout. A wedged coreauthd / LocalAuthentication dialog can hang
+ * the parent forever; this makes the failure explicit and arms the read back-off.
+ */
+export class KeychainHelperTimeoutError extends Error {
+    bin;
+    args;
+    constructor(bin, args) {
+        super(`keychain helper timed out (${bin} ${args.join(' ')}) — keychain locked / ` +
+            `LocalAuthentication unresponsive — retry; if it persists, lock/unlock the screen or reboot`);
+        this.bin = bin;
+        this.args = args;
+        this.name = 'KeychainHelperTimeoutError';
+    }
+}
+let keychainDaemonBootEnabled = true;
+let keychainDaemonBootAttempted = false;
+/** Test seam: suppress the side-effect daemon boot in unit tests. */
+export function setKeychainDaemonBootForTest(enabled) {
+    keychainDaemonBootEnabled = enabled;
+}
+/**
+ * Single wrapper for every keychain-helper (and /usr/bin/security) spawnSync.
+ * Applies a hard timeout + SIGKILL so a wedged coreauthd can never hang the
+ * parent process. Throws {@link KeychainHelperTimeoutError} when the child is
+ * killed by the timeout. Also boots the daemon once per process so the reaper
+ * can clean up any stuck helpers this or prior invocations left behind.
+ */
+function spawnKeychainHelper(bin, args, opts, timeoutMs) {
+    if (keychainDaemonBootEnabled && !keychainDaemonBootAttempted) {
+        keychainDaemonBootAttempted = true;
+        // Fire-and-forget: daemon start must not block the foreground secrets op.
+        import('../daemon.js')
+            .then(({ ensureDaemonStarted }) => ensureDaemonStarted())
+            .catch(() => { });
+    }
+    const result = spawnSync(bin, args, { ...opts, timeout: timeoutMs, killSignal: 'SIGKILL' });
+    if (result.signal) {
+        throw new KeychainHelperTimeoutError(bin, args);
+    }
+    return result;
+}
+/** Test seam: exercise the timeout wrapper with an arbitrary binary. */
+export function spawnKeychainHelperForTest(bin, args, opts, timeoutMs) {
+    return spawnKeychainHelper(bin, args, opts, timeoutMs);
+}
 const REF_PATTERN = /^(keychain|env|file|exec):(.+)$/s;
 /** Parse a bundle value into either a literal string or a typed secret ref. */
 export function parseBundleValue(raw) {
@@ -725,14 +776,28 @@ export function hasKeychainToken(item) {
     if (isWindows())
         return windowsBackend.has(item);
     if (!isOurItem(item)) {
-        return spawnSync('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item], {
+        return spawnKeychainHelper('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item], {
             stdio: ['ignore', 'ignore', 'ignore'],
-        }).status === 0;
+        }, KEYCHAIN_SILENT_TIMEOUT_MS).status === 0;
     }
     const bin = getKeychainHelperPath();
-    return spawnSync(bin, ['has', item, os.userInfo().username], {
+    const r = spawnKeychainHelper(bin, ['has', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    }).status === 0;
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
+    // The helper exits 0 = present (incl. errSecInteractionNotAllowed — a locked or
+    // biometry-ACL'd item still EXISTS), 1 = genuinely absent. Any other outcome
+    // (bad args, helper failure, spawn error) means the keychain could not be
+    // reached — and a false "absent" silently disarms every destructive-write guard
+    // that calls this (see the docblock), so it MUST fail loud rather than answer
+    // "no" (RUSH-2235). Timeouts already throw inside spawnKeychainHelper.
+    if (r.status === 0)
+        return true;
+    if (r.status === 1)
+        return false;
+    const stderr = r.stderr?.toString().trim();
+    throw new Error(stderr ||
+        `keychain existence check for '${item}' failed (helper exit ${r.status ?? 'null'}` +
+            `${r.error ? `: ${r.error.message}` : ''}) — keychain unreachable, not a proven absence.`);
 }
 /**
  * The detector the raw-read storm guard consults, overridable so tests on any
@@ -808,9 +873,9 @@ export function getKeychainToken(item, context = {}) {
     if (isWindows())
         return windowsBackend.get(item);
     if (!isOurItem(item)) {
-        const sec = spawnSync('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+        const sec = spawnKeychainHelper('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
             stdio: ['ignore', 'pipe', 'pipe'],
-        });
+        }, KEYCHAIN_SILENT_TIMEOUT_MS);
         if (sec.status === 0) {
             const token = sec.stdout?.toString().trim();
             if (token) {
@@ -821,15 +886,24 @@ export function getKeychainToken(item, context = {}) {
         throw new Error(`Keychain item '${requested}' not found.`);
     }
     const bin = getKeychainHelperPath();
-    const result = spawnSync(bin, ['get', item, os.userInfo().username], {
-        env: {
-            ...process.env,
-            AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
-            AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
-            AGENTS_KEYCHAIN_SKIP_AUTH_UI: context.silentNoAcl ? '1' : '0',
-        },
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    let result;
+    try {
+        result = spawnKeychainHelper(bin, ['get', item, os.userInfo().username], {
+            env: {
+                ...process.env,
+                AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
+                AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+                AGENTS_KEYCHAIN_SKIP_AUTH_UI: context.silentNoAcl ? '1' : '0',
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }, KEYCHAIN_INTERACTIVE_TIMEOUT_MS);
+    }
+    catch (err) {
+        if (err instanceof KeychainHelperTimeoutError && !context.silentNoAcl) {
+            noteKeychainReadFailure(requested);
+        }
+        throw err;
+    }
     // Exit 1 is a plain miss — no prompt was raised, so it opens no back-off.
     if (result.status === 1)
         throw new Error(`Keychain item '${requested}' not found.`);
@@ -913,19 +987,28 @@ export function getKeychainTokens(items, context = {}) {
         return result;
     }
     const bin = getKeychainHelperPath();
-    const child = spawnSync(bin, ['get-batch', os.userInfo().username, ...storageItems], {
-        env: {
-            ...process.env,
-            AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
-            AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
-            AGENTS_KEYCHAIN_SKIP_AUTH_UI: context.silentNoAcl ? '1' : '0',
-            // The signed helper's own vocabulary is unchanged (it predates the rename
-            // and ships as a separately-versioned binary), so map to its legacy token.
-            AGENTS_KEYCHAIN_DEFAULT_POLICY: (context.defaultPolicy ?? 'hold') === 'hold' ? 'daily' : context.defaultPolicy,
-            AGENTS_KEYCHAIN_FORCE_DURATION: context.forceDuration ? '1' : '0',
-        },
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    let child;
+    try {
+        child = spawnKeychainHelper(bin, ['get-batch', os.userInfo().username, ...storageItems], {
+            env: {
+                ...process.env,
+                AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
+                AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+                AGENTS_KEYCHAIN_SKIP_AUTH_UI: context.silentNoAcl ? '1' : '0',
+                // The signed helper's own vocabulary is unchanged (it predates the rename
+                // and ships as a separately-versioned binary), so map to its legacy token.
+                AGENTS_KEYCHAIN_DEFAULT_POLICY: (context.defaultPolicy ?? 'hold') === 'hold' ? 'daily' : context.defaultPolicy,
+                AGENTS_KEYCHAIN_FORCE_DURATION: context.forceDuration ? '1' : '0',
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }, KEYCHAIN_INTERACTIVE_TIMEOUT_MS);
+    }
+    catch (err) {
+        if (err instanceof KeychainHelperTimeoutError && !context.silentNoAcl) {
+            noteKeychainReadFailure(backoffKey);
+        }
+        throw err;
+    }
     if (child.status !== 0 && !context.silentNoAcl)
         noteKeychainReadFailure(backoffKey);
     if (child.status === 4) {
@@ -1063,7 +1146,7 @@ export function setKeychainToken(item, value, opts) {
         // controlling terminal, so readpassphrase always falls back to our piped
         // stdin. Without it, an interactive `agents view` (refreshing+saving a Claude
         // OAuth token) or `agents secrets add` pops a keychain password sheet.
-        const sec = spawnSync('/usr/bin/security', buildAddGenericPasswordArgs(os.userInfo().username, item), buildAddGenericPasswordSpawnOptions(value));
+        const sec = spawnKeychainHelper('/usr/bin/security', buildAddGenericPasswordArgs(os.userInfo().username, item), buildAddGenericPasswordSpawnOptions(value), KEYCHAIN_SILENT_TIMEOUT_MS);
         if (sec.status !== 0) {
             const msg = sec.stderr?.toString().trim();
             throw new Error(msg || `Failed to write keychain item '${item}'.`);
@@ -1076,10 +1159,10 @@ export function setKeychainToken(item, value, opts) {
     // re-notarized helper; an older pinned helper dies with "Unknown command:
     // set-no-acl" (exit 2), surfaced below — never a silent ACL'd downgrade.
     const helperCmd = opts?.noAcl ? 'set-no-acl' : 'set';
-    const result = spawnSync(bin, [helperCmd, item, os.userInfo().username], {
+    const result = spawnKeychainHelper(bin, [helperCmd, item, os.userInfo().username], {
         input: value,
         stdio: ['pipe', 'pipe', 'pipe'],
-    });
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
     if (result.status !== 0) {
         const msg = result.stderr?.toString().trim();
         if (opts?.noAcl && /unknown command/i.test(msg ?? '')) {
@@ -1106,14 +1189,26 @@ export function deleteKeychainToken(item) {
     if (isWindows())
         return windowsBackend.delete(item);
     const bin = getKeychainHelperPath();
-    const deleted = spawnSync(bin, ['delete', item, os.userInfo().username], {
+    const r = spawnKeychainHelper(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    }).status === 0;
-    // A deleted item must fail its next read as plain "not found", not with a
-    // stale back-off error left over from a pre-delete cancel.
-    if (deleted)
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
+    // The helper exits 0 = an item was removed from at least one keychain, 1 =
+    // nothing to delete (genuinely absent). Any other outcome means the keychain
+    // could not be reached; like hasKeychainToken this must fail loud rather than
+    // report a false "nothing was there" (RUSH-2235) — a swallowed failure lets a
+    // rename/purge believe it cleared a name it did not.
+    if (r.status === 0) {
+        // A deleted item must fail its next read as plain "not found", not with a
+        // stale back-off error left over from a pre-delete cancel.
         clearKeychainReadBackoff(requested);
-    return deleted;
+        return true;
+    }
+    if (r.status === 1)
+        return false;
+    const stderr = r.stderr?.toString().trim();
+    throw new Error(stderr ||
+        `keychain delete for '${item}' failed (helper exit ${r.status ?? 'null'}` +
+            `${r.error ? `: ${r.error.message}` : ''}) — keychain unreachable, deletion unproven.`);
 }
 /**
  * True when the active keychain backend transparently routes reads/writes to
@@ -1149,9 +1244,9 @@ export function listKeychainItems(prefix) {
     if (isWindows())
         return apply(windowsBackend.list(mapped.prefix));
     const bin = getKeychainHelperPath();
-    const result = spawnSync(bin, ['list', mapped.prefix], {
+    const result = spawnKeychainHelper(bin, ['list', mapped.prefix], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
     if (result.status !== 0) {
         const msg = result.stderr?.toString().trim();
         throw new Error(msg || `Failed to enumerate keychain items with prefix '${prefix}'.`);
@@ -1176,9 +1271,9 @@ export function listLegacyKeychainItems(prefix) {
     if (isLinux())
         return [];
     const bin = getKeychainHelperPath();
-    const result = spawnSync(bin, ['list-legacy', prefix], {
+    const result = spawnKeychainHelper(bin, ['list-legacy', prefix], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
     if (result.status !== 0) {
         const msg = result.stderr?.toString().trim();
         throw new Error(msg || `Failed to enumerate legacy keychain items with prefix '${prefix}'.`);
@@ -1209,9 +1304,9 @@ export function listSyncedKeychainItems(prefix) {
     if (isLinux() || isWindows())
         return [];
     const bin = getKeychainHelperPath();
-    const result = spawnSync(bin, ['list-synced', prefix], {
+    const result = spawnKeychainHelper(bin, ['list-synced', prefix], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
     if (result.status !== 0) {
         const msg = result.stderr?.toString().trim();
         throw new Error(msg || `Failed to enumerate iCloud keychain items with prefix '${prefix}'.`);
@@ -1237,9 +1332,9 @@ export function getSyncedKeychainTokens(items) {
     if (isLinux() || isWindows())
         return result;
     const bin = getKeychainHelperPath();
-    const child = spawnSync(bin, ['get-batch-synced', os.userInfo().username, ...items], {
+    const child = spawnKeychainHelper(bin, ['get-batch-synced', os.userInfo().username, ...items], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    }, KEYCHAIN_INTERACTIVE_TIMEOUT_MS);
     if (child.status === 4) {
         throw new Error(`Auth cancelled while reading ${items.length} iCloud keychain item(s).`);
     }
@@ -1265,9 +1360,9 @@ export function deleteSyncedKeychainItem(item) {
     if (isLinux() || isWindows())
         return false;
     const bin = getKeychainHelperPath();
-    return spawnSync(bin, ['delete-synced', item, os.userInfo().username], {
+    return spawnKeychainHelper(bin, ['delete-synced', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    }).status === 0;
+    }, KEYCHAIN_SILENT_TIMEOUT_MS).status === 0;
 }
 /**
  * One-time upgrade for a keychain item that was written by a previous helper
@@ -1286,9 +1381,9 @@ export function migrateKeychainItem(item) {
     if (isWindows())
         return windowsBackend.has(item);
     const bin = getKeychainHelperPath();
-    const result = spawnSync(bin, ['migrate-acl', item, os.userInfo().username], {
+    const result = spawnKeychainHelper(bin, ['migrate-acl', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    }, KEYCHAIN_INTERACTIVE_TIMEOUT_MS);
     if (result.status === 0)
         return true;
     if (result.status === 1)
@@ -1310,9 +1405,9 @@ export function listOrphanedKeychainItems(prefix) {
     if (isLinux() || isWindows())
         return [];
     const bin = getKeychainHelperPath();
-    const result = spawnSync(bin, ['list-orphans', prefix, os.userInfo().username], {
+    const result = spawnKeychainHelper(bin, ['list-orphans', prefix, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    }, KEYCHAIN_SILENT_TIMEOUT_MS);
     if (result.status !== 0) {
         const msg = result.stderr?.toString().trim();
         throw new Error(msg || `Failed to enumerate orphaned keychain items with prefix '${prefix}'.`);
@@ -1368,9 +1463,9 @@ export function migrateOrphanedKeychainItems(prefix) {
     if (isLinux() || isWindows())
         return [];
     const bin = getKeychainHelperPath();
-    const result = spawnSync(bin, ['migrate-orphans', prefix, os.userInfo().username], {
+    const result = spawnKeychainHelper(bin, ['migrate-orphans', prefix, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    }, KEYCHAIN_INTERACTIVE_TIMEOUT_MS);
     if (result.status === 4)
         throw new Error('Touch ID cancelled during orphan migration.');
     if (result.status !== 0) {

package/dist/lib/secrets/reaper.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Reaper for orphaned / wedged keychain-helper processes.
+ *
+ * macOS keychain-helper calls are synchronous spawnSync invocations. When
+ * coreauthd / LocalAuthentication hangs, the helper process (and sometimes its
+ * parent `agents` process) can pile up forever. This module detects two classes
+ * of stale process and kills them.
+ *
+ * The design splits cleanly into:
+ *   - a pure planner ({@link planKeychainReap}) that is unit-testable without a
+ *     real `ps` shell, and
+ *   - an impure driver ({@link reapOrphanedKeychainProcesses}) that shells `ps`
+ *     once per tick and executes kills through {@link killTree}.
+ */
+/** Elapsed grace before a helper whose parent exited is considered an orphan. */
+export declare const ORPHAN_GRACE_SEC = 30;
+/** Elapsed grace before a helper with a live parent is considered stuck. */
+export declare const STUCK_GRACE_SEC = 90;
+/** Snapshot of one process row from `ps`, fed into the pure planner. */
+export interface KeychainProcessSnapshot {
+    pid: number;
+    ppid: number;
+    /** Elapsed seconds since the process started. */
+    elapsedSec: number;
+    /**
+     * Stable start-time fingerprint from {@link captureProcessStartTime}.
+     * `null` means "could not capture" — the planner must fail closed.
+     */
+    startTime: string | null;
+    /** True when this process's executable path matches the installed helper. */
+    isHelper: boolean;
+}
+/**
+ * Tracked state for a stuck `agents` parent that has a live helper child.
+ * Keyed by parent PID. The two-sweep debounce avoids acting on a racy `ps`
+ * snapshot; the `stage` field drives child-first kill then parent escalation.
+ */
+export interface StuckParentCandidate {
+    pid: number;
+    startTime: string | null;
+    helperPid: number;
+    helperStartTime: string | null;
+    firstSeenAt: number;
+    stage: 'watch' | 'escalate';
+}
+/** Result of one planning pass. */
+export interface ReapPlan {
+    /** PIDs that should be killed this tick. */
+    kill: number[];
+    /** Candidates to carry forward to the next sweep. */
+    nextCandidates: Map<number, StuckParentCandidate>;
+}
+/**
+ * Pure predicate: decide which processes to kill given a `ps`-like snapshot.
+ *
+ * Mirrors the shape of {@link isExpiredPoolStray} in `lib/crabbox/lease.ts`:
+ * a side-effect-free classifier that the impure driver shells `ps` for. Two
+ * conservative reap classes:
+ *
+ *   1. Orphaned helper: PPID == 1, path-matches the helper, alive longer than
+ *      {@link ORPHAN_GRACE_SEC}.
+ *   2. Stuck `agents` parent: helper child alive longer than
+ *      {@link STUCK_GRACE_SEC}. Recorded on first sight, child killed on the
+ *      second consecutive sweep with the same PID + startTime, parent killed on
+ *      the third sweep if the helper child is still present.
+ *
+ * Never reaps a process whose start time could not be captured, whose path does
+ * not match the helper, or whose parent is no longer in the snapshot.
+ */
+export declare function planKeychainReap(snapshots: KeychainProcessSnapshot[], now: number, prevCandidates: ReadonlyMap<number, StuckParentCandidate>): ReapPlan;
+/**
+ * Parse macOS `ps -o etime=` elapsed time into whole seconds.
+ *
+ * BSD `etime` renders as `[[dd-]hh:]mm:ss` (e.g. `05:03`, `01:02:03`,
+ * `14-04:10:52`). This is the portable keyword: `etimes` (raw seconds) is a
+ * GNU/Linux procps extension that macOS `ps` rejects with a non-zero exit, so
+ * the reaper — which only ever runs on darwin — must read `etime`.
+ * Returns null for an unparseable value so the caller drops the row.
+ */
+export declare function parseEtimeToSeconds(raw: string): number | null;
+/** Test seam: reset the persisted candidate state. */
+export declare function resetKeychainReaperCandidatesForTest(): void;
+/**
+ * Impure driver: snapshot all processes once with `ps`, plan the reap, then
+ * execute kills through {@link killTree}.
+ *
+ * Path-matching uses the full helper path (proc_pidpath-style), not just the
+ * executable name, so an unrelated binary named "Agents CLI" is never targeted.
+ *
+ * Returns on non-darwin platforms without shelling anything — the helper only
+ * exists on macOS.
+ */
+export declare function reapOrphanedKeychainProcesses(): {
+    reaped: number;
+    details: string[];
+    plan: ReapPlan;
+};

package/dist/lib/secrets/reaper.js

@@ -0,0 +1,219 @@
+/**
+ * Reaper for orphaned / wedged keychain-helper processes.
+ *
+ * macOS keychain-helper calls are synchronous spawnSync invocations. When
+ * coreauthd / LocalAuthentication hangs, the helper process (and sometimes its
+ * parent `agents` process) can pile up forever. This module detects two classes
+ * of stale process and kills them.
+ *
+ * The design splits cleanly into:
+ *   - a pure planner ({@link planKeychainReap}) that is unit-testable without a
+ *     real `ps` shell, and
+ *   - an impure driver ({@link reapOrphanedKeychainProcesses}) that shells `ps`
+ *     once per tick and executes kills through {@link killTree}.
+ */
+import { execFileSync } from 'child_process';
+import { killTree, captureProcessStartTime } from '../platform/process.js';
+import { getKeychainHelperPath } from './install-helper.js';
+/** Elapsed grace before a helper whose parent exited is considered an orphan. */
+export const ORPHAN_GRACE_SEC = 30;
+/** Elapsed grace before a helper with a live parent is considered stuck. */
+export const STUCK_GRACE_SEC = 90;
+/**
+ * Pure predicate: decide which processes to kill given a `ps`-like snapshot.
+ *
+ * Mirrors the shape of {@link isExpiredPoolStray} in `lib/crabbox/lease.ts`:
+ * a side-effect-free classifier that the impure driver shells `ps` for. Two
+ * conservative reap classes:
+ *
+ *   1. Orphaned helper: PPID == 1, path-matches the helper, alive longer than
+ *      {@link ORPHAN_GRACE_SEC}.
+ *   2. Stuck `agents` parent: helper child alive longer than
+ *      {@link STUCK_GRACE_SEC}. Recorded on first sight, child killed on the
+ *      second consecutive sweep with the same PID + startTime, parent killed on
+ *      the third sweep if the helper child is still present.
+ *
+ * Never reaps a process whose start time could not be captured, whose path does
+ * not match the helper, or whose parent is no longer in the snapshot.
+ */
+export function planKeychainReap(snapshots, now, prevCandidates) {
+    const pidMap = new Map(snapshots.map((s) => [s.pid, s]));
+    const kill = [];
+    const nextCandidates = new Map();
+    for (const s of snapshots) {
+        if (!s.isHelper)
+            continue;
+        if (s.ppid === 1) {
+            // Orphaned helper: parent is init/launchd. Fail closed if we can't prove
+            // the process identity with a start-time fingerprint.
+            if (s.elapsedSec <= ORPHAN_GRACE_SEC)
+                continue;
+            if (s.startTime == null)
+                continue;
+            kill.push(s.pid);
+            continue;
+        }
+        // Stuck agents: a helper with a live parent that has been wedged for longer
+        // than the interactive timeout. The parent must still exist in the snapshot.
+        if (s.elapsedSec <= STUCK_GRACE_SEC)
+            continue;
+        const parent = pidMap.get(s.ppid);
+        if (!parent)
+            continue;
+        if (s.startTime == null || parent.startTime == null)
+            continue;
+        const prev = prevCandidates.get(parent.pid);
+        if (prev &&
+            prev.helperPid === s.pid &&
+            prev.helperStartTime === s.startTime &&
+            prev.startTime === parent.startTime) {
+            if (prev.stage === 'watch') {
+                // Second sweep: kill the child first so the parent's spawnSync returns.
+                // Keep the parent candidate at stage 'escalate' for the next sweep.
+                kill.push(s.pid);
+                nextCandidates.set(parent.pid, { ...prev, stage: 'escalate' });
+                continue;
+            }
+            // Third sweep: child did not free the parent, so the parent itself is wedged.
+            kill.push(parent.pid);
+            continue;
+        }
+        // First sight of this (parent, helper) pair — record it and wait.
+        nextCandidates.set(parent.pid, {
+            pid: parent.pid,
+            startTime: parent.startTime,
+            helperPid: s.pid,
+            helperStartTime: s.startTime,
+            firstSeenAt: now,
+            stage: 'watch',
+        });
+    }
+    return { kill, nextCandidates };
+}
+/**
+ * Parse macOS `ps -o etime=` elapsed time into whole seconds.
+ *
+ * BSD `etime` renders as `[[dd-]hh:]mm:ss` (e.g. `05:03`, `01:02:03`,
+ * `14-04:10:52`). This is the portable keyword: `etimes` (raw seconds) is a
+ * GNU/Linux procps extension that macOS `ps` rejects with a non-zero exit, so
+ * the reaper — which only ever runs on darwin — must read `etime`.
+ * Returns null for an unparseable value so the caller drops the row.
+ */
+export function parseEtimeToSeconds(raw) {
+    const m = raw.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
+    if (!m)
+        return null;
+    const days = m[1] ? parseInt(m[1], 10) : 0;
+    const hours = m[2] ? parseInt(m[2], 10) : 0;
+    const mins = parseInt(m[3], 10);
+    const secs = parseInt(m[4], 10);
+    if ([days, hours, mins, secs].some(isNaN))
+        return null;
+    return ((days * 24 + hours) * 60 + mins) * 60 + secs;
+}
+/**
+ * Parse one `ps` output line.
+ *
+ * Expected format from `ps -ax -o pid=,ppid=,etime=,command=`:
+ *   "<pid> <ppid> <etime> <command...>"
+ * where `<etime>` is BSD elapsed time (`[[dd-]hh:]mm:ss`). The command field is
+ * the remainder of the line and may contain spaces.
+ */
+function parsePsLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    const m = trimmed.match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
+    if (!m)
+        return null;
+    const pid = parseInt(m[1], 10);
+    const ppid = parseInt(m[2], 10);
+    const elapsedSec = parseEtimeToSeconds(m[3]);
+    const command = m[4];
+    if (isNaN(pid) || isNaN(ppid) || elapsedSec == null)
+        return null;
+    return { pid, ppid, elapsedSec, command };
+}
+/** Module-state for the two-sweep stuck-parent debounce. */
+let stuckParentCandidates = new Map();
+/** Test seam: reset the persisted candidate state. */
+export function resetKeychainReaperCandidatesForTest() {
+    stuckParentCandidates = new Map();
+}
+/**
+ * Impure driver: snapshot all processes once with `ps`, plan the reap, then
+ * execute kills through {@link killTree}.
+ *
+ * Path-matching uses the full helper path (proc_pidpath-style), not just the
+ * executable name, so an unrelated binary named "Agents CLI" is never targeted.
+ *
+ * Returns on non-darwin platforms without shelling anything — the helper only
+ * exists on macOS.
+ */
+export function reapOrphanedKeychainProcesses() {
+    const details = [];
+    if (process.platform !== 'darwin') {
+        return { reaped: 0, details, plan: { kill: [], nextCandidates: new Map() } };
+    }
+    let helperPath;
+    try {
+        helperPath = getKeychainHelperPath();
+    }
+    catch (err) {
+        return { reaped: 0, details: [`helper path resolution failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
+    }
+    let out;
+    try {
+        out = execFileSync('ps', ['-ax', '-o', 'pid=,ppid=,etime=,command='], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch (err) {
+        return { reaped: 0, details: [`ps failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
+    }
+    const rows = [];
+    for (const line of out.split('\n')) {
+        const parsed = parsePsLine(line);
+        if (!parsed)
+            continue;
+        const { pid, ppid, elapsedSec, command } = parsed;
+        // Exact path-match: the helper invocation's command line begins with the
+        // absolute helper path, followed by a space and its arguments (or nothing).
+        const isHelper = command === helperPath || command.startsWith(`${helperPath} `);
+        rows.push({ pid, ppid, elapsedSec, isHelper, startTime: null });
+    }
+    const rowByPid = new Map(rows.map((r) => [r.pid, r]));
+    for (const row of rows) {
+        if (!row.isHelper)
+            continue;
+        row.startTime = captureProcessStartTime(row.pid);
+        if (row.ppid !== 1 && row.elapsedSec > STUCK_GRACE_SEC) {
+            const parent = rowByPid.get(row.ppid);
+            if (parent && parent.startTime === null) {
+                parent.startTime = captureProcessStartTime(row.ppid);
+            }
+        }
+    }
+    const snapshots = rows.map((r) => ({
+        pid: r.pid,
+        ppid: r.ppid,
+        elapsedSec: r.elapsedSec,
+        startTime: r.startTime,
+        isHelper: r.isHelper,
+    }));
+    const plan = planKeychainReap(snapshots, Date.now(), stuckParentCandidates);
+    stuckParentCandidates = plan.nextCandidates;
+    for (const pid of plan.kill) {
+        if (pid === process.pid)
+            continue; // never self-terminate the reaper
+        try {
+            killTree(pid);
+            details.push(`killed pid ${pid}`);
+        }
+        catch (err) {
+            details.push(`failed to kill pid ${pid}: ${err.message}`);
+        }
+    }
+    return { reaped: plan.kill.length, details, plan };
+}