@phnx-labs/agents-cli 1.22.56 → 1.22.58

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

@@ -1,20 +1,14 @@
 /**
  * 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}.
+ * coreauthd / LocalAuthentication hangs can leave helper (and parent `agents`)
+ * processes pile up. The pure planner ({@link planKeychainReap}) is unit-testable
+ * without a real `ps`; the driver ({@link reapOrphanedKeychainProcesses}) shells
+ * `ps` once per tick and kills through {@link killTree}.
  */
-/** Elapsed grace before a helper whose parent exited is considered an orphan. */
+/** 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. */
+/** 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 {
@@ -22,32 +16,19 @@ export interface KeychainProcessSnapshot {
     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.
-     */
+    /** Stable start-time fingerprint from {@link captureProcessStartTime}; null fails closed. */
     startTime: string | null;
-    /**
-     * True when this process is a REAP-ELIGIBLE helper invocation — the installed
-     * helper binary running a short-lived keychain verb. False for a non-helper
-     * process AND for the long-lived `watch-lock` watcher (see
-     * {@link isReapableHelperCommand}).
-     */
+    /** True for a reap-eligible helper invocation (short-lived keychain verb). */
     isHelper: boolean;
     /**
-     * True when this process is the deliberately long-lived `watch-lock` watcher
-     * (auto-lock-on-sleep). Mutually exclusive with {@link isHelper}:
-     * {@link isReapableHelperCommand} keeps live-parent watch-locks out of the
-     * stuck-helper path, and a SEPARATE orphan path in {@link planKeychainReap}
-     * reaps them only once the owning daemon is provably dead (RUSH-2419).
+     * True for the deliberately long-lived `watch-lock` watcher
+     * (auto-lock-on-sleep). Mutually exclusive with {@link isHelper}; killing it
+     * silently disables auto-lock-on-sleep, so it is reaped only once the owning
+     * daemon is provably dead (RUSH-2419).
      */
     isWatchLock?: 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.
- */
+/** Tracked state for a stuck parent across two-sweep debounce. */
 export interface StuckParentCandidate {
     pid: number;
     startTime: string | null;
@@ -58,7 +39,7 @@ export interface StuckParentCandidate {
 }
 /** Result of one planning pass. */
 export interface ReapPlan {
-    /** PIDs that should be killed this tick. */
+    /** PIDs to kill this tick. */
     kill: number[];
     /** Candidates to carry forward to the next sweep. */
     nextCandidates: Map<number, StuckParentCandidate>;
@@ -66,51 +47,31 @@ export interface ReapPlan {
 /**
  * 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. Three
- * conservative reap classes:
+ * Three conservative classes:
+ *   1. Orphaned helper: PPID == 1, helper path, alive longer than grace.
+ *   2. Stuck `agents` parent: helper child alive longer than stuck grace,
+ *      recorded on first sight, child killed on second sweep, parent on third.
+ *   3. Orphaned `watch-lock`: long-lived watcher whose owning daemon is gone.
  *
- *   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.
- *   3. Orphaned `watch-lock` watcher (RUSH-2419): the long-lived auto-lock
- *      child whose owning daemon is provably dead. {@link isReapableHelperCommand}
- *      still excludes live-parent watch-locks from class 1/2; this path only
- *      reaps when the parent is gone from the snapshot (Unix reparents to init
- *      after daemon death) and the watcher itself has a start-time fingerprint.
- *
- * Never reaps a process whose start time could not be captured, whose path does
- * not match the helper, or (for stuck parents) whose parent is no longer in the
- * snapshot. A watch-lock whose parent IS still in the snapshot is never touched.
+ * Fails closed when start time can't be captured.
  */
 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.
+ * BSD `etime` renders as `[[dd-]hh:]mm:ss`. `etimes` (raw seconds) is a GNU
+ * extension that macOS `ps` rejects, so darwin uses `etime`.
  */
 export declare function parseEtimeToSeconds(raw: string): number | null;
 /**
- * Whether a `ps` command line is a REAP-ELIGIBLE helper invocation: the installed
- * helper binary running a short-lived keychain verb (get/has/list/set/delete/
- * migrate-*) that a wedged `coreauthd` can hang. Returns false for a non-helper
- * command AND for the deliberately long-lived `watch-lock` watcher — matching by
- * the full argv (`ps … command=`), so a live-parent `watch-lock` child is never
- * mistaken for a stuck read and killed. Pure; unit-tested.
+ * Whether a `ps` command line is a reap-eligible helper invocation: the installed
+ * helper binary running a short-lived keychain verb. Returns false for the
+ * long-lived `watch-lock` watcher, which must never be mistaken for a stuck read.
  */
 export declare function isReapableHelperCommand(command: string, helperPath: string): boolean;
 /**
  * Whether a `ps` command line is the deliberately long-lived `watch-lock`
- * watcher (auto-lock-on-sleep). Inverse of {@link isReapableHelperCommand} for
- * the watch-lock verb only — used by the orphaned-watch-lock reaper path
- * (RUSH-2419). Pure; unit-tested.
+ * watcher. Inverse of {@link isReapableHelperCommand} for the watch-lock verb.
  */
 export declare function isWatchLockHelperCommand(command: string, helperPath: string): boolean;
 /** Test seam: reset the persisted candidate state. */
@@ -119,11 +80,8 @@ 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.
+ * Path-matches the full helper path so an unrelated binary named "Agents CLI" is
+ * never targeted. Returns on non-darwin without shelling anything.
  */
 export declare function reapOrphanedKeychainProcesses(): {
     reaped: number;

package/dist/lib/secrets/reaper.js

@@ -1,46 +1,28 @@
 /**
  * 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}.
+ * coreauthd / LocalAuthentication hangs can leave helper (and parent `agents`)
+ * processes pile up. The pure planner ({@link planKeychainReap}) is unit-testable
+ * without a real `ps`; the driver ({@link reapOrphanedKeychainProcesses}) shells
+ * `ps` once per tick and 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. */
+/** 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. */
+/** 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. Three
- * 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.
- *   3. Orphaned `watch-lock` watcher (RUSH-2419): the long-lived auto-lock
- *      child whose owning daemon is provably dead. {@link isReapableHelperCommand}
- *      still excludes live-parent watch-locks from class 1/2; this path only
- *      reaps when the parent is gone from the snapshot (Unix reparents to init
- *      after daemon death) and the watcher itself has a start-time fingerprint.
+ * Three conservative classes:
+ *   1. Orphaned helper: PPID == 1, helper path, alive longer than grace.
+ *   2. Stuck `agents` parent: helper child alive longer than stuck grace,
+ *      recorded on first sight, child killed on second sweep, parent on third.
+ *   3. Orphaned `watch-lock`: long-lived watcher whose owning daemon is gone.
  *
- * Never reaps a process whose start time could not be captured, whose path does
- * not match the helper, or (for stuck parents) whose parent is no longer in the
- * snapshot. A watch-lock whose parent IS still in the snapshot is never touched.
+ * Fails closed when start time can't be captured.
  */
 export function planKeychainReap(snapshots, now, prevCandidates) {
     const pidMap = new Map(snapshots.map((s) => [s.pid, s]));
@@ -50,8 +32,7 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
         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.
+            // Orphaned helper: fail closed without a start-time fingerprint.
             if (s.elapsedSec <= ORPHAN_GRACE_SEC)
                 continue;
             if (s.startTime == null)
@@ -59,8 +40,7 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
             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.
+        // Stuck agents: helper with a live parent wedged longer than the timeout.
         if (s.elapsedSec <= STUCK_GRACE_SEC)
             continue;
         const parent = pidMap.get(s.ppid);
@@ -74,13 +54,12 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
             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.
+                // Second sweep: kill the child first so spawnSync returns; escalate next.
                 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.
+            // Third sweep: child did not free the parent, so the parent is wedged.
             kill.push(parent.pid);
             continue;
         }
@@ -94,32 +73,21 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
             stage: 'watch',
         });
     }
-    // Separate path for orphaned watch-lock watchers (RUSH-2419). Does NOT
-    // weaken {@link isReapableHelperCommand}: a watch-lock with a live parent
-    // stays isHelper=false and is skipped above. Here we only kill when the
-    // owning daemon is provably absent from the process table.
+    // Separate path for orphaned watch-lock watchers: only reap when the owning
+    // daemon is provably absent from the process table.
     for (const s of snapshots) {
         if (!s.isWatchLock)
             continue;
-        // Fail closed: no start-time fingerprint → refuse to kill (pid-reuse guard
-        // for the process we are about to target, same as orphan helpers).
         if (s.startTime == null)
             continue;
         if (s.elapsedSec <= ORPHAN_GRACE_SEC)
             continue;
-        // Live parent in this snapshot → owning daemon is still up. Leave it alone
-        // (this is the property isReapableHelperCommand protects for stuck-helper
-        // reaping; re-assert it here so a mis-tagged row cannot be killed either).
         if (s.ppid !== 1) {
             const parent = pidMap.get(s.ppid);
             if (parent)
                 continue;
-            // Parent pid not listed: the process occupying that slot is gone. On Unix
-            // a dead parent reparents the child to init; a missing parent with a
-            // non-1 ppid is the race window before reparenting. Either way the owner
-            // is dead — safe to reap after grace + fingerprint.
+            // Parent missing means the owner is dead (or reparenting race); safe to reap.
         }
-        // ppid===1 (reparented to init/launchd) or parent missing → orphaned.
         kill.push(s.pid);
     }
     return { kill, nextCandidates };
@@ -127,11 +95,8 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
 /**
  * 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.
+ * BSD `etime` renders as `[[dd-]hh:]mm:ss`. `etimes` (raw seconds) is a GNU
+ * extension that macOS `ps` rejects, so darwin uses `etime`.
  */
 export function parseEtimeToSeconds(raw) {
     const m = raw.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
@@ -150,8 +115,6 @@ export function parseEtimeToSeconds(raw) {
  *
  * 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();
@@ -168,22 +131,12 @@ function parsePsLine(line) {
         return null;
     return { pid, ppid, elapsedSec, command };
 }
-/**
- * The one helper verb that is DELIBERATELY long-lived: the broker's auto-lock
- * sleep/lock watcher (`spawn(getKeychainHelperPath(), ['watch-lock'], …)` in
- * `agent.ts`). It lives for the broker's whole hold — potentially days — as a
- * healthy child of the live broker/daemon, emitting LOCK/SLEEP lines that wipe
- * the in-memory secret store on sleep. It is NOT a stuck keychain read, so the
- * reaper must never target it: killing it silently disables auto-lock-on-sleep.
- */
+/** The one helper verb that is deliberately long-lived: the auto-lock watcher. */
 const HELPER_WATCH_LOCK_VERB = 'watch-lock';
 /**
- * Whether a `ps` command line is a REAP-ELIGIBLE helper invocation: the installed
- * helper binary running a short-lived keychain verb (get/has/list/set/delete/
- * migrate-*) that a wedged `coreauthd` can hang. Returns false for a non-helper
- * command AND for the deliberately long-lived `watch-lock` watcher — matching by
- * the full argv (`ps … command=`), so a live-parent `watch-lock` child is never
- * mistaken for a stuck read and killed. Pure; unit-tested.
+ * Whether a `ps` command line is a reap-eligible helper invocation: the installed
+ * helper binary running a short-lived keychain verb. Returns false for the
+ * long-lived `watch-lock` watcher, which must never be mistaken for a stuck read.
  */
 export function isReapableHelperCommand(command, helperPath) {
     if (command === helperPath)
@@ -195,9 +148,7 @@ export function isReapableHelperCommand(command, helperPath) {
 }
 /**
  * Whether a `ps` command line is the deliberately long-lived `watch-lock`
- * watcher (auto-lock-on-sleep). Inverse of {@link isReapableHelperCommand} for
- * the watch-lock verb only — used by the orphaned-watch-lock reaper path
- * (RUSH-2419). Pure; unit-tested.
+ * watcher. Inverse of {@link isReapableHelperCommand} for the watch-lock verb.
  */
 export function isWatchLockHelperCommand(command, helperPath) {
     if (!command.startsWith(`${helperPath} `))
@@ -215,11 +166,8 @@ export function resetKeychainReaperCandidatesForTest() {
  * 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.
+ * Path-matches the full helper path so an unrelated binary named "Agents CLI" is
+ * never targeted. Returns on non-darwin without shelling anything.
  */
 export function reapOrphanedKeychainProcesses() {
     const details = [];
@@ -249,11 +197,8 @@ export function reapOrphanedKeychainProcesses() {
         if (!parsed)
             continue;
         const { pid, ppid, elapsedSec, command } = parsed;
-        // Reap-eligible = the helper binary running a short-lived keychain verb. The
-        // full-argv match excludes the deliberately long-lived `watch-lock` watcher,
-        // whose live-parent child would otherwise be killed as if it were stuck
-        // (RUSH-2232 — that silently disabled auto-lock-on-sleep). Orphaned
-        // watch-locks are tracked separately via isWatchLock (RUSH-2419).
+        // Match the full argv so the long-lived `watch-lock` watcher is never
+        // mistaken for a stuck read. Orphaned watch-locks are tracked separately.
         const isHelper = isReapableHelperCommand(command, helperPath);
         const isWatchLock = isWatchLockHelperCommand(command, helperPath);
         rows.push({ pid, ppid, elapsedSec, isHelper, isWatchLock, startTime: null });

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

@@ -1,37 +1,14 @@
 /**
  * Remote secrets — read and use `agents secrets` bundles that live on another
- * host, over the same hardened SSH path that `agents secrets export --device`
- * (the write inverse) already uses.
+ * host over the same SSH path that `agents secrets export --device` uses.
  *
- * This is the READ / USE direction:
- *   - browse:  drive the remote `agents secrets list|view` and stream its
- *              stdout back verbatim (lossless, no parsing).
- *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
- *              inject it ephemerally — never written to this machine's keychain.
- *
- * Trust model: relies on the operator's existing SSH access to the host (same
- * boundary as `export --device` / `run --device`). Bundle names are shell-quoted
- * into the remote command; resolved VALUES return over ssh stdout. File-backend
- * import never forwards AGENTS_SECRETS_PASSPHRASE (PHNX-2371). Nothing is
- * persisted locally.
+ * Browse streams remote stdout verbatim; use resolves a bundle to an env map
+ * and injects it ephemerally without persisting it locally.
  */
 import { type SshExecResult } from '../ssh-exec.js';
 /**
- * SSH options for a SECRET-carrying transport (RUSH-2527). Every `agents secrets
- * --host` operation moves credential bytes — over ssh stdin (push) or ssh stdout
- * (resolve/read-back) — so it MUST NOT ride the shared `accept-new` baseline
- * against the user's own `~/.ssh/known_hosts` with a reusable control socket.
- * Two hardenings over that baseline, matching the posture the `--copy-creds`
- * dispatch already uses (`hosts/dispatch.ts` -> `hostKeyCheckingOpts`):
- *
- *   - **Managed pinned host keys.** Verify against the CLI-owned known_hosts
- *     store (`known-hosts.ts`), not `~/.ssh/known_hosts`. A CHANGED key on a
- *     known host is refused (`StrictHostKeyChecking` `yes` once pinned,
- *     `accept-new` before that). Callers that copy durable provider credentials
- *     must separately require an existing pin before invoking this transport.
- *   - **No multiplex reuse.** `multiplex: false` — a credential channel never
- *     leaves a persistent `ControlMaster` socket lingering (60s `ControlPersist`)
- *     that any other `agents` invocation to that host would silently reuse.
+ * SSH options for secret-carrying transport. Pins the managed host key and
+ * disables multiplex so no reusable control socket lingers for other invocations.
  */
 export declare function credentialTransportSshOpts(target: string): {
     hostKeyOpts: string[];
@@ -40,37 +17,21 @@ export declare function credentialTransportSshOpts(target: string): {
 /** Refuse durable credential transfer until the destination SSH key is pinned. */
 export declare function assertCredentialTransportHostPinned(target: string, pinned?: boolean): void;
 /**
- * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
- * is untrusted input: a compromised or misconfigured host could return keys that
- * silently reshape THIS process's behavior once merged into the agent env
- * (bundles.ts:251 `sanitizeProcessEnv` only strips loader vars from process.env,
- * never the remote bundle). Block the dangerous-override classes here — at the
- * source — so every consumer (`run --secrets b@host`, `secrets exec --host`) is
- * protected, not just one call site:
- *   - LD_* / DYLD_* / NODE_OPTIONS and the other loader/interpreter injections
- *     (reuses the canonical bundles.ts predicate);
- *   - GIT_*        — GIT_SSH_COMMAND et al. hijack every git subprocess;
- *   - *_PROXY      — HTTP(S)_PROXY / ALL_PROXY reroute outbound traffic (MITM);
- *   - *_BASE_URL   — ANTHROPIC_BASE_URL / OPENAI_BASE_URL redirect the model API.
- * These keys are already rejected on the ADD side (validateEnvKey for loaders),
- * so a legitimate bundle never carries them — only a hostile peer would.
+ * Trust boundary for a remote-resolved env map. A peer's export output is
+ * untrusted input that could reshape this process once merged into the env, so
+ * block dangerous override classes here for every consumer:
+ * loader/interpreter vars, GIT_*, *_PROXY, and *_BASE_URL.
  */
 export declare function isDangerousRemoteEnvKey(name: string): boolean;
 /**
- * Resolve a `--device` value to an ssh target STRING for the remote-secrets path.
- * Delegates to the single host/device resolver (`resolveHost`, RUSH-1967) so a
- * name here dials the exact same box `run --device` does; on a miss, treats the
- * value as a raw ssh target and validates it against injection. Named distinctly
- * from `../devices/resolve-target.ts` (which returns richer shapes) so importing
- * the wrong one can't silently change which machine you dial.
+ * Resolve a `--device` value to an ssh target string for the remote-secrets
+ * path. Delegates to the same resolver `run --device` uses; on a miss, treats
+ * the value as a raw ssh target and validates it.
  */
 export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;
 /**
- * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
- * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
- * works. `--device`/`--devices` resolve identically to `--device`/`--hosts` so the
- * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
- * works on the secrets remote commands too. Empty when none is set.
+ * Merge `--host` / `--hosts` (and their `--device` / `--devices` aliases) into
+ * an ordered, de-duplicated list. Empty when none is set.
  */
 export declare function parseHostsOption(opts: {
     host?: string;
@@ -79,11 +40,9 @@ export declare function parseHostsOption(opts: {
     devices?: string;
 }): string[];
 /**
- * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
- * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
- * separates the bundle from the ssh target — and the target itself may be a
- * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
- * `muqsit@box`).
+ * Split a `bundle@host` reference. No `@` → a local bundle. Bundle names can't
+ * contain `@`, so the FIRST `@` separates bundle from ssh target; the target
+ * itself may be `user@host` (e.g. `r2.backups@muqsit@box`).
  */
 export declare function splitBundleRef(ref: string): {
     bundle: string;
@@ -91,9 +50,8 @@ export declare function splitBundleRef(ref: string): {
 };
 /**
  * Run `agents secrets <args>` on a remote host over ssh and return the raw
- * result. Used by the browse commands — the remote's human-readable stdout is
- * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
- * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ * result. Used by browse commands; `tty` forces `-tt` so remote passphrase
+ * prompts can surface.
  */
 export declare function remoteSecretsRaw(target: string, args: string[], opts?: {
     tty?: boolean;
@@ -102,17 +60,9 @@ export declare function remoteSecretsRaw(target: string, args: string[], opts?:
     secret?: boolean;
 }): SshExecResult;
 /**
- * Run a remote `agents secrets <args>` FOREGROUND, with the local stdio wired
- * straight through (`stdio: 'inherit'` + `-tt`), and return its exit code.
- *
- * Unlike `remoteSecretsRaw` — which pipes stdin, so even with `-tt` the remote
- * process's `process.stdin.isTTY` is false and a passphrase prompt refuses to
- * appear (the macOS file-store guard then hard-errors "needs
- * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
- * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
- * the keystrokes. This is the transport for `unlock --device`: you type the remote
- * bundle's passphrase at your own terminal. Output is NOT captured (it streams
- * to the terminal); only the exit code is returned.
+ * Run a remote `agents secrets <args>` foreground with local stdio inherited,
+ * so the remote sees a real TTY and its passphrase prompt surfaces and reads
+ * keystrokes. Output streams to the terminal; only the exit code is returned.
  */
 export declare function remoteSecretsStream(target: string, args: string[], opts?: {
     osLookupName?: string;
@@ -120,31 +70,20 @@ export declare function remoteSecretsStream(target: string, args: string[], opts
 /**
  * Resolve a remote bundle to a plaintext env map by driving the remote's
  * `agents secrets export <bundle> --plaintext --format json`. Values cross over
- * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ * ssh stdout, parsed in memory, never persisted.
  *
- * The remote unlocks the bundle with ITS OWN credentials — the owner host's
- * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
- * env) for a file-backed bundle. We deliberately do NOT forward this machine's
- * passphrase: the remote bundle is encrypted with the remote's passphrase, so
- * overriding it would break the read. (A macOS remote under non-interactive
- * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
- * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ * The remote unlocks the bundle with its own credentials; this machine does NOT
+ * forward its passphrase because the remote bundle is encrypted with the
+ * remote's passphrase.
  */
 export declare function remoteResolveEnv(target: string, bundle: string, opts?: {
     osLookupName?: string;
 }): Promise<Record<string, string>>;
 /**
- * Outcome of a post-push read-back verification (see verifyRemoteKeychainPush).
- *   - `ok`               — the pushed keys materialized readably on the remote.
- *   - `locked-keychain`  — the read-back gave the SPECIFIC signal of a keychain
- *                          that didn't persist (the remote's headless "not unlocked
- *                          in the secrets agent" guard, or a "stored item … not
- *                          found" on read-back, or pushed keys simply absent). Only
- *                          this verdict earns the locked-login-keychain diagnosis +
- *                          `--remote-backend file` steer.
- *   - `error`            — a DIFFERENT failure (flaky SSH, timeout, unparseable
- *                          payload). The raw error is re-surfaced verbatim, never
- *                          mislabeled as a locked keychain.
+ * Outcome of a post-push read-back verification.
+ *   - `ok`              — the pushed keys materialized readably.
+ *   - `locked-keychain` — read-back gave the specific locked-keychain signal.
+ *   - `error`           — a different failure (SSH, timeout, etc.).
  */
 export type RemoteKeychainWriteVerification = {
     ok: true;
@@ -158,24 +97,10 @@ export type RemoteKeychainWriteVerification = {
     reason: string;
 };
 /**
- * Decide whether a keychain-backed push to a remote actually PERSISTED its secret
- * value items, given the read-back of that bundle from the remote's own store.
- *
- * The silent-failure this guards: pushing `--remote-backend keychain` (default) to
- * a macOS host over headless SSH lands the bundle METADATA but not readable value
- * items — the remote login keychain is locked in the non-interactive SSH context,
- * so Security accepts the item WRITE at the DB level but the biometry-ACL'd item is
- * unreadable, and the remote `import` still reports success (values written first,
- * metadata `noAcl` last — bundles.ts writeBundleWithItems). The metadata-only bundle
- * then fails every later read with the confusing `Bundle '<b>' key '<k>': stored
- * item '<item>' not found` (bundles.ts resolveBundleEnv). We catch it by reading
- * the bundle back the same way a later `secrets exec`/resolve will (the marker-gated
- * json transport, driven headlessly on the remote so its `agentOnly` guard FAILS FAST
- * before any keychain read — no Touch ID prompt) and confirming every pushed key
- * returned.
- *
- * Pure so both branches are unit-testable without a real locked keychain: inject the
- * "read-back failed / key absent" condition through `readBack`.
+ * Decide whether a keychain-backed push to a remote actually persisted its
+ * secret value items by reading the bundle back the same way a later resolve
+ * will. Catches the silent failure where headless SSH writes metadata but not
+ * readable value items to a locked macOS login keychain.
  */
 export declare function evaluateKeychainWriteVerification(pushedKeys: string[], readBack: {
     ok: true;
@@ -185,38 +110,26 @@ export declare function evaluateKeychainWriteVerification(pushedKeys: string[],
     stderr: string;
 }): RemoteKeychainWriteVerification;
 /**
- * The actionable error message for a failed keychain-over-SSH push verification.
- * Names the cause (locked remote login keychain) and steers to the two real fixes:
- * re-run with the headless-readable file backend, or unlock the remote keychain.
- * Pure + exported so the exact guidance is asserted in tests.
+ * Actionable error message for a failed keychain-over-SSH push. Names the cause
+ * (locked remote login keychain) and steers to the two real fixes.
  */
 export declare function keychainWriteFailureMessage(host: string, bundle: string, reason: string): string;
 /**
- * Read a bundle back from a remote over SSH (headlessly, so it fails fast rather
- * than prompting Touch ID) and confirm the pushed keys materialized. Drives the
- * remote's marker-gated json transport (`secrets export <bundle> --plaintext
- * --format json` under AGENTS_SECRETS_REMOTE_TRANSPORT) but keeps only the KEY
- * NAMES; the plaintext values are dropped immediately and never retained or
- * logged. Returns a verification verdict; the caller renders
- * `keychainWriteFailureMessage` on failure.
+ * Read a bundle back from a remote over SSH and confirm the pushed keys
+ * materialized. Drives the marker-gated json transport but keeps only KEY NAMES;
+ * plaintext values are discarded immediately. Returns a verification verdict.
  */
 export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
     osLookupName?: string;
     secret?: boolean;
 }): RemoteKeychainWriteVerification;
 /**
- * The `bash -lc` command + stdin payload that drives a **file-backed** remote
- * import for `secrets export --device … --remote-backend file`.
+ * `bash -lc` command + stdin payload for a file-backed remote import.
  *
- * The file store is passphrase-free: 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. AGENTS_SECRETS_PASSPHRASE is a deprecated override and MUST NOT be
+ * The file store is passphrase-free: the remote auto-provisions its own machine-
+ * local key, so reads are headless. AGENTS_SECRETS_PASSPHRASE must NOT be
  * forwarded (PHNX-2371): a remote keyed to a secret its daemon does not hold
  * reports "Imported N key(s)" then fails every later decrypt.
- *
- * 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?: {
     force?: boolean;