@phnx-labs/agents-cli 1.20.57 → 1.20.58

package/dist/lib/teams/agents.js

@@ -27,7 +27,7 @@ import { recordRunName } from '../session/run-names.js';
 import { sshExec, shellQuote } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
 import { sshTargetFor } from '../hosts/types.js';
-import { dispatchAgentsCommand } from '../hosts/dispatch.js';
+import { dispatchAgentsCommand, terminateDispatchedTask } from '../hosts/dispatch.js';
 import { ensureHostReady } from '../hosts/ready.js';
 import { remoteShellFor } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
@@ -746,6 +746,16 @@ export class AgentProcess {
             }
         }
     }
+    /** Reset the local stdout cursor for a newly truncated resume log. */
+    resetLogReadPosition() {
+        const previous = this.lastReadPos;
+        this.lastReadPos = 0;
+        return previous;
+    }
+    /** Restore the cursor when a resume transaction puts the prior log back. */
+    restoreLogReadPosition(position) {
+        this.lastReadPos = position;
+    }
     async readNewEvents() {
         // Distributed teammate: mirror the host's new log bytes locally first, then
         // fall through to the identical local read+parse below.
@@ -1107,6 +1117,62 @@ export class AgentProcess {
         }
     }
 }
+export async function beginResumeLogTransaction(agent) {
+    const stdoutPath = await agent.getStdoutPath();
+    const backupPath = `${stdoutPath}.resume-backup-${randomUUID()}`;
+    let hadOriginal = false;
+    try {
+        await fs.rename(stdoutPath, backupPath);
+        hadOriginal = true;
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    const previousReadPos = agent.resetLogReadPosition();
+    return { agent, stdoutPath, backupPath, hadOriginal, previousReadPos };
+}
+export async function commitResumeLogTransaction(transaction) {
+    if (transaction.hadOriginal)
+        await fs.rm(transaction.backupPath, { force: true });
+}
+async function rollbackResumeLogTransaction(transaction) {
+    try {
+        await fs.rm(transaction.stdoutPath, { force: true });
+        if (transaction.hadOriginal) {
+            await fs.rename(transaction.backupPath, transaction.stdoutPath);
+        }
+    }
+    finally {
+        transaction.agent.restoreLogReadPosition(transaction.previousReadPos);
+    }
+}
+export async function terminateSpawnedProcess(pid) {
+    try {
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch (err) {
+        if (err?.code === 'ESRCH')
+            return;
+        throw err;
+    }
+    await new Promise(resolve => setTimeout(resolve, 250));
+    try {
+        process.kill(-pid, 0);
+    }
+    catch (err) {
+        if (err?.code === 'ESRCH')
+            return;
+        throw err;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch (err) {
+        if (err?.code !== 'ESRCH')
+            throw err;
+    }
+}
 export class AgentManager {
     agents = new Map();
     maxAgents;
@@ -1402,16 +1468,42 @@ export class AgentManager {
                 `(it may have failed before its first turn). Start a fresh teammate instead.`);
         }
         const resume = { id: agent.remoteSessionId ?? agent.agentId, message };
+        const priorRuntime = {
+            status: agent.status,
+            completedAt: agent.completedAt,
+            pid: agent.pid,
+            startTime: agent.startTime,
+            startedAt: agent.startedAt,
+            remotePid: agent.remotePid,
+            remoteLog: agent.remoteLog,
+            remoteExit: agent.remoteExit,
+            remoteLogOffset: agent.remoteLogOffset,
+            worktreePath: agent.worktreePath,
+        };
         // Flip to RUNNING up front so a concurrent status poll can't reap the
         // teammate between the exit-sentinel clear and the new PID landing; the
-        // launch re-persists with the fresh pid/startTime.
+        // launch re-persists with the fresh pid/startTime. If relaunch fails before
+        // that happens, restore the stopped lifecycle state and keep its existing
+        // metadata/log directory intact so the user can retry.
         agent.status = AgentStatus.RUNNING;
         agent.completedAt = null;
-        if (agent.hostName) {
-            await this.launchRemoteProcess(agent, resume);
+        try {
+            if (agent.hostName) {
+                await this.launchRemoteProcess(agent, resume);
+            }
+            else {
+                await this.launchProcess(agent, resume);
+            }
         }
-        else {
-            await this.launchProcess(agent, resume);
+        catch (err) {
+            Object.assign(agent, priorRuntime);
+            try {
+                await agent.saveMeta();
+            }
+            catch (restoreErr) {
+                throw new Error(`Failed to resume teammate: ${err.message}; restoring stopped state also failed: ${restoreErr.message}`, { cause: err });
+            }
+            throw err;
         }
         return agent;
     }
@@ -1429,8 +1521,13 @@ export class AgentManager {
         const resolvedModel = agent.model ?? null;
         const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName, resume);
         debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]${resume ? ' (resume)' : ''}: ${cmd.slice(0, 3).join(' ')}...`);
+        let childProcess = null;
+        let stdoutFile = null;
+        let resumeLog = null;
         try {
-            const stdoutPath = await agent.getStdoutPath();
+            if (resume)
+                resumeLog = await beginResumeLogTransaction(agent);
+            const stdoutPath = resumeLog?.stdoutPath ?? await agent.getStdoutPath();
             // Always TRUNCATE — including on resume. The status reader re-reads the
             // whole log from byte 0 every poll (lastReadPos is in-memory, not
             // persisted) and marks terminal status from the last `result` event it
@@ -1441,7 +1538,7 @@ export class AgentManager {
             // a forked session. Truncating keeps exactly one turn in the log, so the
             // re-read is always correct. The authoritative transcript lives in the
             // agent's own session (resumed via --resume), not this stdout mirror.
-            const stdoutFile = await fs.open(stdoutPath, 'w');
+            stdoutFile = await fs.open(stdoutPath, 'w');
             const stdoutFd = stdoutFile.fd;
             // Wrap the teammate command in a shell that records the underlying CLI's
             // exit code to a sentinel file. Detached + unref()'d children can't be
@@ -1455,7 +1552,7 @@ export class AgentManager {
             const wrappedCmd = buildSentinelCommand(cmd, exitCodePath);
             // detached:true makes the shell the process-group leader, so stop()'s
             // `kill(-pid)` still reaches the underlying CLI through the group.
-            const childProcess = spawn('/bin/sh', ['-c', wrappedCmd], {
+            childProcess = spawn('/bin/sh', ['-c', wrappedCmd], {
                 stdio: ['ignore', stdoutFd, stdoutFd],
                 cwd: agent.cwd || undefined,
                 detached: true,
@@ -1463,8 +1560,13 @@ export class AgentManager {
                     ? { ...sanitizeProcessEnv(process.env), ...agent.envOverrides }
                     : sanitizeProcessEnv(process.env),
             });
+            await new Promise((resolve, reject) => {
+                childProcess.once('spawn', resolve);
+                childProcess.once('error', reject);
+            });
             childProcess.unref();
-            stdoutFile.close().catch(() => { });
+            await stdoutFile.close();
+            stdoutFile = null;
             agent.pid = childProcess.pid || null;
             // Capture start-time NOW, while we know the PID is ours. Once the
             // OS reuses this PID slot, /proc and `ps` will report a different
@@ -1474,9 +1576,21 @@ export class AgentManager {
             agent.status = AgentStatus.RUNNING;
             agent.startedAt = new Date();
             await agent.saveMeta();
+            if (resumeLog)
+                await commitResumeLogTransaction(resumeLog);
         }
         catch (err) {
-            await this.cleanupPartialAgent(agent);
+            if (stdoutFile)
+                await stdoutFile.close().catch(() => { });
+            if (childProcess?.pid)
+                await terminateSpawnedProcess(childProcess.pid);
+            if (resumeLog)
+                await rollbackResumeLogTransaction(resumeLog);
+            // Fresh spawns own a newly-created directory, so a failed launch removes
+            // that partial record. A resume reuses an existing teammate: its caller
+            // restores the prior terminal state and preserves the directory for retry.
+            if (!resume)
+                await this.cleanupPartialAgent(agent);
             console.error(`Failed to spawn agent ${agent.agentId}:`, err);
             throw new Error(`Failed to spawn agent: ${err.message}`);
         }
@@ -1535,12 +1649,19 @@ export class AgentManager {
         // — the supervisor polls the host, we don't block here.
         const effort = agent.effort ?? 'medium';
         const forwardedArgs = this.buildRunArgv(agent.agentType, agent.prompt, agent.mode, agent.model ?? null, effort, agent.version, agent.profileName, resume);
+        let dispatchedTask = null;
+        let resumeLog = null;
         try {
+            if (resume) {
+                resumeLog = await beginResumeLogTransaction(agent);
+                await fs.writeFile(resumeLog.stdoutPath, '');
+            }
             const { task } = await dispatchAgentsCommand(host, {
                 forwardedArgs,
                 remoteCwd,
                 follow: false,
             });
+            dispatchedTask = task;
             agent.remotePid = task.pid ?? null;
             agent.remoteLog = task.remoteLog ?? null;
             agent.remoteExit = task.remoteExit ?? null;
@@ -1549,15 +1670,34 @@ export class AgentManager {
             // syncRemoteMirror appends the delta onto the local mirror. Truncate that
             // mirror first so the prior turn's terminal event can't linger and get
             // re-read as the current status (same hazard the local path truncates for).
-            if (resume) {
-                await fs.writeFile(await agent.getStdoutPath(), '').catch(() => { });
-            }
             agent.status = AgentStatus.RUNNING;
             agent.startedAt = new Date();
             await agent.saveMeta();
+            if (resumeLog)
+                await commitResumeLogTransaction(resumeLog);
         }
         catch (err) {
+            let cleanupError = null;
+            if (dispatchedTask) {
+                try {
+                    terminateDispatchedTask(dispatchedTask);
+                }
+                catch (cleanupErr) {
+                    cleanupError = cleanupErr;
+                }
+            }
+            if (resumeLog) {
+                try {
+                    await rollbackResumeLogTransaction(resumeLog);
+                }
+                catch (cleanupErr) {
+                    cleanupError = cleanupError ?? cleanupErr;
+                }
+            }
             console.error(`Failed to launch remote teammate ${agent.agentId} on ${agent.hostName}:`, err);
+            if (cleanupError) {
+                throw new Error(`Failed to launch remote teammate: ${err.message}; cleanup failed: ${cleanupError.message}`, { cause: err });
+            }
             throw new Error(`Failed to launch remote teammate: ${err.message}`);
         }
         debug(`Launched remote agent ${agent.agentId} on ${agent.hostName} (remote pid ${agent.remotePid})`);
@@ -1910,17 +2050,13 @@ export class AgentManager {
         if (!agent) {
             return false;
         }
-        // Distributed teammate: no local PID — signal it over SSH. Try the process
-        // GROUP first (negative pid, matching local `kill(-pid)`) to catch the
-        // detached `agents run` and its children; but the remote launcher is
-        // `nohup bash -lc … &` under a non-interactive shell where job control is off,
-        // so `&` may NOT open a new group — fall back to signalling the wrapper pid
-        // directly. Best-effort either way; the `.exit` sentinel is the durable
-        // terminal-status source if a grandchild lingers.
+        // Distributed teammate: no local PID — signal the dedicated process group
+        // created by dispatch.ts. The persisted PID is the group leader, so one
+        // negative-PID signal reaches the login-shell wrapper and every descendant.
         if (agent.hostName && agent.status === AgentStatus.RUNNING) {
             if (agent.hostTarget && agent.remotePid) {
                 try {
-                    sshExec(agent.hostTarget, `kill -TERM -- -${agent.remotePid} 2>/dev/null || kill -TERM ${agent.remotePid} 2>/dev/null`, {
+                    sshExec(agent.hostTarget, `kill -TERM -- -${agent.remotePid} 2>/dev/null`, {
                         timeoutMs: 10000,
                         multiplex: true,
                     });

package/dist/lib/types.d.ts

@@ -643,6 +643,12 @@ export interface Meta {
     registries?: Record<RegistryType, Record<string, RegistryConfig>>;
     versions?: Partial<Record<AgentId, Record<string, VersionResources>>>;
     source?: string;
+    /**
+     * Projects root for the `agents run --project <slug>` shorthand, e.g.
+     * `~/src/github.com/<user>`. Auto-inferred from the repo you launch inside and
+     * cached here; stored home-relative (`~/…`) so it resolves on remote hosts too.
+     */
+    projectRoot?: string;
     /**
      * Extra DotAgent repos merged after ~/.agents/. Managed clones live as peer
      * dirs at ~/.agents-<alias>/; user-owned repos can point at arbitrary paths
@@ -771,6 +777,13 @@ export interface ClaudePermissions {
         additionalDirectories?: string[];
     };
 }
+/** Cursor CLI native format in ~/.cursor/cli-config.json (Shell/Read/Write/WebFetch/Mcp). */
+export interface CursorPermissions {
+    permissions: {
+        allow: string[];
+        deny: string[];
+    };
+}
 /** OpenCode's native permission format (per-command allow/deny/ask). */
 export interface OpenCodePermissions {
     permission: {

package/dist/lib/versions.d.ts

@@ -114,6 +114,41 @@ export declare function getVersionDir(agent: AgentId, version: string): string;
  * Get the binary path for a specific agent version.
  */
 export declare function getBinaryPath(agent: AgentId, version: string): string;
+/**
+ * Does this agent resolve to ONE global binary that is the same file regardless
+ * of the `version` argument? (droid → always `~/.local/bin/droid`.) Computed
+ * generically by probing `getBinaryPath` with two distinct versions rather than
+ * hardcoding an agent id, so it stays correct if another global-binary agent is
+ * added.
+ *
+ * This is the narrower cousin of `isSelfUpdatingAgent`: every global-binary
+ * agent is self-updating, but grok is self-updating WITHOUT a global binary — it
+ * stores a real per-version binary copy under each version-home
+ * (`versions/grok/<v>/home/.grok/downloads/grok-<v>`), so its version-homes are
+ * genuinely distinct and must NOT be collapsed. Gate the single-binary
+ * collapse/live-version logic on THIS predicate; gate pin-refusal / "switch
+ * profile" copy on `isSelfUpdatingAgent`.
+ */
+export declare function isGlobalBinaryAgent(agent: AgentId): boolean;
+/** Drop the live-version cache (call after an install/remove that changes the
+ * running binary, e.g. `agents add droid@latest`). */
+export declare function invalidateLiveVersionCache(agent?: AgentId): void;
+/**
+ * Resolve the version the ONE globally-installed binary actually reports via
+ * `<cli> --version`, cached for {@link LIVE_VERSION_TTL_MS}. For a self-updating
+ * global-binary agent (droid) this is the single source of truth for "which
+ * version is installed" — the on-disk version-dir NAMES are just stale labels
+ * left behind by successive `agents add`/self-update cycles. Returns null when
+ * the binary isn't on PATH or the probe fails.
+ */
+export declare function getLiveVersion(agent: AgentId): Promise<string | null>;
+/**
+ * Synchronous, non-blocking read of the live-version cache — returns the value
+ * only if a recent {@link getLiveVersion} call already warmed it, else null.
+ * `listInstalledVersions` is sync and must not shell out, so it prefers this
+ * warm value (accurate) and otherwise falls back to the newest on-disk dir.
+ */
+export declare function getCachedLiveVersion(agent: AgentId): string | null;
 /**
  * Get the isolated HOME directory for a specific agent version.
  * Each version has its own config isolation (like jobs sandbox).
@@ -155,6 +190,10 @@ export declare function isOldestInstalled(agent: AgentId): Promise<{
 export declare function invalidateInstalledVersionsCache(agent?: AgentId): void;
 /**
  * List all installed versions for an agent (cached by versions-dir mtime).
+ *
+ * For a self-updating global-binary agent (droid) every version dir resolves to
+ * the SAME binary, so this collapses them to a single canonical entry — one
+ * install, one row in `agents view`, never the phantom set of semver dir names.
  */
 export declare function listInstalledVersions(agent: AgentId): string[];
 /**

package/dist/lib/versions.js

@@ -28,7 +28,7 @@ import { listResources } from './resources.js';
 // (single source of truth). Re-exported below so existing importers of
 // `compareVersions` from './versions.js' keep working.
 import { VERSION_RE, compareVersions } from './agent-spec/primitives.js';
-import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath } from './agents.js';
+import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath, isSelfUpdatingAgent } from './agents.js';
 import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { parseMcpServerConfig } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
@@ -835,6 +835,65 @@ export function getBinaryPath(agent, version) {
     const versionDir = getVersionDir(agent, version);
     return path.join(versionDir, 'node_modules', '.bin', agentConfig.cliCommand);
 }
+/**
+ * Does this agent resolve to ONE global binary that is the same file regardless
+ * of the `version` argument? (droid → always `~/.local/bin/droid`.) Computed
+ * generically by probing `getBinaryPath` with two distinct versions rather than
+ * hardcoding an agent id, so it stays correct if another global-binary agent is
+ * added.
+ *
+ * This is the narrower cousin of `isSelfUpdatingAgent`: every global-binary
+ * agent is self-updating, but grok is self-updating WITHOUT a global binary — it
+ * stores a real per-version binary copy under each version-home
+ * (`versions/grok/<v>/home/.grok/downloads/grok-<v>`), so its version-homes are
+ * genuinely distinct and must NOT be collapsed. Gate the single-binary
+ * collapse/live-version logic on THIS predicate; gate pin-refusal / "switch
+ * profile" copy on `isSelfUpdatingAgent`.
+ */
+export function isGlobalBinaryAgent(agent) {
+    return getBinaryPath(agent, '0.0.0-probe-a') === getBinaryPath(agent, '0.0.0-probe-b');
+}
+// Live-version cache for self-updating global binaries. `<cli> --version` is a
+// ~real shell-out, so hold the result briefly: the same `agents view` render
+// asks for it from both listInstalledVersions (sync) and the label path (async).
+const LIVE_VERSION_TTL_MS = 5000;
+const liveVersionCache = new Map();
+/** Drop the live-version cache (call after an install/remove that changes the
+ * running binary, e.g. `agents add droid@latest`). */
+export function invalidateLiveVersionCache(agent) {
+    if (agent)
+        liveVersionCache.delete(agent);
+    else
+        liveVersionCache.clear();
+}
+/**
+ * Resolve the version the ONE globally-installed binary actually reports via
+ * `<cli> --version`, cached for {@link LIVE_VERSION_TTL_MS}. For a self-updating
+ * global-binary agent (droid) this is the single source of truth for "which
+ * version is installed" — the on-disk version-dir NAMES are just stale labels
+ * left behind by successive `agents add`/self-update cycles. Returns null when
+ * the binary isn't on PATH or the probe fails.
+ */
+export async function getLiveVersion(agent) {
+    const cached = liveVersionCache.get(agent);
+    if (cached && Date.now() - cached.at < LIVE_VERSION_TTL_MS)
+        return cached.version;
+    const version = await getCliVersionFromPath(agent);
+    liveVersionCache.set(agent, { at: Date.now(), version });
+    return version;
+}
+/**
+ * Synchronous, non-blocking read of the live-version cache — returns the value
+ * only if a recent {@link getLiveVersion} call already warmed it, else null.
+ * `listInstalledVersions` is sync and must not shell out, so it prefers this
+ * warm value (accurate) and otherwise falls back to the newest on-disk dir.
+ */
+export function getCachedLiveVersion(agent) {
+    const cached = liveVersionCache.get(agent);
+    if (cached && Date.now() - cached.at < LIVE_VERSION_TTL_MS)
+        return cached.version;
+    return null;
+}
 /**
  * Get the isolated HOME directory for a specific agent version.
  * Each version has its own config isolation (like jobs sandbox).
@@ -970,8 +1029,43 @@ export function invalidateInstalledVersionsCache(agent) {
     else
         installedVersionsCache.clear();
 }
+/**
+ * Choose the single canonical version-dir to represent a self-updating
+ * global-binary agent (droid). All its version dirs map to ONE binary, so
+ * exactly one is real; the rest are stale labels. Prefer, in order: the dir the
+ * live config symlink points at (what actually runs), the recorded global
+ * default, the live `--version` (when the cache is warm), else the newest dir.
+ * `versions` MUST be sorted ascending. Callers guarantee it is non-empty.
+ */
+function pickCanonicalGlobalBinaryVersion(agent, versions) {
+    const symlinkVersion = getConfigSymlinkVersion(agent);
+    if (symlinkVersion && versions.includes(symlinkVersion))
+        return symlinkVersion;
+    const globalDefault = getGlobalDefault(agent);
+    if (globalDefault && versions.includes(globalDefault))
+        return globalDefault;
+    const live = getCachedLiveVersion(agent);
+    if (live && versions.includes(live))
+        return live;
+    return versions[versions.length - 1];
+}
+/**
+ * Collapse a global-binary agent's phantom version dirs to the single canonical
+ * one (see {@link pickCanonicalGlobalBinaryVersion}). No-op for npm-packaged and
+ * per-version agents (claude/codex/grok/…), whose version dirs are genuinely
+ * distinct installs.
+ */
+function collapseGlobalBinaryVersions(agent, versions) {
+    if (!isGlobalBinaryAgent(agent) || versions.length === 0)
+        return versions;
+    return [pickCanonicalGlobalBinaryVersion(agent, versions)];
+}
 /**
  * List all installed versions for an agent (cached by versions-dir mtime).
+ *
+ * For a self-updating global-binary agent (droid) every version dir resolves to
+ * the SAME binary, so this collapses them to a single canonical entry — one
+ * install, one row in `agents view`, never the phantom set of semver dir names.
  */
 export function listInstalledVersions(agent) {
     const agentVersionsDir = path.join(getVersionsDir(), agent);
@@ -985,7 +1079,9 @@ export function listInstalledVersions(agent) {
     }
     const cached = installedVersionsCache.get(agent);
     if (cached && cached.stamp === stamp) {
-        return cached.versions;
+        // Collapse is applied per-call (not cached): it depends on the live-version
+        // cache + config symlink, which can change without the versions-dir mtime.
+        return collapseGlobalBinaryVersions(agent, cached.versions);
     }
     const entries = fs.readdirSync(agentVersionsDir, { withFileTypes: true });
     const versions = [];
@@ -1001,7 +1097,7 @@ export function listInstalledVersions(agent) {
     }
     versions.sort(compareVersions);
     installedVersionsCache.set(agent, { stamp, versions });
-    return versions;
+    return collapseGlobalBinaryVersions(agent, versions);
 }
 /**
  * List every version directory for an agent, including ones missing the
@@ -1067,18 +1163,31 @@ export async function installVersion(agent, version, onProgress, opts) {
         if (!agentConfig.installScript) {
             return { success: false, installedVersion: version, error: 'Agent has no npm package' };
         }
-        if (version !== 'latest' && !agentConfig.installScript.includes('VERSION')) {
-            return {
-                success: false,
-                installedVersion: version,
-                error: `${agentConfig.name} installer does not support version-pinned installs. Use ${agent}@latest.`,
-            };
+        // A self-updating agent (droid, grok, …) is a single global binary whose
+        // installer only ever fetches the CURRENT release — there is no semver to
+        // pin. Rather than hard-refuse `<agent>@1.2.3` (the old behavior):
+        //   - if the binary is already installed, a pin is a no-op — it self-updates
+        //     in place, so skip the installer and just refresh our bookkeeping;
+        //   - otherwise redirect the pin to a current-release install.
+        let runInstaller = true;
+        if (version !== 'latest' && isSelfUpdatingAgent(agent)) {
+            const liveVersion = await getLiveVersion(agent);
+            if (liveVersion) {
+                onProgress?.(`${agentConfig.name} is a single self-updating binary — @${version} maps to the already-installed current release (${liveVersion}); nothing to install.`);
+                runInstaller = false;
+            }
+            else {
+                onProgress?.(`${agentConfig.name} is a single self-updating binary with no pinnable versions — installing the current release (ignoring @${version}).`);
+            }
+            version = 'latest';
         }
         let installedVersion = version;
         try {
-            const script = agentConfig.installScript.replaceAll('VERSION', version);
-            onProgress?.(`Installing ${agentConfig.name}@${version} via official installer...`);
-            await execAsync(script, { timeout: 120000 });
+            if (runInstaller) {
+                const script = agentConfig.installScript.replaceAll('VERSION', version);
+                onProgress?.(`Installing ${agentConfig.name}@${version} via official installer...`);
+                await execAsync(script, { timeout: 120000 });
+            }
             if (version === 'latest') {
                 installedVersion = await getCliVersionFromPath(agent) || version;
                 // Fold any stale literal `latest` dir from an earlier probe-failed
@@ -1125,6 +1234,9 @@ export async function installVersion(agent, version, onProgress, opts) {
                correctly reports it uninstalled. */
         }
         createVersionedAlias(agent, installedVersion);
+        // The self-updating binary just changed on disk — drop the cached
+        // `--version` so `agents view` reflects the freshly-installed release.
+        invalidateLiveVersionCache(agent);
         emit('version.install', { agent, version: installedVersion });
         return { success: true, installedVersion };
     }
@@ -1319,6 +1431,13 @@ function removeInstallArtifacts(versionDir) {
  * renaming that dir would dangle the live symlink.
  */
 export async function reconcileStaleLatestForAgent(agent) {
+    // Global-binary agents (droid) can accumulate MANY stale semver dirs — not
+    // just a literal `latest` — because every `agents add` after an in-place
+    // self-update creates a fresh dir for the same one binary. Fold them all.
+    if (isGlobalBinaryAgent(agent)) {
+        await reconcileGlobalBinaryVersions(agent);
+        return;
+    }
     if (!fs.existsSync(getVersionDir(agent, 'latest')))
         return;
     if (getConfigSymlinkVersion(agent) === 'latest')
@@ -1328,6 +1447,74 @@ export async function reconcileStaleLatestForAgent(agent) {
         await reconcileStaleLatestDir(agent, concrete);
     }
 }
+/**
+ * Fold every stale version-dir of a global-binary agent (droid) into the single
+ * canonical survivor. All its dirs point at ONE binary, so the extras — left by
+ * successive `agents add` + in-place self-updates, and by probe-failed installs
+ * that created a literal `latest` dir — are phantom labels. Soft-delete each
+ * non-survivor dir (its `home/` stays recoverable via `agents restore`) so disk
+ * converges to a single install matching what `agents view` shows.
+ *
+ * Survivor selection matches listInstalledVersions' canonical choice
+ * (config-symlink target → global default → live version → newest). The survivor
+ * is NOT renamed: droid's ~/.factory symlink points inside its home, and the
+ * live version label is surfaced by the view renderer via getLiveVersion.
+ */
+async function reconcileGlobalBinaryVersions(agent) {
+    // Step 1 — preserve the original literal-`latest` reconcile: a probe-failed
+    // install leaves a `versions/<agent>/latest/` dir; fold it onto the concrete
+    // live version (rename if that dir is absent, else trash). Skipped while the
+    // config symlink still points at `latest` (renaming would dangle it).
+    if (fs.existsSync(getVersionDir(agent, 'latest')) && getConfigSymlinkVersion(agent) !== 'latest') {
+        const concrete = await getCliVersionFromPath(agent);
+        if (concrete && concrete !== 'latest') {
+            await reconcileStaleLatestDir(agent, concrete);
+        }
+    }
+    // Step 2 — collapse any remaining phantom SEMVER dirs (successive `agents add`
+    // after in-place self-updates) into a single survivor.
+    const agentVersionsDir = path.join(getVersionsDir(), agent);
+    let entries;
+    try {
+        entries = fs.readdirSync(agentVersionsDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort(compareVersions);
+    if (dirs.length <= 1)
+        return;
+    // Warm the live-version cache so the survivor pick (and later view labels) can
+    // prefer the version the binary actually reports.
+    await getLiveVersion(agent);
+    const survivor = pickCanonicalGlobalBinaryVersion(agent, dirs);
+    const symlinkVersion = getConfigSymlinkVersion(agent);
+    let foldedAny = false;
+    for (const version of dirs) {
+        if (version === survivor)
+            continue;
+        // Never trash the dir the live config symlink points at — that would dangle
+        // the symlink. pickCanonical already prefers it as survivor; this guards the
+        // rare mismatch.
+        if (version === symlinkVersion)
+            continue;
+        const staleDir = getVersionDir(agent, version);
+        const trashPath = softDeleteVersionDir(agent, version);
+        if (trashPath) {
+            const { updateSessionFilePaths } = await import('./session/db.js');
+            updateSessionFilePaths(staleDir, trashPath);
+            foldedAny = true;
+        }
+    }
+    if (foldedAny) {
+        invalidateInstalledVersionsCache(agent);
+        // Keep the recorded default pointing at a dir that still exists on disk.
+        const def = getGlobalDefault(agent);
+        if (!def || !fs.existsSync(getVersionDir(agent, def))) {
+            setGlobalDefault(agent, survivor);
+        }
+    }
+}
 export async function reconcileStaleLatestDir(agent, installedVersion) {
     if (installedVersion === 'latest')
         return 'none';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.57",
+  "version": "1.20.58",
   "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",