@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/secrets/push.js

@@ -22,7 +22,7 @@
 import { sshExec } from '../ssh-exec.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
-import { remoteSecretsRaw, verifyRemoteKeychainPush, keychainWriteFailureMessage, buildRemoteFileImportCommand, } from './remote.js';
+import { remoteSecretsRaw, verifyRemoteKeychainPush, keychainWriteFailureMessage, buildRemoteFileImportCommand, credentialTransportSshOpts, } from './remote.js';
 import { readAndResolveBundleEnv } from './bundles.js';
 /**
  * Serialize a resolved env map to `.env` lines that round-trip losslessly through
@@ -42,15 +42,35 @@ export function bundleEnvToDotenv(env) {
     }
     return lines.join('\n') + '\n';
 }
+/** Preserve the literal-vs-secret schema that dotenv transport cannot encode. */
+export function planLiteralRestoration(bundle, literalValues = {}) {
+    return Object.entries(literalValues).map(([key, value]) => ({
+        key,
+        removeArgs: ['remove', bundle, key, '--yes'],
+        addArgs: ['add', bundle, key, '--value', value],
+    }));
+}
 /**
  * Read and resolve a bundle once, for pushing to one or more hosts.
  *
- * `agentOnly` + `keyMode: 'storage'` match what `export --host` has always
- * passed: storage-shaped values, and the headless guard that fails fast rather
- * than popping Touch ID inside an automated run.
+ * `keyMode: 'storage'` is fixed — a push always sends storage-shaped values.
+ *
+ * `agentOnly` is the caller's to decide, and it is NOT a security level: it
+ * selects the broker-only read (fail fast with the `agents secrets unlock` hint)
+ * over the interactive read (macOS may raise a Touch ID sheet). The headless
+ * guard exists because an AGENT LAUNCH must never enumerate the keychain — a
+ * per-bundle prefix becomes a broad `agents-cli.` scan after service-name
+ * hashing, and macOS evaluates unrelated biometry ACLs during it, one sheet per
+ * installed version (bundles.ts, RUSH-2440). A human at a TTY is not that case:
+ * they can answer one prompt, and the interactive sibling reads (`view --reveal`,
+ * `exec`) already let them. NOT `get` — it is unconditionally `agentOnly` on
+ * purpose, because prompting would hang a `$(agents secrets get …)` capture
+ * mid-pipeline (SEC-13b). It defaults to `true` so an automated caller that says
+ * nothing stays broker-only.
  */
-export function resolveBundleForPush(bundle, caller) {
-    const { env } = readAndResolveBundleEnv(bundle, { caller, keyMode: 'storage', agentOnly: true });
+export function resolveBundleForPush(bundle, caller, opts = {}) {
+    const agentOnly = opts.agentOnly ?? true;
+    const { env } = readAndResolveBundleEnv(bundle, { caller, keyMode: 'storage', agentOnly });
     return { env, dotenv: bundleEnvToDotenv(env), keyCount: Object.keys(env).length };
 }
 function isPowershellTarget(host) {
@@ -70,7 +90,7 @@ export function planPushTransport(resolved, bundle, host, opts) {
             passphrase: opts.passphrase ?? '',
             force: opts.force,
         });
-        return { kind: 'ssh', remoteCmd, input };
+        return { kind: 'ssh', remoteCmd, input, multiplex: false };
     }
     if (powershell) {
         // Keychain on a Windows target: the `agents.ps1` shim doesn't forward
@@ -82,6 +102,7 @@ export function planPushTransport(resolved, bundle, host, opts) {
             kind: 'ssh',
             remoteCmd: buildWindowsStdinImportCommand(bundle, { force: opts.force }),
             input: resolved.dotenv,
+            multiplex: false,
         };
     }
     // Keychain on a POSIX target: OS-aware wrapping + the hardened ssh engine
@@ -91,6 +112,7 @@ export function planPushTransport(resolved, bundle, host, opts) {
         kind: 'remote-secrets',
         args: ['import', bundle, '--from', '-', ...(opts.force ? ['--force'] : [])],
         input: resolved.dotenv,
+        multiplex: false,
     };
 }
 /**
@@ -105,9 +127,15 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
     const plan = planPushTransport(resolved, bundle, host, opts);
     if (plan.kind === 'refuse')
         return fail(plan.message);
+    // Every ssh below rides the credential-transport posture: the managed host key
+    // is pinned (a changed key is refused) and the connection never reuses or
+    // leaves a persistent authenticated control master to the destination
+    // (RUSH-2527, `credentialTransportSshOpts`). The plan's `multiplex: false` is
+    // the raw-`ssh` branch's half of that; the `remote-secrets` branch and the
+    // read-back/policy/literal follow-ups pass `secret: true` for the same posture.
     const res = plan.kind === 'ssh'
-        ? sshExec(host, plan.remoteCmd, { input: plan.input })
-        : remoteSecretsRaw(host, plan.args, { input: plan.input, osLookupName: host });
+        ? sshExec(host, plan.remoteCmd, { input: plan.input, hostKeyOpts: credentialTransportSshOpts(host).hostKeyOpts, multiplex: plan.multiplex })
+        : remoteSecretsRaw(host, plan.args, { input: plan.input, osLookupName: host, secret: true });
     if (res.code === null) {
         return fail(res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed'));
     }
@@ -123,13 +151,32 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
     // metadata-only bundle that breaks later with "stored item not found". The
     // file backend is headless-readable by construction, so it is skipped.
     if (opts.remoteBackend === 'keychain') {
-        const verdict = verifyRemoteKeychainPush(host, bundle, Object.keys(resolved.env), { osLookupName: host });
+        const verdict = verifyRemoteKeychainPush(host, bundle, Object.keys(resolved.env), { osLookupName: host, secret: true });
         if (!verdict.ok) {
             return fail(verdict.kind === 'locked-keychain'
                 ? keychainWriteFailureMessage(host, bundle, verdict.reason)
                 : `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) {
+            const msg = (removed.stderr || removed.stdout || '').trim();
+            return fail(`pushed '${bundle}' but could not replace transported ${step.key}${msg ? `: ${msg}` : ''}`);
+        }
+        const literal = remoteSecretsRaw(host, step.addArgs, { osLookupName: host, secret: true });
+        if (literal.code !== 0) {
+            const msg = (literal.stderr || literal.stdout || '').trim();
+            return fail(`pushed '${bundle}' but could not preserve literal ${step.key}${msg ? `: ${msg}` : ''}`);
+        }
+    }
     const remoteMsg = (res.stdout || '').trim().split('\n').map((l) => l.trim()).filter(Boolean).pop();
     return {
         ok: true,
@@ -141,5 +188,5 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
 }
 /** Resolve and push in one call — for a single host. */
 export function pushBundleToHost(bundle, host, opts) {
-    return pushResolvedBundleToHost(resolveBundleForPush(bundle, opts.operation), bundle, host, opts);
+    return pushResolvedBundleToHost(resolveBundleForPush(bundle, opts.operation, { agentOnly: opts.agentOnly }), bundle, host, opts);
 }

package/dist/lib/secrets/read-backoff.d.ts

@@ -2,7 +2,7 @@
  * Negative memo for failed/cancelled macOS keychain reads (the "back-off").
  *
  * A cancelled Touch ID sheet is the user saying "not now" — but a polling
- * caller (the Factory extension host's `agents view` loop, a watch script)
+ * caller (AGI EXT host's `agents view` loop, a watch script)
  * retries the same read a few seconds later and pops the sheet again, forever.
  * The headless guard (index.ts `assertRawKeychainReadAllowed`) covers the
  * no-TTY case; this memo covers a context that CAN prompt but just had its

package/dist/lib/secrets/read-backoff.js

@@ -2,7 +2,7 @@
  * Negative memo for failed/cancelled macOS keychain reads (the "back-off").
  *
  * A cancelled Touch ID sheet is the user saying "not now" — but a polling
- * caller (the Factory extension host's `agents view` loop, a watch script)
+ * caller (AGI EXT host's `agents view` loop, a watch script)
  * retries the same read a few seconds later and pops the sheet again, forever.
  * The headless guard (index.ts `assertRawKeychainReadAllowed`) covers the
  * no-TTY case; this memo covers a context that CAN prompt but just had its

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

@@ -16,6 +16,28 @@
  * in argv / `ps` / remote shell history. Nothing is persisted 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` — 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.
+ *   - **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.
+ */
+export declare function credentialTransportSshOpts(target: string): {
+    hostKeyOpts: string[];
+    multiplex: false;
+};
 /**
  * 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
@@ -76,6 +98,7 @@ export declare function remoteSecretsRaw(target: string, args: string[], opts?:
     tty?: boolean;
     input?: string;
     osLookupName?: string;
+    secret?: boolean;
 }): SshExecResult;
 /**
  * Run a remote `agents secrets <args>` FOREGROUND, with the local stdio wired
@@ -176,6 +199,7 @@ export declare function keychainWriteFailureMessage(host: string, bundle: string
  */
 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

package/dist/lib/secrets/remote.js

@@ -22,7 +22,33 @@ import { sshTargetFor } from '../hosts/types.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { isLoaderOrInterpreterEnv } from './bundles.js';
+import { isHostPinned, hostKeyCheckingOpts } from '../devices/known-hosts.js';
 const REMOTE_TIMEOUT_MS = 30_000;
+/** The host part of an ssh target (`user@host` -> `host`) for known_hosts matching. */
+function hostKeyLookupName(target) {
+    return target.split('@').pop() ?? target;
+}
+/**
+ * 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` — 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.
+ *   - **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.
+ */
+export function credentialTransportSshOpts(target) {
+    return { hostKeyOpts: hostKeyCheckingOpts(isHostPinned(hostKeyLookupName(target))), multiplex: false };
+}
 /**
  * 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
@@ -128,11 +154,21 @@ export function splitBundleRef(ref) {
  */
 export function remoteSecretsRaw(target, args, opts = {}) {
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target, opts.osLookupName));
+    // A secret-bearing call (`secret: true`) pins the managed host key and refuses
+    // 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,
+    // 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) : {};
+    const conn = opts.tty
+        ? { ...posture, extraSshArgs: ['-tt'], multiplex: false }
+        : posture;
     return sshExec(target, remoteCmd, {
         timeoutMs: REMOTE_TIMEOUT_MS,
         input: opts.input,
-        extraSshArgs: opts.tty ? ['-tt'] : undefined,
-        multiplex: opts.tty ? false : undefined,
+        ...conn,
     });
 }
 /**
@@ -150,7 +186,10 @@ export function remoteSecretsRaw(target, args, opts = {}) {
  */
 export function remoteSecretsStream(target, args, opts = {}) {
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target, opts.osLookupName));
-    return sshStream(target, remoteCmd, { tty: true });
+    // `unlock --host` 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) });
 }
 /**
  * Resolve a remote bundle to a plaintext env map by driving the remote's
@@ -168,8 +207,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));
+    // 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`).
     const res = sshExec(target, remoteCmd, {
         timeoutMs: REMOTE_TIMEOUT_MS,
+        ...credentialTransportSshOpts(target),
     });
     if (res.code !== 0) {
         const msg = (res.stderr || res.stdout || '').trim();
@@ -317,7 +360,14 @@ export function keychainWriteFailureMessage(host, bundle, reason) {
  */
 export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {}) {
     const remoteCmd = buildRemoteAgentsInvocation(['secrets', 'export', bundle, '--plaintext', '--format', 'json'], undefined, osForTarget(target, opts.osLookupName));
-    const res = sshExec(target, remoteCmd, { timeoutMs: REMOTE_TIMEOUT_MS });
+    // 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
+    // the destination (RUSH-2527).
+    const res = sshExec(target, remoteCmd, {
+        timeoutMs: REMOTE_TIMEOUT_MS,
+        ...(opts.secret ? credentialTransportSshOpts(target) : {}),
+    });
     if (res.code !== 0) {
         const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
         const stderr = `${why}${(res.stderr || res.stdout || '').trim() ? `: ${(res.stderr || res.stdout).trim()}` : ''}`;

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

@@ -12,6 +12,14 @@
  * to PATH resolution.
  */
 export declare const NPM_PACKAGE_NAME = "@phnx-labs/agents-cli";
+/**
+ * First published release that stopped the usage/auth-health probe from reading
+ * Claude Code's interactive login (commit 3f3554c51). Pre-this versions on a
+ * macOS box re-introduce the Touch ID storm + fleet-wide revocation class
+ * (RUSH-2415 / RUSH-1822). Anything older is a latent regression while a fixed
+ * copy sits next to it.
+ */
+export declare const TOUCH_ID_STORM_FIXED_SINCE = "1.22.30";
 export type PackageManager = 'npm' | 'bun';
 /**
  * The directory bun installs global packages into:
@@ -55,6 +63,44 @@ export declare function saveUpdateCheck(file: string, latestVersion: string): vo
 export declare function dismissUpdateVersion(file: string, version: string): void;
 /** Whether the cached state warrants an upgrade prompt for a copy running `currentVersion`. */
 export declare function shouldPromptUpgrade(cache: UpdateCheckCache | null, currentVersion: string): boolean;
+/**
+ * Short TTL for the multi-install PATH scan cache (RUSH-2324). The full
+ * `findAgentsCliInstalls` walk over PATH + known roots costs ~1ms on a warm
+ * box and runs on every ordinary CLI invocation via `maybeWarnMultiInstall`.
+ * Same 5-minute window as the detached-sync spawn gate so both bootstrap
+ * savings share one recency policy.
+ */
+export declare const MULTI_INSTALL_SCAN_TTL_MS: number;
+/** On-disk shape for the multi-install scan cache (beside `.update-check`). */
+export interface MultiInstallScanCache {
+    scannedAt: number;
+    /** Full PATH string at scan time — any change invalidates the cache. */
+    pathEnv: string;
+    runningRoot: string;
+    runningVersion: string;
+    inventory: MultiInstallInventoryEntry[];
+}
+/** Read a multi-install scan cache. Returns null if missing or corrupt. */
+export declare function readMultiInstallScanCache(file: string): MultiInstallScanCache | null;
+/** Persist a multi-install scan result. Best-effort. */
+export declare function writeMultiInstallScanCache(file: string, cache: MultiInstallScanCache): void;
+/**
+ * Whether a multi-install scan cache is still usable for this invocation.
+ * Invalid when missing, past TTL, PATH changed, or the running copy identity
+ * (root / version) changed — those are exactly the cases where a re-scan can
+ * surface a different inventory and re-fire the warning.
+ */
+export declare function isMultiInstallScanFresh(cache: MultiInstallScanCache | null, pathEnv: string, runningRoot: string, runningVersion: string, now?: number, ttlMs?: number): boolean;
+/**
+ * Resolve the multi-install inventory, hitting the on-disk scan cache when
+ * fresh. Callers that only need the inventory (the bootstrap multi-install
+ * warning) avoid the ~1ms PATH walk on the warm path (RUSH-2324).
+ */
+export declare function resolveMultiInstallInventory(runningRoot: string, runningVersion: string, pathEnv: string, cacheFile: string, opts?: {
+    now?: number;
+    ttlMs?: number;
+    findOpts?: FindAgentsCliInstallsOptions;
+}): MultiInstallInventoryEntry[];
 /**
  * The on-disk package root of the copy that is currently running.
  *
@@ -156,6 +202,68 @@ export interface MultiInstallInventoryEntry {
     note: 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';
+export interface RemovableAgentsCliInstall {
+    packageRoot: string;
+    version: string;
+    reasons: RemovableInstallReason[];
+}
+export interface PurgeRemovableInstallsResult {
+    removed: RemovableAgentsCliInstall[];
+    failed: Array<RemovableAgentsCliInstall & {
+        error: string;
+    }>;
+    skippedRunning: number;
+}
+/** True when the package root lives under npm's `_npx` cache (ephemeral runs). */
+export declare function isNpxCacheInstall(packageRoot: string): boolean;
+/**
+ * A release string that is at least TOUCH_ID_STORM_FIXED_SINCE, or a side-by-side
+ * dev build (`0.0.0-dev.*`) which tracks main and therefore carries the fix.
+ * Non-semver junk never qualifies as "fixed" — better to leave a weird copy
+ * alone than delete the only working install.
+ */
+export declare function isTouchIdStormFixedVersion(version: string): boolean;
+/**
+ * Classify discovered installs that doctor --fix / upgrade may delete.
+ *
+ * Never marks the running package root. Auto-purge is limited to copies that
+ * cannot be the intended primary install:
+ *   - npx-cache trees (ephemeral)
+ *   - pre-atomic-helper-installer trees ("unsafe legacy helper installer")
+ *   - pre-TOUCH_ID_STORM_FIXED_SINCE trees, but only when at least one fixed
+ *     copy already exists on the box (so we never strand the machine)
+ *
+ * A pre-fixed copy that is also the only install stays — the user must upgrade
+ * it in place rather than delete it.
+ */
+export declare function classifyRemovableAgentsCliInstalls(runningRoot: string, installs: AgentsCliInstall[], opts?: {
+    fixedSince?: string;
+}): RemovableAgentsCliInstall[];
+/**
+ * Delete classified removable package roots from disk. Re-reads package.json
+ * immediately before the unlink so a path that is no longer @phnx-labs/agents-cli
+ * is never removed. Best-effort: one failure does not stop the rest.
+ */
+export declare function purgeRemovableAgentsCliInstalls(candidates: RemovableAgentsCliInstall[], opts?: {
+    dryRun?: boolean;
+    runningRoot?: string;
+}): PurgeRemovableInstallsResult;
+/**
+ * Scan + classify + purge in one call. Used by `agents doctor --fix` and
+ * `agents upgrade` so both paths remediate the same set of latent copies.
+ */
+export declare function remediateStaleAgentsCliInstalls(opts: {
+    runningRoot: string;
+    runningVersion?: string;
+    pathEnv?: string;
+    findOpts?: FindAgentsCliInstallsOptions;
+    dryRun?: boolean;
+}): PurgeRemovableInstallsResult & {
+    inventory: MultiInstallInventoryEntry[];
+    candidates: RemovableAgentsCliInstall[];
+};
 /**
  * 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