@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/secrets/push.js

@@ -1,9 +1,9 @@
 /**
  * Push one bundle's values to a remote host over SSH — the provisioning
- * primitive behind `agents secrets export --host` and, from RUSH-1968, behind
+ * primitive behind `agents secrets export --device` and, from RUSH-1968, behind
  * `agents fleet apply --provision-secrets`.
  *
- * This logic used to live inline in the `export --host` command action. It moved
+ * This logic used to live inline in the `export --device` command action. It moved
  * here because `lib/fleet/apply.ts` needs it and a lib MUST NOT import a command
  * module — and because the absence of a callable primitive is part of why
  * `fleet apply` never provisioned secrets at all, leaving an operator to
@@ -17,7 +17,7 @@
  *   interleaving stray lines into it.
  * - **Resolve once, push N times.** `resolveBundleForPush` is separate because
  *   reading a bundle can prompt (Touch ID); doing it per host would prompt per
- *   host. `export --host a,b,c` resolves once and pushes three times.
+ *   host. `export --device a,b,c` resolves once and pushes three times.
  */
 import { sshExec } from '../ssh-exec.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../hosts/remote-cmd.js';
@@ -89,6 +89,7 @@ export function planPushTransport(resolved, bundle, host, opts) {
         const { remoteCmd, input } = buildRemoteFileImportCommand(bundle, resolved.dotenv, {
             passphrase: opts.passphrase ?? '',
             force: opts.force,
+            policyNever: opts.policyNever,
         });
         return { kind: 'ssh', remoteCmd, input, multiplex: false };
     }
@@ -100,7 +101,7 @@ export function planPushTransport(resolved, bundle, host, opts) {
         // the wire over ssh stdin.
         return {
             kind: 'ssh',
-            remoteCmd: buildWindowsStdinImportCommand(bundle, { force: opts.force }),
+            remoteCmd: buildWindowsStdinImportCommand(bundle, { force: opts.force, policyNever: opts.policyNever }),
             input: resolved.dotenv,
             multiplex: false,
         };
@@ -110,7 +111,11 @@ export function planPushTransport(resolved, bundle, host, opts) {
     // path the READ inverse (`remoteResolveEnv`) uses.
     return {
         kind: 'remote-secrets',
-        args: ['import', bundle, '--from', '-', ...(opts.force ? ['--force'] : [])],
+        args: [
+            'import', bundle, '--from', '-',
+            ...(opts.force ? ['--force'] : []),
+            ...(opts.policyNever ? ['--policy', 'never', '--i-understand'] : []),
+        ],
         input: resolved.dotenv,
         multiplex: false,
     };
@@ -158,13 +163,6 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
                 : `pushed '${bundle}' but could not verify it on the remote: ${verdict.reason}`);
         }
     }
-    if (opts.policyNever) {
-        const policy = remoteSecretsRaw(host, ['policy', bundle, 'never', '--i-understand'], { osLookupName: host, secret: true });
-        if (policy.code !== 0) {
-            const msg = (policy.stderr || policy.stdout || '').trim();
-            return fail(`pushed '${bundle}' but could not set remote policy never${msg ? `: ${msg}` : ''}`);
-        }
-    }
     for (const step of planLiteralRestoration(bundle, opts.literalValues)) {
         const removed = remoteSecretsRaw(host, step.removeArgs, { osLookupName: host, secret: true });
         if (removed.code !== 0) {

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

@@ -1,6 +1,6 @@
 /**
  * Remote secrets — read and use `agents secrets` bundles that live on another
- * host, over the same hardened SSH path that `agents secrets export --host`
+ * host, over the same hardened SSH path that `agents secrets export --device`
  * (the write inverse) already uses.
  *
  * This is the READ / USE direction:
@@ -10,7 +10,7 @@
  *              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 --host` / `run --host`). Bundle names are shell-quoted
+ * boundary as `export --device` / `run --device`). Bundle names are shell-quoted
  * into the remote command; resolved VALUES return over ssh stdout; a forwarded
  * file-backend passphrase travels over ssh stdin (first line) so it never lands
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
@@ -27,9 +27,8 @@ import { type SshExecResult } from '../ssh-exec.js';
  *   - **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` — which still refuses a changed key, only learns a genuinely
- *     new one — before that). So a machine-in-the-middle swapping a pinned host's
- *     key can never receive or return a secret.
+ *     `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.
@@ -38,6 +37,8 @@ export declare function credentialTransportSshOpts(target: string): {
     hostKeyOpts: string[];
     multiplex: false;
 };
+/** 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
@@ -56,9 +57,9 @@ export declare function credentialTransportSshOpts(target: string): {
  */
 export declare function isDangerousRemoteEnvKey(name: string): boolean;
 /**
- * Resolve a `--host` value to an ssh target STRING for the remote-secrets path.
+ * 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 --host` does; on a miss, treats the
+ * 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.
@@ -67,7 +68,7 @@ export declare function resolveHostSshTarget(nameOrAlias: string): Promise<strin
 /**
  * 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 `--host`/`--hosts` so the
+ * 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.
  */
@@ -109,7 +110,7 @@ export declare function remoteSecretsRaw(target: string, args: string[], opts?:
  * 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 --host`: you type the remote
+ * 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.
  */
@@ -168,9 +169,10 @@ export type RemoteKeychainWriteVerification = {
  * 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 release will (`secrets export --plaintext --format
- * json`, 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.
+ * 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`.
@@ -192,10 +194,11 @@ export declare function keychainWriteFailureMessage(host: string, bundle: 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 own `secrets export <bundle> --plaintext --format json` — the same read
- * a headless release performs — 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.
+ * 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.
  */
 export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
     osLookupName?: string;
@@ -203,7 +206,7 @@ export declare function verifyRemoteKeychainPush(target: string, bundle: string,
 }): RemoteKeychainWriteVerification;
 /**
  * The `bash -lc` command + stdin payload that drives a **file-backed** remote
- * import for `secrets export --host … --remote-backend file`.
+ * import for `secrets export --device … --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
@@ -226,6 +229,7 @@ export declare function verifyRemoteKeychainPush(target: string, bundle: string,
 export declare function buildRemoteFileImportCommand(bundle: string, dotenv: string, opts?: {
     passphrase?: string;
     force?: boolean;
+    policyNever?: boolean;
 }): {
     remoteCmd: string;
     input: string;

package/dist/lib/secrets/remote.js

@@ -1,6 +1,6 @@
 /**
  * Remote secrets — read and use `agents secrets` bundles that live on another
- * host, over the same hardened SSH path that `agents secrets export --host`
+ * host, over the same hardened SSH path that `agents secrets export --device`
  * (the write inverse) already uses.
  *
  * This is the READ / USE direction:
@@ -10,7 +10,7 @@
  *              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 --host` / `run --host`). Bundle names are shell-quoted
+ * boundary as `export --device` / `run --device`). Bundle names are shell-quoted
  * into the remote command; resolved VALUES return over ssh stdout; a forwarded
  * file-backend passphrase travels over ssh stdin (first line) so it never lands
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
@@ -39,9 +39,8 @@ function hostKeyLookupName(target) {
  *   - **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` — which still refuses a changed key, only learns a genuinely
- *     new one — before that). So a machine-in-the-middle swapping a pinned host's
- *     key can never receive or return a secret.
+ *     `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.
@@ -49,6 +48,13 @@ function hostKeyLookupName(target) {
 export function credentialTransportSshOpts(target) {
     return { hostKeyOpts: hostKeyCheckingOpts(isHostPinned(hostKeyLookupName(target))), multiplex: false };
 }
+/** Refuse durable credential transfer until the destination SSH key is pinned. */
+export function assertCredentialTransportHostPinned(target, pinned = isHostPinned(hostKeyLookupName(target))) {
+    if (pinned)
+        return;
+    throw new Error(`Refusing to transfer provider credentials to '${target}' before its SSH host key is pinned. ` +
+        `Connect once with 'agents ssh ${target}' and verify the host, then retry.`);
+}
 /**
  * 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
@@ -85,9 +91,9 @@ function osForTarget(target, lookupName) {
     return byName ?? resolveRemoteOsSync(target.split('@').pop() ?? target);
 }
 /**
- * Resolve a `--host` value to an ssh target STRING for the remote-secrets path.
+ * 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 --host` does; on a miss, treats the
+ * 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.
@@ -102,7 +108,7 @@ export async function resolveHostSshTarget(nameOrAlias) {
 /**
  * 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 `--host`/`--hosts` so the
+ * 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.
  */
@@ -158,7 +164,7 @@ export function remoteSecretsRaw(target, args, opts = {}) {
     // to multiplex — see `credentialTransportSshOpts` (RUSH-2527). A `-tt` session
     // (a remote reveal/passphrase prompt) additionally allocates a PTY and never
     // multiplexes, and it COMPOSES with the secret posture: a `view --reveal` over
-    // `--host` both prompts AND streams the plaintext value back over ssh stdout,
+    // `--device` both prompts AND streams the plaintext value back over ssh stdout,
     // so it needs the managed host-key pin too — `tty` must not short-circuit past
     // `secret`. A plain browse `list` passes neither and keeps the shared baseline.
     const posture = opts.secret ? credentialTransportSshOpts(target) : {};
@@ -180,13 +186,13 @@ export function remoteSecretsRaw(target, args, opts = {}) {
  * 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 --host`: you type the remote
+ * 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.
  */
 export function remoteSecretsStream(target, args, opts = {}) {
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target, opts.osLookupName));
-    // `unlock --host` carries the remote bundle's passphrase to the destination over
+    // `unlock --device` carries the remote bundle's passphrase to the destination over
     // this interactive channel, so it is secret-bearing: pin the managed host key
     // (a changed key is refused) and never multiplex (RUSH-2527).
     return sshStream(target, remoteCmd, { tty: true, ...credentialTransportSshOpts(target) });
@@ -206,7 +212,12 @@ export function remoteSecretsStream(target, args, opts = {}) {
  */
 export async function remoteResolveEnv(target, bundle, opts = {}) {
     assertValidSshTarget(target);
-    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName));
+    // AGENTS_SECRETS_REMOTE_TRANSPORT is the marker that lets the remote's
+    // `export --plaintext --format json` emit at all — the public shell-eval
+    // export mode was removed (RUSH-2774), and this machine-to-machine resolve is
+    // the only surviving caller of the JSON emitter. Riding the legacy argv keeps
+    // a new driver compatible with an old remote during a fleet rollout.
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName), { AGENTS_SECRETS_REMOTE_TRANSPORT: '1' });
     // Resolving a remote bundle streams its plaintext values back over ssh stdout,
     // so this read is secret-bearing: pin the managed host key and never leave a
     // reusable control master to the source (RUSH-2527, `credentialTransportSshOpts`).
@@ -293,9 +304,10 @@ function isLockedKeychainReadBackError(stderr) {
  * 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 release will (`secrets export --plaintext --format
- * json`, 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.
+ * 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`.
@@ -346,20 +358,23 @@ export function keychainWriteFailureMessage(host, bundle, reason) {
         `A macOS login keychain is LOCKED under headless SSH, so a keychain-backed write ` +
         `lands the bundle metadata but no readable secret items, and later reads fail with ` +
         `"stored item '…' not found". Re-run with a headless-readable backend:\n` +
-        `    agents secrets export ${bundle} --host ${host} --remote-backend file\n` +
+        `    agents secrets export ${bundle} --device ${host} --remote-backend file\n` +
         `(needs AGENTS_SECRETS_PASSPHRASE set locally), or unlock the remote keychain first ` +
         `(e.g. an interactive login / \`agents secrets unlock\` on ${host}) and retry.`);
 }
 /**
  * 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 own `secrets export <bundle> --plaintext --format json` — the same read
- * a headless release performs — 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.
+ * 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.
  */
 export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {}) {
-    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName));
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName), 
+    // Same transport marker as remoteResolveEnv — see the comment there (RUSH-2774).
+    { AGENTS_SECRETS_REMOTE_TRANSPORT: '1' });
     // This read-back streams the just-pushed plaintext over ssh stdout, so it is
     // as secret-bearing as the push itself — the push path passes `secret: true`
     // so it too pins the managed host key and leaves no reusable control master to
@@ -400,7 +415,7 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
 }
 /**
  * The `bash -lc` command + stdin payload that drives a **file-backed** remote
- * import for `secrets export --host … --remote-backend file`.
+ * import for `secrets export --device … --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
@@ -422,7 +437,8 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
  */
 export function buildRemoteFileImportCommand(bundle, dotenv, opts = {}) {
     const force = opts.force ? ' --force' : '';
-    const importCmd = `agents secrets import ${shellQuote(bundle)} --from - --backend file${force}`;
+    const policy = opts.policyNever ? ' --policy never --i-understand' : '';
+    const importCmd = `agents secrets import ${shellQuote(bundle)} --from - --backend file${force}${policy}`;
     const passphrase = opts.passphrase ?? '';
     if (passphrase) {
         // Opt-in shared passphrase: read it off the FIRST stdin line, export it, then

package/dist/lib/secrets/vault.js

@@ -237,7 +237,7 @@ export function getVaultSession() {
 function requireVaultKey() {
     const session = getVaultSession();
     if (!session.loggedIn) {
-        throw new Error('Not logged in. Run: agents login');
+        throw new Error('Synced secrets locked. Run: agents secrets vault unlock');
     }
     return session.key;
 }
@@ -259,7 +259,7 @@ function parseVaultItem(item) {
 function vaultMissingError(file) {
     return new Error(`Vault file is missing: ${file}. A vault was created but the file is gone` +
         ' (a sync conflict, an undownloaded placeholder, or an accidental move/delete).' +
-        ' Restore it before writing, or run: agents login --create --force to start over.');
+        ' Restore it before writing, or run: agents secrets vault unlock --create --force to start over.');
 }
 function readVaultData() {
     const file = vaultPath();

package/dist/lib/self-heal/checks/shadowing.js

@@ -6,7 +6,7 @@
 import { resultOf } from '../types.js';
 import { AGENTS } from '../../agents.js';
 import { getPathShadowingExecutable, adoptShadowingLauncher, listAgentsWithNonIsolatedInstalledVersions, } from '../../shims.js';
-import { getGlobalDefault } from '../../versions.js';
+import { getGlobalDefault } from '../../installations/versions.js';
 export const shadowingCheck = {
     id: 'shadowing',
     title: 'Launcher shadowing the version-managed shim',

package/dist/lib/self-heal/checks/shims.js

@@ -5,7 +5,7 @@
 import { resultOf } from '../types.js';
 import { AGENTS } from '../../agents.js';
 import { createShim, ensureShimCurrent, ensureVersionedAliasCurrent, isShimCurrent, isVersionedAliasCurrent, removeShim, shimExists, shimPointsAtLiveInstall, removeLegacyUserShim, listAgentsWithInstalledVersions, listAgentsWithNonIsolatedInstalledVersions, listShimFileNames, pruneOrphanedCommandShim, } from '../../shims.js';
-import { listInstalledVersions } from '../../versions.js';
+import { listInstalledVersions } from '../../installations/versions.js';
 export const shimsCheck = {
     id: 'shims',
     title: 'Dispatch shims + versioned aliases',

package/dist/lib/self-update.d.ts

@@ -200,7 +200,24 @@ export interface MultiInstallInventoryEntry {
     packageRoot: string;
     version: string;
     note: string;
+    /** True for the copy that is currently executing. */
+    running: boolean;
+    /**
+     * True when a bare `agents doctor --fix` deletes this copy (RUSH-2415:
+     * npx-cache / unsafe-legacy / pre-1.22.30 with a fixed peer). False for the
+     * running copy and for any duplicate --fix will not touch — a healthy
+     * >=1.22.30 peer, or a pre-1.22.30 copy with no fixed peer to fall back to;
+     * both need the manual command from manualUninstallCommand() (RUSH-2705/2713).
+     */
+    autoPurgeable: boolean;
 }
+/**
+ * The exact shell command that removes the install at `packageRoot` by hand —
+ * the remedy for duplicates `doctor --fix` deliberately will not purge
+ * (RUSH-2705). `--prefix` pins the target tree no matter which npm binary
+ * PATH resolves, mirroring installPackageIntoPrefix.
+ */
+export declare function manualUninstallCommand(packageRoot: string): string;
 export declare function buildMultiInstallInventory(runningRoot: string, runningVersion: string, installs: AgentsCliInstall[]): MultiInstallInventoryEntry[];
 /** Why a discovered install is safe to delete without an interactive confirm. */
 export type RemovableInstallReason = 'npx-cache' | 'unsafe-legacy-helper' | 'pre-fixed-version';
@@ -250,6 +267,27 @@ export declare function purgeRemovableAgentsCliInstalls(candidates: RemovableAge
     dryRun?: boolean;
     runningRoot?: string;
 }): PurgeRemovableInstallsResult;
+/** A detected duplicate that `doctor --fix` will not purge (RUSH-2705). */
+export interface UnresolvedDuplicateInstall {
+    packageRoot: string;
+    version: string;
+    /** Exact shell command that removes this copy by hand. */
+    manualRemoveCommand: string;
+}
+export interface RemediateStaleInstallsResult extends PurgeRemovableInstallsResult {
+    inventory: MultiInstallInventoryEntry[];
+    candidates: RemovableAgentsCliInstall[];
+    /**
+     * Duplicates detected but NOT auto-purged, for either reason:
+     *   1. a healthy >=1.22.30 global (safe, just redundant), or
+     *   2. a pre-1.22.30 copy left alone only because no fixed peer exists to fall
+     *      back to (the anti-stranding guard) — this one is genuinely vulnerable,
+     *      not healthy.
+     * Either way the caller must surface manualRemoveCommand — otherwise the
+     * multi-install warning keeps firing with no working remedy (RUSH-2705/2713).
+     */
+    unresolved: UnresolvedDuplicateInstall[];
+}
 /**
  * Scan + classify + purge in one call. Used by `agents doctor --fix` and
  * `agents upgrade` so both paths remediate the same set of latent copies.
@@ -260,10 +298,7 @@ export declare function remediateStaleAgentsCliInstalls(opts: {
     pathEnv?: string;
     findOpts?: FindAgentsCliInstallsOptions;
     dryRun?: boolean;
-}): PurgeRemovableInstallsResult & {
-    inventory: MultiInstallInventoryEntry[];
-    candidates: RemovableAgentsCliInstall[];
-};
+}): RemediateStaleInstallsResult;
 /**
  * Resolve every `agents` entrypoint on PATH, then inspect the bounded global
  * install layouts used by NVM, fnm, Volta, Bun, npm, and npx. More than one

package/dist/lib/self-update.js

@@ -145,6 +145,13 @@ export function readMultiInstallScanCache(file) {
             !Array.isArray(raw.inventory)) {
             return null;
         }
+        // A cache written before the entries carried running/autoPurgeable
+        // (RUSH-2705) cannot drive the banner's remedy choice — treat it as
+        // corrupt so the caller re-scans rather than mis-advertising --fix.
+        const entries = raw.inventory;
+        if (entries.some((entry) => typeof entry?.running !== 'boolean' || typeof entry?.autoPurgeable !== 'boolean')) {
+            return null;
+        }
         return raw;
     }
     catch {
@@ -415,11 +422,67 @@ function packageRootForEntry(real) {
     }
     return null;
 }
+/** Best-effort canonical path; keeps the input when realpath fails. */
+function canonicalPath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Ensure the running copy participates in classification (the "has a fixed
+ * peer" check) even when the PATH scan missed it — a source tree or unusual
+ * layout. The running root is never deleted regardless.
+ */
+function withRunningInstall(installs, runningRoot, runningVersion) {
+    const runningCanonical = canonicalPath(runningRoot);
+    const already = installs.some((install) => canonicalPath(install.packageRoot) === runningCanonical);
+    if (already)
+        return installs;
+    return [...installs, {
+            packageRoot: runningRoot,
+            version: runningVersion,
+            // Unknown for a synthetic entry — classify only uses version for the
+            // fixed-peer check; the running root is never deleted regardless.
+            atomicHelperInstall: true,
+        }];
+}
+/**
+ * The exact shell command that removes the install at `packageRoot` by hand —
+ * the remedy for duplicates `doctor --fix` deliberately will not purge
+ * (RUSH-2705). `--prefix` pins the target tree no matter which npm binary
+ * PATH resolves, mirroring installPackageIntoPrefix.
+ */
+export function manualUninstallCommand(packageRoot) {
+    const resolved = path.resolve(packageRoot);
+    if (detectPackageManager(resolved) === 'bun') {
+        return `bun remove -g ${NPM_PACKAGE_NAME}`;
+    }
+    try {
+        return `npm uninstall -g --prefix '${deriveGlobalPrefix(resolved)}' ${NPM_PACKAGE_NAME}`;
+    }
+    catch {
+        // Not inside a node_modules tree — no npm prefix owns it; deleting the
+        // directory is the only removal there is.
+        return `rm -rf '${resolved}'`;
+    }
+}
 export function buildMultiInstallInventory(runningRoot, runningVersion, installs) {
+    const runningCanonical = canonicalPath(runningRoot);
+    const removableRoots = new Set(classifyRemovableAgentsCliInstalls(runningRoot, withRunningInstall(installs, runningRoot, runningVersion)).map((candidate) => candidate.packageRoot));
     const byRoot = new Map();
-    byRoot.set(runningRoot, { packageRoot: runningRoot, version: runningVersion, note: 'running' });
+    byRoot.set(runningRoot, {
+        packageRoot: runningRoot,
+        version: runningVersion,
+        note: 'running',
+        running: true,
+        autoPurgeable: false,
+    });
     for (const install of installs) {
-        const notes = [install.packageRoot === runningRoot
+        const running = canonicalPath(install.packageRoot) === runningCanonical;
+        const notes = [running
                 ? 'running'
                 : install.binPath
                     ? `agents on PATH: ${install.binPath}`
@@ -430,6 +493,8 @@ export function buildMultiInstallInventory(runningRoot, runningVersion, installs
             packageRoot: install.packageRoot,
             version: install.version,
             note: notes.join('; '),
+            running,
+            autoPurgeable: !running && removableRoots.has(canonicalPath(install.packageRoot)),
         });
     }
     return [...byRoot.values()];
@@ -588,38 +653,26 @@ export function purgeRemovableAgentsCliInstalls(candidates, opts = {}) {
  */
 export function remediateStaleAgentsCliInstalls(opts) {
     const pathEnv = opts.pathEnv ?? (process.env.PATH || '');
-    const installs = findAgentsCliInstalls(pathEnv, opts.findOpts);
+    let installs = findAgentsCliInstalls(pathEnv, opts.findOpts);
     // Ensure the running root participates in "has a fixed peer" even when the
     // PATH scan missed it (source tree, unusual layout).
     if (opts.runningVersion) {
-        const already = installs.some((i) => {
-            try {
-                return fs.realpathSync(i.packageRoot) === fs.realpathSync(opts.runningRoot);
-            }
-            catch {
-                return i.packageRoot === opts.runningRoot;
-            }
-        });
-        if (!already) {
-            installs.push({
-                packageRoot: opts.runningRoot,
-                version: opts.runningVersion,
-                // Unknown for a synthetic entry — classify only uses version for the
-                // fixed-peer check; the running root is never deleted regardless.
-                atomicHelperInstall: true,
-            });
-        }
+        installs = withRunningInstall(installs, opts.runningRoot, opts.runningVersion);
     }
     const candidates = classifyRemovableAgentsCliInstalls(opts.runningRoot, installs);
     const purge = purgeRemovableAgentsCliInstalls(candidates, {
         dryRun: opts.dryRun,
         runningRoot: opts.runningRoot,
     });
-    return {
-        ...purge,
-        candidates,
-        inventory: buildMultiInstallInventory(opts.runningRoot, opts.runningVersion ?? 'unknown', installs),
-    };
+    const inventory = buildMultiInstallInventory(opts.runningRoot, opts.runningVersion ?? 'unknown', installs);
+    const unresolved = inventory
+        .filter((entry) => !entry.running && !entry.autoPurgeable)
+        .map((entry) => ({
+        packageRoot: entry.packageRoot,
+        version: entry.version,
+        manualRemoveCommand: manualUninstallCommand(entry.packageRoot),
+    }));
+    return { ...purge, candidates, inventory, unresolved };
 }
 function childDirectories(parent) {
     try {

package/dist/lib/serve/control.d.ts

@@ -77,7 +77,7 @@ export declare function spawnDetached(command: string, args: string[], stdio?: S
 /**
  * Default run dispatcher: re-invoke `agents run` with a server-minted id so the
  * run is addressable, detached so it outlives this request (and the anchor
- * process). Local runs detach here; `--host` runs detach on the executor via
+ * process). Local runs detach here; `--device` runs detach on the executor via
  * the existing dispatch path.
  */
 export declare const defaultRunner: RunDispatcher;

package/dist/lib/serve/control.js

@@ -2,7 +2,7 @@ import { createServer } from 'http';
 import fs from 'fs';
 import { spawn } from 'child_process';
 import { randomUUID, randomBytes } from 'crypto';
-import { getAgentsInvocation } from '../daemon.js';
+import { getAgentsInvocation } from '../daemon/daemon.js';
 import { handleServeGet, resolveServeContext } from './server.js';
 import { verifyControlToken } from './token.js';
 import { readNewEvents, streamDir, streamLogPath } from './stream.js';
@@ -127,7 +127,7 @@ export function spawnDetached(command, args, stdio = 'ignore') {
 /**
  * Default run dispatcher: re-invoke `agents run` with a server-minted id so the
  * run is addressable, detached so it outlives this request (and the anchor
- * process). Local runs detach here; `--host` runs detach on the executor via
+ * process). Local runs detach here; `--device` runs detach on the executor via
  * the existing dispatch path.
  */
 export const defaultRunner = async (req) => {
@@ -144,7 +144,7 @@ export const defaultRunner = async (req) => {
     if (req.mode)
         argv.push('--mode', req.mode);
     if (req.host)
-        argv.push('--host', req.host);
+        argv.push('--device', req.host);
     if (req.cwd)
         argv.push('--cwd', req.cwd);
     const inv = getAgentsInvocation(argv);
@@ -152,7 +152,7 @@ export const defaultRunner = async (req) => {
     // unhandled 'error' that crashes the anchor for every other session.
     //
     // For an anchor-local run, capture the `--json` NDJSON to a per-session file
-    // so `GET /api/session/:id/stream` can offset-tail it. A `--host` run emits
+    // so `GET /api/session/:id/stream` can offset-tail it. A `--device` run emits
     // its NDJSON on the remote box (streaming that reuses pullRemoteLogDelta — a
     // follow-up), so we don't capture the local dispatcher's output.
     if (req.host) {

package/dist/lib/serve/data.d.ts

@@ -15,7 +15,7 @@
  */
 import { AgentManager } from '../teams/agents.js';
 import type { AgentStatusSummary } from '../teams/api.js';
-import type { JobConfig } from '../routines.js';
+import type { JobConfig } from '../scheduling/routines.js';
 import type { CloudTask } from '../cloud/types.js';
 /** One teammate's worktree and its current uncommitted diff. */
 export interface WorktreeDiff {