@phnx-labs/agents-cli 1.22.49 → 1.22.50

package/dist/commands/traces.js

@@ -32,6 +32,10 @@ const SYNC_NOTES = `
   An incremental gate (traces-sync.json ledger) means re-runs only upload
   sessions whose file_mtime_ms changed since the last sync.
 
+  On a real (non-dry-run) sync with the managed Phoenix backend, also
+  fire-and-forget registers this session with Prix (api.prix.dev) so the
+  console can serve live trajectories — a link failure never blocks sync.
+
   Sign in first with: agents auth login
 `.trimStart();
 const STATUS_EXAMPLES = `

package/dist/lib/account-provider-registry.d.ts

@@ -15,4 +15,13 @@ export interface AccountProviderAdapter {
     validate(kind: AccountAuthKind, value: string): void;
 }
 export declare function getAccountProvider(provider: string): AccountProviderAdapter;
+/**
+ * Whether a provider account of kind `auth` can authenticate `agent` — i.e. the
+ * adapter has an `envFor(agent, auth)` mapping. Used both by the account UI and by
+ * the run-candidate pool so a Cursor key never enters Claude's pool and a harness
+ * with no provider adapter at all (e.g. kimi, native-login only) yields nothing.
+ * A "cannot authenticate" is a clean false; any other error (unknown provider,
+ * unsupported kind) is a real bug and re-throws rather than being swallowed.
+ */
+export declare function providerAuthenticatesHarness(provider: string, auth: AccountAuthKind, agent: AgentId): boolean;
 export declare function listAccountProviders(): string[];

package/dist/lib/account-provider-registry.js

@@ -54,6 +54,26 @@ export function getAccountProvider(provider) {
         throw new Error(`Unknown account provider '${provider}'. Supported: ${listAccountProviders().join(', ')}.`);
     return adapter;
 }
+/**
+ * Whether a provider account of kind `auth` can authenticate `agent` — i.e. the
+ * adapter has an `envFor(agent, auth)` mapping. Used both by the account UI and by
+ * the run-candidate pool so a Cursor key never enters Claude's pool and a harness
+ * with no provider adapter at all (e.g. kimi, native-login only) yields nothing.
+ * A "cannot authenticate" is a clean false; any other error (unknown provider,
+ * unsupported kind) is a real bug and re-throws rather than being swallowed.
+ */
+export function providerAuthenticatesHarness(provider, auth, agent) {
+    try {
+        getAccountProvider(provider).envFor(agent, auth);
+        return true;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('cannot authenticate'))
+            return false;
+        throw err;
+    }
+}
 export function listAccountProviders() {
     return [...ADAPTERS.keys()].sort();
 }

package/dist/lib/accounting/account-pool-collect.d.ts

@@ -0,0 +1,34 @@
+import type { AgentId } from '../types.js';
+import { type RotateCandidate } from './rotate.js';
+import { type RegistryAccountRecord } from './account-pool.js';
+/** Inputs to {@link foldRegistryCandidates} — injectable so the fold is unit-tested. */
+export interface RunCandidateInputs {
+    native: RotateCandidate[];
+    records: RegistryAccountRecord[];
+    runVersion: string | undefined;
+}
+/**
+ * PURE: fold provider-account candidates into the native version-home list.
+ *
+ * A registry account runs in `runVersion` (the agent's default installed home);
+ * the token/key overrides that home's own login at exec, so any home works. It
+ * carries `providerAccount` so the run path routes it through the existing
+ * `--account` injection (`resolveSpawnAccount` → `accountEnv`). An account already
+ * covered by a native login is skipped by accountKey. With no installed version
+ * there is nowhere to execute a registry account, so the native list passes
+ * through unchanged.
+ */
+export declare function foldRegistryCandidates(agent: AgentId, inputs: RunCandidateInputs): RotateCandidate[];
+/**
+ * Candidate list for the `agents run` strategy pick, account-centric: the usual
+ * native version-home candidates PLUS one candidate per provider account whose
+ * provider can authenticate `agent` and whose credential is present locally
+ * (RUSH-3182). This is what makes a setup-token / API-key account balance-eligible.
+ *
+ * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path
+ * ONLY — the other consumers of {@link collectRunCandidates} (watchdog, session
+ * recovery, teams placement) keep calling it directly and are unaffected. The
+ * existing {@link pickBalancedCandidate} selects over the combined list, so the
+ * revoked / rate-limit / exhausted logic is unchanged.
+ */
+export declare function collectRunCandidatesForRun(agent: AgentId): Promise<RotateCandidate[]>;

package/dist/lib/accounting/account-pool-collect.js

@@ -0,0 +1,71 @@
+import { readAccountRegistry } from '../account-registry.js';
+import { hasKeychainToken } from '../secrets/index.js';
+import { getGlobalDefault, listInstalledVersions } from '../installations/versions.js';
+import { collectRunCandidates } from './rotate.js';
+import { registryPoolCandidates } from './account-pool.js';
+/**
+ * Provider accounts whose credential is present on THIS device, as capability
+ * records. A registry entry with no local secret is skipped: including it would
+ * let `--strategy balanced` pick an account that then fails at spawn and exits the
+ * whole run (`resolveSpawnAccount` throws on a missing credential) instead of
+ * rotating to a healthy one.
+ */
+function localRegistryRecords() {
+    return Object.values(readAccountRegistry().accounts)
+        .filter((a) => hasKeychainToken(a.secretRef))
+        .map((a) => ({ name: a.name, provider: a.provider, auth: a.auth }));
+}
+/**
+ * PURE: fold provider-account candidates into the native version-home list.
+ *
+ * A registry account runs in `runVersion` (the agent's default installed home);
+ * the token/key overrides that home's own login at exec, so any home works. It
+ * carries `providerAccount` so the run path routes it through the existing
+ * `--account` injection (`resolveSpawnAccount` → `accountEnv`). An account already
+ * covered by a native login is skipped by accountKey. With no installed version
+ * there is nowhere to execute a registry account, so the native list passes
+ * through unchanged.
+ */
+export function foldRegistryCandidates(agent, inputs) {
+    const { native, records, runVersion } = inputs;
+    if (!runVersion)
+        return native;
+    const seen = new Set(native.filter((c) => c.accountKey).map((c) => c.accountKey));
+    const extra = registryPoolCandidates(records, agent)
+        .filter((r) => !seen.has(r.accountKey))
+        .map((r) => ({
+        agent,
+        version: runVersion,
+        accountKey: r.accountKey,
+        accountLabel: r.name,
+        email: null,
+        usageKey: null,
+        usageStatus: null,
+        usageSnapshot: null,
+        usageError: null,
+        usageMinutesToLimit: null,
+        plan: null,
+        signedIn: true,
+        authVerdict: null,
+        lastActive: null,
+        providerAccount: r.name,
+    }));
+    return [...native, ...extra];
+}
+/**
+ * Candidate list for the `agents run` strategy pick, account-centric: the usual
+ * native version-home candidates PLUS one candidate per provider account whose
+ * provider can authenticate `agent` and whose credential is present locally
+ * (RUSH-3182). This is what makes a setup-token / API-key account balance-eligible.
+ *
+ * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path
+ * ONLY — the other consumers of {@link collectRunCandidates} (watchdog, session
+ * recovery, teams placement) keep calling it directly and are unaffected. The
+ * existing {@link pickBalancedCandidate} selects over the combined list, so the
+ * revoked / rate-limit / exhausted logic is unchanged.
+ */
+export async function collectRunCandidatesForRun(agent) {
+    const native = await collectRunCandidates(agent);
+    const runVersion = getGlobalDefault(agent) ?? listInstalledVersions(agent)[0];
+    return foldRegistryCandidates(agent, { native, records: localRegistryRecords(), runVersion });
+}

package/dist/lib/accounting/account-pool.d.ts

@@ -0,0 +1,46 @@
+import type { AgentId } from '../types.js';
+import type { AccountAuthKind } from '../account-provider-registry.js';
+/**
+ * The provider-account side of the run-candidate pool (RUSH-3182).
+ *
+ * `--strategy balanced` used to enumerate only version-home native logins, so a
+ * setup-token / API-key account added via `agents accounts add` never balanced.
+ * This module turns the account registry into the extra candidates the run path
+ * folds in — see `collectRunCandidatesForRun` in `account-pool-collect.ts`.
+ *
+ * Pure + dependency-light so the harness-capability filter is unit-tested in
+ * isolation with fixtures.
+ */
+/** A provider account record as stored in the registry (identity captured separately). */
+export interface RegistryAccountRecord {
+    name: string;
+    provider: string;
+    auth: AccountAuthKind;
+}
+/** A registry account eligible to run one harness, ready to map to a candidate. */
+export interface RegistryAccountInput {
+    /** Agent-scoped key so `(claude, X)` and `(codex, X)` stay distinct. */
+    accountKey: string;
+    email: string | null;
+    name: string;
+    provider: string;
+    auth: AccountAuthKind;
+}
+/**
+ * Which provider accounts can authenticate `agent`. An account is a candidate for
+ * harness H only when its provider adapter has an `envFor(H, kind)` mapping
+ * (`providerAuthenticatesHarness`, the same check the account UI uses) — so a
+ * Cursor key never enters Claude's pool and a Claude setup-token never enters
+ * Codex's. This is registry-driven, no per-harness `else if`: a harness gets a
+ * provider-account pool exactly when the adapter table maps a provider to it —
+ * today claude, codex, grok, cursor, opencode (plus gemini/antigravity). A harness
+ * with only a native OAuth login and no provider adapter — kimi — returns `[]`
+ * here and keeps balancing its native logins only.
+ *
+ * `accountKey` is synthetic here (`${agent}:name=${name}`) — a stable per-account
+ * key so balancing can include it immediately; the real agent-scoped identity
+ * (email / org uuid) is backfilled by identity capture and replaces it. `email`
+ * is null until then, which routes the account as usage-unverified but still a
+ * candidate, never excluded.
+ */
+export declare function registryPoolCandidates(records: RegistryAccountRecord[], agent: AgentId): RegistryAccountInput[];

package/dist/lib/accounting/account-pool.js

@@ -0,0 +1,33 @@
+import { providerAuthenticatesHarness } from '../account-provider-registry.js';
+/**
+ * Which provider accounts can authenticate `agent`. An account is a candidate for
+ * harness H only when its provider adapter has an `envFor(H, kind)` mapping
+ * (`providerAuthenticatesHarness`, the same check the account UI uses) — so a
+ * Cursor key never enters Claude's pool and a Claude setup-token never enters
+ * Codex's. This is registry-driven, no per-harness `else if`: a harness gets a
+ * provider-account pool exactly when the adapter table maps a provider to it —
+ * today claude, codex, grok, cursor, opencode (plus gemini/antigravity). A harness
+ * with only a native OAuth login and no provider adapter — kimi — returns `[]`
+ * here and keeps balancing its native logins only.
+ *
+ * `accountKey` is synthetic here (`${agent}:name=${name}`) — a stable per-account
+ * key so balancing can include it immediately; the real agent-scoped identity
+ * (email / org uuid) is backfilled by identity capture and replaces it. `email`
+ * is null until then, which routes the account as usage-unverified but still a
+ * candidate, never excluded.
+ */
+export function registryPoolCandidates(records, agent) {
+    const out = [];
+    for (const r of records) {
+        if (!providerAuthenticatesHarness(r.provider, r.auth, agent))
+            continue;
+        out.push({
+            accountKey: `${agent}:name=${r.name}`,
+            email: null,
+            name: r.name,
+            provider: r.provider,
+            auth: r.auth,
+        });
+    }
+    return out;
+}

package/dist/lib/accounting/capacity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Remaining-capacity weighting for account selection — a pure, dependency-free
+ * primitive shared by the version-home router (`rotate.ts`) and the account pool
+ * (`account-pool.ts`). Kept in its own module so either can import it without
+ * dragging in the heavy usage/secrets graph.
+ */
+/**
+ * How far from its projected cap an account must be to keep its FULL headroom
+ * weight. Inside this horizon the weight is scaled down linearly toward the
+ * floor, so an account racing toward its 5h cap loses priority before it maxes.
+ */
+export declare const PROJECTION_HORIZON_MIN = 30;
+/**
+ * Weight one candidate by remaining routing capacity, deprioritized by how soon
+ * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
+ * an account with no live snapshot is treated as full-capacity (100) since there
+ * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
+ * projection on the 5h session window) then scales that base: >= horizon (or
+ * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
+ * so a launch avoids an account projected to cap soon, not just a 100%-maxed
+ * one. Pure + exported so the deprioritization is unit-tested directly (a
+ * weighted-random draw is not).
+ */
+export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;

package/dist/lib/accounting/capacity.js

@@ -0,0 +1,30 @@
+/**
+ * Remaining-capacity weighting for account selection — a pure, dependency-free
+ * primitive shared by the version-home router (`rotate.ts`) and the account pool
+ * (`account-pool.ts`). Kept in its own module so either can import it without
+ * dragging in the heavy usage/secrets graph.
+ */
+/**
+ * How far from its projected cap an account must be to keep its FULL headroom
+ * weight. Inside this horizon the weight is scaled down linearly toward the
+ * floor, so an account racing toward its 5h cap loses priority before it maxes.
+ */
+export const PROJECTION_HORIZON_MIN = 30;
+/**
+ * Weight one candidate by remaining routing capacity, deprioritized by how soon
+ * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
+ * an account with no live snapshot is treated as full-capacity (100) since there
+ * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
+ * projection on the 5h session window) then scales that base: >= horizon (or
+ * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
+ * so a launch avoids an account projected to cap soon, not just a 100%-maxed
+ * one. Pure + exported so the deprioritization is unit-tested directly (a
+ * weighted-random draw is not).
+ */
+export function capacityWeight(usedPercent, minutesToLimit) {
+    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
+    if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
+        return base;
+    const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));
+    return Math.max(1, base * factor);
+}

package/dist/lib/accounting/rotate.d.ts

@@ -6,6 +6,7 @@
  */
 import type { AgentId, RunStrategy } from '../types.js';
 import type { FallbackEntry } from '../exec.js';
+import { PROJECTION_HORIZON_MIN, capacityWeight } from './capacity.js';
 import { type AccountInfo, type CredentialPresence } from '../agents.js';
 import { type UsageSnapshot } from './usage.js';
 import { type AuthVerdict } from '../auth-health.js';
@@ -49,6 +50,15 @@ export interface RotateCandidate {
      */
     authVerdict: AuthVerdict | null;
     lastActive: Date | null;
+    /**
+     * Set only for a candidate that comes from a provider account bundle rather
+     * than a native version-home login (RUSH-3182): the account name to inject via
+     * the `--account` spawn path (`resolveSpawnAccount` → `accountEnv`). Undefined
+     * for a native login, whose credential already lives in `version`'s home. The
+     * run path routes on this so a balanced pick of a setup-token / API-key account
+     * authenticates through the existing provider-account injection.
+     */
+    providerAccount?: string;
 }
 export interface RotateResult {
     /** The version picked for this run. */
@@ -212,24 +222,7 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  * version so behavior stays predictable.
  */
 export declare function pickBalancedCandidate(candidates: RotateCandidate[], nowMs?: number): RotateResult | null;
-/**
- * How far from its projected cap an account must be to keep its FULL headroom
- * weight. Inside this horizon the weight is scaled down linearly toward the
- * floor, so an account racing toward its 5h cap loses priority before it maxes.
- */
-export declare const PROJECTION_HORIZON_MIN = 30;
-/**
- * Weight one candidate by remaining routing capacity, deprioritized by how soon
- * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
- */
-export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;
+export { PROJECTION_HORIZON_MIN, capacityWeight };
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most

package/dist/lib/accounting/rotate.js

@@ -6,6 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { PROJECTION_HORIZON_MIN, capacityWeight } from './capacity.js';
 import { accountDisplayLabel, getAccountInfo, credentialPresence, ALL_AGENT_IDS, } from '../agents.js';
 import { readMeta, writeMeta, getHelpersDir } from '../state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from '../installations/versions.js';
@@ -365,30 +366,11 @@ function preferVerified(pool, nowMs, choose, narrowing = 'any-verified') {
         usageUnverified: !isUsageVerified(picked, nowMs),
     };
 }
-/**
- * How far from its projected cap an account must be to keep its FULL headroom
- * weight. Inside this horizon the weight is scaled down linearly toward the
- * floor, so an account racing toward its 5h cap loses priority before it maxes.
- */
-export const PROJECTION_HORIZON_MIN = 30;
-/**
- * Weight one candidate by remaining routing capacity, deprioritized by how soon
- * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
- */
-export function capacityWeight(usedPercent, minutesToLimit) {
-    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
-    if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
-        return base;
-    const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));
-    return Math.max(1, base * factor);
-}
+// capacityWeight + PROJECTION_HORIZON_MIN moved to ./capacity.js (a pure,
+// dependency-free module the account pool can import without this file's heavy
+// graph). Imported at the top for internal use; re-exported here so existing
+// importers keep resolving them from rotate.
+export { PROJECTION_HORIZON_MIN, capacityWeight };
 /**
  * Pick one candidate from `sorted` using weights proportional to remaining
  * routing capacity (see {@link capacityWeight}). Floor each weight at 1 so a

package/dist/lib/installations/store.js

@@ -269,10 +269,13 @@ export function getBinaryPath(agent, version) {
     const agentConfig = AGENTS[agent];
     if (agent === 'grok') {
         const grokDownloads = path.join(getVersionHomePath(agent, version), '.grok', 'downloads');
-        // Best effort: first matching file for this version
+        // The directory token is the stable installation/account label. A
+        // self-updating slot may carry a newer vendor release, whose binary keeps
+        // the release in its filename; resolve through the frozen install record.
+        const releaseVersion = readInstallation(agent, version)?.releaseVersion ?? version;
         try {
             const entries = fs.readdirSync(grokDownloads);
-            const match = entries.find((e) => e.includes(version) && e.startsWith('grok-'));
+            const match = entries.find((e) => e.includes(releaseVersion) && e.startsWith('grok-'));
             if (match)
                 return path.join(grokDownloads, match);
         }
@@ -280,7 +283,7 @@ export function getBinaryPath(agent, version) {
         const fallback = resolveGrokFallbackBinary(grokDownloads);
         if (fallback)
             return fallback;
-        return path.join(grokDownloads, `grok-${version}`);
+        return path.join(grokDownloads, `grok-${releaseVersion}`);
     }
     if (agent === 'droid') {
         // Factory.ai's installer drops a standalone native binary (no npm package,

package/dist/lib/installations/versions.js

@@ -34,7 +34,7 @@ import { discoverPermissionGroups, getActivePermissionPresetName, readPermission
 import { parseMcpConfigForScan, isProjectMcpTrusted } from '../mcp.js';
 import { createVersionedAlias, removeVersionedAlias, switchConfigSymlink, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, isIsolationProtected, } from './shims.js';
 import { importInstallScriptBinary } from '../import.js';
-import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveVersion, } from './store.js';
+import { createInstallation, getBinaryPath, getCliVersionFromPath, getGlobalDefault, getIsolatedDefault, getLiveVersion, getVersionDir, getVersionHomePath, invalidateInstalledVersionsCache, invalidateLiveVersionCache, isGlobalBinaryAgent, isVersionInstalled, isVersionIsolated, listInstalledVersions, pickCanonicalGlobalBinaryVersion, resolveGrokFallbackBinary, resolveVersion, } from './store.js';
 export * from './store.js';
 import { INSTALLATION_RECORD_FILE } from './types.js';
 import { composeWin32CommandLine } from '../platform/index.js';
@@ -1032,9 +1032,9 @@ export function setIsolatedDefault(agent, version) {
 /**
  * Move any `grok-<installedVersion>-...` binary (and its generic platform
  * copy) found directly under `sourceDownloads` into `targetDownloads`.
- * Returns true if the versioned binary was moved.
+ * Returns true if the versioned binary was transferred.
  */
-function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion) {
+function transferGrokDownloads(sourceDownloads, targetDownloads, copy) {
     if (!fs.existsSync(sourceDownloads))
         return false;
     if (path.resolve(sourceDownloads) === path.resolve(targetDownloads))
@@ -1042,42 +1042,36 @@ function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion
     const entries = fs.readdirSync(sourceDownloads).filter((e) => e.startsWith('grok-'));
     if (entries.length === 0)
         return false;
-    const escapedVersion = installedVersion.replace(/\./g, '\\.');
-    const versionedPattern = new RegExp(`^grok-${escapedVersion}-`);
-    const movedPaths = [];
-    // Move the versioned binary first — only create the target dir once we
-    // know there is something to move into it.
-    for (const entry of entries) {
-        if (!versionedPattern.test(entry))
-            continue;
-        const src = path.join(sourceDownloads, entry);
-        const dst = path.join(targetDownloads, entry);
-        if (fs.existsSync(dst))
-            continue;
-        try {
-            fs.mkdirSync(targetDownloads, { recursive: true });
-            fs.renameSync(src, dst);
-            movedPaths.push(dst);
-        }
-        catch {
-            /* ignore per-file failures */
-        }
+    const realBinary = resolveGrokFallbackBinary(sourceDownloads);
+    if (!realBinary)
+        return false;
+    const transferred = path.join(targetDownloads, path.basename(realBinary));
+    try {
+        fs.mkdirSync(targetDownloads, { recursive: true });
+        if (copy)
+            fs.copyFileSync(realBinary, transferred);
+        else
+            fs.renameSync(realBinary, transferred);
     }
-    if (movedPaths.length === 0)
+    catch {
         return false;
+    }
     // The installer also creates a generic platform binary (e.g. grok-macos-aarch64)
     // that is a copy of the versioned binary. Move it too if its size matches.
-    const movedSize = fs.statSync(movedPaths[0]).size;
+    const movedSize = fs.statSync(transferred).size;
     for (const entry of entries) {
-        if (versionedPattern.test(entry))
-            continue; // already handled
+        if (entry === path.basename(realBinary))
+            continue;
         const src = path.join(sourceDownloads, entry);
         const dst = path.join(targetDownloads, entry);
         if (fs.existsSync(dst))
             continue;
         try {
             if (fs.statSync(src).size === movedSize) {
-                fs.renameSync(src, dst);
+                if (copy)
+                    fs.copyFileSync(src, dst);
+                else
+                    fs.renameSync(src, dst);
             }
         }
         catch {
@@ -1099,7 +1093,7 @@ function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion
  * whatever version was default at the time), sweep every other installed
  * grok version home for the missing file before giving up.
  */
-function relocateGrokBinaryToVersionHome(installedVersion) {
+function relocateGrokBinaryToVersionHome(installationLabel, copyExisting) {
     const hostGrokLink = path.join(getHomeDir(), agentConfigDirName('grok'));
     let sourceDownloads;
     try {
@@ -1108,16 +1102,16 @@ function relocateGrokBinaryToVersionHome(installedVersion) {
     catch {
         sourceDownloads = path.join(hostGrokLink, 'downloads');
     }
-    const targetDownloads = path.join(getVersionHomePath('grok', installedVersion), agentConfigDirName('grok'), 'downloads');
-    if (tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion))
+    const targetDownloads = path.join(getVersionHomePath('grok', installationLabel), agentConfigDirName('grok'), 'downloads');
+    if (transferGrokDownloads(sourceDownloads, targetDownloads, copyExisting))
         return;
     for (const version of listInstalledVersions('grok')) {
-        if (version === installedVersion)
+        if (version === installationLabel)
             continue;
         const candidate = path.join(getVersionHomePath('grok', version), agentConfigDirName('grok'), 'downloads');
         if (path.resolve(candidate) === path.resolve(sourceDownloads))
             continue; // already tried
-        if (tryMoveGrokDownloads(candidate, targetDownloads, installedVersion))
+        if (transferGrokDownloads(candidate, targetDownloads, copyExisting))
             return;
     }
 }
@@ -1158,6 +1152,7 @@ async function checkGrokAccountCollision(installedVersion) {
  */
 export async function installVersion(agent, version, onProgress, opts) {
     const agentConfig = AGENTS[agent];
+    const requestedLabel = version;
     if (isAgentHardDeprecated(agent)) {
         return { success: false, installedVersion: version, error: hardDeprecationError(agent) };
     }
@@ -1189,7 +1184,7 @@ export async function installVersion(agent, version, onProgress, opts) {
             }
             version = 'latest';
         }
-        let installedVersion = version;
+        let releaseVersion = version;
         try {
             if (runInstaller) {
                 const script = agentConfig.installScript.replaceAll('VERSION', version);
@@ -1218,13 +1213,19 @@ export async function installVersion(agent, version, onProgress, opts) {
                         error: `${agentConfig.name} installed but its version could not be determined after several attempts.`,
                     };
                 }
-                installedVersion = probed;
+                releaseVersion = probed;
                 // 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);
+                await reconcileStaleLatestDir(agent, releaseVersion);
             }
+            // Self-updating installers always fetch the current vendor release, but a
+            // concrete requested token is still the stable installation/account slot.
+            // Keeping the two strings separate lets several homes carry the same
+            // release without sharing credentials. `latest` remains the convenient
+            // release-named slot; concrete tokens remain exactly addressable.
+            const installationLabel = requestedLabel === 'latest' ? releaseVersion : requestedLabel;
             if (agent === 'grok') {
-                await checkGrokAccountCollision(installedVersion);
+                await checkGrokAccountCollision(installationLabel);
             }
             onProgress?.(`${agentConfig.name} installed. Setting up agents-cli version home for isolation...`);
         }
@@ -1233,14 +1234,15 @@ export async function installVersion(agent, version, onProgress, opts) {
             return { success: false, installedVersion: version, error: `${agentConfig.name} installer failed: ${err.message}` };
         }
         ensureAgentsDir();
-        const versionDir = getVersionDir(agent, installedVersion);
+        const installationLabel = requestedLabel === 'latest' ? releaseVersion : requestedLabel;
+        const versionDir = getVersionDir(agent, installationLabel);
         fs.mkdirSync(versionDir, { recursive: true });
         fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
         // Grok's installer drops the binary into ~/.grok/downloads, which currently
         // resolves to the PREVIOUS default home. Move it into the target version home
         // so version isolation is correct.
         if (agent === 'grok') {
-            relocateGrokBinaryToVersionHome(installedVersion);
+            relocateGrokBinaryToVersionHome(installationLabel, !runInstaller);
         }
         // Symlink the installed binary into the version's node_modules/.bin so
         // listInstalledVersions (which checks getBinaryPath) sees this version as
@@ -1265,26 +1267,26 @@ export async function installVersion(agent, version, onProgress, opts) {
             // that exec-loops forever).
             const installedBinary = findInPath(agentConfig.cliCommand);
             if (installedBinary) {
-                importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installedVersion, installedBinary, versionDir);
+                importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installationLabel, installedBinary, versionDir);
             }
             /* If null: binary missing from PATH (install script failed silently) or
                only our shim is present. Leave the version dir empty so getBinaryPath
                correctly reports it uninstalled. */
         }
-        createVersionedAlias(agent, installedVersion);
+        createVersionedAlias(agent, installationLabel);
         // Freeze this installation's identity. The dir name is its stable label from
         // here on; the release it carries is recorded separately so `agents update`
         // can move the release without invalidating any reference to the label.
-        createInstallation(agent, installedVersion, installedVersion);
-        const trackerInstall = await installSessionTrackerHook(agent, installedVersion);
+        createInstallation(agent, installationLabel, releaseVersion);
+        const trackerInstall = await installSessionTrackerHook(agent, installationLabel);
         if (!trackerInstall.installed && trackerInstall.error) {
-            console.warn(`agents: SessionStart hook not installed for ${agent}@${installedVersion}: ${trackerInstall.error}`);
+            console.warn(`agents: SessionStart hook not installed for ${agent}@${installationLabel}: ${trackerInstall.error}`);
         }
         // 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 };
+        emit('version.install', { agent, version: installationLabel });
+        return { success: true, installedVersion: installationLabel };
     }
     // Resolve the `latest`/`oldest` aliases to a concrete npm version up front so
     // the rest of the install path treats them as an ordinary pinned install.