@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/utils.js

@@ -1,9 +1,3 @@
-/**
- * Shared utilities for command implementations.
- *
- * Small helpers used across multiple commands: prompt cancellation detection,
- * table formatting, spinner management, and platform-specific workarounds.
- */
 import * as os from 'os';
 import { spawnSync } from 'child_process';
 import chalk from 'chalk';
@@ -12,13 +6,6 @@ import { confirm } from '@inquirer/prompts';
 import { agentLabel, resolveAgentName } from '../lib/agents.js';
 import { installVersion, listInstalledVersions, resolveAgentVersionTargets, resolveInstalledAgentTargets, } from '../lib/installations/versions.js';
 import { resolveListFilter, AgentSpecError } from '../lib/agent-spec/index.js';
-/**
- * Resolve a read/list command's `@version` filter through the agent-spec engine,
- * exiting cleanly on a bad spec. Drop-in for the old
- * `resolveVersionAlias(agent, parts[1])`:
- *   undefined → show all · @default/@pinned → the default version ·
- *   @latest/@oldest/@x.y.z → concrete.
- */
 export function resolveListFilterOrExit(agent, qualifier) {
     try {
         return resolveListFilter(agent, qualifier);
@@ -31,23 +18,8 @@ export function resolveListFilterOrExit(agent, qualifier) {
         throw e;
     }
 }
-// Defined in lib/format.ts so `lib/` callers don't have to import upward into
-// the command layer; re-exported here for the ~50 command-layer consumers.
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList } from '../lib/format.js';
 export { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList };
-/**
- * Compute a command's I/O surface once, in one place, instead of each command
- * re-deriving the human-vs-agent split (and raw-sniffing `process.std*.isTTY`
- * with inconsistent stream choices — the audit's R4). Reads the merged option
- * set via `optsWithGlobals()`, so it sees the command's own flags and any
- * inherited global ones, and folds in the terminal state:
- *
- *   - `assumeYes` = explicit `--yes` OR a non-interactive shell (no one to prompt).
- *   - `interactive` = a real TTY AND not `--json`.
- *
- * Adopt incrementally: a command switches its ad-hoc `isTTY`/`options.yes` checks
- * to a single `const s = resolveSurface(cmd)` without changing its flag surface.
- */
 export function resolveSurface(cmd) {
     const opts = cmd.optsWithGlobals();
     const tty = isInteractiveTerminal();
@@ -59,14 +31,6 @@ export function resolveSurface(cmd) {
         interactive: tty && !json,
     };
 }
-/**
- * Coerce a `--device` value that may arrive as a scalar or an array to a single
- * host string. A subcommand whose own `--device` collides in name with an
- * ancestor's variadic `-D, --device <target...>` (e.g. `sessions inject`,
- * `sessions resume` under the parent `sessions` command) can receive an array
- * even when the command only ever targets one device — fail loud on more than
- * one rather than guessing the first (PHNX-3688, PHNX-3940).
- */
 export function normalizeSingleDeviceOption(value, commandLabel) {
     const list = value == null ? [] : Array.isArray(value) ? value : [value];
     const hosts = list.map((v) => String(v).trim()).filter((v) => v.length > 0);
@@ -77,9 +41,6 @@ export function normalizeSingleDeviceOption(value, commandLabel) {
     }
     return hosts[0];
 }
-/**
- * Exit with a clean message when a picker would be required in a non-interactive shell.
- */
 export function requireInteractiveSelection(action, alternatives) {
     console.error(chalk.red(`${action} requires an interactive terminal.`));
     if (alternatives.length > 0) {
@@ -90,13 +51,6 @@ export function requireInteractiveSelection(action, alternatives) {
     }
     process.exit(1);
 }
-/**
- * Print a properly-cased "missing argument" error for destructive commands and
- * exit. Destructive commands (remove, disband, disable) deliberately do NOT
- * fall back to an interactive picker — typing the name is the safety check.
- *
- * Lists available items so the user can copy-paste, but never auto-selects.
- */
 export function requireDestructiveArg(opts) {
     const { argName, command, itemNoun, available, emptyHint } = opts;
     console.error(chalk.red(`Missing required argument: ${argName.toUpperCase()}`));
@@ -118,9 +72,6 @@ export function requireDestructiveArg(opts) {
     console.error(chalk.gray(`Tip: this is a destructive command, so you have to type the ${itemNoun} name explicitly.`));
     process.exit(2);
 }
-/**
- * Print long content directly in non-interactive shells, use a pager only for real terminals.
- */
 export function printWithPager(output, lineCount) {
     if (!isInteractiveTerminal() || lineCount <= 40) {
         process.stdout.write(output.endsWith('\n') ? output : `${output}\n`);
@@ -134,11 +85,6 @@ export function printWithPager(output, lineCount) {
         process.stdout.write(output.endsWith('\n') ? output : `${output}\n`);
     }
 }
-/**
- * Prompt user to select which agent/version targets to remove a resource from.
- * If only one target, returns it without prompting. If multiple, shows checkbox.
- * Returns empty array if user cancels or selects nothing.
- */
 export async function promptRemovalTargets(resourceName, targets, options) {
     if (targets.length === 0)
         return [];
@@ -166,9 +112,6 @@ export async function promptRemovalTargets(resourceName, targets, options) {
         throw err;
     }
 }
-/**
- * Format a path for display, using ~ for home directory
- */
 export function formatPath(fullPath, cwd) {
     const home = os.homedir();
     if (fullPath.startsWith(home)) {
@@ -180,27 +123,17 @@ export function formatPath(fullPath, cwd) {
     }
     return fullPath;
 }
-/**
- * Parse a --agents selector and collect every (agentId, specificVersion) pair
- * the user requested where the version is a concrete x.y.z (not `default`,
- * not `all`, not `latest`) and is NOT currently installed.
- *
- * This is the lookahead the auto-install wrappers use to decide whether to
- * prompt + install before delegating to resolveAgentVersionTargets.
- */
 function collectMissingVersions(value, availableAgents) {
     const missing = [];
     const seen = new Set();
     for (const raw of value.split(',').map((s) => s.trim()).filter(Boolean)) {
-        // Literal `all` / `all@all` expand to per-agent — never missing.
         if (raw === 'all' || raw === 'all@all')
             continue;
         const atIndex = raw.indexOf('@');
         if (atIndex === -1)
-            continue; // bare agent → resolves to default; never missing in this sense
+            continue;
         const agentToken = raw.slice(0, atIndex).trim();
         const versionToken = raw.slice(atIndex + 1).trim();
-        // Non-specific selectors handled by the underlying resolver.
         if (!versionToken || versionToken === 'default' || versionToken === 'all')
             continue;
         const agentId = resolveAgentName(agentToken);
@@ -217,12 +150,6 @@ function collectMissingVersions(value, availableAgents) {
     }
     return missing;
 }
-/**
- * Sequentially install every requested missing version with a per-version
- * spinner. Aborts via process.exit(1) on the first failure — the user
- * already approved the install so a partial-install outcome is worse than
- * a hard stop.
- */
 async function installMissingVersions(missing) {
     for (const { agentId, version } of missing) {
         const label = `${agentLabel(agentId)}@${version}`;
@@ -243,13 +170,6 @@ async function installMissingVersions(missing) {
         }
     }
 }
-/**
- * Make sure every specific `agent@x.y.z` the user typed is installed before
- * the caller resolves targets. Returns true if the caller should continue,
- * false if the user declined the prompt. Exported so non-standard caller
- * shapes (e.g. mcp.ts's manifest-shaped parser) can run the pre-flight
- * without going through resolveAgentVersionTargets first.
- */
 export async function ensureAgentVersionsInstalled(value, availableAgents, options = {}) {
     const missing = collectMissingVersions(value, availableAgents);
     if (missing.length === 0)
@@ -288,30 +208,16 @@ export async function ensureAgentVersionsInstalled(value, availableAgents, optio
     await installMissingVersions(missing);
     return true;
 }
-/**
- * Resolve a `--agents` selector and, if any requested `agent@version` isn't
- * installed yet, prompt to install it (or auto-install with --yes) before
- * delegating to resolveAgentVersionTargets. Returns null when the user
- * declines the install prompt — callers should treat that as a clean cancel.
- */
 export async function resolveAgentTargetsAutoInstalling(value, availableAgents, options = {}) {
     const ok = await ensureAgentVersionsInstalled(value, availableAgents, options);
     if (!ok)
         return null;
     return resolveAgentVersionTargets(value, availableAgents, { allVersions: options.allVersions });
 }
-/**
- * Same as resolveAgentTargetsAutoInstalling but returns the broader
- * InstalledAgentTargetResult that includes `directAgents` (for paths like
- * `agents install` and `sync --mcp` that fall through to unmanaged homes
- * when no managed version is installed).
- */
 export async function resolveInstalledAgentTargetsAutoInstalling(value, availableAgents, options = {}) {
     const ok = await ensureAgentVersionsInstalled(value, availableAgents, options);
     if (!ok)
         return null;
     return resolveInstalledAgentTargets(value, availableAgents, { allVersions: options.allVersions });
 }
-// Re-export so callers can `catch (err) { if (err instanceof VersionNotInstalledError) … }`
-// without reaching into ../lib/versions directly.
 export { VersionNotInstalledError } from '../lib/installations/versions.js';

package/dist/commands/versions.d.ts

@@ -1,22 +1,6 @@
-/**
- * Version management commands for installing, switching, and removing agent CLIs.
- *
- * Implements `agents add`, `agents prune`, `agents remove` (alias),
- * and `agents use`. Handles npm-based installation,
- * shim creation, config symlink
- * switching, resource sync prompts, and project-level version pinning.
- */
 import type { Command } from 'commander';
-/**
- * What `agents add <spec>` does with the harness's ONE managed installation
- * (PHNX-3940): with no managed install it installs one (label `main`); with
- * one, a bare spec reuses it and an explicit `@<release>` pins that same
- * install — exactly `agents update <agent> --to <release>`. A second home is
- * only ever an `--isolated` copy, which bypasses this plan entirely.
- */
 export declare function planManagedAdd(input: {
     explicitPin: boolean;
     managedInstalled: boolean;
 }): 'reuse' | 'pin' | 'install';
-/** Register `agents add`, `agents prune`, `agents remove`, and `agents use`. */
 export declare function registerVersionsCommands(program: Command): void;

package/dist/commands/versions.js

@@ -17,22 +17,11 @@ import { tryAutoPullSystemRepo } from '../lib/git.js';
 import { getAgentsDir, getTrashVersionsDir } from '../lib/state.js';
 import { setHelpSections } from '../lib/help.js';
 import { updateSessionFilePaths } from '../lib/session/db.js';
-/**
- * What `agents add <spec>` does with the harness's ONE managed installation
- * (PHNX-3940): with no managed install it installs one (label `main`); with
- * one, a bare spec reuses it and an explicit `@<release>` pins that same
- * install — exactly `agents update <agent> --to <release>`. A second home is
- * only ever an `--isolated` copy, which bypasses this plan entirely.
- */
 export function planManagedAdd(input) {
     if (!input.managedInstalled)
         return 'install';
     return input.explicitPin ? 'pin' : 'reuse';
 }
-/**
- * After removeVersion soft-deletes a version dir to trash, rewrite session
- * file_path entries in the DB so reads still work from the new trash location.
- */
 function fixSessionFilePaths(agent, version, oldVersionDir) {
     const trashAgentDir = path.join(getTrashVersionsDir(), agent, version);
     if (!fs.existsSync(trashAgentDir))
@@ -46,8 +35,6 @@ function fixSessionFilePaths(agent, version, oldVersionDir) {
 function formatAccountHint(info, usage, unverified = false, headless = false) {
     const parts = [];
     if (info.email) {
-        // Same-email accounts can live in different orgs (personal Max vs a Team
-        // seat) — the badge is what makes the picker disambiguate them.
         const badge = accountOrgBadge(info);
         parts.push(badge ? `${info.email} (${badge})` : info.email);
     }
@@ -114,16 +101,6 @@ function warnIfShimShadowed(agent) {
     console.log(chalk.green(`  Added shim directory to ${result.location}.`));
     console.log(chalk.gray(`  ${result.reloadHint}`));
 }
-/**
- * Install an isolated copy of an agent version: a fully self-contained install
- * that never touches the user's existing setup.
- *
- * Unlike a normal install it does NOT set (or offer to set) the global default,
- * does NOT create/replace the bare `<agent>` shim, does NOT back up or symlink
- * the user's real `~/.<agent>`, and does NOT carry over settings or resources.
- * It only creates the versioned alias (so the copy is launchable) and records
- * the isolated marker. Invoke the copy explicitly with `agents run <agent>@<v>`.
- */
 function finalizeIsolatedInstall(agent, version) {
     const agentConfig = AGENTS[agent];
     const label = agentLabel(agentConfig.id);
@@ -148,21 +125,12 @@ async function versionPruneAction(specs, options, commandName) {
         }
         const { agent, version } = parsed;
         const agentConfig = AGENTS[agent];
-        // --isolated only ever applies to agents that can BE installed isolated;
-        // for the rest no isolated version can exist, so say so plainly.
         if (isIsolated && !supportsIsolatedInstall(agent)) {
             console.log(chalk.gray(`${agentLabel(agentConfig.id)} has no isolated installs (--isolated is not supported for it).`));
             continue;
         }
-        // Script-installed agents (droid, grok) can have a *literal* `latest`
-        // version dir on disk when the post-install version probe failed. An
-        // explicit `<agent>@latest` should remove that dir directly rather than
-        // routing to the interactive picker (which can't run non-interactively),
-        // so treat an installed literal `latest` as a concrete pinned version.
         const isLiteralLatestInstalled = version === 'latest' && spec.includes('@') && isVersionInstalled(agent, 'latest');
         if (!isLiteralLatestInstalled && (version === 'latest' || version === 'oldest' || !spec.includes('@'))) {
-            // With --isolated, only isolated installs are eligible for the picker, so
-            // a normal/default install can never be selected here by accident.
             const versions = listInstalledVersions(agent)
                 .filter((v) => !isIsolated || isVersionIsolated(agent, v));
             if (versions.length === 0) {
@@ -211,8 +179,6 @@ async function versionPruneAction(specs, options, commandName) {
                     }
                     moved.push({ agent, version: v });
                 }
-                // Default reassignment/clearing is handled at the source in
-                // removeVersion() so it applies to every removal path uniformly.
                 const remaining = listInstalledVersions(agent);
                 if (remaining.length === 0) {
                     removeShim(agent);
@@ -230,9 +196,6 @@ async function versionPruneAction(specs, options, commandName) {
             console.log(chalk.gray(`${agentLabel(agentConfig.id)}@${version} not installed`));
         }
         else if (isIsolated && !isVersionIsolated(agent, version)) {
-            // Safety guard: `--isolated` refuses to remove a normal/default install,
-            // so an accidental `remove <agent>@<default> --isolated` can never delete
-            // the user's primary version or disturb their real ~/.<agent>.
             console.log(chalk.yellow(`${agentLabel(agentConfig.id)}@${version} is not an isolated install; refusing to remove it under --isolated.`));
             console.log(chalk.gray(`  Drop --isolated to remove a normal version: agents ${commandName} ${agent}@${version}`));
         }
@@ -300,7 +263,6 @@ function configureVersionPruneCommand(cmd, commandName) {
     });
     cmd.action((specs, options) => versionPruneAction(specs, options, commandName));
 }
-/** Register `agents add`, `agents prune`, `agents remove`, and `agents use`. */
 export function registerVersionsCommands(program) {
     const addCmd = program
         .command('add <specs...>')
@@ -361,14 +323,6 @@ export function registerVersionsCommands(program) {
                 continue;
             }
             warnAgentDeprecated(agent);
-            // Isolation relies on a config-dir env var to redirect the copy away
-            // 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.`));
@@ -389,23 +343,12 @@ export function registerVersionsCommands(program) {
                 console.log(chalk.yellow(`${agentLabel(agentConfig.id)} has no npm package. Install manually.`));
                 continue;
             }
-            // One managed installation per harness (PHNX-3940): bare `agents add`
-            // installs it (label `main`) or reuses the one already there, and
-            // `<harness>@<release>` pins that SAME install — exactly
-            // `agents update <harness> --to <release>`. A second home exists only
-            // as an --isolated copy, which keeps its own release-labelled flow.
             let installedAsVersion = version;
             const managed = isIsolated ? null : resolveManagedInstallation(agent);
-            // `<harness>@main` (or @<the managed label>) names the installation
-            // itself, not a release: it reads as the bare form — reuse when
-            // present, install latest into `main` when absent — never an
-            // `npm install <pkg>@main` guessing at a registry tag.
             const namesManagedLabel = version === MANAGED_INSTALLATION_LABEL || (managed !== null && version === managed.label);
             const addPlan = planManagedAdd({ explicitPin: spec.includes('@') && !namesManagedLabel, managedInstalled: managed !== null });
             if (addPlan === 'pin' && managed) {
                 if (version !== 'latest' && !supportsPinnedUpdate(agent)) {
-                    // Fail loud at the boundary rather than updating to the current
-                    // release and reporting it as the pin that was asked for.
                     console.log(chalk.red(`${agentLabel(agentConfig.id)} is a single self-updating binary with no pinnable releases — drop the @${version}, or use @latest.`));
                     process.exitCode = 1;
                     continue;
@@ -437,7 +380,6 @@ export function registerVersionsCommands(program) {
                 console.log(chalk.gray(`${agentLabel(agentConfig.id)} is already installed. Your account home is unchanged.`));
                 console.log(chalk.gray(`  Accounts: agents view ${agent}. Update now: agents update ${agent}.`));
                 installedAsVersion = managed.label;
-                // Ensure shim exists (in case it was deleted or needs updating)
                 createShim(agent);
             }
             else if (isIsolated) {
@@ -461,14 +403,10 @@ export function registerVersionsCommands(program) {
                 }
                 if (alreadyInstalled) {
                     if (!isVersionIsolated(agent, installedAsVersion)) {
-                        // A normal and an isolated install of the SAME version share one
-                        // on-disk dir, so they can't coexist. Refuse rather than silently
-                        // convert the user's existing (possibly default) install.
                         console.log(chalk.yellow(`${agentLabel(agentConfig.id)}@${installedAsVersion} is already installed as a normal (default-eligible) version.`));
                         console.log(chalk.gray(`  Remove it first (agents remove ${agent}@${installedAsVersion}) then re-add with --isolated, or pick a different version.`));
                         continue;
                     }
-                    // Already isolated: re-affirm the alias + marker idempotently.
                     finalizeIsolatedInstall(agent, installedAsVersion);
                     continue;
                 }
@@ -481,10 +419,6 @@ export function registerVersionsCommands(program) {
                     console.error(chalk.gray(redactSecrets(result.error || 'Unknown error')));
                     continue;
                 }
-                // Isolated installs stop here: no bare shim, no settings carry-over,
-                // no resource sync, no default switch, no PATH edits. Just a
-                // launchable versioned alias + the isolated marker, leaving the
-                // user's real ~/.<agent> and default untouched.
                 finalizeIsolatedInstall(agent, result.installedVersion || version);
                 continue;
             }
@@ -508,19 +442,11 @@ export function registerVersionsCommands(program) {
                     const installedModel = resolveConfiguredModel(agentConfig.id, ensured.installation.releaseVersion)?.model;
                     const installedIdentity = formatAgentIdentity(`${agentLabel(agentConfig.id)}@${installedVersion}`, installedModel ? chalk.yellow(installedModel) : null);
                     spinner.succeed(`Installed ${installedIdentity}`);
-                    // The project pin below names the installation, never the release
-                    // inside it — the release moves on update, the label is frozen.
                     installedAsVersion = installedVersion;
-                    // Create shim if first install
                     if (!shimExists(agent)) {
                         createShim(agent);
                         console.log(chalk.gray(`  Created shim: ${getShimsDir()}/${agentConfig.cliCommand}`));
                     }
-                    // Seed the fresh version home with user settings from the current
-                    // default version (settings.json, keybindings, codex config).
-                    // Credentials are deliberately excluded so each version keeps its own
-                    // login (see SETTINGS_MANIFEST). Gap-filling only — never overwrites
-                    // what the new home has.
                     const carrySource = getGlobalDefault(agent);
                     if (carrySource && carrySource !== installedVersion) {
                         const carried = carryForwardSettings(agent, getVersionHomePath(agent, carrySource), getVersionHomePath(agent, installedVersion));
@@ -528,7 +454,6 @@ export function registerVersionsCommands(program) {
                             console.log(chalk.gray(`  Carried settings from ${agent}@${carrySource}: ${carried.applied.map(r => path.basename(r)).join(', ')}`));
                         }
                     }
-                    // Smart resource detection: compare available vs ACTUALLY synced (source of truth: files)
                     const available = getAvailableResources();
                     const actuallySynced = getActuallySyncedResources(agent, installedVersion);
                     const newResources = getNewResources(available, actuallySynced, getProjectOnlyResources());
@@ -550,20 +475,17 @@ export function registerVersionsCommands(program) {
                             }
                         }
                         else if (!hasAnySynced) {
-                            // Nothing synced yet - prompt for ALL resources
                             const userSelection = await promptResourceSelection(agent);
                             if (userSelection) {
                                 selection = userSelection;
                             }
                         }
                         else if (hasNewResources(newResources, agent, installedVersion)) {
-                            // Some synced, but NEW resources available - prompt for new only
                             const userSelection = await promptNewResourceSelection(agent, newResources, installedVersion);
                             if (userSelection) {
                                 selection = userSelection;
                             }
                         }
-                        // else: everything already synced, no prompt needed
                     }
                     catch (err) {
                         if (isPromptCancelled(err)) {
@@ -573,7 +495,6 @@ export function registerVersionsCommands(program) {
                             throw err;
                         }
                     }
-                    // Sync resources if user made a selection
                     if (selection && Object.keys(selection).length > 0) {
                         const syncResult = syncResourcesToVersion(agent, installedVersion, selection);
                         const synced = [];
@@ -595,11 +516,9 @@ export function registerVersionsCommands(program) {
                             console.log(chalk.green(`  Synced: ${synced.join(', ')}`));
                         }
                     }
-                    // Set as default: auto-set if no default exists, otherwise prompt
                     const currentDefault = getGlobalDefault(agent);
                     if (currentDefault !== installedVersion) {
                         if (!currentDefault) {
-                            // First install for this agent - auto-set without prompting
                             await setDefaultVersion(agent, installedVersion);
                         }
                         else if (skipPrompts) {
@@ -607,7 +526,6 @@ export function registerVersionsCommands(program) {
                         }
                         else {
                             try {
-                                // Fetch account info for context in the prompt
                                 const home = getVersionHomePath(agent, installedVersion);
                                 const info = await getAccountInfo(agent, home);
                                 const usage = await getUsageInfoForIdentity({
@@ -616,9 +534,6 @@ export function registerVersionsCommands(program) {
                                     cliVersion: installedVersion,
                                     info,
                                 });
-                                // This hint sits in a "switch your default to this version?"
-                                // confirm — the one place a stale reading directly steers a
-                                // choice, so it must not present an unconfirmed bar as fact.
                                 const headless = isUsageHeadlessScopeError(usage.error);
                                 const accountHint = formatAccountHint(info, usage.snapshot, !headless && !!usage.snapshot && !!usage.error, headless);
                                 const message = `Switch default from ${agentLabel(agentConfig.id)}@${currentDefault} to ${agentLabel(agentConfig.id)}@${installedVersion}${accountHint}?`;
@@ -640,7 +555,6 @@ export function registerVersionsCommands(program) {
                             }
                         }
                     }
-                    // Auto-add shims to PATH if not already there
                     if (!isShimsInPath()) {
                         const pathResult = addShimsToPath();
                         if (pathResult.success && !pathResult.alreadyPresent) {
@@ -654,7 +568,6 @@ export function registerVersionsCommands(program) {
                     }
                 }
             }
-            // Update project manifest if -p flag
             if (isProject) {
                 const projectManifestDir = path.join(process.cwd(), '.agents');
                 const projectManifestPath = path.join(projectManifestDir, 'agents.yaml');
@@ -665,9 +578,6 @@ export function registerVersionsCommands(program) {
                     ? readManifest(process.cwd()) || createDefaultManifest()
                     : createDefaultManifest();
                 manifest.agents = manifest.agents || {};
-                // A project pin names the installation (its frozen label), never the
-                // release inside it — the release moves on update, the label is what
-                // every resolver reads back.
                 manifest.agents[agent] = installedAsVersion;
                 writeManifest(process.cwd(), manifest);
                 console.log(chalk.green(`  Pinned ${agentLabel(agentConfig.id)}@${installedAsVersion} in .agents/agents.yaml`));
@@ -675,9 +585,6 @@ export function registerVersionsCommands(program) {
         }
     });
     configureVersionPruneCommand(program.command('prune <specs...>'), 'prune');
-    // `rm` and `purge` are commander aliases for `remove` (which is itself an
-    // alias for `prune`). Native `.aliases()` keeps them in lockstep — same
-    // action, same options, no duplicate registration.
     configureVersionPruneCommand(program.command('remove <specs...>', { hidden: true }).aliases(['rm', 'purge']), 'remove');
     const useCmd = program
         .command('use <agent> [version]')
@@ -704,10 +611,6 @@ export function registerVersionsCommands(program) {
     useCmd.action(async (agentArg, versionArg, options) => {
         try {
             const skipPrompts = options.yes || !isInteractiveTerminal();
-            // Auto-pull ~/.agents/.system if it's a git repo tracking the EXPECTED
-            // system remote (silent on success). The system repo ships hooks that run
-            // as shell on tool events, so pulling from a repointed origin would be
-            // remote code execution — tryAutoPullSystemRepo refuses that (PHNX-2957).
             const agentsDir = getAgentsDir();
             const pullResult = await tryAutoPullSystemRepo(agentsDir);
             if (pullResult.refused) {
@@ -718,7 +621,6 @@ export function registerVersionsCommands(program) {
             else if (pullResult.pulled) {
                 console.log(chalk.gray('Synced ~/.agents/.system from remote'));
             }
-            // Support both "claude 2.0.65" and "claude@2.0.65" formats
             let agent;
             let version;
             if (agentArg.includes('@')) {
@@ -745,10 +647,6 @@ export function registerVersionsCommands(program) {
             const agentConfig = AGENTS[agentId];
             let selectedVersion = version;
             if (!version) {
-                // Interactive version picker. Isolated installs are walled off from the
-                // real ~/.<agent> on purpose, so they must never be selectable here —
-                // setting one as the default would repoint the real config at it. Filter
-                // them out (same as the `remove` picker), leaving only usable versions.
                 const versions = listInstalledVersions(agentId).filter((v) => !isVersionIsolated(agentId, v));
                 if (versions.length === 0) {
                     console.log(chalk.red(`No versions of ${agentLabel(agentConfig.id)} installed`));
@@ -762,7 +660,6 @@ export function registerVersionsCommands(program) {
                     ]);
                 }
                 const globalDefault = getGlobalDefault(agentId);
-                // Sort versions with default first
                 const sortedVersions = [...versions].sort((a, b) => {
                     if (a === globalDefault)
                         return -1;
@@ -770,7 +667,6 @@ export function registerVersionsCommands(program) {
                         return 1;
                     return 0;
                 });
-                // Pre-fetch account info for picker labels and usage identity lookup
                 const pickerAccounts = await Promise.all(sortedVersions.map((v) => getAccountInfo(agentId, getVersionHomePath(agentId, v)).then((info) => ({ v, info }))));
                 const pickerAccountMap = new Map(pickerAccounts.map(({ v, info }) => [v, info]));
                 const { usageByKey } = await getUsageInfoByIdentity(pickerAccounts.map(({ v, info }) => ({
@@ -815,20 +711,7 @@ export function registerVersionsCommands(program) {
                 console.log(chalk.gray(`Run: agents add ${agentId}@${selectedVersion ?? 'latest'}`));
                 return;
             }
-            // selectedVersion is guaranteed to be defined after the check above
             const finalVersion = selectedVersion;
-            // An isolated install is deliberately walled off from the real
-            // ~/.<agent>. `agents use` would repoint the real config symlink at it
-            // (switchConfigSymlink) and carry settings forward INTO it
-            // (carryForwardSettings) — a direct breach of the isolation guarantee.
-            // 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)) {
                 if (options.project) {
                     console.log(chalk.yellow(`${agentLabel(agentConfig.id)}@${finalVersion} is an isolated install; --project pins are for shared versions.`));
@@ -848,7 +731,6 @@ export function registerVersionsCommands(program) {
                 return;
             }
             if (options.project) {
-                // Set in project manifest
                 const projectManifestDir = path.join(process.cwd(), '.agents');
                 const projectManifestPath = path.join(projectManifestDir, 'agents.yaml');
                 if (!fs.existsSync(projectManifestDir)) {
@@ -866,11 +748,9 @@ export function registerVersionsCommands(program) {
                 console.log(`Set ${projIdentity} for this project`);
             }
             else {
-                // Smart resource detection: compare available vs ACTUALLY synced (source of truth: files, not tracking)
                 const available = getAvailableResources();
                 const actuallySynced = getActuallySyncedResources(agentId, finalVersion);
                 const newResources = getNewResources(available, actuallySynced, getProjectOnlyResources());
-                // Check if anything is actually synced (source of truth: actual files)
                 const hasAnySynced = actuallySynced.commands.length > 0 ||
                     actuallySynced.skills.length > 0 ||
                     actuallySynced.hooks.length > 0 ||
@@ -909,7 +789,6 @@ export function registerVersionsCommands(program) {
                         }
                     }
                     else if (!hasAnySynced) {
-                        // First time: prompt for ALL resources
                         console.log(chalk.yellow(`\n${agentLabel(agentConfig.id)}@${finalVersion} has no synced resources.`));
                         const userSelection = await promptResourceSelection(agentId);
                         if (userSelection && Object.keys(userSelection).length > 0) {
@@ -935,7 +814,6 @@ export function registerVersionsCommands(program) {
                         }
                     }
                     else if (hasNewResources(newResources, agentId, finalVersion)) {
-                        // Has synced before, but NEW items available
                         const userSelection = await promptNewResourceSelection(agentId, newResources, finalVersion);
                         if (userSelection && Object.keys(userSelection).length > 0) {
                             const syncResult = syncResourcesToVersion(agentId, finalVersion, userSelection);
@@ -959,7 +837,6 @@ export function registerVersionsCommands(program) {
                             }
                         }
                     }
-                    // else: everything already synced, no prompt needed
                 }
                 catch (err) {
                     if (isPromptCancelled(err)) {
@@ -971,9 +848,6 @@ export function registerVersionsCommands(program) {
                     }
                 }
                 const previousDefault = getGlobalDefault(agentId);
-                // Carry user settings from the outgoing default into the target
-                // version home before switching. Gap-filling only, so versions that
-                // already have their own settings are left untouched.
                 if (previousDefault && previousDefault !== finalVersion) {
                     const carried = carryForwardSettings(agentId, getVersionHomePath(agentId, previousDefault), getVersionHomePath(agentId, finalVersion));
                     if (carried.applied.length > 0) {
@@ -983,13 +857,9 @@ export function registerVersionsCommands(program) {
                         }
                     }
                 }
-                // Set global default
                 setGlobalDefault(agentId, finalVersion);
-                // Regenerate shim so it uses the latest script format
                 createShim(agentId);
                 createVersionedAlias(agentId, finalVersion);
-                // Switch config symlink (e.g., ~/.claude -> version's config)
-                // No conflict prompts - just backup existing config if needed
                 const symlinkResult = await switchConfigSymlink(agentId, finalVersion);
                 if (!symlinkResult.success) {
                     console.log(chalk.yellow(`Warning: Could not update config symlink: ${symlinkResult.error}`));
@@ -997,16 +867,12 @@ export function registerVersionsCommands(program) {
                 else if (symlinkResult.backupPath) {
                     console.log(chalk.gray(`Backed up existing config to: ${symlinkResult.backupPath}`));
                 }
-                // Switch home-level files (e.g., ~/.claude.json -> version's auth file)
                 switchHomeFileSymlinks(agentId, finalVersion);
                 warnIfShimShadowed(agentId);
                 const useEmail = await getAccountEmail(agentId, getVersionHomePath(agentId, finalVersion));
                 const useModel = resolveConfiguredModel(agentId, finalVersion)?.model;
                 const useModelStr = useModel ? chalk.yellow(useModel) : null;
                 const useAcctStr = useEmail ? chalk.cyan(useEmail) : null;
-                // Self-updating agents are one binary; `use` only swaps the config
-                // symlink (the profile), it does not change which binary runs — so say
-                // "profile", not "version", to match what actually happened.
                 if (isSelfUpdatingAgent(agentId)) {
                     const identity = formatAgentIdentity(chalk.green(agentLabel(agentConfig.id)), useModelStr, useAcctStr);
                     console.log(`Switched ${identity} to config profile ${chalk.green(finalVersion)}`);