@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/commands/view.js

@@ -1,11 +1,3 @@
-/**
- * View command for inspecting installed agents, versions, accounts, and resources.
- *
- * Implements `agents view` -- shows installed agent CLIs with version info,
- * account emails, usage stats, and active status. When given an agent@version
- * argument, displays a detailed breakdown of commands, skills, MCP servers,
- * rules, hooks, and promptcuts synced to that version.
- */
 import { Option } from 'commander';
 import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
@@ -48,29 +40,15 @@ import { renderHarnessDetail } from './harness.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
-/** Shared account identity formatter, re-exported for the view-specific tests. */
 export const accountColumnLabel = accountDisplayLabel;
-/**
- * The account column with the durable native-account name folded in: when the
- * signed-in identity of `agentId` has been named via `agents accounts add`,
- * render `work · email` instead of the bare email. Falls back to the plain
- * display label when the identity is unnamed.
- */
 export function namedAccountColumnLabel(agentId, info) {
     const display = accountColumnLabel(info);
     const saved = findNativeAccountByIdentity(readMeta(), agentId, info);
     return saved ? `${saved.name} · ${display || saved.identityLabel || saved.identityKey}` : display;
 }
-/** Human account identity; release labels belong only in installation diagnostics. */
 export function nativeAccountViewLabel(row) {
     return row.name && row.name !== row.display ? `${row.name} · ${row.display}` : row.display;
 }
-/**
- * Human `agents view` row order: selected default first, then email-bearing
- * accounts alphabetically, then installs whose account has no email. Version
- * descending is the deterministic tie-breaker and preserves the old order for
- * every non-email harness.
- */
 export function compareAccountOrderedVersions(a, b, globalDefault) {
     const aIsDefault = a.version === globalDefault;
     const bIsDefault = b.version === globalDefault;
@@ -89,28 +67,15 @@ export function compareAccountOrderedVersions(a, b, globalDefault) {
     }
     return compareVersions(b.version, a.version);
 }
-/**
- * Join fixed view columns with a consistent two-space gutter. Empty trailing
- * columns are dropped so a row without an auth chip does not grow a dangling
- * gutter, but interior empties stay padded so later columns stay aligned.
- */
 export function joinViewColumns(cols) {
-    // Trim only pure-trailing empty strings so auth/status can be absent without
-    // shifting earlier columns for rows that do carry them.
     let end = cols.length;
     while (end > 0 && cols[end - 1] === '')
         end--;
     return cols.slice(0, end).join('  ');
 }
-/**
- * Custom harnesses (the `~/.agents/profiles/*.yml` bundles), sorted by name.
- * YAMLs that fail validation are silently skipped by `listProfiles`, so this
- * never throws on a malformed file.
- */
 function getHarnesses() {
     return listProfiles().map(profileSummary);
 }
-/** Version-first label: "<version> (forked from <host>[, tracks default])" */
 function harnessVersionLabel(harness, globalDefault) {
     const version = harness.hostVersion ?? globalDefault;
     if (version) {
@@ -123,7 +88,6 @@ function harnessVersionLabel(harness, globalDefault) {
     }
     return chalk.gray(`(forked from ${harness.agent})`);
 }
-/** One-hop or two-hop fork origin label for the harness block header. */
 function buildHarnessOrigin(harness, allHarnesses) {
     if (!harness.forkedFrom || harness.forkedFrom === harness.agent)
         return 'custom';
@@ -133,12 +97,6 @@ function buildHarnessOrigin(harness, allHarnesses) {
     }
     return `custom · forked from ${harness.forkedFrom}`;
 }
-/**
- * Resolve a resource path to something the IDE can open inline. When `p` is a
- * directory, OSC 8 file:// links cause IDEs (Cursor/VS Code) to open it as a
- * new workspace window; pointing at the bundle's marker file (SKILL.md /
- * WORKFLOW.md / AGENT.md) opens in the current window instead.
- */
 function linkTarget(p) {
     try {
         if (!fs.statSync(p).isDirectory())
@@ -197,11 +155,6 @@ function getProjectVersionFromCwd(agent) {
     }
 }
 const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts', 'clis'];
-/**
- * Decide whether a section should render given the filter. If no flags are set,
- * everything renders (current behavior). If any flag is set, only those sections
- * render — flags are additive.
- */
 function shouldRenderSection(key, filter) {
     if (!filter)
         return true;
@@ -210,7 +163,6 @@ function shouldRenderSection(key, filter) {
         return true;
     return filter[key] === true;
 }
-/** Trim a description to a column-friendly snippet. Strips newlines, collapses whitespace. */
 export function summarizeDescription(desc, maxLen = 80) {
     if (!desc)
         return '';
@@ -224,16 +176,6 @@ export function descriptionForPrefix(desc, prefix) {
     const budget = Math.max(1, terminalWidth() - stringWidth(visiblePrefix));
     return summarizeDescription(desc, budget);
 }
-/**
- * Render custom harnesses as their own agent-type blocks — peers of the native
- * Claude/Codex blocks, not indented rows under the host CLI that executes them.
- * `agents run <name>` already treats a custom harness like a native agent id, so
- * `agents view` lists it the same way: a bold name header, then one row carrying
- * the model, the account/auth state, and the host it runs on.
- *
- * `installedHosts` is the set of agent ids with a usable install; a harness whose
- * host is missing is flagged rather than silently listed as runnable.
- */
 export function renderHarnessBlocks(harnesses, installedHosts, showPaths, byokMap) {
     if (harnesses.length === 0)
         return;
@@ -256,11 +198,6 @@ export function renderHarnessBlocks(harnesses, installedHosts, showPaths, byokMa
         console.log();
     }
 }
-/**
- * Show installed versions for one or all agents.
- * Called when: `agents view` or `agents view claude`
- */
-/** Color the source-layer tag for a host CLI, matching the rules-section convention. */
 function hostCliSourceTag(source) {
     if (source === 'project')
         return chalk.blue('[project]');
@@ -268,17 +205,8 @@ function hostCliSourceTag(source) {
         return chalk.cyan('[user]');
     if (source === 'system')
         return chalk.gray('[system]');
-    // Anything else is an extra repo, tagged by its alias.
     return chalk.magenta(`[${source}]`);
 }
-/**
- * Render the host-CLI section. Host CLIs are host-global: declared in any
- * DotAgents repo's `clis/` (project > user > system > extras), installed to PATH
- * rather than copied into a version home. They render identically in the overview
- * and in a per-agent detail view because every agent on the host shares them.
- * The source tag shows which repo layer declared each — so user-level and
- * extra-repo manifests are visibly supported.
- */
 function renderHostClisSection(cwd) {
     const { statuses, errors } = listCliStatus(cwd);
     console.log(chalk.bold('\nHost CLIs\n'));
@@ -307,27 +235,9 @@ function renderHostClisSection(cwd) {
         console.log(`  ${chalk.red('error')}      ${chalk.gray(err.file)}: ${chalk.gray(err.reason)}`);
     }
 }
-/**
- * The USAGE-READ-2 decision, isolated from its runtime inputs so it can be
- * tested directly: a usage read may fall through to the interactive OAuth login
- * ONLY for a foreground human render on a headed device (`personal` or
- * `desktop`). Both conditions are required — role alone is not sufficient.
- */
 export function allowInteractiveUsageLogin(role, isTTY) {
     return isHeadedDeviceRole(role) && isTTY === true;
 }
-/**
- * Whether this `agents view` invocation may fall through to the interactive
- * OAuth login for a usage read (USAGE-READ-2). True only for a foreground human
- * render on a headed device (`personal` or `desktop`): the interactive login is
- * the sole credential carrying the `user:profile` scope the usage endpoint needs,
- * and a human
- * running one command is not the unattended-loop revocation risk RUSH-1822
- * fixed. The `--json` path never reaches these render functions (it returns
- * early via `collectAgentsJson`), and a non-TTY (piped/scripted) run is excluded
- * here too, so a machine reader can never silently acquire the interactive
- * credential — role alone is not sufficient.
- */
 function usageAllowInteractiveLogin() {
     return allowInteractiveUsageLogin(selfConfiguredDeviceRole(), process.stdout.isTTY === true);
 }
@@ -337,39 +247,13 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         : 'Checking installed agents...';
     const spinner = ora({ text: spinnerText, isSilent: !process.stdout.isTTY }).start();
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
-    // Overview caps meter count; single-agent view shows every blocking window.
     const usageWindowCap = filterAgentId ? undefined : OVERVIEW_MAX_USAGE_WINDOWS;
-    // 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)])));
     const showPaths = !!filterAgentId && viewOpts?.versions === true;
-    // A filtered native view is about that native harness's installed versions.
-    // Custom forks are standalone agent types and only belong in the overview.
     const harnesses = filterAgentId ? [] : getHarnesses();
-    // Auto-heal stale versioned aliases. Pre-v2 aliases (e.g. pre-CLAUDE_CONFIG_DIR
-    // claude shims) silently route login through the default version's symlinked
-    // home, so `agents view` would never reflect the right account. Regenerate on
-    // sight — it's safe, idempotent, and fixes the symptom exactly where the user
-    // notices it.
-    // Yield between agents so the heal loop doesn't block the event loop as one
-    // long sync burst — per-version readFileSync+writeFileSync across 5 agents
-    // can otherwise stall spinners and stdout flushes.
     const healedAliases = [];
     for (const agentId of agentsToShow) {
         await new Promise((resolve) => setImmediate(resolve));
@@ -380,10 +264,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             }
         }
     }
-    // Shim healing is silent — users don't need to know about internal repairs
-    // Pre-fetch account info for all versions in parallel. Spinner stays up through
-    // account + usage so a multi-account cold path doesn't leave a blank terminal
-    // after "Checking…" vanishes (the hang the screenshots caught).
     spinner.text = filterAgentId
         ? `Loading ${agentLabel(filterAgentId)} accounts...`
         : 'Loading accounts and usage...';
@@ -399,8 +279,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 info,
             })));
         }
-        // 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,
@@ -411,7 +289,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     }
     const infoResults = await Promise.all(infoFetches);
     const globalInfoResults = await Promise.all(globalInfoFetches);
-    // Build lookup: agentId:version -> AccountInfo
     const infoMap = new Map();
     for (const { agentId, version, info } of infoResults) {
         infoMap.set(`${agentId}:${version}`, info);
@@ -420,11 +297,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     for (const { agentId, info } of globalInfoResults) {
         globalInfoMap.set(agentId, info);
     }
-    // Usage status, plan, and overage credits belong to the same underlying account
-    // or org scope, not a specific installed version. Version homes cache those
-    // values independently, so older installs can show stale values. Reuse the
-    // freshest cache entry per stable usage identity and keep lastActive per version.
-    // Goes through the unified usage core (SWR cache + concurrency cap + timeout).
     const { canonicalByUsageKey, usageByKey } = await getUsageInfoByIdentity([
         ...infoResults.map(({ agentId, home, version, info }) => ({
             agentId,
@@ -452,19 +324,11 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             return info;
         return {
             ...info,
-            // Prefer a plan the live usage fetch surfaced (Kimi reports membership
-            // tier in /usages; its local auth file has none) and fall back to the
-            // account-derived plan (Claude's billingType).
             plan: usageByKey.get(key)?.snapshot?.plan ?? canon.plan,
-            // Throttle state comes from the live usage windows, not the pay-as-you-go
-            // overage flag that AccountInfo.usageStatus used to carry. A maxed window
-            // means rate-limited; no snapshot means no badge. See
-            // deriveUsageStatusFromSnapshot.
             usageStatus: deriveUsageStatusFromSnapshot(usageByKey.get(key)?.snapshot),
             overageCredits: canon.overageCredits,
         };
     };
-    // Separate version-managed from globally-installed agents
     const versionManaged = [];
     const globallyInstalled = [];
     for (const agentId of agentsToShow) {
@@ -474,18 +338,11 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             versionManaged.push(agentId);
         }
         if (cliState?.installed) {
-            // Isolated-only installs sit alongside the global CLI rather than replacing it.
             if (!hasNonIsolatedVersion(agentId))
                 globallyInstalled.push(agentId);
         }
     }
-    // A custom harness runs through its host CLI, so it is only launchable when
-    // that host has an install of some kind.
     const installedHosts = new Set([...versionManaged, ...globallyInstalled]);
-    // For self-updating global-binary agents (droid) the on-disk version-dir name
-    // is a stale label — the real version is whatever `<cli> --version` reports.
-    // Resolve it once so every row/width pass shows the live version, while the
-    // per-version home + account lookups keep using the real dir name.
     const liveVersionByAgent = new Map();
     await Promise.all(versionManaged
         .filter((agentId) => isGlobalBinaryAgent(agentId))
@@ -495,24 +352,18 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             liveVersionByAgent.set(agentId, live);
     }));
     const displayVersion = (agentId, dirVersion) => liveVersionByAgent.get(agentId) ?? readInstallation(agentId, dirVersion)?.releaseVersion ?? 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 release = displayVersion(agentId, version);
         const shown = release === version ? version : `${version} → ${release}`;
         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 && !viewOpts?.versions) {
         const catalog = await loadAccountCatalog();
         const note = secretsUnavailableNote(catalog);
@@ -527,7 +378,7 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                     updateLabel = `automatic updates ${isAutoUpdateEnabledForAgent(agentId) ? 'on' : 'off'}`;
                 }
             }
-            catch { /* unsupported updater: keep the truthful manual label */ }
+            catch { }
             console.log(`  ${chalk.bold(agentLabel(agentId))}${chalk.gray(` · ${updateLabel}`)}`);
             if (accounts.length > 0 || providers.length > 0) {
                 console.log(renderAccountRows(accounts, {
@@ -558,19 +409,14 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         if (filterAgentId) {
             console.log(chalk.gray(`  Add an account: agents accounts add ${filterAgentId} [name]`));
         }
-        // Overview renders the same account rows with footer:false, so both paths
-        // need the legend the shared renderer would otherwise have printed.
         console.log(chalk.gray(`  ${ACCOUNT_LISTING_LEGEND}\n`));
     }
     if (versionManaged.length > 0 && viewOpts?.versions) {
-        // Calculate column widths across all agents for alignment
         let maxVerLabel = 0;
         let maxEmail = 0;
         let maxPlanWidth = 3;
         let maxUsageWidth = 0;
         let maxStatusWidth = 0;
-        // The configured model sits right after the version, at the same priority.
-        // Resolve once here (fs + catalog reads) and reuse in the render loop.
         let maxModelWidth = 0;
         const modelByKey = new Map();
         for (const agentId of versionManaged) {
@@ -592,8 +438,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 }
             }
         }
-        // Second pass: compute max visible usage + status widths (now that maxPlanWidth is settled).
-        // stringWidth (not String.length) so chalk + block-bar glyphs pad correctly.
         for (const agentId of versionManaged) {
             const versions = listInstalledVersions(agentId);
             for (const v of versions) {
@@ -613,18 +457,10 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             const globalDefault = getGlobalDefault(agentId);
             const runStrategy = getConfiguredRunStrategy(agentId);
             const strategyLabel = chalk.gray(` (${runStrategy})`);
-            // `(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}`);
-            // Account information is already loaded above. Keep the selected default
-            // first, then make multi-account installs scannable by email. Harnesses
-            // without email identities retain their prior version-descending order.
             const sortedVersions = versions
                 .map((version) => ({
                 version,
@@ -649,13 +485,7 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 const vInfo = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const usageKey = getUsageLookupKey(vInfo);
                 const usageInfo = usageKey ? usageByKey.get(usageKey) : undefined;
-                // Fixed columns for every signed-in row so status / lastActive / auth
-                // stay vertically aligned across agents — even when this row has no
-                // usage bars or no rate-limit badge. Skipping empty columns mid-table
-                // was what made the multi-agent view look unjustified next to
-                // `agents view claude`.
                 const parts = [`    ${label}`];
-                // Configured model — same priority as the version, right beside it.
                 if (maxModelWidth > 0) {
                     const model = modelByKey.get(`${agentId}:${version}`) ?? '';
                     parts.push(chalk.yellow(padToWidth(model, maxModelWidth)));
@@ -664,12 +494,9 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 const signedIn = !!vInfo?.signedIn;
                 const usageStr = formatUsageSummary(vInfo?.plan || null, usageInfo?.snapshot || null, maxPlanWidth, viewUsageSummaryOptions(agentId, signedIn, usageInfo, usageWindowCap, version));
                 const hasUsage = usageStr.length > 0;
-                // Only show lastActive for versions with an actual logged-in account.
-                // Otherwise it reflects install time (misleading "just now" for fresh installs).
                 const lastActive = vInfo && hasEmail ? formatLastActive(vInfo.lastActive) : '';
                 const activeStr = lastActive;
                 const hasActive = activeStr.length > 0;
-                // The model now has its own column above; keep only the run mode here.
                 const runDefaults = resolveRunDefaults(agentId, version);
                 const runDefaultBits = [];
                 if (runDefaults.mode)
@@ -677,24 +504,11 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 if (runDefaults.effort)
                     runDefaultBits.push('effort:' + runDefaults.effort);
                 if (!hasEmail && !hasUsage && !signedIn) {
-                    // No per-version credential. That is NOT the same as unusable: Claude
-                    // Code authenticates from `CLAUDE_CODE_OAUTH_TOKEN` when the
-                    // environment carries one, and a run then succeeds against whatever
-                    // account minted that token — while `signedIn` (agents.ts: `!!email`,
-                    // read from this version home's `.claude.json`) stays false because no
-                    // account was ever written here. Reporting that as "logged out" reads
-                    // as a locked-out account and sends people hunting a login that is not
-                    // missing; naming the ambient token instead points at the real state —
-                    // every version on this box resolves to the SAME account, so balanced
-                    // rotation across them is not actually rotating.
                     parts.push(chalk.gray(ambientClaudeToken(agentId)
                         ? '(no per-version login — using ambient CLAUDE_CODE_OAUTH_TOKEN)'
                         : '(logged out — log in with: ' + loginHint(agentId) + ')'));
                 }
                 else {
-                    // Always emit account / usage / status / lastActive columns once any
-                    // signed-in row exists in the table (widths are global). Empty cells
-                    // are space-padded so later columns do not drift left.
                     const display = namedAccountColumnLabel(agentId, vInfo);
                     parts.push(display ? chalk.cyan(padToWidth(display, maxEmail)) : ' '.repeat(maxEmail));
                     if (maxUsageWidth > 0) {
@@ -716,7 +530,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                     console.log(chalk.gray(`      ${versionDir}`));
                 }
             }
-            // Check for project override
             const projectVersion = getProjectVersionFromCwd(agentId);
             if (projectVersion && projectVersion !== globalDefault) {
                 console.log(chalk.cyan(`    -> ${projectVersion} (project)`));
@@ -724,9 +537,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             console.log();
         }
     }
-    // Custom harnesses sit in the same list as the native ones — they are run the
-    // same way (`agents run <name>`), so they read as their own agent type rather
-    // than as an indented row under whichever host CLI executes them.
     const byokMap = new Map();
     const byKeychainItem = new Map();
     for (const h of harnesses) {
@@ -760,16 +570,12 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         }
     }
     renderHarnessBlocks(harnesses, installedHosts, showPaths, byokMap.size > 0 ? byokMap : undefined);
-    // Show globally installed (not managed) agents
     if (globallyInstalled.length > 0) {
         console.log(chalk.bold('Not Managed by Agents CLI\n'));
-        // Calculate max version label width for alignment
         const globalMaxVerLabel = Math.max(...globallyInstalled.map((agentId) => {
             const cliState = cliStates[agentId];
             return `${cliState?.version || 'installed'} (global)`.length;
         }));
-        // Pre-pass: max badge/usage/email widths so columns line up the same way
-        // the version-managed block does (stringWidth for chalk-aware padding).
         let gMaxStatusWidth = 0;
         let gMaxUsageWidth = 0;
         let gMaxEmail = 0;
@@ -819,14 +625,11 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 console.log(chalk.gray(`    Manage: agents add ${agentId}@${cliState.version} -y`));
             }
             else if (!agent.npmPackage && cliState?.installed) {
-                // installScript-based agent already on PATH — direct users to adopt the
-                // existing install with `agents import` instead of re-running curl.
                 console.log(chalk.gray(`    Adopt:  agents import ${agentId}`));
             }
             console.log();
         }
     }
-    // If filtering to a specific agent and not found
     if (filterAgentId &&
         versionManaged.length === 0 &&
         globallyInstalled.length === 0 &&
@@ -834,7 +637,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         console.log(`  ${chalk.bold(agentLabel(filterAgentId))}: ${chalk.gray('not installed')}`);
         console.log();
     }
-    // No agents installed at all
     if (versionManaged.length === 0 &&
         globallyInstalled.length === 0 &&
         harnesses.length === 0 &&
@@ -843,11 +645,6 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         console.log(chalk.gray('  Run: agents add claude@latest'));
         console.log();
     }
-    // `--refresh` used to print a table that looked fully refreshed no matter how
-    // many accounts it had failed to reach, so a box whose every Claude credential
-    // had expired rendered identically to a healthy one — the bars beside each row
-    // came from a cache that the run had not managed to update. Name the accounts
-    // it could not confirm, and why.
     if (viewOpts?.forceRefresh) {
         const unrefreshed = [];
         for (const [key, usage] of usageByKey) {
@@ -864,21 +661,15 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             console.log();
         }
     }
-    // Host CLIs are host-global, not per-agent — show them once in the overview.
     if (!filterAgentId) {
         renderHostClisSection(process.cwd());
     }
 }
-/**
- * Show detailed resources for a specific agent version.
- * Called when: `agents view claude@2.0.65` or `agents view claude@default`
- */
 async function showAgentResources(agentId, requestedVersion, filter) {
     const spinner = ora({ text: 'Loading...', isSilent: !process.stdout.isTTY }).start();
     const cwd = process.cwd();
     const agentsDir = getAgentsDir();
     const cliStates = await getAllCliStates();
-    // Resolve 'default' to actual version
     let version = null;
     if (requestedVersion === 'default') {
         version = getGlobalDefault(agentId);
@@ -902,8 +693,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         }
     }
     const home = getVersionHomePath(agentId, version);
-    // Git sync status if ~/.agents/ is a git repo (shared loader — see
-    // loadResourceSyncData / resolveResourceSyncState, reused by --json --resources).
     const { hasGitRepo, commands: commandsSync, skills: skillsSync, hooks: hooksSync, memory: memorySync } = await loadResourceSyncData();
     const resources = getAgentResources(agentId, {
         cwd,
@@ -921,7 +710,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         })),
         skills: resources.skills.map(r => ({
             ...r,
-            // ruleCount of 0 is noise — every skill has 0 unless it ships subrules, which is rare.
             ruleCount: r.ruleCount && r.ruleCount > 0 ? r.ruleCount : undefined,
             syncState: r.scope === 'project' ? undefined : resolveResourceSyncState(agentId, r.name, 'skills', skillsSync),
         })),
@@ -938,7 +726,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         workflows: resources.workflows.map(r => ({ name: r.name, path: r.path, scope: r.scope })),
     };
     spinner.stop();
-    // Render helper for resources
     function renderSection(title, items) {
         console.log(chalk.bold(`\n${title}\n`));
         if (items.length === 0) {
@@ -962,7 +749,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             let display = nameColor(linkedName);
             if (r.ruleCount !== undefined)
                 display += chalk.gray(` (${r.ruleCount} rules)`);
-            // Source annotation: project overrides user, user overrides system
             const sourceTag = r.scope === 'project' ? chalk.blue('[project]')
                 : r.scope === 'user' ? chalk.cyan('[user]')
                     : chalk.gray('[system]');
@@ -974,9 +760,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             console.log(prefix + descStr);
         }
     }
-    // Render promptcuts (cross-agent, not per-version). Shortcuts are layered
-    // across system + user files with user precedence; the displayed file path
-    // is whichever is "live" — user if it exists, else system.
     function renderPromptcuts() {
         console.log(chalk.bold(`\nPromptcuts\n`));
         const merged = readMergedPromptcuts();
@@ -989,8 +772,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         console.log(`  ${chalk.green(label).padEnd(24)} ${chalk.gray(formatPath(getEffectivePromptcutsPath(), cwd))}`);
     }
     const anyFilterSet = filter && SECTION_KEYS.some((k) => filter[k]);
-    // 1. Agent CLI info — skip the header entirely when the user asked for a
-    // specific section. They want "nothing more or less."
     if (!anyFilterSet) {
         console.log(chalk.bold('Agent CLIs\n'));
         const accountInfo = await getAccountInfo(agentId, home);
@@ -1003,7 +784,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         const accountLabel = accountColumnLabel(accountInfo);
         const emailStr = accountLabel ? chalk.cyan(`  ${accountLabel}`) : '';
         const status = chalk.green(version);
-        // Configured model sits right beside the version, same priority (no label).
         const configuredModel = resolveConfiguredModel(agentId, version);
         const modelStr = configuredModel ? chalk.yellow(`  ${configuredModel.model}`) : '';
         const usageStr = formatUsageSummary(usageInfo.snapshot?.plan ?? accountInfo.plan, null);
@@ -1017,13 +797,11 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             }
         }
     }
-    // 2. Resources
     if (shouldRenderSection('commands', filter)) {
         renderSection('Commands', agentData.commands);
     }
     if (shouldRenderSection('skills', filter)) {
         renderSection('Skills', agentData.skills);
-        // Show skill parse errors only when skills section is visible
         if (agentData.skillErrors.length > 0) {
             console.log(`\n  ${chalk.red('Skill Errors')}:`);
             for (const err of agentData.skillErrors) {
@@ -1075,7 +853,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             }
         }
     }
-    // Rules section with subrules breakdown
     function renderRulesSection() {
         console.log(chalk.bold('\nRules\n'));
         const items = agentData.memory;
@@ -1085,14 +862,12 @@ async function showAgentResources(agentId, requestedVersion, filter) {
         }
         const versionStr = agentData.version ? ` (${agentData.version})` : '';
         console.log(`  ${chalk.bold(agentData.agentName)}${chalk.gray(versionStr)}:`);
-        // Get composed subrules for the user scope
         let composedSubrules = [];
         try {
             const composed = composeRulesFromState({ cwd });
             composedSubrules = composed.subrules;
         }
         catch {
-            // No preset configured or rules.yaml missing — show rules without subrule breakdown
         }
         for (const r of items) {
             let nameColor = chalk.cyan;
@@ -1114,7 +889,6 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             display += ` ${sourceTag}`;
             const syncStr = r.syncState ? chalk.gray(` [${r.syncState}]`) : '';
             console.log(`    ${display}${syncStr}`);
-            // Show subrules for user-scope rules (the compiled CLAUDE.md)
             if (r.scope === 'user' && composedSubrules.length > 0) {
                 for (const sub of composedSubrules) {
                     const scopeLabel = sub.layerScope === 'project' ? chalk.blue('[project]')
@@ -1139,16 +913,12 @@ async function showAgentResources(agentId, requestedVersion, filter) {
     if (shouldRenderSection('clis', filter)) {
         renderHostClisSection(cwd);
     }
-    // Show legend at the end if git repo exists and we showed all sections.
-    // Filtered single-section views skip it — noise for promptcuts or plugins.
     if (hasGitRepo && !anyFilterSet) {
         console.log();
         console.log(chalk.gray('Legend:'), chalk.green('Tracked'), chalk.blue('Local-only'), chalk.yellow('Modified'), chalk.red('Deleted'));
     }
 }
 const ALL_RESOURCE_SECTIONS = ['commands', 'skills', 'mcp', 'memory', 'hooks', 'workflows', 'plugins'];
-/** Load git sync-state for the tracked resource kinds. Shared by the human
- *  detail view (showAgentResources) and the `--json --resources` path. */
 async function loadResourceSyncData() {
     const userAgentsDir = getUserAgentsDir();
     const hasGitRepo = isGitRepo(userAgentsDir);
@@ -1160,8 +930,6 @@ async function loadResourceSyncData() {
         memory: hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'rules') : null,
     };
 }
-/** Resolve one resource's git sync-state. Extracted from showAgentResources so
- *  the human view and the JSON path derive drift identically. */
 function resolveResourceSyncState(agentId, resourceName, resourceType, syncStatus) {
     if (!syncStatus)
         return undefined;
@@ -1176,7 +944,6 @@ function resolveResourceSyncState(agentId, resourceName, resourceType, syncStatu
         relativePath = `hooks/${resourceName}`;
     }
     else {
-        // Rules files: map agent-specific name (CLAUDE.md) back to canonical (AGENTS.md)
         const centralName = getCentralRulesFileName(agentId);
         relativePath = `rules/${centralName}`;
     }
@@ -1189,11 +956,8 @@ function resolveResourceSyncState(agentId, resourceName, resourceType, syncStatu
         return 'deleted';
     if (syncStatus.synced.some(matchesPath))
         return 'synced';
-    // Not in any array = local-only (untracked with no files)
     return 'new';
 }
-/** Collect one version's resources for `--json`, limited to `sections`. Scans
- *  the version's `home`, so per-version differences are reported accurately. */
 function collectVersionResources(agentId, home, cwd, cliInstalled, sections, sync) {
     const res = getAgentResources(agentId, { cwd, scope: 'all', cliInstalled, home });
     const out = {};
@@ -1213,7 +977,6 @@ function collectVersionResources(agentId, home, cwd, cliInstalled, sections, syn
     if (sections.has('skills')) {
         out.skills = res.skills.map((r) => {
             const item = withSync(r, 'skills', sync.skills);
-            // ruleCount of 0 is noise — every skill has 0 unless it ships subrules.
             if (r.ruleCount && r.ruleCount > 0)
                 item.ruleCount = r.ruleCount;
             return item;
@@ -1240,9 +1003,6 @@ function collectVersionResources(agentId, home, cwd, cliInstalled, sections, syn
     }
     return out;
 }
-/** Build the set of resource sections to include in `--json` from the
- *  `--resources` / `--detailed` flags, plus (in --json mode) the per-section
- *  boolean filters (`--skills` etc.) that plain `--json` historically ignored. */
 export function parseResourceSections(options, jsonMode) {
     const set = new Set();
     const addAll = () => ALL_RESOURCE_SECTIONS.forEach((s) => set.add(s));
@@ -1255,7 +1015,7 @@ export function parseResourceSections(options, jsonMode) {
         }
         else {
             for (const raw of String(rv).split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)) {
-                const section = raw === 'rules' ? 'memory' : raw; // --rules is the memory file
+                const section = raw === 'rules' ? 'memory' : raw;
                 if (ALL_RESOURCE_SECTIONS.includes(section))
                     set.add(section);
             }
@@ -1272,16 +1032,6 @@ export function parseResourceSections(options, jsonMode) {
     }
     return set;
 }
-/**
- * The one run-readiness gate for one agent on THIS box (PHNX-4116). Runs the
- * SAME enumeration the local router picks from — `collectRunCandidates` (native
- * slots + version homes) through `readinessFromCandidate` — so the answer
- * `agents view --json` publishes is exactly what a `run` here would find, and a
- * remote `--device auto` dispatcher can read it instead of re-deriving freshness
- * on its own box (which drifted: view.ts lists version homes, the router lists
- * slots). Returns undefined when the agent has no candidates at all (nothing
- * installed), so the field is simply absent rather than a misleading verdict.
- */
 export async function computeAgentRunReady(agentId) {
     const candidates = await collectRunCandidates(agentId);
     if (candidates.length === 0)
@@ -1302,18 +1052,11 @@ export async function computeAgentRunReady(agentId) {
     }
     return { ready: !!readyAccount, reason, accounts };
 }
-/**
- * Collect structured info for one or more agents without rendering to the
- * terminal. Used by `--json` output and any programmatic consumer (e.g. the
- * agents-cli extension's "resume current session in best available version"
- * command).
- */
 export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
     const authCache = readAuthHealthCache();
     const host = machineId();
     const wantResources = !!resourceSections && resourceSections.size > 0;
-    // Only pay for the git-status + resource scans when resources were requested.
     const resourceSync = wantResources ? await loadResourceSyncData() : null;
     const cliStates = wantResources ? await getAllCliStates() : null;
     const infoFetches = [];
@@ -1348,14 +1091,7 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
             return info;
         return {
             ...info,
-            // Prefer a plan the live usage fetch surfaced (Kimi reports membership
-            // tier in /usages; its local auth file has none) and fall back to the
-            // account-derived plan (Claude's billingType).
             plan: usageByKey.get(key)?.snapshot?.plan ?? canon.plan,
-            // Throttle state comes from the live usage windows, not the pay-as-you-go
-            // overage flag that AccountInfo.usageStatus used to carry. A maxed window
-            // means rate-limited; no snapshot means no badge. See
-            // deriveUsageStatusFromSnapshot.
             usageStatus: deriveUsageStatusFromSnapshot(usageByKey.get(key)?.snapshot),
             overageCredits: canon.overageCredits,
         };
@@ -1375,10 +1111,6 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
             isolated: isVersionIsolated(agentId, version),
             isIsolatedDefault: getIsolatedDefault(agentId) === version,
             signedIn: info.signedIn,
-            // The strict per-version launch truth (vs the display `signedIn` above,
-            // which inherits the active/global HOME login). The same primitive
-            // `collectRunCandidates` uses locally, so remote `--device auto` placement
-            // is gated on identical launchability (PHNX-3466).
             launchable: isLaunchableSignedIn(info.signedIn, credentialPresence(agentId, home)),
             authVerdict: authHealth?.verdict ?? null,
             authCheckedAt: authHealth?.checkedAt ?? null,
@@ -1418,16 +1150,11 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
         else
             byAgent.set(agentId, [entry]);
     }
-    // Keep filtered native JSON consistent with the text view: custom forks are
-    // not children of the native harness they execute through.
     const harnesses = filterAgentId ? [] : getHarnesses();
     const catalog = await loadAccountCatalog();
     const note = secretsUnavailableNote(catalog);
     if (note)
-        console.error(chalk.yellow(note)); // stderr — never corrupts --json stdout
-    // The one run-readiness gate per agent, computed off the router's own
-    // enumeration (PHNX-4116). Runs in parallel across agents; a harness with
-    // nothing installed yields undefined and the field is omitted.
+        console.error(chalk.yellow(note));
     const runReadyByAgent = new Map();
     await Promise.all(agentsToShow.map(async (agentId) => {
         const runReady = await computeAgentRunReady(agentId);
@@ -1442,8 +1169,6 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
                 return a.isDefault ? -1 : 1;
             return compareVersions(b.version, a.version);
         });
-        // Project through the public JSON v2 serializer — the internal catalog row
-        // (identityKey, home, installations) is not the machine contract.
         const accounts = accountListJson(catalog.native.filter((row) => row.agent === agentId), catalog.provider.filter((row) => row.harnesses.includes(agentId)), agentId).accounts;
         out.push({
             agent: agentId,
@@ -1455,14 +1180,6 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
     }
     return out;
 }
-/**
- * Identity key for duplicate-install detection. Prefers accountKey — which
- * encodes account AND org — over the bare email: two installs can share an
- * email yet belong to different orgs (a personal Max plan and a Team seat),
- * and grouping those by email alone would propose pruning a live account.
- * Falls back to the lowercased email for agents whose credentials expose no
- * identity key. Null when there is no usable identity.
- */
 export function pruneGroupKey(info) {
     return info.accountKey ?? info.email?.toLowerCase() ?? null;
 }
@@ -1487,14 +1204,7 @@ export function pruneGroupKey(info) {
  *    trashing the identified home is the exact bug this replaces.
  */
 export function planDuplicatePrune(candidates) {
-    // Only installs with a working binary compete for "the live install for this account".
     const installed = candidates.filter((c) => c.hasBinary && c.email);
-    // email -> every DISTINCT captured accountKey seen for it. An email-only home
-    // folds into an identified account only when that email maps to EXACTLY ONE
-    // account; when two distinct orgs share the email (the Personal+Team case) the
-    // fold is ambiguous, so the identity-less home is left ungrouped rather than
-    // guessed into one — guessing could retire the actually-working re-login of the
-    // OTHER org (the exact bug this function exists to prevent, one level up).
     const emailToAccountKeys = new Map();
     for (const c of installed) {
         if (!c.accountKey)
@@ -1509,11 +1219,8 @@ export function planDuplicatePrune(candidates) {
         const keys = email ? emailToAccountKeys.get(email) : undefined;
         if (keys && keys.size === 1)
             return [...keys][0];
-        // ≥2 identified orgs on this email: never merge the ambiguous home. A unique
-        // key makes it its own singleton group (length 1 → never pruned).
         if (keys && keys.size >= 2)
             return `ambiguous:${c.email.toLowerCase()}:${c.version}`;
-        // No identified sibling at all: group equally-bare homes by email as before.
         return pruneGroupKey(c);
     };
     const byAccount = new Map();
@@ -1570,21 +1277,15 @@ async function buildAgentPrunePlan(agentId) {
             version: d.version,
             email: d.email,
             keeper: d.keeper,
-            // The default may itself be a to-be-retired duplicate (a freshly created
-            // home often becomes the global default). We do NOT skip it: executePrune
-            // repoints the default onto the keeper first, then retires the duplicate.
             isDefault: d.version === globalDefault,
             reason: 'duplicate',
         });
     }
-    // Home-only leftovers: dirs without a binary. These are residue from a
-    // prior removeVersion before the soft-delete migration, plus any hand-edited
-    // installs. Surface them so the user can move them to trash.
     for (const e of entries) {
         if (e.hasBinary)
             continue;
         if (e.version === globalDefault)
-            continue; // never auto-suggest the default
+            continue;
         toPrune.push({
             agentId,
             version: e.version,
@@ -1598,10 +1299,6 @@ async function buildAgentPrunePlan(agentId) {
 }
 export async function executePrunePlan(plan) {
     const moved = [];
-    // Repoint the global default onto the keeper BEFORE retiring a duplicate that
-    // currently holds it, so consolidation collapses the duplicate instead of
-    // leaving it pinned as the default (and so removeVersion's own fallback never
-    // has to guess a replacement).
     for (const p of plan.toPrune) {
         if (p.reason === 'duplicate' && p.isDefault && p.keeper && p.keeper !== p.version) {
             setGlobalDefault(p.agentId, p.keeper);
@@ -1640,17 +1337,6 @@ function printPrunePlan(plan, isFirst) {
     }
     console.log();
 }
-/**
- * Consolidate to one home per logical account: retire the redundant duplicate
- * homes an account accumulated, keeping the single home that best represents it
- * (see {@link planDuplicatePrune} for the keeper/merge rules). When the retired
- * duplicate holds the global default, the default is first repointed onto the
- * keeper, so consolidation collapses it instead of leaving it pinned.
- *
- * When filterAgentId is set, prunes that agent first, then cascades: after
- * each agent, offers the next agent with duplicates. User answering "no"
- * stops the chain.
- */
 export async function pruneDuplicates(filterAgentId, yes, dryRun) {
     const ordered = filterAgentId
         ? [filterAgentId, ...ALL_AGENT_IDS.filter((a) => a !== filterAgentId)]
@@ -1719,20 +1405,12 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
         printTrashFooter(allMoved);
     }
 }
-/**
- * Main view action handler.
- * Exported for use by deprecated aliases.
- */
 export async function viewAction(agentArg, options) {
-    // --merged renders the cross-layer, first-wins resource surface (the former
-    // `agents resources`), independent of the per-version detail view below.
     if (options?.merged) {
         renderMergedResources();
         return;
     }
-    // --live is a shorter-to-type alias of --refresh; both force a live probe.
     const forceRefresh = options?.refresh === true || options?.live === true;
-    // --resources / --detailed imply --json (they only shape structured output).
     const explicitResources = options?.detailed === true || options?.resources !== undefined;
     const json = options?.json === true || explicitResources;
     const resourceSections = parseResourceSections(options ?? {}, json);
@@ -1751,11 +1429,6 @@ export async function viewAction(agentArg, options) {
         clis: options?.clis,
     };
     const filterIsSet = SECTION_KEYS.some((k) => filter[k]);
-    // RUSH-1320: fold any stale literal `latest` version-home into its concrete
-    // version before rendering, so it stops appearing as a bogus "version" next
-    // to the real ones. Best-effort — must never break `agents view`. Scoped to
-    // the queried agent when one is given (cheap no-op for agents with no
-    // `latest` dir, i.e. almost all of them).
     {
         const target = agentArg ? resolveAgentName(agentArg.split('@')[0]) : null;
         const toReconcile = agentArg ? (target ? [target] : []) : ALL_AGENT_IDS;
@@ -1774,11 +1447,8 @@ export async function viewAction(agentArg, options) {
         await showInstalledVersions(undefined, { forceRefresh, versions: options?.versions });
         return;
     }
-    // Parse agent@version syntax
     const parts = agentArg.split('@');
     const agentName = parts[0];
-    // Match run resolution: an exact custom harness name wins over a native id or
-    // alias with the same spelling, so every fork remains independently viewable.
     if (profileExists(agentName)) {
         const harness = profileSummary(readProfile(agentName));
         if (json) {
@@ -1797,9 +1467,6 @@ export async function viewAction(agentArg, options) {
         console.log(chalk.red(formatAgentError(agentName)));
         process.exit(1);
     }
-    // Resolve the @version filter through the agent-spec engine:
-    //   bare/@any → null (show all versions), @default/@pinned → 'default'
-    //   (showAgentResources handles it), @latest/@oldest/@x.y.z → concrete.
     let requestedVersion;
     try {
         requestedVersion = resolveVersionFilter(agentId, parts[1]).version;
@@ -1826,26 +1493,20 @@ export async function viewAction(agentArg, options) {
         return;
     }
     if (json) {
-        // --json ignores the @version suffix, but --resources/--detailed (or a
-        // section flag) now attach each version's resource inventory + sync-state.
         const data = await collectAgentsJson(agentId, resourceSections, { forceRefresh });
         console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [], harnesses: [] }, null, 2));
         return;
     }
     if (requestedVersion) {
-        // Specific version requested: show detailed resources
         await showAgentResources(agentId, requestedVersion, filter);
     }
     else if (filterIsSet) {
-        // `agents view claude --skills` → fall through to detail view on default.
-        // Section filters only make sense for the per-version detail view.
         await showAgentResources(agentId, 'default', filter);
     }
     else {
         await showInstalledVersions(agentId, { forceRefresh, versions: options?.versions });
     }
 }
-/** Register the `agents view` command. */
 export function registerViewCommand(program) {
     addHostOption(program.command('view [agent]'))
         .description('Show your agents, connected accounts, and usage.')