@phnx-labs/agents-cli 1.22.21 → 1.22.23

package/dist/lib/runner.js

@@ -22,6 +22,7 @@ import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv, getJobHomePath } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, redactPrompt } from './events.js';
+import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
 import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, detectAuthFailure, isAuthFailureFromLog, authFailureReason, } from './exec.js';
 import { resolveActor } from './actor.js';
 import { loadTask as loadHostTask } from './hosts/tasks.js';
@@ -99,11 +100,12 @@ function terminateRoutineTree(pid) {
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
-    codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
+    codex: ['codex', 'exec', '{prompt}', '--json'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
     cursor: ['cursor-agent', '-p', '{prompt}', '--output-format', 'stream-json'],
     kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
     droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
+    muse: ['muse', 'exec', '{prompt}', '--json'],
 };
 /** Agents the daemon can actually run, derived from the command table above
  * so the `--agent` help and any validation can never drift from it. */
@@ -137,6 +139,8 @@ const ROUTINE_TRANSCRIPT_SPECS = {
         { root: ['.kimi-code', 'sessions'], ext: '.jsonl' },
     ],
     grok: [{ root: ['.grok', 'sessions'], ext: '.json' }],
+    // Muse: ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl
+    muse: [{ root: ['.local', 'share', 'muse', 'sessions'], ext: '.jsonl' }],
 };
 /** Stable working directory for routine children, independent of the daemon's launch cwd. */
 export function routineSpawnCwd(config, configuredRoot = getProjectRoot()) {
@@ -210,24 +214,14 @@ export function buildJobCommand(config, resolvedPrompt) {
         appendModelAndReasoning(cmd, config);
     }
     if (config.agent === 'codex') {
-        if (mode === 'plan') {
-            // The template defaults to workspace-write; plan means read-only.
-            const sbIndex = cmd.indexOf('--sandbox');
-            if (sbIndex !== -1)
-                cmd[sbIndex + 1] = 'read-only';
-        }
-        else if (mode === 'edit' || mode === 'auto') {
-            // Keep the workspace-write sandbox — no approval bypass; only skip drops
-            // the guardrails. Re-enable network, which workspace-write turns off.
-            cmd.push('-c', 'sandbox_workspace_write.network_access=true');
-        }
-        else if (mode === 'skip') {
-            // Remove sandbox restriction, just --dangerously-bypass-approvals-and-sandbox
-            const sbIndex = cmd.indexOf('--sandbox');
-            if (sbIndex !== -1)
-                cmd.splice(sbIndex, 2);
-            cmd.push('--dangerously-bypass-approvals-and-sandbox');
-        }
+        const policyMode = mode === 'plan' || mode === 'skip' ? mode : 'edit';
+        const routineRoots = (config.allow?.dirs ?? []).map((dir) => {
+            if (dir.startsWith('-')) {
+                throw new Error(`allow.dirs entries must not start with '-': ${JSON.stringify(dir)}`);
+            }
+            return dir.replace(/^~/, os.homedir());
+        });
+        cmd.push(...codexPolicyArgs(policyMode, [...codexEditWritableRoots(), ...routineRoots]));
         appendModelAndReasoning(cmd, config);
     }
     if (config.agent === 'gemini') {
@@ -277,6 +271,21 @@ export function buildJobCommand(config, resolvedPrompt) {
         }
         appendModelAndReasoning(cmd, config);
     }
+    if (config.agent === 'muse') {
+        // muse exec: plan ≈ no non-shell writes; auto skips approval prompts but
+        // keeps the OS sandbox; skip is --yolo (no approval, no sandbox, trust).
+        if (mode === 'plan') {
+            cmd.push('--disable-write');
+        }
+        else if (mode === 'auto') {
+            cmd.push('--disable-approval');
+        }
+        else if (mode === 'skip') {
+            cmd.push('--yolo');
+        }
+        // edit: default on-request approval + sandbox
+        appendModelAndReasoning(cmd, config);
+    }
     return cmd;
 }
 /**

package/dist/lib/secrets/Agents CLI.app/Contents/Info.plist

@@ -8,8 +8,6 @@
   <string>Agents CLI</string>
   <key>CFBundleDisplayName</key>
   <string>Agents CLI</string>
-  <key>CFBundleIconFile</key>
-  <string>AppIcon</string>
   <key>CFBundleExecutable</key>
   <string>Agents CLI</string>
   <key>CFBundlePackageType</key>

package/dist/lib/secrets/Agents CLI.app/Contents/_CodeSignature/CodeResources

@@ -3,21 +3,9 @@
 <plist version="1.0">
 <dict>
 	<key>files</key>
-	<dict>
-		<key>Resources/AppIcon.icns</key>
-		<data>
-		DFq5H08EkhgWIC3UvGMR9B58BZw=
-		</data>
-	</dict>
+	<dict/>
 	<key>files2</key>
 	<dict>
-		<key>Resources/AppIcon.icns</key>
-		<dict>
-			<key>hash2</key>
-			<data>
-			mBSjM6jlvN7J1jQowsvqTl7CHM0pur0e6qsHMuzk5k0=
-			</data>
-		</dict>
 		<key>embedded.provisionprofile</key>
 		<dict>
 			<key>hash2</key>

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

@@ -22,10 +22,24 @@
  * through the explicit export/import flow in src/lib/secrets/sync.ts
  * rather than the system's cloud-keychain path.
  */
-import { type SpawnSyncOptions } from 'child_process';
+import { type SpawnSyncOptions, type SpawnSyncReturns } from 'child_process';
 import type { NativeImportReport } from './fallback.js';
 export type { NativeImportReport, NativeImportResult, NativeImportStatus } from './fallback.js';
 export declare const SECRETS_ITEM_PREFIX = "agents-cli.secrets.";
+/**
+ * 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 declare class KeychainHelperTimeoutError extends Error {
+    readonly bin: string;
+    readonly args: string[];
+    constructor(bin: string, args: string[]);
+}
+/** Test seam: suppress the side-effect daemon boot in unit tests. */
+export declare function setKeychainDaemonBootForTest(enabled: boolean): void;
+/** Test seam: exercise the timeout wrapper with an arbitrary binary. */
+export declare function spawnKeychainHelperForTest(bin: string, args: string[], opts: SpawnSyncOptions, timeoutMs: number): SpawnSyncReturns<Buffer>;
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
 /** A typed reference to a secret, consisting of a provider and a provider-specific value. */

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,14 @@ 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], {
+    return spawnKeychainHelper(bin, ['has', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    }).status === 0;
+    }, KEYCHAIN_SILENT_TIMEOUT_MS).status === 0;
 }
 /**
  * The detector the raw-read storm guard consults, overridable so tests on any
@@ -808,9 +859,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 +872,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 +973,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 +1132,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 +1145,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,9 +1175,9 @@ export function deleteKeychainToken(item) {
     if (isWindows())
         return windowsBackend.delete(item);
     const bin = getKeychainHelperPath();
-    const deleted = spawnSync(bin, ['delete', item, os.userInfo().username], {
+    const deleted = spawnKeychainHelper(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
-    }).status === 0;
+    }, KEYCHAIN_SILENT_TIMEOUT_MS).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)
@@ -1149,9 +1218,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 +1245,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 +1278,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 +1306,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 +1334,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 +1355,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 +1379,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 +1437,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,87 @@
+/**
+ * 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;
+/** 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;
+};