@phnx-labs/agents-cli 1.20.19 → 1.20.21

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+**`agents secrets start`: persistent secrets-agent service (fixes the broker under heavy load)**
+
+- On a heavily-loaded machine (many concurrent agents, high load average) the on-demand broker — a full CLI cold-start — couldn't get scheduled enough CPU to finish booting and bind its socket, so `unlock`/auto-cache silently failed and reads kept prompting. New `agents secrets start` installs the broker as a **launchd user service** (`RunAtLoad` + `KeepAlive`, `ProcessType: Interactive` for foreground scheduling priority): it starts once and stays up for the whole login session, so every read just connects — the cold start happens once (and launchd retries until it wins), never per read. `agents secrets stop` removes it; `agents secrets status` shows whether it's installed.
+- `unlock` and the auto-cache worker now install/kickstart this service automatically via `ensureAgentRunning`, falling back to the old one-off detached spawn only if the service path is unavailable. So the persistent broker is set up on first use with no extra step.
+- macOS only. Security model unchanged: in-memory only, per-bundle TTL, wiped on screen-lock/sleep.
+
 **Fix: secrets-agent auto-cache now survives a slow broker cold-start under load**
 
 - `secrets.agent.auto` (auto-cache on first read of a `session`-tier bundle) used a fire-and-forget inline loader that gave up connecting to the broker after 3s. But the broker it spawns is itself a full CLI cold-starting; under heavy load (many concurrent agents) that can exceed 3s, so the loader quit before the broker bound and the cache silently never populated — every read kept prompting. The auto-load now runs through a detached `secrets _agent-load` worker that reuses the robust `ensureAgentRunning` path (spawn-then-ping, 20s budget) and loads synchronously, so it reliably populates even when the broker is slow to start. Manual `agents secrets unlock` was always reliable and is unchanged. (secret values still travel over stdin, never argv.)

package/dist/commands/secrets.js

@@ -11,7 +11,7 @@ import { spawnSync } from 'child_process';
 import { bundleExists, bundleItemStore, bundleTier, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
-import { DEFAULT_TTL_MS, agentLoad, agentLock, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, } from '../lib/secrets/agent.js';
+import { DEFAULT_TTL_MS, agentLoad, agentLock, agentStatus, ensureAgentRunning, installSecretsAgentService, runAgentLoadFromStdin, runSecretsAgent, secretsAgentServiceInstalled, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -416,7 +416,7 @@ export function registerSecretsCommands(program) {
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
-        { title: 'Agent commands', names: ['unlock', 'lock', 'status', 'tier'] },
+        { title: 'Agent commands', names: ['start', 'stop', 'unlock', 'lock', 'status', 'tier'] },
         { title: 'Raw item commands', names: ['get', 'set'] },
         { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
         { title: 'Utilities', names: ['exec', 'generate', 'migrate-acl'] },
@@ -1363,6 +1363,10 @@ Examples:
             console.log(chalk.gray('secrets-agent is macOS-only.'));
             return;
         }
+        console.log(chalk.gray('service: ') +
+            (secretsAgentServiceInstalled()
+                ? chalk.green('installed (persistent)')
+                : chalk.yellow('not installed — run `agents secrets start` for a persistent broker')));
         const entries = await agentStatus();
         if (entries.length === 0) {
             console.log(chalk.gray('No bundles unlocked. The secrets-agent is idle or not running.'));
@@ -1397,11 +1401,38 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('start')
+        .description('Install + start the secrets-agent as a persistent background service (macOS). Survives heavy load; reads connect instantly.')
+        .action(async () => {
+        if (process.platform !== 'darwin') {
+            console.error(chalk.red('secrets-agent service is macOS-only.'));
+            process.exit(1);
+        }
+        process.stdout.write(chalk.gray('Installing launchd service…\n'));
+        if (await installSecretsAgentService()) {
+            console.log(chalk.green('secrets-agent service running.') + chalk.gray(' It stays up across the session; unlock/auto-cache now connect instantly.'));
+        }
+        else {
+            console.error(chalk.red('Service installed but did not become reachable in time (machine may be heavily loaded — launchd will keep retrying).'));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('stop')
+        .description('Stop + remove the persistent secrets-agent service and wipe what it held.')
+        .action(async () => {
+        if (process.platform !== 'darwin')
+            return;
+        await uninstallSecretsAgentService();
+        console.log(chalk.green('secrets-agent service stopped and removed.'));
+    });
     cmd
         .command('_agent-run', { hidden: true })
         .description('Run the secrets-agent broker in the foreground (internal)')
-        .action(async () => {
-        await runSecretsAgent();
+        .option('--service', 'run as a persistent launchd service (never idle-exit)')
+        .action(async (opts) => {
+        await runSecretsAgent({ service: Boolean(opts.service) });
     });
     cmd
         .command('_agent-load', { hidden: true })

package/dist/commands/versions.js

@@ -105,7 +105,13 @@ async function versionPruneAction(specs, options, commandName) {
         }
         const { agent, version } = parsed;
         const agentConfig = AGENTS[agent];
-        if (version === 'latest' || version === 'oldest' || !spec.includes('@')) {
+        // Script-installed agents (droid, grok) can have a *literal* `latest`
+        // version dir on disk when the post-install version probe failed. An
+        // explicit `<agent>@latest` should remove that dir directly rather than
+        // routing to the interactive picker (which can't run non-interactively),
+        // so treat an installed literal `latest` as a concrete pinned version.
+        const isLiteralLatestInstalled = version === 'latest' && spec.includes('@') && isVersionInstalled(agent, 'latest');
+        if (!isLiteralLatestInstalled && (version === 'latest' || version === 'oldest' || !spec.includes('@'))) {
             const versions = listInstalledVersions(agent);
             if (versions.length === 0) {
                 console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));

package/dist/lib/daemon.js

@@ -265,6 +265,9 @@ export async function runDaemon() {
         scheduler.reloadAll();
         const reloaded = scheduler.listScheduled();
         log('INFO', `Reloaded ${reloaded.length} jobs`);
+        // Drop the memoized R2 config so rotated/added sync credentials are re-read
+        // on the next cycle instead of waiting for a restart.
+        void import('./session/sync/config.js').then(m => m.clearR2ConfigCache());
     };
     const handleShutdown = async () => {
         log('INFO', 'Daemon shutting down');

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

@@ -37,6 +37,17 @@ export interface AgentStatusEntry {
     expiresAt: number;
     keyCount: number;
 }
+/** True if the launchd plist for the persistent broker is installed. */
+export declare function secretsAgentServiceInstalled(): boolean;
+/**
+ * Install + start the persistent broker as a launchd user service (idempotent).
+ * Writes the plist, bootstraps it into the GUI domain, and waits for the socket.
+ * `ProcessType: Interactive` asks launchd to schedule it at foreground priority
+ * so it can boot even when the machine is loaded. Returns true once reachable.
+ */
+export declare function installSecretsAgentService(timeoutMs?: number): Promise<boolean>;
+/** Stop + remove the persistent broker service, and wipe whatever it held. */
+export declare function uninstallSecretsAgentService(): Promise<void>;
 export type Request = {
     cmd: 'ping';
 } | {
@@ -95,7 +106,9 @@ export declare function handleAgentRequest(store: Map<string, StoredBundle>, req
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
  * sweeps expired entries, wipes on screen-lock/sleep, and self-exits when idle.
  */
-export declare function runSecretsAgent(): Promise<void>;
+export declare function runSecretsAgent(opts?: {
+    service?: boolean;
+}): Promise<void>;
 /** True if a broker socket exists at all. Cheap; gates the sync read so the
  * never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;
@@ -140,8 +153,13 @@ export declare function agentLock(name?: string): Promise<number>;
 /** List currently-unlocked bundles, or [] when no broker is running. */
 export declare function agentStatus(): Promise<AgentStatusEntry[]>;
 /**
- * Ensure a broker is running and reachable, spawning one detached if not.
- * Returns true once the socket answers a ping. On protocol-version skew, kills
- * the stale broker and respawns. macOS only.
+ * Ensure a broker is running and reachable. Returns true once the socket answers
+ * a ping. macOS only.
+ *
+ * Prefers the persistent launchd service: if it isn't installed we install it
+ * (which makes the broker survive for the whole login session, so subsequent
+ * reads never cold-start); if it's installed but unreachable we kickstart it.
+ * Only when the service path can't be used do we fall back to a one-off detached
+ * broker — that's the model that gets starved under heavy load, so it's last.
  */
 export declare function ensureAgentRunning(timeoutMs?: number): Promise<boolean>;

package/dist/lib/secrets/agent.js

@@ -24,6 +24,7 @@
  */
 import * as net from 'net';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { spawn, spawnSync, execFileSync } from 'child_process';
 import { getHelpersDir, readMeta } from '../state.js';
@@ -83,6 +84,113 @@ function cliSpawn(sub) {
 function brokerSpawn() {
     return cliSpawn(['secrets', '_agent-run']);
 }
+// ─── Persistent launchd service ──────────────────────────────────────────────
+// On a heavily-loaded machine a freshly-spawned broker (a full CLI cold start)
+// can't get scheduled enough CPU to finish booting and bind its socket — so the
+// on-demand model fails exactly when there are many agents (the case we care
+// about). The fix is to run the broker as a launchd user service: started once
+// with RunAtLoad + KeepAlive, it stays up, and every read just connects. The
+// cold start happens once (and launchd retries until it wins), never per-read.
+const SERVICE_LABEL = 'com.phnx-labs.agents-secrets-agent';
+function servicePlistPath() {
+    return path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+}
+/** True if the launchd plist for the persistent broker is installed. */
+export function secretsAgentServiceInstalled() {
+    return onDarwin() && fs.existsSync(servicePlistPath());
+}
+function generateServicePlist() {
+    const { cmd, args } = cliSpawn(['secrets', '_agent-run', '--service']);
+    const progArgs = [cmd, ...args]
+        .map((a) => `    <string>${a.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</string>`)
+        .join('\n');
+    const logPath = path.join(agentDir(), 'service.log');
+    const home = os.homedir();
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${progArgs}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>${logPath}</string>
+  <key>StandardErrorPath</key>
+  <string>${logPath}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${home}/.bun/bin</string>
+  </dict>
+</dict>
+</plist>`;
+}
+/**
+ * Install + start the persistent broker as a launchd user service (idempotent).
+ * Writes the plist, bootstraps it into the GUI domain, and waits for the socket.
+ * `ProcessType: Interactive` asks launchd to schedule it at foreground priority
+ * so it can boot even when the machine is loaded. Returns true once reachable.
+ */
+export async function installSecretsAgentService(timeoutMs = 30000) {
+    if (!onDarwin())
+        return false;
+    const plist = servicePlistPath();
+    fs.mkdirSync(path.dirname(plist), { recursive: true });
+    fs.writeFileSync(plist, generateServicePlist());
+    const uid = process.getuid?.() ?? 0;
+    // bootstrap is the modern API; fall back to legacy load. Both idempotent-ish.
+    try {
+        execFileSync('launchctl', ['bootstrap', `gui/${uid}`, plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch {
+        try {
+            execFileSync('launchctl', ['load', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch { /* may already be loaded */ }
+    }
+    // kickstart to force an immediate start even if already bootstrapped.
+    try {
+        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch { /* best effort */ }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await agentPing())
+            return true;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    return false;
+}
+/** Stop + remove the persistent broker service, and wipe whatever it held. */
+export async function uninstallSecretsAgentService() {
+    if (!onDarwin())
+        return;
+    await agentLock(); // wipe the in-memory store before tearing down
+    const plist = servicePlistPath();
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync('launchctl', ['bootout', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch {
+        try {
+            execFileSync('launchctl', ['unload', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch { /* not loaded */ }
+    }
+    try {
+        fs.unlinkSync(plist);
+    }
+    catch { /* already gone */ }
+}
 // ─── Broker server (runs in the detached `secrets _agent-run` process) ───────
 /**
  * Pure request handler over the in-memory store. Extracted so the store
@@ -130,9 +238,13 @@ export function handleAgentRequest(store, req, now = Date.now()) {
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
  * sweeps expired entries, wipes on screen-lock/sleep, and self-exits when idle.
  */
-export async function runSecretsAgent() {
+export async function runSecretsAgent(opts = {}) {
     if (!onDarwin())
         return; // nothing to broker without biometry prompts
+    // When launchd keeps us alive as a persistent service, never idle-exit:
+    // exiting would just make launchd cold-start us again, reintroducing the
+    // startup-under-load fragility the service exists to avoid.
+    const persistent = opts.service === true;
     // Single-instance guard: O_EXCL pid file. If a live broker already holds it,
     // exit quietly — the existing one keeps serving.
     const pidFile = pidPath();
@@ -172,7 +284,7 @@ export async function runSecretsAgent() {
             if (now >= e.expiresAt)
                 store.delete(name);
         if (store.size === 0) {
-            if (now - emptySince >= IDLE_EXIT_MS)
+            if (!persistent && now - emptySince >= IDLE_EXIT_MS)
                 shutdown(0);
         }
         else {
@@ -452,16 +564,43 @@ async function agentPing() {
     return r?.ok === true && r.cmd === 'ping' && r.version === PROTOCOL_VERSION;
 }
 /**
- * Ensure a broker is running and reachable, spawning one detached if not.
- * Returns true once the socket answers a ping. On protocol-version skew, kills
- * the stale broker and respawns. macOS only.
+ * Ensure a broker is running and reachable. Returns true once the socket answers
+ * a ping. macOS only.
+ *
+ * Prefers the persistent launchd service: if it isn't installed we install it
+ * (which makes the broker survive for the whole login session, so subsequent
+ * reads never cold-start); if it's installed but unreachable we kickstart it.
+ * Only when the service path can't be used do we fall back to a one-off detached
+ * broker — that's the model that gets starved under heavy load, so it's last.
  */
 export async function ensureAgentRunning(timeoutMs = 5000) {
     if (!onDarwin())
         return false;
     if (await agentPing())
         return true;
-    // Socket exists but ping failed → stale/old broker. Kill it before respawn.
+    // Path 1: the persistent service. installSecretsAgentService is idempotent and
+    // waits for the socket; for an already-installed service we kickstart and wait.
+    try {
+        if (!secretsAgentServiceInstalled()) {
+            if (await installSecretsAgentService(Math.max(timeoutMs, 20000)))
+                return true;
+        }
+        else {
+            const uid = process.getuid?.() ?? 0;
+            try {
+                execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+            }
+            catch { /* may already be running */ }
+            const d = Date.now() + timeoutMs;
+            while (Date.now() < d) {
+                if (await agentPing())
+                    return true;
+                await new Promise((r) => setTimeout(r, 150));
+            }
+        }
+    }
+    catch { /* fall through to the one-off spawn */ }
+    // Path 2 (fallback): one-off detached broker. Clear a stale socket/pid first.
     const stalePid = (() => {
         try {
             return parseInt(fs.readFileSync(pidPath(), 'utf-8').trim(), 10);
@@ -485,11 +624,7 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
     }
     catch { /* gone */ }
     const { cmd, args } = brokerSpawn();
-    const child = spawn(cmd, args, {
-        stdio: 'ignore',
-        detached: true,
-    });
-    child.unref();
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         if (await agentPing())

package/dist/lib/session/sync/config.d.ts

@@ -13,14 +13,26 @@ export interface R2Config {
     /** S3-compatible endpoint for the account (no bucket, no trailing slash). */
     endpoint: string;
 }
+/** Window after a prompt-bearing resolution failure during which we skip
+ *  re-attempting (and thus re-prompting). SIGHUP / restart bypasses it. */
+export declare const RESOLVE_RETRY_COOLDOWN_MS: number;
+/** Drop the cached resolution so the next call reads the bundle fresh. Called on
+ *  daemon SIGHUP (to pick up rotated credentials) and between tests. */
+export declare function clearR2ConfigCache(): void;
 /**
- * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
- * actionable error if the bundle or any key is missing — sync cannot proceed
- * without real credentials (no silent fallback).
+ * Resolve R2 credentials, reading the keychain at most once per process. The
+ * first call reads (and may prompt for Touch ID); every later call returns the
+ * memoized result. Throws if the bundle/keys are missing — failures are not
+ * memoized, but see isSyncConfigured for the re-prompt cooldown.
  */
 export declare function loadR2Config(): R2Config;
-/** True when the sync bundle exists and looks resolvable, without throwing. */
-export declare function isSyncConfigured(): boolean;
+/**
+ * True when the sync bundle exists and resolves, without throwing. After a
+ * prompt-bearing failure (e.g. a cancelled Touch ID) it returns false without
+ * re-reading the keychain for RESOLVE_RETRY_COOLDOWN_MS, so a dismissed prompt
+ * does not re-storm every cycle. `now` is injectable for tests.
+ */
+export declare function isSyncConfigured(now?: number): boolean;
 /**
  * This machine's stable, human-readable id, used as its R2 prefix and mirror
  * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already

package/dist/lib/session/sync/config.js

@@ -12,7 +12,7 @@ export const SYNC_BUNDLE = 'r2.backups';
  * actionable error if the bundle or any key is missing — sync cannot proceed
  * without real credentials (no silent fallback).
  */
-export function loadR2Config() {
+function resolveR2Config() {
     const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync' });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
@@ -36,13 +36,60 @@ export function loadR2Config() {
         endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
     };
 }
-/** True when the sync bundle exists and looks resolvable, without throwing. */
-export function isSyncConfigured() {
+// ── Resolution cache ────────────────────────────────────────────────────────
+// The daemon calls isSyncConfigured() + syncSessions() every ~90s, and each used
+// to trigger a fresh read of the biometry-gated `r2.backups` keychain items —
+// one Touch ID prompt per gated item, every cycle, forever. We instead resolve
+// at most once per process: a success is memoized for the process lifetime
+// (cleared on daemon SIGHUP via clearR2ConfigCache), so subsequent cycles never
+// touch the keychain again. A *prompt-bearing* failure (cancelled Touch ID, etc.)
+// starts a cooldown so a dismissed prompt is not re-issued every cycle. A simply
+// absent bundle never prompts, so it is re-checked each cycle (fast pickup when
+// the user later adds credentials).
+let cachedConfig = null;
+let lastPromptFailureAt = 0;
+/** Window after a prompt-bearing resolution failure during which we skip
+ *  re-attempting (and thus re-prompting). SIGHUP / restart bypasses it. */
+export const RESOLVE_RETRY_COOLDOWN_MS = 30 * 60 * 1000; // 30 minutes
+/** Drop the cached resolution so the next call reads the bundle fresh. Called on
+ *  daemon SIGHUP (to pick up rotated credentials) and between tests. */
+export function clearR2ConfigCache() {
+    cachedConfig = null;
+    lastPromptFailureAt = 0;
+}
+/**
+ * Resolve R2 credentials, reading the keychain at most once per process. The
+ * first call reads (and may prompt for Touch ID); every later call returns the
+ * memoized result. Throws if the bundle/keys are missing — failures are not
+ * memoized, but see isSyncConfigured for the re-prompt cooldown.
+ */
+export function loadR2Config() {
+    if (cachedConfig)
+        return cachedConfig;
+    cachedConfig = resolveR2Config();
+    return cachedConfig;
+}
+/**
+ * True when the sync bundle exists and resolves, without throwing. After a
+ * prompt-bearing failure (e.g. a cancelled Touch ID) it returns false without
+ * re-reading the keychain for RESOLVE_RETRY_COOLDOWN_MS, so a dismissed prompt
+ * does not re-storm every cycle. `now` is injectable for tests.
+ */
+export function isSyncConfigured(now = Date.now()) {
+    if (cachedConfig)
+        return true;
+    if (lastPromptFailureAt && now - lastPromptFailureAt < RESOLVE_RETRY_COOLDOWN_MS)
+        return false;
     try {
         loadR2Config();
         return true;
     }
-    catch {
+    catch (err) {
+        // A missing bundle never prompts, so keep re-checking it each cycle (so a
+        // later `agents secrets add` is picked up quickly). Any other failure may
+        // have cost a prompt (cancelled Touch ID, keychain error) — back off.
+        if (!/not found/i.test(err.message))
+            lastPromptFailureAt = now;
         return false;
     }
 }

package/dist/lib/versions.d.ts

@@ -176,6 +176,26 @@ export declare function installVersion(agent: AgentId, version: string, onProgre
     installedVersion: string;
     error?: string;
 }>;
+/**
+ * Fold a stale literal `latest` version dir into the real resolved version.
+ *
+ * Script-installed agents (droid, grok) have no npm package to read a version
+ * from, so the installer resolves the version by probing `<cli> --version`
+ * after the install script runs. When that probe failed (3s timeout, or the
+ * freshly-dropped binary not yet resolvable on PATH) the installer fell back to
+ * the literal string `latest`, creating a `versions/<agent>/latest/` dir. A
+ * later install where the probe succeeded then created a SECOND dir at the real
+ * semver, orphaning `latest` — and because these agents' getBinaryPath points
+ * at a single global binary regardless of version dir, `latest` keeps showing
+ * up in `agents view` next to the real version forever.
+ *
+ * Call this once the install path has resolved a real version: if a stale
+ * `latest` dir exists, rename it onto the real version (preserving `home/`), or
+ * if the real dir already exists, soft-delete the `latest` dir to trash. No-op
+ * when nothing was resolved or no stale dir is present, so it is safe to call
+ * on every script-based install. Returns the action taken (for tests/logging).
+ */
+export declare function reconcileStaleLatestDir(agent: AgentId, installedVersion: string): Promise<'none' | 'renamed' | 'trashed'>;
 /**
  * Soft-delete a version directory by moving it to ~/.agents/.system/trash/versions/.
  * Returns the trash path on success or null on failure / no source.

package/dist/lib/versions.js

@@ -996,6 +996,9 @@ export async function installVersion(agent, version, onProgress) {
             await execAsync(script, { timeout: 120000 });
             if (version === 'latest') {
                 installedVersion = await getCliVersionFromPath(agent) || version;
+                // Fold any stale literal `latest` dir from an earlier probe-failed
+                // install into the real version so it stops shadowing `agents view`.
+                await reconcileStaleLatestDir(agent, installedVersion);
             }
             onProgress?.(`${agentConfig.name} installed. Setting up agents-cli version home for isolation...`);
         }
@@ -1158,6 +1161,51 @@ function removeInstallArtifacts(versionDir) {
         fs.rmSync(path.join(versionDir, entry), { recursive: true, force: true });
     }
 }
+/**
+ * Fold a stale literal `latest` version dir into the real resolved version.
+ *
+ * Script-installed agents (droid, grok) have no npm package to read a version
+ * from, so the installer resolves the version by probing `<cli> --version`
+ * after the install script runs. When that probe failed (3s timeout, or the
+ * freshly-dropped binary not yet resolvable on PATH) the installer fell back to
+ * the literal string `latest`, creating a `versions/<agent>/latest/` dir. A
+ * later install where the probe succeeded then created a SECOND dir at the real
+ * semver, orphaning `latest` — and because these agents' getBinaryPath points
+ * at a single global binary regardless of version dir, `latest` keeps showing
+ * up in `agents view` next to the real version forever.
+ *
+ * Call this once the install path has resolved a real version: if a stale
+ * `latest` dir exists, rename it onto the real version (preserving `home/`), or
+ * if the real dir already exists, soft-delete the `latest` dir to trash. No-op
+ * when nothing was resolved or no stale dir is present, so it is safe to call
+ * on every script-based install. Returns the action taken (for tests/logging).
+ */
+export async function reconcileStaleLatestDir(agent, installedVersion) {
+    if (installedVersion === 'latest')
+        return 'none';
+    const staleLatestDir = getVersionDir(agent, 'latest');
+    const realVersionDir = getVersionDir(agent, installedVersion);
+    if (staleLatestDir === realVersionDir || !fs.existsSync(staleLatestDir)) {
+        return 'none';
+    }
+    if (!fs.existsSync(realVersionDir)) {
+        fs.renameSync(staleLatestDir, realVersionDir);
+        return 'renamed';
+    }
+    // Both dirs exist. Stripping install artifacts would not hide `latest` for
+    // global-binary agents (getBinaryPath ignores dir contents), so the whole
+    // dir must go. Soft-delete to trash so any `home/` data stays recoverable
+    // via `agents restore <agent>@latest`, then rewrite session file paths to
+    // point at the trashed location so history stays readable. The session-db
+    // module is imported lazily — it carries a top-level await that the CJS test
+    // harness can't statically transform, so it must stay out of the eager graph.
+    const trashPath = softDeleteVersionDir(agent, 'latest');
+    if (trashPath) {
+        const { updateSessionFilePaths } = await import('./session/db.js');
+        updateSessionFilePaths(staleLatestDir, trashPath);
+    }
+    return 'trashed';
+}
 /**
  * Soft-delete a version directory by moving it to ~/.agents/.system/trash/versions/.
  * Returns the trash path on success or null on failure / no source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.19",
+  "version": "1.20.21",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",