@phnx-labs/agents-cli 1.22.22 → 1.22.23

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

package/dist/lib/secrets/reaper.js

@@ -0,0 +1,184 @@
+/**
+ * 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 one `ps` output line.
+ *
+ * Expected format from `ps -ax -o pid=,ppid=,etimes=,command=`:
+ *   "<pid> <ppid> <etimes> <command...>"
+ * 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+(\d+)\s+(.*)$/);
+    if (!m)
+        return null;
+    const pid = parseInt(m[1], 10);
+    const ppid = parseInt(m[2], 10);
+    const elapsedSec = parseInt(m[3], 10);
+    const command = m[4];
+    if (isNaN(pid) || isNaN(ppid) || isNaN(elapsedSec))
+        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=,etimes=,command='], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch (err) {
+        return { reaped: 0, details: [`ps failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
+    }
+    const snapshots = [];
+    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} `);
+        snapshots.push({
+            pid,
+            ppid,
+            elapsedSec,
+            startTime: captureProcessStartTime(pid),
+            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 };
+}

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

@@ -177,3 +177,32 @@ export declare function keychainWriteFailureMessage(host: string, bundle: string
 export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
     osLookupName?: string;
 }): RemoteKeychainWriteVerification;
+/**
+ * The `bash -lc` command + stdin payload that drives a **file-backed** remote
+ * import for `secrets export --host … --remote-backend file`.
+ *
+ * The file store is passphrase-free by default: with `AGENTS_SECRETS_PASSPHRASE`
+ * unset the remote `agents secrets import --backend file` auto-provisions the
+ * remote's own machine-local key (0600 under `~/.agents/.secrets-key/`), so its
+ * reads are HEADLESS — no passphrase, no Touch ID. A passphrase is therefore
+ * OPTIONAL and only forwarded when the operator sets one locally (opt-in, e.g. to
+ * key the bundle off-disk under a shared secret):
+ *
+ * - **No passphrase** → the remote runs `import … --backend file` directly with
+ *   ONLY the .env on stdin. No `read`/`export AGENTS_SECRETS_PASSPHRASE`
+ *   prologue, so `AGENTS_SECRETS_PASSPHRASE` stays UNSET on the remote → the
+ *   machine-local key path → headless reads.
+ * - **Passphrase set** → forward it as the FIRST stdin line, consumed by
+ *   `IFS= read -r` (so it never lands in argv / `ps` / remote shell history),
+ *   then the .env. The remote then keys the bundle under that shared passphrase.
+ *
+ * Pure — no I/O — so the exact command string and stdin ordering are unit-testable
+ * against the SSH boundary the same way `remoteSecretsRaw` is.
+ */
+export declare function buildRemoteFileImportCommand(bundle: string, dotenv: string, opts?: {
+    passphrase?: string;
+    force?: boolean;
+}): {
+    remoteCmd: string;
+    input: string;
+};

package/dist/lib/secrets/remote.js

@@ -15,7 +15,7 @@
  * file-backend passphrase travels over ssh stdin (first line) so it never lands
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
  */
-import { sshExec, sshStream, assertValidSshTarget } from '../ssh-exec.js';
+import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
 import { emitSecretAudit } from './audit.js';
 import { sshTargetFor } from '../hosts/types.js';
@@ -348,3 +348,39 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
     }
     return evaluateKeychainWriteVerification(pushedKeys, { ok: true, keys });
 }
+/**
+ * The `bash -lc` command + stdin payload that drives a **file-backed** remote
+ * import for `secrets export --host … --remote-backend file`.
+ *
+ * The file store is passphrase-free by default: with `AGENTS_SECRETS_PASSPHRASE`
+ * unset the remote `agents secrets import --backend file` auto-provisions the
+ * remote's own machine-local key (0600 under `~/.agents/.secrets-key/`), so its
+ * reads are HEADLESS — no passphrase, no Touch ID. A passphrase is therefore
+ * OPTIONAL and only forwarded when the operator sets one locally (opt-in, e.g. to
+ * key the bundle off-disk under a shared secret):
+ *
+ * - **No passphrase** → the remote runs `import … --backend file` directly with
+ *   ONLY the .env on stdin. No `read`/`export AGENTS_SECRETS_PASSPHRASE`
+ *   prologue, so `AGENTS_SECRETS_PASSPHRASE` stays UNSET on the remote → the
+ *   machine-local key path → headless reads.
+ * - **Passphrase set** → forward it as the FIRST stdin line, consumed by
+ *   `IFS= read -r` (so it never lands in argv / `ps` / remote shell history),
+ *   then the .env. The remote then keys the bundle under that shared passphrase.
+ *
+ * Pure — no I/O — so the exact command string and stdin ordering are unit-testable
+ * against the SSH boundary the same way `remoteSecretsRaw` is.
+ */
+export function buildRemoteFileImportCommand(bundle, dotenv, opts = {}) {
+    const force = opts.force ? ' --force' : '';
+    const importCmd = `agents secrets import ${shellQuote(bundle)} --from - --backend file${force}`;
+    const passphrase = opts.passphrase ?? '';
+    if (passphrase) {
+        // Opt-in shared passphrase: read it off the FIRST stdin line, export it, then
+        // let `import --from -` read the .env remainder.
+        const remoteAgents = `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ${importCmd}`;
+        return { remoteCmd: `bash -lc ${shellQuote(remoteAgents)}`, input: `${passphrase}\n${dotenv}` };
+    }
+    // No passphrase: NO prologue — AGENTS_SECRETS_PASSPHRASE stays unset on the
+    // remote, so the file store falls back to its machine-local key (headless).
+    return { remoteCmd: `bash -lc ${shellQuote(importCmd)}`, input: dotenv };
+}