@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/commands/ssh.js

@@ -19,6 +19,7 @@ import { getCliVersion } from '../lib/version.js';
 import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../lib/secrets/bundles.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { registerFleetCaptureCommand } from './fleet-capture.js';
+import { registerFleetApplyAlias } from './apply.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, } from '../lib/devices/registry.js';
 import { addControlToken } from '../lib/serve/token.js';
 import { DEFAULT_SERVE_PORT } from '../lib/serve/server.js';
@@ -40,7 +41,10 @@ import { checkAllClis } from '../lib/teams/agents.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
-import { formatCheckedAge, isDeadVerdict, probeLocalFleetAuth, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
+import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js';
+import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort } from './lease.js';
+import { authCellColor, formatCheckedAge, isDeadVerdict, probeLocalFleetAuth, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
+import { runFleetLogin } from '../lib/fleet/remote-login.js';
 /** One-line summary of a device for `list`. `isSelf` marks the machine this
  * command is running on so it stands out from the rest of the tailnet. */
 function deviceSummary(d, isSelf = false) {
@@ -130,6 +134,74 @@ function renderDeviceTable(reg, names, self, statsMap, full = false) {
     }
     return lines;
 }
+/**
+ * Live "Leased boxes" section for `agents devices` (F4, RUSH-1923), computed
+ * from `crabboxList()` — these are ephemeral crabbox leases, NEVER written into
+ * the device registry. Returns [] when crabbox is unavailable / has no creds /
+ * reports no boxes, so the section is simply omitted. `nowSecs` is injected so
+ * the row formatting is deterministic in tests.
+ */
+export function renderLeasedBoxesSection(boxes, nowSecs) {
+    if (boxes.length === 0)
+        return [];
+    const lines = [];
+    lines.push('');
+    lines.push(chalk.bold('Leased boxes') + chalk.gray(' (ephemeral · via crabbox)'));
+    lines.push('  ' +
+        chalk.gray('box'.padEnd(16)) +
+        chalk.gray('class'.padEnd(10)) +
+        chalk.gray('address'.padEnd(24)) +
+        chalk.gray('status'.padEnd(9)) +
+        chalk.gray('idle'.padEnd(12)) +
+        chalk.gray('expires'));
+    for (const b of boxes) {
+        const addr = boxAddress(b) ?? '—';
+        lines.push('  ' +
+            chalk.cyan(b.slug.padEnd(16)) +
+            (b.class ?? '?').padEnd(10) +
+            addr.padEnd(24) +
+            boxStatus(b).padEnd(9) +
+            chalk.gray(fmtIdleShort(b, nowSecs).padEnd(12)) +
+            chalk.gray(fmtExpiresShort(b, nowSecs)));
+    }
+    lines.push(chalk.gray('  Reuse a box with `agents run --box <slug>` · stop with `agents lease stop <slug>`'));
+    return lines;
+}
+/** The leased-box rows for the devices list, or [] when crabbox can't be read. */
+function loadLeasedBoxesSection() {
+    try {
+        const boxes = crabboxList({ secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE, timeoutMs: 5000 });
+        return renderLeasedBoxesSection(boxes, Math.floor(Date.now() / 1000));
+    }
+    catch {
+        return []; // crabbox not installed / no provider creds — omit the section
+    }
+}
+/**
+ * `agents ssh <slug>` targeting a leased crabbox box. crabbox provisions a
+ * per-lease identity key, so we ssh via crabbox's OWN emitted invocation
+ * (`crabboxSshArgv`) — a raw `ssh crabbox@ip` fails publickey. Returns false when
+ * `name` is not a known crabbox slug so the caller can fall through to the normal
+ * "Unknown device" error.
+ */
+function trySshLeasedBox(name, cmd) {
+    let box;
+    try {
+        box = crabboxFind(name, { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE, timeoutMs: 5000 });
+    }
+    catch {
+        return false; // crabbox unavailable — not a leased-box target
+    }
+    if (!box)
+        return false;
+    const sshArgv = crabboxSshArgv(name, { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE, timeoutMs: 8000 });
+    if (!sshArgv) {
+        console.error(chalk.red(`Leased box '${name}' is not reachable yet (status: ${boxStatus(box)}).`));
+        process.exit(1);
+    }
+    const res = spawnSync(sshArgv[0], [...sshArgv.slice(1), ...cmd], { stdio: 'inherit' });
+    process.exit(res.status ?? 1);
+}
 /** Resolve a device or exit with a clear error. */
 async function mustGetDevice(name) {
     const d = await getDevice(name);
@@ -423,17 +495,28 @@ async function runFleetPing(opts) {
     if (opts.strict && anyBad)
         process.exitCode = 1;
 }
-/** Color a per-host×agent cell: green all-live, red any revoked/expired, yellow degraded. */
+/** Resolve an {@link AuthCellColor} to a chalk painter. Single map for cells + labels. */
+const CELL_PAINT = {
+    green: chalk.green,
+    yellow: chalk.yellow,
+    red: chalk.red,
+    gray: chalk.gray,
+    dim: chalk.dim,
+};
+/**
+ * Color a per-host×agent cell. The numerator counts accounts that are usable
+ * right now — live-verified PLUS signed-in-but-unverifiable (codex/grok) — over
+ * the total, so a logged-in codex fleet reads "1/1", not a scary "0/1". Color is
+ * the shared {@link authCellColor}: red only for revoked (re-login), yellow for
+ * soft/expired (self-refreshes), gray for present-but-unverifiable, green when
+ * all live.
+ */
 function authCell(summary, width) {
     if (summary.total === 0)
         return chalk.dim('·'.padEnd(width));
-    const text = `${summary.live}/${summary.total}`;
-    const padded = text.padEnd(width);
-    if (summary.bad > 0)
-        return chalk.red(padded);
-    if (summary.warn > 0)
-        return chalk.yellow(padded);
-    return chalk.green(padded);
+    const ok = summary.live + summary.present;
+    const padded = `${ok}/${summary.total}`.padEnd(width);
+    return CELL_PAINT[authCellColor(summary)](padded);
 }
 /** Render the fleet auth matrix (device rows × agent columns) plus an optional per-account breakdown. */
 function renderAuthMatrix(results, opts) {
@@ -466,7 +549,7 @@ function renderAuthMatrix(results, opts) {
         lines.push(`  ${r.host.padEnd(nameW)}  ${cells.join(' ')}${note}`);
     }
     lines.push('');
-    lines.push(chalk.gray('  cell = live/total accounts · green all live · red revoked (re-login) · yellow expired/unverified/limited'));
+    lines.push(chalk.gray('  cell = signed-in/total accounts · green live · gray signed-in (unverifiable: codex/grok) · yellow expired (self-refreshes) · red revoked (re-login)'));
     if (opts?.verbose) {
         lines.push('');
         lines.push(chalk.bold('Accounts'));
@@ -475,9 +558,7 @@ function renderAuthMatrix(results, opts) {
                 continue;
             for (const row of r.rows.slice().sort((x, y) => (x.agent + x.version).localeCompare(y.agent + y.version))) {
                 const v = row.health.verdict;
-                const label = v === 'live' ? chalk.green(verdictLabel(v))
-                    : (v === 'revoked' || v === 'expired') ? chalk.red(verdictLabel(v))
-                        : chalk.yellow(verdictLabel(v));
+                const label = CELL_PAINT[verdictColor(v)](verdictLabel(v));
                 const acctRaw = row.account ?? '—';
                 const acct = row.account ? chalk.cyan(acctRaw.padEnd(28)) : chalk.dim(acctRaw.padEnd(28));
                 const detail = row.health.detail ? chalk.dim(` ${row.health.detail}`) : '';
@@ -488,6 +569,46 @@ function renderAuthMatrix(results, opts) {
     }
     return lines;
 }
+/** Render the final `fleet login` result summary in the house auth-matrix style. */
+function renderLoginMatrix(results) {
+    const lines = [chalk.bold('Fleet login')];
+    if (results.length === 0) {
+        lines.push(chalk.gray('  Nothing pending — every requested account is already logged in.'));
+        return lines;
+    }
+    const nameW = Math.max(6, ...results.map((r) => `${r.agent}@${r.device}`.length));
+    for (const r of results) {
+        const who = `${r.agent}@${r.device}`.padEnd(nameW);
+        let badge;
+        switch (r.state) {
+            case 'authorized':
+                badge = chalk.green('authorized');
+                break;
+            case 'ready':
+                badge = chalk.cyan('code ready');
+                break;
+            case 'driving':
+                badge = chalk.yellow('driving');
+                break;
+            case 'skipped':
+                badge = chalk.gray('not remotable');
+                break;
+            case 'error':
+                badge = chalk.red('error');
+                break;
+            default:
+                badge = chalk.gray(r.state);
+                break;
+        }
+        const note = r.detail ? chalk.dim(`  ${r.detail}`) : (r.reason && !r.remotable ? chalk.dim(`  ${r.reason}`) : '');
+        lines.push(`  ${who}  ${badge}${note}`);
+    }
+    const auth = results.filter((r) => r.state === 'authorized').length;
+    const remotable = results.filter((r) => r.remotable).length;
+    lines.push('');
+    lines.push(chalk.gray(`  ${auth}/${remotable} remotable logins authorized`));
+    return lines;
+}
 /** Register the `agents devices` command tree (also aliased as `fleet`). */
 function registerDevicesCommands(program) {
     const devicesCmd = program
@@ -529,6 +650,9 @@ Typical workflow:
     });
     // `agents fleet capture` — snapshot live state into agents.yaml fleet:.
     registerFleetCaptureCommand(devicesCmd);
+    // `agents fleet apply` — same reconcile engine as the top-level `agents apply`,
+    // surfaced under the fleet tree for discoverability.
+    registerFleetApplyAlias(devicesCmd);
     devicesCmd
         .command('register <name>')
         .description('Register a discovered (pending) node by name — used by the menu-bar "NEW DEVICES → Register" action.')
@@ -576,16 +700,7 @@ Typical workflow:
         }
         console.log(chalk.green(`No longer ignoring '${name}'`) + chalk.gray(' — run `agents devices sync` to register it.'));
     });
-    devicesCmd
-        .command('list')
-        .alias('ls')
-        .description('List registered devices with platform, address, reachability, and live resource headroom.')
-        .option('--json', 'output the registry as a JSON array (for scripts and hooks)')
-        .option('--no-stats', 'skip the live resource probe (instant; names/addresses only)')
-        .option('--refresh', 'force a live probe of every device, bypassing the cache')
-        .option('--live', 'alias of --refresh (shorter to type)')
-        .option('-f, --full', 'full mode: add per-device core count and free/total memory')
-        .action(async (opts) => {
+    const runList = async (opts = {}) => {
         const reg = await loadDevices();
         const names = Object.keys(reg).sort();
         if (opts.json) {
@@ -629,7 +744,26 @@ Typical workflow:
         if (freshness?.servedFromCache && freshness.oldestFetchedAt != null) {
             console.log(chalk.gray(`  updated ${formatCheckedAge(freshness.oldestFetchedAt)} — pass --refresh (--live) for a live probe`));
         }
-    });
+        // Ephemeral crabbox leases live alongside the registered fleet but are never
+        // written into the registry — surface them as their own live section. This is
+        // a live provider call, so honor --no-stats (the explicit "instant, no probes"
+        // opt-out) and bound it so a slow provider can't hang `agents devices`.
+        if (opts.stats !== false) {
+            for (const line of loadLeasedBoxesSection())
+                console.log(line);
+        }
+    };
+    devicesCmd.action(runList);
+    devicesCmd
+        .command('list')
+        .alias('ls')
+        .description('List registered devices with platform, address, reachability, and live resource headroom.')
+        .option('--json', 'output the registry as a JSON array (for scripts and hooks)')
+        .option('--no-stats', 'skip the live resource probe (instant; names/addresses only)')
+        .option('--refresh', 'force a live probe of every device, bypassing the cache')
+        .option('--live', 'alias of --refresh (shorter to type)')
+        .option('-f, --full', 'full mode: add per-device core count and free/total memory')
+        .action(runList);
     devicesCmd
         .command('status')
         .description('Show fleet health: warnings rollup, per-device sync drift, CLI readiness, version skew, and resource headroom.')
@@ -648,8 +782,41 @@ Typical workflow:
         .option('--local', 'probe only this host (used internally for fan-out)')
         .option('--verbose', 'show a per-account breakdown, not just the per-host rollup')
         .option('--strict', 'exit non-zero when any account is revoked (expired is soft — it self-refreshes)')
+        .action(async (opts, cmd) => {
+        // The root program also defines a global `--verbose` (startup self-heal
+        // detail), and commander binds a shared long flag to the program, not the
+        // leaf — so `fleet ping --verbose` never set opts.verbose and the
+        // per-account breakdown was silently unreachable. Read the effective value
+        // from the merged globals so the flag works at either level.
+        const verbose = opts.verbose ?? Boolean(cmd.optsWithGlobals().verbose);
+        await runFleetPing({ ...opts, verbose });
+    });
+    devicesCmd
+        .command('login')
+        .description('Log agent CLIs into fleet boxes over SSH: drive each box\'s device-code OAuth, scrape the URL + code, and surface every pending login in one local browser page. Default drives all codes at once; --interactive walks one box at a time (codes requested just-in-time so they don\'t expire).')
+        .option('--agents <csv>', 'only these agents (comma-separated); default: every agent with a device-code flow')
+        .option('--devices <csv>', 'only these devices (comma-separated); default: every online box')
+        .option('--all', 'target every device-code pair regardless of cached login state (cold cache / forced re-login)')
+        .option('--interactive', 'guided one-box-at-a-time wizard (codes requested just-in-time)')
+        .option('--json', 'output the final result matrix as JSON')
         .action(async (opts) => {
-        await runFleetPing(opts);
+        const csv = (s) => (s ? s.split(',').map((x) => x.trim()).filter(Boolean) : undefined);
+        const results = await runFleetLogin({
+            agents: csv(opts.agents),
+            devices: csv(opts.devices),
+            all: opts.all,
+            interactive: opts.interactive,
+            json: opts.json,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(results, null, 2));
+        }
+        else {
+            for (const line of renderLoginMatrix(results))
+                console.log(line);
+        }
+        if (results.some((r) => r.remotable && r.state !== 'authorized'))
+            process.exitCode = 1;
     });
     devicesCmd
         .command('show <name>')
@@ -849,6 +1016,9 @@ secrets bundle via an askpass shim — the password never touches argv.
         // A bare unregistered alias still errors as "Unknown device".
         const device = resolveDeviceTarget(name, await loadDevices());
         if (!device) {
+            // Not a registered device — it may be a leased crabbox box slug. ssh into
+            // it directly (crabbox@<tailnet|ip>:2222) before giving up.
+            trySshLeasedBox(name, cmd); // exits the process on a match
             console.error(chalk.red(`Unknown device '${name}'. See 'agents devices list'.`));
             process.exit(1);
         }
@@ -907,7 +1077,7 @@ async function runAskpass() {
         process.exit(1);
     }
     try {
-        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh', agentOnly: isHeadlessSecretsContext() });
+        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh', keys: [key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
         const value = env[key];
         if (value === undefined) {
             console.error(`askpass: key '${key}' not found in bundle '${bundle}'`);

package/dist/commands/sync.js

@@ -544,7 +544,7 @@ function runLaunchMode(agent, version, cwd, quiet) {
     if (result.rulesCompiled)
         bits.push('rules');
     if (result.workspaceLinks > 0)
-        bits.push(`${result.workspaceLinks} workspace link(s)`);
+        bits.push(`${result.workspaceLinks} project resource(s)`);
     const mpCount = Object.keys(result.marketplaces).length;
     if (mpCount > 0) {
         const pluginCount = Object.values(result.marketplaces).reduce((acc, names) => acc + names.length, 0);

package/dist/commands/teams.js

@@ -7,6 +7,8 @@ import { AgentManager, AgentStatus, checkCliSignedIn, collectTeamsDoctorData, ge
 import { mailboxDir, enqueue } from '../lib/mailbox.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { emit } from '../lib/events.js';
+import { maybeShowStarNudge } from '../lib/star-nudge.js';
+import { shareRuntimeEnv } from '../lib/share/config.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
 import { debug } from '../lib/teams/debug.js';
 import { runPrWatch, DEFAULT_MAX_WAVES, } from '../lib/teams/pr-watch.js';
@@ -49,8 +51,6 @@ const VALID_AGENTS = Object.keys(AGENT_NAMES);
 const VALID_MODES = ['plan', 'edit', 'auto', 'skip', 'full'];
 const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'auto'];
 const VALID_CLOUD_PROVIDERS = ['rush', 'codex', 'factory'];
-// Auto-enable JSON mode when piped / not a TTY so AI agent consumers get
-// parseable output by default.
 function statusColor(status) {
     switch (status) {
         case 'pending': return chalk.blue;
@@ -1352,6 +1352,7 @@ export function registerTeamsCommands(program) {
                     repo: opts.repo,
                     branch: opts.branch,
                     model: a.model ?? undefined,
+                    env: shareRuntimeEnv({ agentOnly: true }),
                 };
                 const cloudTask = await prov.dispatch(dispatchOpts);
                 return { cloudSessionId: cloudTask.id };
@@ -1369,6 +1370,7 @@ export function registerTeamsCommands(program) {
                 repo: opts.repo,
                 branch: opts.branch,
                 model: opts.model,
+                env: shareRuntimeEnv({ agentOnly: true }),
             };
             try {
                 const cloudTask = await prov.dispatch(dispatchOpts);
@@ -1594,6 +1596,13 @@ export function registerTeamsCommands(program) {
         emit('teams.complete', { module: 'teams', team, stoppedBy: result.stoppedBy, waves: result.waves, durationMs: result.elapsed_ms });
         if (result.stoppedBy === 'drained') {
             console.log(chalk.green(`Factory drained in ${elapsed}s (${result.waves} waves).`));
+            // First-successful-team star nudge (one-time, non-nagging). "drained"
+            // only means nothing is pending/running — teammates may have failed — so
+            // gate on a clean drain (failed === 0). A team where every teammate
+            // failed is not the success this nudge celebrates.
+            if ((result.failed ?? 0) === 0) {
+                maybeShowStarNudge({ quiet: opts.json });
+            }
         }
         else if (result.stoppedBy === 'max-waves') {
             console.error(chalk.yellow(`Hit --max-waves=${maxWaves}; stopping. Re-run to continue.`));

package/dist/commands/versions.js

@@ -8,9 +8,9 @@ import { AGENTS, ALL_AGENT_IDS, accountOrgBadge, getAccountEmail, getAccountInfo
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
-import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, isOldestInstalled, getGlobalDefault, setGlobalDefault, markVersionIsolated, isVersionIsolated, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
+import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, isOldestInstalled, getGlobalDefault, setGlobalDefault, markVersionIsolated, setIsolatedDefault, isVersionIsolated, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
 import { carryForwardSettings } from '../lib/settings-manifest.js';
-import { createShim, createVersionedAlias, supportsIsolatedInstall, CONFIG_ENV_ISOLATED_AGENTS, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
+import { createShim, createVersionedAlias, supportsIsolatedInstall, isIsolationProtected, CONFIG_ENV_ISOLATED_AGENTS, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { tryAutoPull } from '../lib/git.js';
 import { getAgentsDir, getTrashVersionsDir } from '../lib/state.js';
@@ -342,6 +342,20 @@ export function registerVersionsCommands(program) {
             // from the user's real ~/.<agent>. Agents without one isolate only by
             // adopting ~/.<agent> (which --isolated skips), so an isolated copy
             // would silently read/write the real config. Refuse rather than lie.
+            // A normal install of a currently isolated-only agent would adopt it: set the
+            // global default, create the bare shim, and repoint the real ~/.<agent>. The
+            // primitives refuse that outright, so catch it here — before spending a
+            // network install on something that cannot finish — and say what to do.
+            if (!isIsolated && isIsolationProtected(agent)) {
+                console.log(chalk.red(`${agentLabel(agentConfig.id)} is installed only as isolated copies.`));
+                console.log(chalk.gray(`  A normal install would adopt ${agentConfig.configDir} and your ${agentConfig.cliCommand} launcher.`));
+                console.log(chalk.gray(`  Keep the sandbox:  agents add ${agent}@${version ?? 'latest'} --isolated`));
+                console.log(chalk.gray('  Or manage it normally by removing the isolated copies first:'));
+                for (const v of listInstalledVersions(agent)) {
+                    console.log(chalk.gray(`    agents remove ${agent}@${v} --isolated`));
+                }
+                continue;
+            }
             if (isIsolated && !supportsIsolatedInstall(agent)) {
                 console.log(chalk.red(`${agentLabel(agentConfig.id)} does not support --isolated installs.`));
                 console.log(chalk.gray(`  It has no config-directory env var, so it can only isolate by adopting ${agentConfig.configDir} — which --isolated deliberately avoids.`));
@@ -705,10 +719,27 @@ export function registerVersionsCommands(program) {
             // Refuse for both the explicit `use <agent>@<isolated>` path (the picker
             // above already filters isolated versions out of the interactive path).
             // Isolated copies are launched explicitly via `agents run <agent>@<v>`.
+            // ...so `use` is scoped to the sandbox rather than refused. Setting the
+            // ISOLATED default records which copy a bare `agents run <agent>` should
+            // reach, and touches none of the five adopting side effects above. The
+            // pointer lives in `meta.isolatedAgents`, never in `meta.agents`, so
+            // `getGlobalDefault` still cannot return an isolated version.
             if (isVersionIsolated(agentId, finalVersion)) {
-                console.log(chalk.red(`${agentLabel(agentConfig.id)}@${finalVersion} is an isolated install and can't be set as your active version.`));
-                console.log(chalk.gray(`Isolated copies stay walled off from your real ${agentConfig.configDir}. Run it directly: agents run ${agentId}@${finalVersion}`));
-                console.log(chalk.gray(`To install this version normally: agents add ${agentId}@${finalVersion}`));
+                if (options.project) {
+                    console.log(chalk.yellow(`${agentLabel(agentConfig.id)}@${finalVersion} is an isolated install; --project pins are for shared versions.`));
+                    console.log(chalk.gray(`Run it directly instead: agents run ${agentId}@${finalVersion}`));
+                    return;
+                }
+                setIsolatedDefault(agentId, finalVersion);
+                console.log(chalk.green(`Set ${agentLabel(agentConfig.id)}@${finalVersion} as your default ISOLATED copy.`));
+                console.log(chalk.gray(`  agents run ${agentId}   now reaches it (no @version needed).`));
+                const globalDefault = getGlobalDefault(agentId);
+                if (globalDefault) {
+                    console.log(chalk.gray(`  Your default ${agentConfig.cliCommand} is still ${globalDefault}; ${agentConfig.configDir} is untouched.`));
+                }
+                else {
+                    console.log(chalk.gray(`  ${agentConfig.configDir} and your ${agentConfig.cliCommand} launcher are untouched.`));
+                }
                 return;
             }
             if (options.project) {

package/dist/commands/view.js

@@ -4,13 +4,13 @@ import { visibleWidth, termLink } from '../lib/format.js';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanagedCliState, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, formatCheckedAge, readAuthHealthCache } from '../lib/auth-health.js';
 import { agentReportsUsage, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { resolveVersionFilter, AgentSpecError } from '../lib/agent-spec/index.js';
@@ -243,9 +243,27 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         ? `Checking ${agentLabel(filterAgentId)} agents...`
         : 'Checking installed agents...';
     const spinner = ora({ text: spinnerText, isSilent: !process.stdout.isTTY }).start();
-    const cliStates = await getAllCliStates();
-    spinner.stop();
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
+    // A globally-installed CLI is superseded only by a NORMAL managed version — that
+    // is when agents-cli owns the launcher and a "global" row would just be our own
+    // shim reported back. `--isolated` promises the opposite: no default, no bare
+    // shim, no adopted launcher, the user's own `~/.<agent>` untouched. So an
+    // isolated-only install must not make that still-live global CLI disappear from
+    // `agents view` — the two are genuinely separate installs and both get listed.
+    const hasNonIsolatedVersion = (agentId) => listInstalledVersions(agentId).some((v) => !isVersionIsolated(agentId, v));
+    // Every `cliStates` read in this function feeds the "Not Managed by Agents CLI"
+    // block, so resolve it the way that block means it: the user's own CLI on PATH.
+    // `getCliState` would answer with a version-dir install — including an isolated
+    // copy that is deliberately absent from PATH — and print it as "(global)".
+    //
+    // Resolved only for agents that can actually reach that block. `getCliState`
+    // deliberately avoids subprocesses for a version-managed agent, and PATH
+    // resolution costs a `<cli> --version` spawn on a cold cache — so probing an
+    // agent whose global row is suppressed anyway would be pure added latency.
+    const cliStates = Object.fromEntries(await Promise.all(agentsToShow
+        .filter((agentId) => !hasNonIsolatedVersion(agentId))
+        .map(async (agentId) => [agentId, await getUnmanagedCliState(agentId)])));
+    spinner.stop();
     const showPaths = !!filterAgentId;
     const profilesByAgent = getProfilesByAgent(filterAgentId);
     const profileSummaries = [...profilesByAgent.values()].flat();
@@ -276,19 +294,18 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     const infoFetches = [];
     const globalInfoFetches = [];
     for (const agentId of agentsToShow) {
-        const versions = listInstalledVersions(agentId);
-        if (versions.length > 0) {
-            for (const ver of versions) {
-                const home = getVersionHomePath(agentId, ver);
-                infoFetches.push(getAccountInfo(agentId, home).then((info) => ({
-                    agentId,
-                    version: ver,
-                    home,
-                    info,
-                })));
-            }
+        for (const ver of listInstalledVersions(agentId)) {
+            const home = getVersionHomePath(agentId, ver);
+            infoFetches.push(getAccountInfo(agentId, home).then((info) => ({
+                agentId,
+                version: ver,
+                home,
+                info,
+            })));
         }
-        else {
+        // Mirrors the classification below: fetch the global account whenever the
+        // global install will still be rendered (no versions at all, or isolated-only).
+        if (!hasNonIsolatedVersion(agentId)) {
             globalInfoFetches.push(getAccountInfo(agentId).then((info) => ({
                 agentId,
                 cliVersion: cliStates[agentId]?.version || null,
@@ -356,10 +373,12 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         if (versions.length > 0) {
             versionManaged.push(agentId);
         }
-        else if (cliState?.installed) {
-            globallyInstalled.push(agentId);
+        if (cliState?.installed) {
+            // Isolated-only installs sit alongside the global CLI rather than replacing it.
+            if (!hasNonIsolatedVersion(agentId))
+                globallyInstalled.push(agentId);
         }
-        else if (hasProfiles) {
+        else if (versions.length === 0 && hasProfiles) {
             profileOnly.push(agentId);
         }
     }
@@ -376,6 +395,22 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             liveVersionByAgent.set(agentId, live);
     }));
     const displayVersion = (agentId, dirVersion) => liveVersionByAgent.get(agentId) ?? dirVersion;
+    // Uncolored row label, shared by the width pass and the render so padding lines
+    // up. An isolated copy is never the global default (installing one deliberately
+    // records no default), so the two tags can't collide.
+    const versionRowLabel = (agentId, version, globalDefault) => {
+        const shown = displayVersion(agentId, version);
+        if (version === globalDefault)
+            return `${shown} (default)`;
+        if (isVersionIsolated(agentId, version)) {
+            // The isolated default is what a bare `agents run <agent>` reaches, so it is
+            // worth distinguishing from the other isolated copies sitting beside it.
+            return getIsolatedDefault(agentId) === version
+                ? `${shown} (isolated default)`
+                : `${shown} (isolated)`;
+        }
+        return shown;
+    };
     // Show version-managed agents
     if (versionManaged.length > 0) {
         // Calculate column widths across all agents for alignment
@@ -388,9 +423,7 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             const versions = listInstalledVersions(agentId);
             const globalDefault = getGlobalDefault(agentId);
             for (const v of versions) {
-                const shown = displayVersion(agentId, v);
-                const label = v === globalDefault ? `${shown} (default)` : shown;
-                maxVerLabel = Math.max(maxVerLabel, label.length);
+                maxVerLabel = Math.max(maxVerLabel, versionRowLabel(agentId, v, globalDefault).length);
                 const rawInfo = infoMap.get(`${agentId}:${v}`);
                 const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const accountLabel = accountColumnLabel(info);
@@ -431,7 +464,14 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             const globalDefault = getGlobalDefault(agentId);
             const runStrategy = getConfiguredRunStrategy(agentId);
             const strategyLabel = chalk.gray(` (${runStrategy})`);
-            const noDefaultLabel = !globalDefault ? chalk.yellow(' (no default)') : '';
+            // `(no default)` is a nudge to go set one. It would read as a contradiction
+            // directly above a row tagged `(isolated default)`, and it would be bad
+            // advice besides: for an isolated-only agent the pointer below IS how a
+            // bare `agents run <agent>` resolves, and setting a global default is
+            // precisely what `--isolated` exists to avoid.
+            const noDefaultLabel = !globalDefault && !getIsolatedDefault(agentId)
+                ? chalk.yellow(' (no default)')
+                : '';
             console.log(`  ${chalk.bold(agentLabel(agentId))}${strategyLabel}${noDefaultLabel}`);
             // Sort versions with default first, then by semver descending
             const sortedVersions = [...versions].sort((a, b) => {
@@ -443,10 +483,16 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             });
             for (const version of sortedVersions) {
                 const isDefault = version === globalDefault;
+                const isolated = !isDefault && isVersionIsolated(agentId, version);
+                const isolatedTag = getIsolatedDefault(agentId) === version ? ' (isolated default)' : ' (isolated)';
                 const shown = displayVersion(agentId, version);
-                const base = isDefault ? `${shown} (default)` : shown;
-                const padded = base.padEnd(maxVerLabel);
-                const label = isDefault ? `${shown}${chalk.green(' (default)')}${' '.repeat(maxVerLabel - base.length)}` : padded;
+                const base = versionRowLabel(agentId, version, globalDefault);
+                const tagPad = ' '.repeat(maxVerLabel - base.length);
+                const label = isDefault
+                    ? `${shown}${chalk.green(' (default)')}${tagPad}`
+                    : isolated
+                        ? `${shown}${chalk.gray(isolatedTag)}${tagPad}`
+                        : base.padEnd(maxVerLabel);
                 const rawInfo = infoMap.get(`${agentId}:${version}`);
                 const vInfo = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const usageKey = getUsageLookupKey(vInfo);
@@ -580,7 +626,9 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             // Profile rows under a globally-installed harness. Use a simpler
             // alignment here since this section doesn't share column state with
             // the version-managed block.
-            const profilesHere = profilesByAgent.get(agentId) ?? [];
+            // An isolated-only agent now appears in BOTH blocks; its profiles already
+            // rendered under the version-managed one, so don't print them twice.
+            const profilesHere = versionManaged.includes(agentId) ? [] : (profilesByAgent.get(agentId) ?? []);
             if (profilesHere.length > 0) {
                 const nameWidth = Math.max(globalMaxVerLabel, ...profilesHere.map((p) => p.name.length));
                 const authWidth = Math.max(...profilesHere.map((p) => p.auth.length));