@phnx-labs/agents-cli 1.20.56 → 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;
@@ -1357,11 +1423,95 @@ export class AgentManager {
         await this.cleanupOldAgents();
         return agent;
     }
+    /**
+     * Resume a STOPPED teammate (completed / failed / stopped) by re-entering its
+     * own session with `message` as the next user turn. Re-launches through the
+     * SAME backend the teammate first used (local process or remote host), reusing
+     * its stored cwd / worktree / host / version / model / effort, and flips it
+     * back to RUNNING so the team tracks it live again.
+     *
+     * The resume target is the teammate's underlying agent session id: for Claude
+     * that IS its agent_id (unified identity, pinned via --session-id at first
+     * launch); other harnesses only expose their session/thread id after their
+     * first stream event, captured as `remoteSessionId`.
+     *
+     * Callers branch on status first — a RUNNING teammate is steered via its
+     * mailbox, never re-launched — so this method assumes a non-running teammate.
+     */
+    async resumeTeammate(agentId, message) {
+        await this.initialize();
+        const agent = await this.get(agentId);
+        if (!agent)
+            throw new Error(`No teammate with id ${agentId}`);
+        const who = agent.name ?? agent.agentId.slice(0, 8);
+        // The message rides as `agents run`'s prompt positional. A leading '-' makes
+        // commander parse it as an (unknown) flag, exiting the child non-zero — the
+        // teammate would silently land FAILED. `--` can't rescue it: `agents run`
+        // treats post-`--` tokens as native passthrough and unsets the prompt. Fail
+        // loud and early instead. (Steer/mailbox delivery has no such limit.)
+        if (message.startsWith('-')) {
+            throw new Error(`Resume message can't start with '-' — \`agents run\` would parse it as a flag. ` +
+                `Rephrase so it leads with a word (e.g. "Please ${message}").`);
+        }
+        // Cloud-backed teammates run on remote provider infrastructure with no local
+        // or host process to re-launch; continuing them goes through the provider.
+        if (agent.cloudProvider) {
+            throw new Error(`Teammate '${who}' is a ${agent.cloudProvider} cloud task — resume it with ` +
+                `\`agents message ${agent.cloudSessionId ?? agent.agentId} "<message>"\` instead.`);
+        }
+        // For non-Claude teammates the agent_id is NOT the harness session id — that
+        // is only known once the agent emitted its first stream event. If it never
+        // did (e.g. it failed before its first turn), there is no resumable handle.
+        if (agent.agentType !== 'claude' && !agent.remoteSessionId) {
+            throw new Error(`No resumable session id was captured for ${agent.agentType} teammate '${who}' — ` +
+                `its session id is discovered from the agent's own output, which never arrived ` +
+                `(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. 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;
+        try {
+            if (agent.hostName) {
+                await this.launchRemoteProcess(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;
+    }
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().
      */
-    async launchProcess(agent) {
+    async launchProcess(agent, resume) {
         const running = await this.listRunning();
         warnIfMemoryLow(running.length);
         const effort = agent.effort ?? 'medium';
@@ -1369,11 +1519,26 @@ export class AgentManager {
         // forwarded). Effort is a separate knob wired into buildReasoningFlags
         // inside buildCommand.
         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);
-        debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]: ${cmd.slice(0, 3).join(' ')}...`);
+        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();
-            const stdoutFile = await fs.open(stdoutPath, 'w');
+            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
+            // sees, with no liveness guard. If the resumed turn's stream were appended
+            // after the prior turn's `result:success`, that stale event would win for
+            // the entire duration of the new (still-running) turn — reporting the
+            // teammate COMPLETED while it works, and steering a second follow-up into
+            // 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.
+            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
@@ -1387,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,
@@ -1395,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
@@ -1406,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}`);
         }
@@ -1424,7 +1606,7 @@ export class AgentManager {
      * created ON THE HOST off the freshly-fetched default branch; the teammate runs
      * there. Otherwise it runs in the host repo path directly.
      */
-    async launchRemoteProcess(agent) {
+    async launchRemoteProcess(agent, resume) {
         if (!agent.hostName || !agent.hostTarget || !agent.repoPath) {
             throw new Error(`Remote teammate ${agent.agentId} is missing host placement (host/target/repo).`);
         }
@@ -1448,33 +1630,74 @@ export class AgentManager {
         }
         // Worktree isolation on the host, if the team enables it. createRemoteWorktree
         // fetches origin and branches off origin/<default>, returning the host path.
+        // On RESUME the worktree already exists from the original launch — reuse it
+        // (its path is persisted) instead of re-creating (which would fail on the
+        // existing branch and would also discard the teammate's in-progress work).
         let remoteCwd = agent.repoPath;
         if (agent.worktreeName) {
-            const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
-            agent.worktreePath = worktreePath;
-            remoteCwd = worktreePath;
+            if (resume && agent.worktreePath) {
+                remoteCwd = agent.worktreePath;
+            }
+            else {
+                const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+                agent.worktreePath = worktreePath;
+                remoteCwd = worktreePath;
+            }
         }
         // Same run argv the local path builds (shared buildRunArgv keeps the prompt
         // scaffolding + flags from drifting); dispatched non-blocking (follow:false)
         // — 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);
+        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;
             agent.remoteLogOffset = 0;
+            // On resume the offset resets to 0 against a FRESH remote log, and
+            // 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).
             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})`);
@@ -1670,38 +1893,46 @@ export class AgentManager {
      * before invoking `agents`. `sessionId` is likewise local-only (the remote run
      * mints its own session on the host).
      */
-    buildRunArgv(agentType, prompt, mode, model, effort, version, profileName) {
-        // Compose the prompt: a plan-mode prefix for Claude (clarifying headless
-        // plan-mode restrictions) and a universal summary suffix. These are
-        // team-specific prompt scaffolding — `agents run` does not apply them.
-        let fullPrompt = prompt + PROMPT_SUFFIX;
-        if (agentType === 'claude' && mode === 'plan') {
-            fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
+    buildRunArgv(agentType, prompt, mode, model, effort, version, profileName, resume) {
+        // Compose the prompt. On RESUME the message is the teammate's next user turn,
+        // not a fresh brief — so skip the original brief and the plan-mode prefix, but
+        // keep PROMPT_SUFFIX so the resumed run still emits a final summary the team
+        // parser reads. On a fresh launch, add the plan-mode prefix for Claude and the
+        // universal summary suffix. These are team-specific prompt scaffolding —
+        // `agents run` does not apply them.
+        let fullPrompt;
+        if (resume) {
+            fullPrompt = resume.message + PROMPT_SUFFIX;
+        }
+        else {
+            fullPrompt = prompt + PROMPT_SUFFIX;
+            if (agentType === 'claude' && mode === 'plan') {
+                fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
+            }
         }
         // Profile target takes precedence — `agents run <profile>` resolves the
         // host harness, version pin, and env injection in one place. Plain
         // version pins only apply when no profile is selected.
         const target = profileName ?? (version ? `${agentType}@${version}` : agentType);
-        const args = [
-            'run',
-            target,
-            fullPrompt,
-            '--mode', mode,
-            '--effort', effort,
-            '--json',
-            '--headless',
-            '--quiet',
-        ];
+        // Keep the prompt as the first positional (right after target), matching the
+        // fresh-launch shape, and add `--resume <id>` among the flags. `agents run`
+        // continues the teammate's own session natively (claude `--resume`, codex
+        // `resume`) or via the universal `/continue` replay for other harnesses.
+        const args = ['run', target, fullPrompt];
+        if (resume) {
+            args.push('--resume', resume.id);
+        }
+        args.push('--mode', mode, '--effort', effort, '--json', '--headless', '--quiet');
         if (model)
             args.push('--model', model);
         args.push('--env', 'AGENTS_RUNTIME=teams');
         return args;
     }
-    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null) {
+    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null, resume) {
         // Route through getAgentsInvocation so a teammate launched by the compiled
         // standalone binary (#315) doesn't relaunch as `agents /$bunfs/root/agents …`
         // (process.argv[1] is the bun virtual entry there) → "unknown command".
-        const inv = getAgentsInvocation(this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName));
+        const inv = getAgentsInvocation(this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName, resume));
         const cmd = [inv.command, ...inv.args];
         if (cwd)
             cmd.push('--cwd', cwd);
@@ -1709,7 +1940,9 @@ export class AgentManager {
         // AGENTS_MAILBOX_DIR by the same id mailboxIdForActiveSession returns.
         // Claude also forwards --session-id to its CLI (unified identity);
         // other agents ignore the flag but still get the correct mailbox dir.
-        if (sessionId) {
+        // On RESUME we continue an existing session — `--session-id` CREATES one and
+        // `agents run` rejects it alongside `--resume`, so it must be omitted.
+        if (sessionId && !resume) {
             cmd.push('--session-id', sessionId);
         }
         // Claude: grant access to the teammate's working directory.
@@ -1817,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[];
 /**