@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/agent-spec/agents.js

@@ -1,14 +1,3 @@
-/**
- * Core agent configuration and detection module.
- *
- * Defines the canonical registry of current and legacy AI coding agents (Claude,
- * Codex, Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Goose, Grok)
- * with their CLI commands, config paths, capability flags, and MCP integration
- * points.
- *
- * Provides functions for detecting installed CLIs, resolving version-managed binaries,
- * reading account/auth info, and managing MCP server registrations across agents.
- */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as crypto from 'crypto';
@@ -30,11 +19,6 @@ import { MCP_TARGETS } from '../mcp-registry.js';
 import { VERSION_RE } from './primitives.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
-/**
- * Minimum Codex CLI version that supports hooks.
- * Mirrored on `AGENTS.codex.capabilities.hooks.since` -- kept exported for
- * legacy import sites that haven't migrated to `supports()` yet.
- */
 export const CODEX_HOOKS_MIN_VERSION = '0.116.0';
 const CLI_VERSION_CACHE_PATH = getCliVersionCachePath();
 let cliVersionCache = null;
@@ -45,7 +29,6 @@ function loadCliVersionCache() {
         cliVersionCache = JSON.parse(fs.readFileSync(CLI_VERSION_CACHE_PATH, 'utf-8'));
     }
     catch {
-        /* missing or corrupt cache, rebuild */
         cliVersionCache = {};
     }
     return cliVersionCache;
@@ -60,19 +43,12 @@ function saveCliVersionCache() {
         fs.writeFileSync(CLI_VERSION_CACHE_PATH, JSON.stringify(cliVersionCache));
     }
     catch {
-        /* best-effort cache persist */
     }
 }
 function pathIsWithin(candidate, directory) {
     const relative = path.relative(directory, candidate);
     return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
 }
-/**
- * Resolve a PATH candidate to the immutable native executable agents-cli may
- * safely register. An adopted launcher can live outside the shims directory
- * while resolving back into it; in that case its durable adoption record is
- * the source of truth for the original executable.
- */
 export function resolveNativeBinaryPath(command, candidate, options = {}) {
     const shimsDir = options.shimsDir ?? getShimsDir();
     const historyDir = options.historyDir ?? getHistoryDir();
@@ -88,10 +64,10 @@ export function resolveNativeBinaryPath(command, candidate, options = {}) {
         canonicalShimsDir = fs.realpathSync(shimsDir);
     }
     catch {
-        /* An absent shims dir cannot make an existing native binary invalid. */
     }
     if (!pathIsWithin(canonicalCandidate, canonicalShimsDir))
         return canonicalCandidate;
+    // A shim resolves only to its recorded original; never recurse into the shim tree.
     const recordPath = path.join(historyDir, 'adopted-launchers', command);
     try {
         const [original] = fs.readFileSync(recordPath, 'utf-8').split(/\r?\n/, 1);
@@ -125,10 +101,6 @@ export function findInPath(command, options = {}) {
                 const stat = fs.statSync(full);
                 if (!stat.isFile())
                     continue;
-                // A shell only runs an executable file; `which` skips a mode-644 namesake and
-                // so must this, or a stray non-executable `secrets`/`claude` file earlier on
-                // PATH would shadow the real binary further down. On win32 the mode bit is
-                // meaningless (PATHEXT decides), so the check is POSIX-only.
                 if (process.platform !== 'win32')
                     fs.accessSync(full, fs.constants.X_OK);
                 const native = resolveNativeBinaryPath(command, full, options);
@@ -136,17 +108,11 @@ export function findInPath(command, options = {}) {
                     return native;
             }
             catch {
-                /* not in this dir */
             }
         }
     }
     return null;
 }
-/** Grok-specific binary resolution.
- * Grok does not live in node_modules/.bin. Its versioned binaries live in each
- * managed version home under `.grok/downloads/`, so detection must not follow
- * the host ~/.grok config symlink.
- */
 function resolveGrokBinary(version) {
     if (version && version !== 'latest') {
         const binaryPath = getBinaryPath('grok', version);
@@ -236,13 +202,6 @@ function splitCommandLine(command) {
     }
     return args;
 }
-/**
- * Master registry of all supported agents keyed by AgentId.
- *
- * Each entry defines the agent's CLI command, npm package, config directory layout,
- * instructions file name, slash-command format, and capability flags. This is the
- * single source of truth for agent metadata consumed throughout the codebase.
- */
 export const AGENTS = {
     claude: {
         id: 'claude',
@@ -269,15 +228,11 @@ export const AGENTS = {
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
         nativePluginSkills: true,
+        // Harness-owned skill directories survive orphan cleanup.
         ownedSkillDirs: ['synced'],
-        // Claude Code grew a native `claude --cloud "<prompt>"` (Anthropic-managed
-        // infra, claude.ai/code; requires claude.ai subscription auth). Routing
-        // still goes to Rush Cloud deliberately — it keeps cloud tasks in one
-        // tracked fleet (agents cloud list/status/logs) regardless of harness.
         cloudProvider: 'rush',
         capabilities: { hooks: true, mcp: true, mcpHttp: true, mcpHeaders: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'CLAUDE.md' }, workflows: true, memory: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true, interactiveRepl: true },
     },
-    // codex hooks: gated to >= 0.116.0 (introduced [features] codex_hooks flag).
     codex: {
         id: 'codex',
         name: 'Codex',
@@ -303,8 +258,6 @@ export const AGENTS = {
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
         cloudProvider: 'codex',
-        // Subagents: multi-agent plumbing since 0.117.0; custom agents as
-        // ~/.codex/agents/*.toml (name, description, developer_instructions).
         capabilities: { hooks: { since: '0.116.0' }, mcp: true, mcpHttp: true, mcpHeaders: false, allowlist: { since: '0.138.0' }, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: { since: '0.117.0' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'auto', 'skip'], interactiveRepl: true },
     },
     cursor: {
@@ -327,28 +280,13 @@ export const AGENTS = {
         commandsDir: path.join(HOME, '.cursor', 'commands'),
         commandsSubdir: 'commands',
         skillsDir: path.join(HOME, '.cursor', 'skills'),
-        // Hooks: ~/.cursor/hooks.json (`{ "version": 1, "hooks": { event: [{ command }] } }`).
-        // CLI hooks since 2026-01-16. See registerHooksForCursor — only CLI-fired events.
         hooksDir: 'hooks',
-        // Plugins: `.cursor-plugin/plugin.json` (re-enabled in CLI 2026-05). Mirror the
-        // Claude marketplace layout into ~/.cursor/plugins/ and copy the manifest into
-        // pluginManifestDir so Cursor's native loader sees it (same pattern as droid/
-        // codex).
         pluginManifestDir: '.cursor-plugin',
         instructionsFile: '.cursorrules',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        // Subagents: `.cursor/agents/<name>.md` (project) or `~/.cursor/agents/<name>.md`
-        // (user), Markdown with YAML frontmatter (name, description, model, readonly,
-        // is_background — no `color`). Shipped in cursor-agent CLI 2026.01 (Cursor 2.4,
-        // 2026-01-22); cursor-agent uses CalVer build tags (e.g. 2025.11.25-<hash>), so
-        // gate at `>= 2026.1.22`. The `agents sync` path enforces this (versions.ts skips
-        // + warns for pre-2.4 installs); the direct `subagents add --agents cursor` path
-        // writes unconditionally, same as the other since-gated agents.
-        // See transformSubagentForCursor / https://cursor.com/docs/subagents.
-        // Current cursor-agent builds open their interactive TUI with no argv.
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '2026.1.22' }, rules: { file: '.cursorrules' }, workflows: false, memory: false, modes: ['plan', 'edit', 'skip'], interactiveRepl: true }, // allowlist: ~/.cursor/cli-config.json
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '2026.1.22' }, rules: { file: '.cursorrules' }, workflows: false, memory: false, modes: ['plan', 'edit', 'skip'], interactiveRepl: true },
     },
     opencode: {
         id: 'opencode',
@@ -368,11 +306,6 @@ export const AGENTS = {
         commandsDir: path.join(HOME, '.opencode', 'commands'),
         commandsSubdir: 'commands',
         skillsDir: path.join(HOME, '.opencode', 'skills'),
-        // Plugins: TS/JS modules auto-loaded from ~/.config/opencode/plugins/ (global)
-        // and .opencode/plugins/ (project). Not Claude marketplace format — see
-        // installOpenCodePlugin in plugins.ts. OpenCode v1.18.4 exposes lifecycle
-        // hooks through plugin modules (event/tool/etc. functions), not a native
-        // opencode.json shell-command hooks block.
         hooksDir: 'hooks',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
@@ -395,29 +328,15 @@ export const AGENTS = {
         cliCommand: 'openclaw',
         npmPackage: 'openclaw',
         configDir: path.join(HOME, '.openclaw'),
-        commandsDir: '', // OpenClaw uses Gateway-based slash commands, not file-based
+        commandsDir: '',
         commandsSubdir: '',
         skillsDir: path.join(HOME, '.openclaw', 'skills'),
-        nativeCommandRuntime: true, // Gateway resolves slash commands — don't convert commands to skills
+        nativeCommandRuntime: true,
         hooksDir: 'hooks',
-        instructionsFile: 'workspace/AGENTS.md', // Primary memory file (also has SOUL.md, IDENTITY.md, etc.)
+        instructionsFile: 'workspace/AGENTS.md',
         format: 'markdown',
         variableSyntax: '{{ARGUMENTS}}',
-        // hooks: NOT supported. OpenClaw only exposes a fixed set of internal,
-        // named hooks (e.g. `boot-md`, which runs BOOT.md on gateway restart) —
-        // there is no general event->shell-command registration surface (no
-        // PreToolUse/PostToolUse/UserPromptSubmit equivalent an agents-cli
-        // hooks.yaml manifest could target). registerHooksToSettings has no
-        // `openclaw` case and silently no-ops (RUSH-2122: capability claimed
-        // hooks:true with zero hooks ever installed). Flip back to `true` only
-        // alongside a real registerHooksForOpenClaw implementation.
         supportsHooks: false,
-        // allowlist: maps blanket (whole-tool) rules to ~/.openclaw/openclaw.json
-        // tools.alsoAllow (allow) / tools.deny (deny). OpenClaw gates at tool
-        // granularity only, so sub-command/path/domain patterns are skipped.
-        // OpenClaw is self-updating (no pinned since), so `true` is correct.
-        // Workflows sync as Lobster `.lobster` files under `.openclaw/workflows/`;
-        // the Lobster tool runs them by receiving the file path as `pipeline`.
         capabilities: { hooks: false, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: true, memory: true, modes: ['plan', 'edit', 'skip'], interactiveRepl: true },
     },
     copilot: {
@@ -438,21 +357,12 @@ export const AGENTS = {
         commandsDir: path.join(HOME, '.copilot', 'commands'),
         commandsSubdir: 'commands',
         skillsDir: path.join(HOME, '.copilot', 'skills'),
-        // Hooks: user-level `~/.copilot/hooks/*.json` (GA @github/copilot, every
-        // 1.x). Schema `{ "version": 1, "hooks": { event: [...] } }` with camelCase
-        // event names (sessionStart, preToolUse, …). See registerHooksForCopilot.
         hooksDir: 'hooks',
-        // Copilot reads a plugin's manifest from the plugin ROOT (plugin.json),
-        // not `.claude-plugin/plugin.json`. Mirror it there. Verified against the
-        // GitHub Copilot CLI (1.0.56): `copilot plugin install` produces an
-        // installed plugin dir whose manifest sits at the root.
         pluginManifestDir: '.',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        // interactiveRepl: false — copilot requires a prompt for meaningful work; bare invocation
-        // opens a welcome screen but not a persistent coding REPL suitable for agents focus.
         capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '0.0.353' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit', 'auto', 'skip'], interactiveRepl: false },
     },
     amp: {
@@ -478,7 +388,6 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        // interactiveRepl: false — amp requires a prompt; bare invocation exits immediately.
         capabilities: { hooks: false, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit'], interactiveRepl: false },
     },
     goose: {
@@ -499,38 +408,15 @@ export const AGENTS = {
         configDir: path.join(HOME, '.config', 'goose'),
         commandsDir: path.join(HOME, '.config', 'goose', 'commands'),
         commandsSubdir: 'commands',
-        // Goose reads skills directly from central ~/.agents/skills/ via the Summon
-        // extension (block-goose-cli ≥ 1.25.0). No per-version copy is written.
         skillsDir: path.join(HOME, '.agents', 'skills'),
         nativeAgentsSkillsDir: true,
-        // Hooks: Open Plugins format — auto-discovered from
-        // ~/.agents/plugins/<name>/hooks/hooks.json (shipped block-goose-cli
-        // ≥ 1.34.0). See registerHooksForGoose.
         hooksDir: 'hooks',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        // Plugins: Open Plugins under ~/.agents/plugins/<name>/ (same layout as
-        // agents-cli source). Version isolation copies into versionHome/.agents/plugins/.
-        // Workflows sync as Goose recipe YAML. Permissions are NOT supported:
-        // permission.yaml gates whole tools, so canonical rules cannot round-trip.
-        // Commands: a Goose slash command is a recipe YAML under
-        // ~/.config/goose/commands/<name>.yaml, registered in ~/.config/goose/config.yaml
-        // under `slash_commands: [{ command, recipe_path }]` (see goose-commands.ts).
-        // Subagents: recipe YAML named agents under ~/.config/goose/agents/<name>.yaml
-        // (goose auto-discovers and delegates to them by name in autonomous mode).
         capabilities: { hooks: { since: '1.34.0' }, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: { since: '1.25.0' }, commands: true, plugins: true, subagents: true, rules: { file: 'AGENTS.md' }, workflows: true, memory: false, modes: ['edit'], interactiveRepl: true },
     },
-    // Google Antigravity CLI (`agy`) — official replacement for Gemini CLI as of IO 2026.
-    // configDir nests inside `~/.gemini/` since agy shares the parent dir with the Gemini
-    // CLI but isolates its own state in the `antigravity-cli/` subdir. Per-version HOME
-    // isolation works because the shim's configDirName carries the full nested path.
-    // Auth: Google OAuth on first launch, or ANTIGRAVITY_API_KEY env var for headless.
-    // Hooks: JSON entries under a top-level `hooks` key in settings.json; events are
-    // before_tool_call, after_model_call, on_loop_stop, on_error. Plugins are the
-    // renamed Gemini CLI extensions. Permissions live in settings.json under a
-    // `permissions` key with allow/deny arrays.
     antigravity: {
         id: 'antigravity',
         name: 'Antigravity',
@@ -557,16 +443,8 @@ export const AGENTS = {
         variableSyntax: '{{args}}',
         supportsHooks: true,
         cloudProvider: 'antigravity',
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '1.0.16' }, rules: { file: 'AGENTS.md' }, workflows: { since: '1.0.6' }, memory: false, modes: ['edit', 'skip'], rulesImports: false, interactiveRepl: true }, // workflows: markdown files in the shared, HOME-global ~/.gemini/config/global_workflows/ (agy scans it at startup; not version-isolated — see workflows.ts), invoked as /<name> slash commands
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '1.0.16' }, rules: { file: 'AGENTS.md' }, workflows: { since: '1.0.6' }, memory: false, modes: ['edit', 'skip'], rulesImports: false, interactiveRepl: true },
     },
-    // xAI Grok Build CLI (`grok`) — early beta, SuperGrok Heavy. Auth via OAuth on
-    // first launch, or XAI_API_KEY env var for headless. MCP servers configured inline
-    // under [mcp_servers] in ~/.grok/config.toml. Hooks auto-discovered from
-    // ~/.grok/hooks/ (+ project .grok/hooks/) — events PreToolUse, PostToolUse, etc.
-    // Plugins live in ~/.grok/plugins/ with marketplaces. Permissions: --allow/--deny
-    // CLI flags or [permission] TOML block in ~/.grok/config.toml.
-    // Workflows (native Rhai orchestration) enabled by default as of v0.2.111 —
-    // projected into ~/.grok/workflows/<name>.rhai (under GROK_HOME isolation).
     grok: {
         id: 'grok',
         name: 'Grok',
@@ -583,10 +461,6 @@ export const AGENTS = {
         npmPackage: '',
         installScript: 'curl -fsSL https://x.ai/cli/install.sh | bash',
         configDir: path.join(HOME, '.grok'),
-        // Grok discovers file-based slash commands from ~/.agents/commands/ (the
-        // cross-agent compat dir it mirrors from Claude Code) as well as the legacy
-        // ~/.claude/commands/ symlink. We write there directly so the per-agent
-        // install path and the central user repo stay in sync.
         commandsDir: path.join(HOME, '.agents', 'commands'),
         commandsSubdir: path.join('..', '.agents', 'commands'),
         skillsDir: path.join(HOME, '.grok', 'skills'),
@@ -600,30 +474,20 @@ export const AGENTS = {
             mcp: true,
             mcpHttp: false,
             mcpHeaders: false,
-            allowlist: true, // maps to Grok's granular Bash/Edit/Write/Read/Grep/WebFetch/MCPTool rules
+            allowlist: true,
             skills: true,
-            commands: true, // Grok >= 0.2.111: file-based slash commands from ~/.agents/commands/ (docs) + ~/.claude/commands/ (Claude Code compat)
+            commands: true,
             plugins: true,
-            subagents: true, // ~/.grok/agents/*.md (Claude-compatible agent defs)
+            subagents: true,
             rules: { file: 'AGENTS.md' },
-            // Native workflows (`.rhai` under ~/.grok/workflows/) shipped on-by-default
-            // in v0.2.111 (2026-07-22). See transformWorkflowForGrok in workflows.ts.
             workflows: { since: '0.2.111' },
             memory: true,
             modes: ['plan', 'edit', 'skip'],
-            // grok's `--permission-mode plan` silently stalls a headless `-p` run at
-            // its ExitPlanMode gate (no TTY to approve). Headless plan auto-downgrades
-            // to auto (→ edit via resolveMode). Interactive plan is unaffected.
             headlessPlan: false,
             rulesImports: true,
             interactiveRepl: true,
         },
     },
-    // Kimi Code CLI (`kimi`) — Moonshot AI coding agent.
-    // Install: `curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash`
-    //    or: `npm install -g @moonshot-ai/kimi-code`
-    // Config: `~/.kimi-code/config.toml`, `~/.kimi-code/mcp.json`,
-    //         `~/.kimi-code/skills/`, `~/.kimi-code/hooks/`
     kimi: {
         id: 'kimi',
         name: 'Kimi',
@@ -658,66 +522,16 @@ export const AGENTS = {
             skills: true,
             commands: false,
             plugins: true,
-            // Claude-shaped agent markdown under ~/.kimi-code/agents/. kimi-code
-            // discovers that dir from `USER_BRAND_DIRS = ["agents"]` (agent-file
-            // discovery, added in 0.29.0); 0.28.x and older compile their four agent
-            // profiles into the bundle with no filesystem loader at all, so a synced
-            // file there is never read.
             subagents: { since: '0.29.0' },
             rules: { file: 'AGENTS.md' },
             workflows: true,
             memory: false,
             modes: ['plan', 'edit', 'auto', 'skip'],
-            // kimi's headless `-p` refuses to combine with `--plan` (`Cannot combine
-            // --prompt with --plan`). Headless plan auto-downgrades to auto (kimi -p
-            // auto-runs). Interactive plan is unaffected.
             headlessPlan: false,
             rulesImports: false,
             interactiveRepl: true,
         },
     },
-    // Factory AI Droid CLI (`droid`) — agentic coding CLI from factory.ai.
-    // Install: `curl -fsSL https://app.factory.ai/cli | sh` (no npm package).
-    // Binary is NOT in node_modules/.bin — the shim resolves the fixed install
-    // path ~/.local/bin/droid directly (see the droid branch in shims.ts).
-    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/, hooks/,
-    // plugins/). Memory: native AGENTS.md. Subagents = custom droids (top-level
-    // .md files in ~/.factory/droids/). Config isolation rides the ~/.factory
-    // symlink switch (no FACTORY_HOME env var exists). Headless:
-    // `droid exec "<prompt>"` with --auto low|medium|high, -o stream-json,
-    // -m <model>, -r <effort>.
-    //
-    // Hooks: Claude-shaped. settings.json carries a top-level `hooks` object keyed
-    // by event (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart,
-    // SessionEnd, Stop, SubagentStop, Notification, PreCompact), each an array of
-    // `{ matcher?, hooks: [{ type: "command", command, timeout? }] }` matcher
-    // groups — verified against the droid binary's zod schema. So the Claude
-    // registrar is reused verbatim, just targeting `.factory/settings.json`.
-    //
-    // Plugins: native `droid plugin` command group + ~/.factory/plugins/ with the
-    // same marketplace layout Claude uses (known_marketplaces.json +
-    // marketplaces/<name>/plugins/<plugin>/). Droid's plugin manifest dir is
-    // `.factory-plugin/` (it also reads `.claude-plugin/` for compatibility) — set
-    // pluginManifestDir so syncPluginToVersion mirrors the manifest into it, the
-    // same pattern codex uses with `.codex-plugin`.
-    //
-    // Workflows / Factory Missions (RUSH-1864, probed droid v0.177.0; ticket cited
-    // v0.161.0 — self-updating, no pinnable semver): Factory ships genuine multi-
-    // step orchestration ("Missions") via `/missions` (interactive) and
-    // `droid exec --mission` (headless; optional `-f <prompt.md>` is a *prompt*
-    // file, not a named mission template). Docs:
-    // https://docs.factory.ai/cli/features/missions and
-    // https://docs.factory.ai/docs/droid-exec/overview (Mission Mode).
-    //
-    // Mission state may land under `~/.factory/missions/<sessionId>/` at runtime
-    // (`getMissionsDir` = join(home, ".factory", "missions") + per-session
-    // mission.md / features.json / progress_log.jsonl) — that is **session
-    // runtime state**, not a discovery directory of installable named workflows.
-    // There is no discoverMission / template registry, and a cold install has no
-    // `~/.factory/missions/` until a mission is run. agents-cli's workflows
-    // capability means "sync WORKFLOW.md into an auto-discovered dir" — Droid
-    // has no such dir, so workflows stays false (invoke-only; do not fabricate a
-    // writer target).
     droid: {
         id: 'droid',
         name: 'Droid',
@@ -744,8 +558,6 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        // Factory Droid Computers (cloud VMs) reached via `droid computer ssh` +
-        // remote headless `droid exec`.
         cloudProvider: 'factory',
         capabilities: {
             hooks: true,
@@ -758,7 +570,6 @@ export const AGENTS = {
             plugins: true,
             subagents: true,
             rules: { file: 'AGENTS.md' },
-            // Factory Missions are invoke-only — no installable discovery dir (RUSH-1864).
             workflows: false,
             memory: false,
             modes: ['plan', 'edit', 'auto', 'skip'],
@@ -766,9 +577,6 @@ export const AGENTS = {
             interactiveRepl: true,
         },
     },
-    // Nous Hermes Agent. Config lives under ~/.hermes/config.yaml; MCP servers
-    // are YAML `mcp_servers`, skills are local SKILL.md directories, and durable
-    // memory is file-backed.
     hermes: {
         id: 'hermes',
         name: 'Hermes',
@@ -793,24 +601,11 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        // Plugins: Hermes loads plugins from a flat `~/.hermes/plugins/<name>/` dir
-        // with a `plugin.yaml` manifest; a plugin only loads once its name is in the
-        // `plugins.enabled` allowlist in `~/.hermes/config.yaml` (deny-list
-        // `plugins.disabled` wins). Not the Claude marketplace layout, so it installs
-        // via a flat-copy branch (mirrors goose) plus a YAML allowlist toggle.
-        // See https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins
         capabilities: {
-            // Lifecycle hooks land in ~/.hermes/config.yaml under a `hooks:` block
-            // (YAML, shared with `mcp_servers`); gated to Hermes ≥ 0.11.0 which
-            // introduced the configurable hook runner.
             hooks: { since: '0.11.0' },
             mcp: true,
             mcpHttp: true,
             mcpHeaders: false,
-            // Permissions: ~/.hermes/config.yaml carries `command_allowlist` for
-            // always-approved command globs and `approvals.deny` for unconditional
-            // command blocks. It is command-glob only; session `/tools` toggles are
-            // intentionally not persisted by agents-cli.
             allowlist: true,
             skills: true,
             commands: false,
@@ -824,16 +619,6 @@ export const AGENTS = {
             interactiveRepl: true,
         },
     },
-    // Meta Muse Code (`muse`) — first-class harness for Meta's coding agent (terminal/CI), built on
-    // Muse Spark. Native binary via curl installer (self-updating; no npm package).
-    // Config: `~/.config/muse/settings.json` (requires `"schema_version": 1`).
-    // Sessions: `~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl`.
-    // Skills: `~/.config/muse/skills` + `~/.agents/skills` + project `.agents/skills`.
-    // MCP: `mcp_servers` in settings.json (stdio / streamable_http transports).
-    // Headless: `muse exec "<prompt>"` with --model, --reasoning-effort, --json,
-    // --yolo / --disable-approval / --disable-sandbox. Auth: META_API_KEY or
-    // browser OAuth stored at `~/.config/muse/auth.json`. Default model:
-    // muse-spark-1.2. Docs: https://dev.meta.ai/docs/muse-code
     muse: {
         id: 'muse',
         name: 'Muse',
@@ -858,59 +643,26 @@ export const AGENTS = {
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
-        // Muse hooks use the Claude-shaped settings.json hooks block (matcher +
-        // command groups) under ~/.config/muse/settings.json, plus project
-        // `.muse/hooks.json`. registerHooksForClaude is reused with Muse's config
-        // dir and schema_version: 1.
         supportsHooks: true,
-        // Claude-compatible marketplace layout + native `.muse-plugin/` manifest.
         pluginManifestDir: '.muse-plugin',
         capabilities: {
-            // Hooks: Claude-compatible event→matcher→command groups in settings.json.
             hooks: true,
             mcp: true,
             mcpHttp: true,
             mcpHeaders: true,
-            // Muse's safety model is approval-mode + OS sandbox (CLI flags), not a
-            // Claude-style tool-name allow/deny list. No settings.permissions writer.
             allowlist: false,
             skills: true,
-            // No slash-command file dir; skills double as reusable workflows.
             commands: false,
-            // Plugins: Claude marketplace + .muse-plugin (syncPluginToVersion).
             plugins: true,
-            // Runtime multi-agent / subagents exist, but there is no installable
-            // subagent-definition directory for agents-cli to sync into (capability
-            // table must stay truthful — see subagents-registry completeness).
             subagents: false,
             rules: { file: 'AGENTS.md' },
             workflows: false,
-            // Portable memory at <repo>/.agents/memory/ + personal scopes.
             memory: true,
             modes: ['plan', 'edit', 'auto', 'skip'],
             rulesImports: false,
             interactiveRepl: true,
         },
     },
-    // Warp Agent CLI (`warp`) — Warp's standalone interactive TUI coding agent
-    // (docs.warp.dev/cli). Installed by the official cross-platform installer
-    // `curl -fsSL https://app.warp.dev/download/agent-cli | bash` (Windows: the
-    // sibling agent-cli.ps1), which drops a self-updating `warp` binary at
-    // ~/.local/bin/warp — NOT the older `oz` platform runner (brew cask `oz` /
-    // apt `oz-stable`), a separate headless product that no longer matches this
-    // CLI. Config lives under `~/.warp/` (`.mcp.json`, `skills/`, `tui/`). It is
-    // interactive-only: bare `warp` opens the TUI (streamed responses, diffs,
-    // inline approvals). There is NO headless one-shot form — the documented
-    // flags are --api-key / --auto-approve / --resume <token> /
-    // --set-provider-api-key / --clear-provider-api-key / --version / --help; no
-    // -p/--prompt, no --model (model is the `/model` picker), no JSON output.
-    // Auth: interactive browser sign-in on launch, or the `WARP_API_KEY` env
-    // token / `--api-key` for CI. Rules/context file is `AGENTS.md` (also reads
-    // WARP.md / CLAUDE.md). Conversations sync SERVER-SIDE to the Warp/Oz
-    // platform (resume a prior one with `warp --resume <token>`), so there is no
-    // local transcript for `agents sessions` to index — warp is intentionally
-    // absent from SESSION_AGENTS.
-    // Docs: https://docs.warp.dev/cli/quickstart
     warp: {
         id: 'warp',
         name: 'Warp',
@@ -934,57 +686,27 @@ export const AGENTS = {
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
-        // Warp has no event->shell-command hook registration surface (its startup
-        // flags are --api-key/--auto-approve/--resume/--set-provider-api-key/
-        // --clear-provider-api-key — no hooks).
         supportsHooks: false,
         capabilities: {
             hooks: false,
-            // MCP: Warp reads the Claude `{ "mcpServers": {...} }` schema from
-            // `.warp/.mcp.json` (user `~/.warp/.mcp.json`, project `<root>/.warp/.mcp.json`),
-            // stdio + http with headers, same schema as Claude's .mcp.json.
             mcp: true,
             mcpHttp: true,
             mcpHeaders: true,
-            // Autonomy is a single toggle (`--auto-approve`), not a Claude-style
-            // tool-name allow/deny list agents-cli can write — so no allowlist writer
-            // (mirrors muse).
             allowlist: false,
-            // Skills searched in `.agents/skills/`, `.warp/skills/`, `.claude/skills/`,
-            // `.codex/skills/`.
             skills: true,
-            // Slash-commands are native/server-managed (no droppable markdown
-            // command-file directory for agents-cli to sync into).
             commands: false,
-            // No Claude marketplace / plugin manifest support.
             plugins: false,
-            // Cloud agents are server-side; no installable subagent-definition
-            // directory to sync into (keeps the table truthful).
             subagents: false,
             rules: { file: 'AGENTS.md' },
             workflows: false,
             memory: false,
-            // No per-run permission flag beyond `--auto-approve`; the single `edit`
-            // mode maps to no flags (mirrors hermes).
             modes: ['edit'],
             rulesImports: false,
-            // Bare `warp` opens the interactive TUI (its only run form).
             interactiveRepl: true,
         },
     },
 };
-/** All current and legacy agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
-/**
- * Agents the routine daemon can fire locally. Lives here (not runner.ts) so
- * routines.ts can import it for schedule-time validation without a circular
- * import (runner.ts already imports from routines.ts).
- *
- * This is a curated subset of AGENT_COMMANDS, not "every harness that can run
- * headlessly". Expanding it is a product change. Argv itself is baked from
- * AGENT_COMMANDS in daemon/runner.ts bakeRoutineArgv — do not reintroduce a
- * second token table.
- */
 export const ROUTINE_AGENT_IDS = Object.freeze([
     'claude',
     'codex',
@@ -993,62 +715,30 @@ export const ROUTINE_AGENT_IDS = Object.freeze([
     'droid',
     'muse',
 ]);
-/** Agents that can receive managed installs, imports, and resource sync writes. */
 export const MANAGED_AGENT_IDS = ALL_AGENT_IDS.filter((id) => !AGENTS[id].deprecated?.hard);
-/**
- * A self-updating agent is a single global binary installed by an official
- * `curl … | sh` / `brew install` script that carries NO version token — the
- * installer can only ever fetch the *current* release, and the binary then keeps
- * itself up to date in place (droid, grok, antigravity, cursor, hermes,
- * goose). There is no semver to pin, so agents-cli must not model these as
- * having multiple installable version-homes the way it does for npm-packaged
- * agents (claude, codex, kimi, …).
- *
- * The predicate is `!npmPackage && installScript && !installScript.includes('VERSION')`:
- *   - `npmPackage` empty       → not installed from npm, so `agents add x@1.2.3`
- *                                can't resolve a registry version.
- *   - `installScript` present  → it IS installed by a script (not unmanaged).
- *   - no `VERSION` placeholder → the script has no slot for a pinned version
- *                                (contrast: an installer templated with `VERSION`
- *                                could pin, and is NOT self-updating).
- *
- * Route every "is this a pinnable, multi-version agent?" decision through here —
- * never a scattered `agent === 'droid'`.
- */
 export function isSelfUpdatingAgent(agent) {
     const cfg = AGENTS[agent];
     return !cfg.npmPackage && !!cfg.installScript && !cfg.installScript.includes('VERSION');
 }
 export function isAgentHardDeprecated(agent) {
-    // Tolerate ids outside the registry (legacy YAML, test fixtures): an unknown
-    // agent is not hard-deprecated — its own validation rejects it elsewhere.
     return AGENTS[agent]?.deprecated?.hard === true;
 }
-// Capability-filtered agent lists used to live here as `*_CAPABLE_AGENTS`
-// constants. They were a frequent source of silent-skip bugs (e.g. grok
-// rules sync gated on `COMMANDS_CAPABLE_AGENTS`). Use `capableAgents(cap)`
-// from `./capabilities.js` instead — it consults the AgentConfig matrix
-// directly, so a single source of truth drives every gate.
-/** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export function colorAgent(agentId) {
     const agent = AGENTS[agentId];
     if (!agent)
         return chalk.white;
     return chalk[agent.color];
 }
-/** Return the agent's display name, colored. */
 export function agentLabel(agentId) {
     const agent = AGENTS[agentId];
     if (!agent)
         return agentId;
     return chalk[agent.color](agent.name);
 }
-/** Check whether the given agent's CLI binary is present on PATH. */
 export async function isCliInstalled(agentId) {
     const agent = AGENTS[agentId];
     return findInPath(agent.cliCommand) !== null;
 }
-/** Return the installed CLI version for the given agent, or null if not found. */
 export async function getCliVersion(agentId) {
     const agent = AGENTS[agentId];
     const binaryPath = findInPath(agent.cliCommand);
@@ -1056,18 +746,15 @@ export async function getCliVersion(agentId) {
         return null;
     return getCachedVersionForBinary(agentId, binaryPath);
 }
-/** Return the absolute path to the agent's CLI binary on PATH, or null. */
 export async function getCliPath(agentId) {
     return findInPath(AGENTS[agentId].cliCommand);
 }
-/** Look up version from cache by (binary, mtime). On miss or stale, spawn `--version` and cache. */
 async function getCachedVersionForBinary(agentId, binaryPath) {
     let mtime = 0;
     try {
         mtime = fs.statSync(binaryPath).mtimeMs;
     }
     catch {
-        /* binary vanished between findInPath and statSync */
         return null;
     }
     const cache = loadCliVersionCache();
@@ -1078,10 +765,6 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
     const agent = AGENTS[agentId];
     let version = null;
     try {
-        // probeCapture, not bare execFileAsync: a probed harness can fork its own
-        // children (copilot's platform-binary downloader), and a timeout kill of
-        // the direct child would orphan them mid-write (RUSH-3028). The probe runs
-        // in its own process group and the whole group is reaped on settle.
         const { stdout } = await probeCapture(agent.cliCommand, ['--version'], 3000);
         const versionRe = agent.versionStdoutMatch === 'openclaw'
             ? /openclaw\/(\d+\.\d+\.\d+)/
@@ -1090,32 +773,18 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
         version = match ? match[1] : stdout.trim();
     }
     catch {
-        /* version command failed */
         version = null;
     }
-    // Skip persisting null results — the most common cause is a transient
-    // `--version` failure (slow startup, stdout race, etc.). A sticky-null
-    // entry kept users in a broken state where every subsequent
-    // `getCachedVersionForBinary` short-circuited to null forever, even
-    // after the binary started working. Re-probing on the next call costs
-    // one execFile; persisting null costs the whole feature.
     if (version !== null) {
         cache[agentId] = { binaryPath, mtime, version };
         saveCliVersionCache();
     }
     return version;
 }
-/**
- * Resolve the full CLI state for an agent: whether it is installed, its version,
- * and the path to the binary. Checks version-managed installs first, then falls
- * back to a plain PATH lookup.
- */
 export async function getCliState(agentId) {
-    // Fast path: if version-managed, derive state from filesystem (no subprocesses)
     const agent = AGENTS[agentId];
     const agentVersionsDir = path.join(getVersionsDir(), agentId);
     if (fs.existsSync(agentVersionsDir)) {
-        // Use resolved version (project manifest -> global default)
         const resolvedVer = resolveVersion(agentId, process.cwd());
         if (resolvedVer) {
             const binaryPath = path.join(agentVersionsDir, resolvedVer, 'node_modules', '.bin', agent.cliCommand);
@@ -1128,7 +797,6 @@ export async function getCliState(agentId) {
                 };
             }
         }
-        // Fallback: if no default set or resolved version not installed, return first available
         const entries = fs.readdirSync(agentVersionsDir, { withFileTypes: true });
         for (const entry of entries) {
             if (entry.isDirectory()) {
@@ -1146,20 +814,9 @@ export async function getCliState(agentId) {
     }
     return getUnmanagedCliState(agentId);
 }
-/**
- * Resolve the agent's OWN install — the one agents-cli does not manage — by plain
- * PATH lookup, ignoring the version dirs entirely.
- *
- * Callers that specifically mean "the user's own globally-installed CLI" must use
- * this rather than `getCliState`, whose managed fast path reports an installed
- * version (any version dir, in readdir order) and would therefore hand back an
- * isolated copy — a copy that is deliberately unreachable from PATH — labelled as
- * the global install.
- */
 export async function getUnmanagedCliState(agentId) {
+    // This path must never relabel an isolated managed version as the user's global install.
     const agent = AGENTS[agentId];
-    // Grok (and any future harness with unmanagedBinary: 'grok-downloads')
-    // keeps versioned binaries under ~/.grok/downloads/, not on PATH.
     if (agent.unmanagedBinary === 'grok-downloads') {
         const grokBin = resolveGrokBinary();
         if (!grokBin) {
@@ -1181,7 +838,6 @@ export async function getUnmanagedCliState(agentId) {
         path: binaryPath,
     };
 }
-/** Resolve CLI state for all registered agents in parallel. */
 export async function getAllCliStates() {
     const states = {};
     const results = await Promise.all(ALL_AGENT_IDS.map(async (agentId) => ({
@@ -1193,16 +849,7 @@ export async function getAllCliStates() {
     }
     return states;
 }
-/**
- * Agents that `agents setup` probes for pre-existing native installations
- * (i.e., a config dir present before agents-cli took over). Derived from
- * `sessionDir` so a new harness cannot be walkable yet missing from setup.
- */
 export const UNMANAGED_DETECTION_CANDIDATES = ALL_AGENT_IDS.filter((id) => AGENTS[id].sessionDir !== null);
-/**
- * Detect existing agent installations that are NOT yet managed by agents-cli.
- * Returns agents whose config dir exists as a real directory (not a symlink).
- */
 export async function getUnmanagedAgentInstalls() {
     const unmanaged = [];
     for (const agentId of UNMANAGED_DETECTION_CANDIDATES) {
@@ -1215,50 +862,26 @@ export async function getUnmanagedAgentInstalls() {
             }
         }
         catch {
-            // Config dir doesn't exist
         }
     }
     return unmanaged;
 }
-/** Create the agent's slash-commands directory if it does not exist. */
 export function ensureCommandsDir(agentId) {
     const agent = AGENTS[agentId];
     if (!fs.existsSync(agent.commandsDir)) {
         fs.mkdirSync(agent.commandsDir, { recursive: true });
     }
 }
-/** Create the agent's skills directory if it does not exist. */
 export function ensureSkillsDir(agentId) {
     const agent = AGENTS[agentId];
     if (!fs.existsSync(agent.skillsDir)) {
         fs.mkdirSync(agent.skillsDir, { recursive: true });
     }
 }
-/**
- * The agent's config-dir name relative to $HOME — e.g. '.claude',
- * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
- *
- * Path segment to join onto a (version) home root when locating an agent's
- * commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong for
- * every agent whose config dir is nested or under ~/.config — antigravity
- * (~/.gemini/antigravity-cli), amp (~/.config/amp), goose (~/.config/goose),
- * kimi (~/.kimi-code). Mirrors the shim configDirName derivation in shims.ts.
- *
- * Relativized against the module-level HOME constant (the same value used to
- * build every `configDir`), NOT a fresh `os.homedir()` — so the result stays a
- * clean relative name even when HOME is overridden after module load (tests,
- * sandboxes). Using `os.homedir()` here would yield `../../real/home/.claude`.
- */
 export function agentConfigDirName(agentId) {
+    // Use import-time HOME: nested config dirs and later HOME overrides must stay relative.
     return path.relative(HOME, AGENTS[agentId].configDir);
 }
-/**
- * Human-readable label for a Claude account's organizationType as read from
- * .claude.json's oauthAccount ("claude_team" -> "Team"). Unrecognized values
- * (future tiers) are rendered by stripping the "claude_" prefix and
- * title-casing the rest — an unfamiliar-but-visible label beats silence.
- * Returns null for missing input.
- */
 export function formatClaudeOrgLabel(orgType) {
     if (!orgType)
         return null;
@@ -1278,22 +901,13 @@ export function formatClaudeOrgLabel(orgType) {
         .map((w) => w[0].toUpperCase() + w.slice(1))
         .join(' ');
 }
-/**
- * Short badge identifying which ORG an account belongs to — "Turing Labs" for a
- * multi-seat Team/Enterprise org, whose name is real identity that disambiguates
- * a Team seat from a same-email personal plan. Returns null for personal plans
- * (Max/Pro/Free): the tier label now lives in the aligned plan column, so a badge
- * would only duplicate it, and a personal org's name is auto-generated boilerplate
- * ("<email>'s Organization"), not identity. Also null when the account carries no
- * organizationType (signed out, non-Claude agents, configs predating the field).
- */
 export function accountOrgBadge(info) {
+    // Personal org names are boilerplate; only named multi-seat orgs disambiguate identity.
     const isMultiSeat = info?.organizationType === 'claude_team' || info?.organizationType === 'claude_enterprise';
     if (isMultiSeat && info?.organizationName)
         return info.organizationName;
     return null;
 }
-/** Agents whose local credential formats expose enough state for account selection. */
 export const ACCOUNT_INSPECTION_AGENT_IDS = [
     'claude',
     'codex',
@@ -1306,15 +920,9 @@ export const ACCOUNT_INSPECTION_AGENT_IDS = [
     'muse',
 ];
 const ACCOUNT_INSPECTION_AGENTS = new Set(ACCOUNT_INSPECTION_AGENT_IDS);
-/** Whether agents-cli can determine this agent's per-version sign-in state. */
 export function supportsAccountInspection(agentId) {
     return ACCOUNT_INSPECTION_AGENTS.has(agentId);
 }
-/**
- * Human-readable account identity shared by every account-aware surface.
- * Prefer email, append a multi-seat Claude organization name when present,
- * then fall back to a non-secret account id or a generic signed-in label.
- */
 export function accountDisplayLabel(info) {
     if (!info)
         return '';
@@ -1326,26 +934,10 @@ export function accountDisplayLabel(info) {
         return info.accountId ? `id:${info.accountId}` : 'signed in';
     return '';
 }
-/** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {
     const info = await getAccountInfo(agentId, home);
     return info.email;
 }
-/**
- * Extract full account information (identity, plan, usage status, credits) from
- * the agent's local auth/config files. Supports Claude, Codex, and Gemini.
- */
-/**
- * Resolve a file-auth agent's credential file. Sign-in is account-global, but
- * each installed version gets an isolated home; the credential physically lives
- * only in the home the user logged in under (the one the `~/.<config>` symlink
- * targets). Check the per-version `base` first, then fall back to the active
- * config location under the real HOME so every installed version reflects the
- * true account state (droid/antigravity/kimi all stored login per-version-home
- * and showed non-active versions as "not signed in"). Returns the first
- * existing path, or null.
- */
-/** True when `dir` is under the per-account slot root (`~/.agents/.history/accounts/`). */
 export function isAccountSlotDir(dir) {
     const root = path.resolve(getHistoryDir(), 'accounts');
     const resolved = path.resolve(dir);
@@ -1357,9 +949,7 @@ function resolveAccountCredentialPath(base, ...segments) {
         if (fs.existsSync(perVersion))
             return perVersion;
     }
-    catch { /* unreadable */ }
-    // A slot is the account's own HOME (PHNX-3940 T5). Never inherit another
-    // account's adopted ~/.<config> — that is the cross-account leak.
+    catch { }
     if (isAccountSlotDir(base))
         return null;
     const active = path.join(process.env.AGENTS_REAL_HOME || os.homedir(), ...segments);
@@ -1368,22 +958,10 @@ function resolveAccountCredentialPath(base, ...segments) {
             if (fs.existsSync(active))
                 return active;
         }
-        catch { /* unreadable */ }
+        catch { }
     }
     return null;
 }
-/**
- * The on-disk credential file(s) each account-inspectable agent authenticates
- * from, expressed as path segments under a home. Mirrors the exact files
- * {@link getAccountInfo} reads, so a presence check here matches what a real
- * launch would find. Each entry is a list of alternatives — the FIRST that
- * exists counts as present (claude writes either `.claude/.claude.json` under
- * the shimmed config dir or a home-level `.claude.json`). Agents whose login is
- * stored only in the OS keychain on some platforms (antigravity, and claude's
- * token) still expose a credential FILE — the presence of that file is the
- * signal we key off; its absence on BOTH the per-version home and the active
- * home is what makes a logged-out claim provable.
- */
 const CREDENTIAL_FILE_SEGMENTS = {
     claude: [['.claude', '.claude.json'], ['.claude.json']],
     codex: [['.codex', 'auth.json']],
@@ -1392,14 +970,9 @@ const CREDENTIAL_FILE_SEGMENTS = {
     droid: [['.factory', 'auth.v2.file']],
     antigravity: [['.gemini', 'antigravity-cli', 'antigravity-oauth-token']],
     opencode: [['.local', 'share', 'opencode', 'auth.json']],
-    // Muse Code stores OAuth / API credentials at ~/.config/muse/auth.json
-    // (or META_API_KEY in the environment, which is not a file).
     muse: [['.config', 'muse', 'auth.json']],
-    // With AGENT_CLI_CREDENTIAL_STORE=file, Cursor stores both OAuth tokens at
-    // ~/.cursor/auth.json. cli-config.json holds account metadata only.
     cursor: [['.cursor', 'auth.json']],
 };
-/** Whether an agent's credential file exists under a given home. */
 function credentialFileExistsUnder(agentId, home) {
     const alternatives = CREDENTIAL_FILE_SEGMENTS[agentId];
     if (!alternatives)
@@ -1415,47 +988,18 @@ function credentialFileExistsUnder(agentId, home) {
     });
     if (!hasSegment)
         return false;
-    // Claude's `.claude.json` is account METADATA Claude Code writes on any
-    // launch, not the credential itself — a version can carry stale identity
-    // there (e.g. install-time carry-forward) with no usable credential behind
-    // it: a failed OAuth refresh blanks `.credentials.json`, and a Linux worker
-    // can be missing BOTH `.credentials.json` and the `.oauth_token` setup-token
-    // file entirely (PHNX-3502). `credentialPresence` promises to mirror what a
-    // real launch would find, so it must fail whenever `isClaudeCredentialFileBlank`
-    // — the SAME floor `getAccountInfo` applies — would. On macOS that floor is a
-    // no-op (Keychain-only, always "not blank"), so this reduces to the identity
-    // check above, unchanged.
     if (agentId === 'claude')
         return !isClaudeCredentialFileBlank(home);
     return true;
 }
-/**
- * File-presence probe for an agent's credential, split by location: whether it
- * exists in a SPECIFIC version home (`perVersion`) and whether it exists under
- * the active/global HOME (`active`). A logged-out claim is only *provable* when
- * BOTH are absent — a version that merely lacks its own copy but shares the
- * global login is signed in, not logged out. Pure file existence; no decrypt,
- * no network, no keychain prompt. Agents with no inspectable identity return
- * `{ perVersion: false, active: false }` and must NEVER yield a provable-logout
- * claim (the caller gates on {@link supportsAccountInspection}).
- */
 export function credentialPresence(agentId, versionHome) {
+    // Logout is provable only for a known location when both isolated and active copies are absent.
     const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
     const perVersion = credentialFileExistsUnder(agentId, versionHome);
     const active = credentialFileExistsUnder(agentId, realHome);
     const knownLocation = (CREDENTIAL_FILE_SEGMENTS[agentId]?.length ?? 0) > 0;
     return { perVersion, active, knownLocation };
 }
-/**
- * Factory Droid stores its OAuth credential encrypted at ~/.factory/auth.v2.file
- * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored
- * in ~/.factory/auth.v2.key. On the keyfile-v2 source there is no OS-keychain /
- * device binding — the key is on disk — so we can decrypt locally with no
- * network call. Every failure (missing key file — e.g. a keyring-v2/legacy
- * login with no on-disk key, a bad GCM tag, or malformed JSON) returns null.
- * Never throws. Shared by account identity below and the Droid usage fetcher
- * in usage.ts.
- */
 export function decryptDroidAuthPayload(base) {
     const filePath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
     const keyPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.key');
@@ -1463,16 +1007,8 @@ export function decryptDroidAuthPayload(base) {
         return null;
     return decryptDroidAuthFile(filePath, keyPath);
 }
-/**
- * Decrypt a Droid `auth.v2.file` (AES-256-GCM `ivB64:tagB64:ctB64`) using the
- * raw 32-byte key stored base64 in `auth.v2.key`, given the EXACT paths to both.
- * Same crypto as decryptDroidAuthPayload but without the account-global HOME
- * fallback, so the identity of a SPECIFIC version home resolves against only
- * that home's files (carryForwardAuthFiles needs per-dir identity). Returns null
- * on any failure (missing file/key, wrong key length, bad GCM tag, malformed
- * JSON). Never throws.
- */
 function decryptDroidAuthFile(filePath, keyPath) {
+    // Exact paths deliberately bypass active-HOME fallback for per-directory carry-forward identity.
     try {
         const blob = fs.readFileSync(filePath, 'utf-8').trim();
         const key = Buffer.from(fs.readFileSync(keyPath, 'utf-8').trim(), 'base64');
@@ -1494,26 +1030,8 @@ function decryptDroidAuthFile(filePath, keyPath) {
         return null;
     }
 }
-/**
- * Stable account identity for a *file-auth* agent's credential directory
- * (droid / kimi / antigravity), or null when the directory holds no decodable
- * account claim. Unlike a naive top-level JSON key-scan (which matched NO real
- * credential file), this decrypts / decodes each agent's REAL on-disk format so
- * the identity resolves against production credentials:
- *   - droid: AES-256-GCM auth.v2.file (+ auth.v2.key) -> WorkOS access-token JWT
- *     -> email / org_id / sub.
- *   - kimi: credentials/kimi-code.json -> access-token JWT -> user_id / sub.
- *   - antigravity: antigravity-oauth-token -> token.refresh_token -> JWT sub
- *     when the token is a JWT, else a SHA-256 hash of the raw refresh-token
- *     value (opaque Google consumer tokens are stable per login — hashed so
- *     the identity key, which is persisted as a usage-cache key, never carries
- *     a live credential).
- * Two directories for the SAME account compare equal; two DIFFERENT accounts
- * compare distinct. Used by carryForwardAuthFiles to refuse overwriting one
- * account's login with a credential that belongs to a DIFFERENT account
- * (RUSH-1764). Never throws.
- */
 export function readAuthAccountIdentity(agent, configDir) {
+    // Identity claims outlive JWT authorization; credential usability is decided elsewhere.
     try {
         switch (agent) {
             case 'droid': {
@@ -1542,9 +1060,6 @@ export function readAuthAccountIdentity(agent, configDir) {
                     return null;
                 const claims = decodeJwtPayload(refreshToken);
                 const sub = normalizeIdentityPart(claims?.sub ?? claims?.user_id);
-                // An opaque (non-JWT) Google refresh token IS the credential — hash it
-                // so the identity key stays stable per login without embedding a live
-                // secret (the key is persisted as a usage-cache filename key).
                 const fallback = crypto.createHash('sha256').update(refreshToken).digest('hex').slice(0, 16);
                 return buildIdentityKey(agent, [['sub', sub ?? fallback]]);
             }
@@ -1556,15 +1071,6 @@ export function readAuthAccountIdentity(agent, configDir) {
         return null;
     }
 }
-/**
- * Derive Droid account identity from the decrypted credential. The
- * `access_token` is a WorkOS JWT carrying an `email` claim (plus org_id /
- * role). We decode the claim WITHOUT verifying `exp`: the email is stable
- * identity for display, not an authorization decision, so an expired token
- * still yields the right address. Returns null when the credential can't be
- * decrypted or has no decodable claims, so the caller falls back to the
- * file-presence signed-in signal.
- */
 function decryptDroidCredential(base) {
     const cred = decryptDroidAuthPayload(base);
     const claims = typeof cred?.access_token === 'string' ? decodeJwtPayload(cred.access_token) : null;
@@ -1577,38 +1083,18 @@ function decryptDroidCredential(base) {
     };
 }
 let cachedAgyKeychainSignedIn;
-/**
- * Antigravity (`agy`) stores its OAuth token via the Go keyring library
- * (zalando/go-keyring), which is platform-split:
- *
- *   - macOS: login keychain, service `gemini`, account `antigravity` — no file.
- *   - Linux with Secret Service (libsecret / gnome-keyring): attributes
- *     service=`gemini`, username=`antigravity` (go-keyring's Secret Service
- *     mapping of service+user). Prefer this over the file when a keyring
- *     daemon is running.
- *   - Linux without Secret Service: file fallback at
- *     `~/.gemini/antigravity-cli/antigravity-oauth-token`.
- *
- * Probe the OS keyring for existence after the file check. On macOS,
- * `security find-generic-password` without `-w` is metadata-only (never
- * prompts). On Linux, `secret-tool lookup` exit 0 means the item exists
- * (stdout is the secret — discarded, never logged). Cached per process —
- * the keyring is account-global, so one probe covers every installed version.
- * Returns false when the platform has no probe (Windows) or the tool is
- * missing. Guard with `AGENTS_NO_KEYCHAIN_PROBE=1` for hermetic tests.
- */
 export function antigravityOsKeyringProbe(platform = process.platform) {
     if (platform === 'darwin') {
         return {
             cmd: 'security',
+            // Omitting -w makes this a metadata-only probe that never reads the secret.
             args: ['find-generic-password', '-s', 'gemini', '-a', 'antigravity'],
         };
     }
     if (platform === 'linux') {
-        // go-keyring secret_service attributes: "service" + "username" (not
-        // "account" — that flag is the macOS security(1) spelling of the same user).
         return {
             cmd: 'secret-tool',
+            // go-keyring maps the user to username, not the macOS account spelling.
             args: ['lookup', 'service', 'gemini', 'username', 'antigravity'],
         };
     }
@@ -1619,8 +1105,6 @@ export function __resetAntigravityKeychainCacheForTest() {
     cachedAgyKeychainSignedIn = undefined;
 }
 async function antigravityKeychainSignedIn() {
-    // Test isolation first (before cache): real OS keyrings can't be sandboxed
-    // per-test. Same spirit as AGENTS_REAL_HOME. Not cached, so tests can toggle.
     if (process.env.AGENTS_NO_KEYCHAIN_PROBE === '1')
         return false;
     if (cachedAgyKeychainSignedIn !== undefined)
@@ -1631,47 +1115,21 @@ async function antigravityKeychainSignedIn() {
         return false;
     }
     try {
-        // Discard stdout: Linux secret-tool lookup prints the secret value.
         await execFileAsync(probe.cmd, probe.args, {
             timeout: 3000,
-            // encoding so stdout is a string we can drop without ever logging it
             encoding: 'utf8',
         });
         cachedAgyKeychainSignedIn = true;
     }
     catch {
-        // Missing tool (ENOENT), missing item, locked collection, timeout → signed out.
         cachedAgyKeychainSignedIn = false;
     }
     return cachedAgyKeychainSignedIn;
 }
-/** The XDG base dirs OpenCode reads, and the env var that overrides each. */
 const OPENCODE_XDG_DIRS = {
     data: { env: 'XDG_DATA_HOME', fallback: ['.local', 'share'] },
     state: { env: 'XDG_STATE_HOME', fallback: ['.local', 'state'] },
 };
-/**
- * Resolve one of OpenCode's (sst/opencode) XDG-rooted files.
- *
- * OpenCode keeps provider credentials under `$XDG_DATA_HOME/opencode/` and TUI
- * state under `$XDG_STATE_HOME/opencode/`, defaulting to `~/.local/share` and
- * `~/.local/state` on EVERY platform — its `xdg-basedir` dependency does not
- * special-case macOS, so there is no `~/Library/Application Support` variant.
- * Both roots are account-global (not per-version), matching how
- * `session/discover.ts` already resolves `~/.local/share/opencode/opencode.db`.
- *
- * Resolution order, first existing wins:
- *   1. `<base>/<fallback>/opencode/<file>` — the passed per-version home. This is
- *      primarily a test hook (suites write a hermetic file under a temp home)
- *      but also covers any relocated install.
- *   2. `$XDG_<KIND>_HOME/opencode/<file>` — an explicit XDG override, exactly
- *      what OpenCode itself honours.
- *   3. `<realHome>/<fallback>/opencode/<file>` — the active default, under
- *      `AGENTS_REAL_HOME` or `os.homedir()`, so every installed version reflects
- *      the one account-global state (same fallback shape as
- *      resolveAccountCredentialPath).
- * Returns the first existing path, or null. Never throws.
- */
 export function resolveOpenCodeXdgPath(base, kind, file) {
     const { env, fallback } = OPENCODE_XDG_DIRS[kind];
     const candidates = [path.join(base, ...fallback, 'opencode', file)];
@@ -1685,23 +1143,15 @@ export function resolveOpenCodeXdgPath(base, kind, file) {
             if (fs.existsSync(candidate))
                 return candidate;
         }
-        catch { /* unreadable */ }
+        catch { }
     }
     return null;
 }
 function resolveOpenCodeAuthPath(base) {
     return resolveOpenCodeXdgPath(base, 'data', 'auth.json');
 }
-/**
- * Validate one OpenCode auth.json entry against its discriminated union
- * (`type: 'oauth' | 'api' | 'wellknown'`) and confirm the credential actually
- * carries its required secret field(s) non-empty. This guards against a
- * corrupt/half-written entry reading as signed-in — the same "must have a real
- * credential" floor grok/antigravity apply. We only INSPECT the shape here; the
- * secret values (`access`/`refresh`/`key`/`token`) are never read out or
- * surfaced anywhere.
- */
 function isValidOpenCodeCredential(value) {
+    // Only complete auth.json discriminated-union credentials establish a login.
     if (!value || typeof value !== 'object')
         return false;
     const cred = value;
@@ -1713,19 +1163,6 @@ function isValidOpenCodeCredential(value) {
         default: return false;
     }
 }
-/**
- * The human identity an OpenCode `type: 'oauth'` credential carries in its
- * access token, when that token is a JWT. Provider-agnostic by shape: the
- * OpenAI-issued token OpenCode stores under its `openai` provider carries the
- * same namespaced claims Codex's own `auth.json` does (`…/profile.email`,
- * `…/auth.chatgpt_plan_type`), so the extraction is shared with `case 'codex'`
- * rather than reinvented. A plain `email` claim is accepted too, for providers
- * that issue an ordinary OIDC token.
- *
- * Only claims are read — the token itself is never returned or logged. A
- * non-JWT credential (Anthropic's `sk-ant-oat…` opaque token, any `type: 'api'`
- * key) simply yields nothing.
- */
 function openCodeOauthIdentity(cred) {
     const access = cred?.access;
     if (typeof access !== 'string' || access.length === 0)
@@ -1743,29 +1180,8 @@ function openCodeOauthIdentity(cred) {
         : null;
     return { email, plan };
 }
-/**
- * OpenCode's account identity, read from `auth.json`.
- *
- * The provider join (`"meta+openai+opencode-go"`) is the stable key: OpenCode is
- * a multi-provider harness, so "which providers are configured" is what actually
- * identifies an install, and `session/discover.ts` indexes sessions by it.
- * Providers that sign in over OAuth additionally hand OpenCode a token with real
- * identity claims, so the email and plan are surfaced alongside it instead of
- * leaving `agents view` showing a bare `id:` key for a login that knows exactly
- * whose it is. Providers are walked in sorted order so a multi-OAuth install
- * resolves to the same email on every machine.
- *
- * This is the ONLY correct source for an OpenCode "account". OpenCode's SQLite
- * `opencode.db` also carries `account`/`account_state`/`control_account` tables,
- * but on a real, actively-used install (yosemite-s1, 1.16.0, 35 applied
- * migrations) all three are permanently empty — no migration ever populates
- * them, and no session has ever written a row. Reading from them instead of
- * `auth.json` always yields `undefined`, credential or not.
- *
- * Sync (`fs.readFileSync`), no network. Returns undefined when `auth.json` is
- * missing, unreadable, or carries no valid credential.
- */
 export function resolveOpenCodeIdentity(base) {
+    // auth.json, not empty SQLite account tables, is authoritative; sorted providers form the stable key.
     const authPath = resolveOpenCodeAuthPath(base);
     if (!authPath)
         return undefined;
@@ -1793,24 +1209,11 @@ export function resolveOpenCodeIdentity(base) {
         return undefined;
     }
 }
-/**
- * The provider join alone — the value `session/discover.ts` indexes sessions by,
- * kept as its own entry point so callers that only need the key do not have to
- * know about the OAuth claim walk.
- */
 export function resolveOpenCodeAccountId(base) {
     return resolveOpenCodeIdentity(base)?.providers;
 }
-/**
- * Whether a Muse Code `~/.config/muse/auth.json` document holds any usable
- * access token. Live shape from `muse login` (device OAuth, Muse Code 0.1.0):
- *   { schema_version: 1, providers: { meta: { access_token, api_key, user_email, … } } }
- * Also accept top-level or one-level-nested tokens for older/alternate writers.
- * Recurses into objects so `providers.meta.access_token` is found — a flat
- * one-level walk only saw `providers` and reported signed-out after a successful
- * login (balanced then excluded the account). Never returns the secret itself.
- */
 function museAuthHasToken(value, depth = 0) {
+    // Live auth nests under providers.meta; bounded recursion also accepts older nested writers.
     if (depth > 4)
         return false;
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -1826,7 +1229,6 @@ function museAuthHasToken(value, depth = 0) {
     }
     return false;
 }
-/** Best-effort email from a Muse auth.json (providers.meta.user_email, etc.). */
 function museAuthEmail(value, depth = 0) {
     if (depth > 4)
         return null;
@@ -1846,46 +1248,16 @@ function museAuthEmail(value, depth = 0) {
     }
     return null;
 }
-/**
- * Whether a Claude version home's credential file is present but carries no
- * token — the "must have a real credential" floor (see
- * `isValidOpenCodeCredential`) applied to claude.
- *
- * A FAILED OAuth refresh leaves exactly this state behind: Claude Code rewrites
- * `.claude/.credentials.json` with `accessToken: ""`, `refreshToken: ""` and
- * `expiresAt: 0`, keeping only the descriptive fields (`subscriptionType`,
- * `rateLimitTier`, `refreshTokenExpiresAt`). Everything we derive from
- * `.claude.json` — email, plan — still looks healthy, so the install reported
- * `signedIn: true`, `agents view` drew usage bars for it, and balanced rotation
- * (whose `authValid` is just "email present") kept picking it — every pick dying
- * at spawn on "OAuth session expired and could not be refreshed".
- *
- * Only decidable off macOS: there the login Keychain is the canonical store and
- * this file is not authoritative, and probing the Keychain would raise an
- * authorization sheet per installed version on every `agents run` — the reason
- * rotation stopped calling `isClaudeAuthValid` at all. Off macOS the file IS the
- * only store, so a missing or token-less file is proof of signed-out — unless a
- * Linux setup-token (`.claude/.oauth_token`) is present, which the shim exports
- * as `CLAUDE_CODE_OAUTH_TOKEN` and can authenticate the run without
- * `.credentials.json`. `platform` is a parameter so both branches are testable
- * on any host.
- *
- * Sync, no Keychain, no network — safe on the `agents run` hot path.
- */
 export function isClaudeCredentialFileBlank(base, platform = process.platform) {
+    // macOS uses Keychain; on Linux absence means logged out while corrupt data fails open.
     if (platform === 'darwin')
         return false;
-    // A per-version setup-token is a real credential on Linux even when
-    // `.credentials.json` was never written (the shim's `$CLAUDE_CONFIG_DIR/.oauth_token`
-    // fallback). Treat it as signed-in so rotation does not skip a worker that
-    // authenticates from an attached setup-token.
     try {
         const token = fs.readFileSync(path.join(base, '.claude', '.oauth_token'), 'utf-8').trim();
         if (token.length > 0)
             return false;
     }
     catch {
-        /* absent — fall through to the credentials.json floor */
     }
     try {
         const raw = fs.readFileSync(path.join(base, '.claude', '.credentials.json'), 'utf-8');
@@ -1896,30 +1268,15 @@ export function isClaudeCredentialFileBlank(base, platform = process.platform) {
         return !nonEmpty(oauth.accessToken) && !nonEmpty(oauth.refreshToken);
     }
     catch (err) {
-        // Off macOS the file IS the store. Missing it means this home cannot
-        // authenticate (a newly installed default with leftover `.claude.json`
-        // oauthAccount is the PHNX-2685 false-healthy case). A corrupt file is
-        // not positive evidence of a blank credential — leave the existing
-        // signal alone rather than declaring a working install signed out.
         if (err.code === 'ENOENT')
             return true;
         return false;
     }
 }
-/**
- * Read a Claude home's config and account identity. Returns null when the home has
- * no readable `.claude.json`, or has one with no `oauthAccount` (never signed in).
- *
- * Sync because the session scanner calls it once per home on a hot path, and the
- * file is a few KB of local JSON. No Keychain access — see `getAccountInfo`.
- */
 export function readClaudeHomeConfig(base) {
-    // Claude reads/writes config at $CLAUDE_CONFIG_DIR/.claude.json when set, falling
-    // back to $HOME/.claude.json. Our shim sets CLAUDE_CONFIG_DIR to the per-version
-    // .claude dir, so prefer that file; fall back to home-level for versions ever
-    // launched without the shim (IDE extension, direct binary).
     const configDirFile = path.join(base, '.claude', '.claude.json');
     const homeLevelFile = path.join(base, '.claude.json');
+    // Version-home config takes precedence over the legacy home-level file.
     const activeFile = fs.existsSync(configDirFile) ? configDirFile : homeLevelFile;
     let config;
     try {
@@ -1934,15 +1291,8 @@ export function readClaudeHomeConfig(base) {
     const email = normalizeIdentityPart(oa.emailAddress);
     let accountId = normalizeIdentityPart(oa.accountUuid);
     let organizationId = normalizeIdentityPart(oa.organizationUuid);
-    // Worker slot provisioned from a durable setup-token: only the email was
-    // seeded on disk (seedClaudeWorkerHomeIdentity), so accountUuid/organizationUuid
-    // are absent and both accountKey and usageKey would be null — the row reads
-    // "not connected here" (PHNX-3940, sibling worker-identity diagnosis). Complete
-    // the identity from the fleet-synced registry row for this email, keyed exactly
-    // as a headed login's home carries it. Guarded on email-only so a headed home
-    // (uuids on disk) never pays the readMeta() read, and fails CLOSED to email-only
-    // when zero or several rows match (registeredNativeAccountForEmail never guesses).
     if (email && !accountId && !organizationId) {
+        // Email-only worker homes accept one exact registry match; ambiguity fails closed.
         const registered = registeredNativeAccountForEmail(readMeta(), 'claude', email);
         const parts = registered ? parseNativeIdentityKey('claude', registered.identityKey) : null;
         if (parts) {
@@ -1959,6 +1309,7 @@ export function readClaudeHomeConfig(base) {
             organizationId,
             organizationName: oa.organizationName ?? null,
             organizationType: oa.organizationType ?? null,
+            // Usage is org-scoped; account routing is account+org scoped.
             usageKey: buildIdentityKey('claude', [['org', organizationId]]),
             accountKey: buildIdentityKey('claude', [
                 ['account', accountId],
@@ -1968,6 +1319,7 @@ export function readClaudeHomeConfig(base) {
     };
 }
 export async function getAccountInfo(agentId, home) {
+    // Group accounts by stable provider/org identity, never display text or stale metadata.
     const base = home || os.homedir();
     const empty = {
         accountKey: null,
@@ -1985,42 +1337,21 @@ export async function getAccountInfo(agentId, home) {
     const configFiles = {
         claude: path.join(base, '.claude.json'),
         codex: path.join(base, '.codex', 'auth.json'),
-        // OpenCode keeps every session in ONE sqlite file rather than a directory of
-        // per-session transcripts, so the session-file walk resolveLastActive runs
-        // for other agents finds nothing. Its mtime fallback is the right read here:
-        // opencode.db is written on every turn, so it tracks real activity.
         opencode: resolveOpenCodeXdgPath(base, 'data', 'opencode.db') ?? undefined,
     };
     const lastActive = resolveLastActive(agentId, base, configFiles[agentId]);
     try {
         switch (agentId) {
             case 'claude': {
-                // Identity extraction is shared with the session scanner's account
-                // attribution — see readClaudeHomeConfig. A home with no readable config or
-                // no oauthAccount is signed out, which is what the pre-refactor code
-                // produced when JSON.parse threw or oauthAccount was absent.
                 const claudeHome = readClaudeHomeConfig(base);
                 if (!claudeHome)
                     return { ...empty, lastActive };
                 const { config: data, identity } = claudeHome;
                 const oa = data.oauthAccount;
                 const { accountId, organizationId, email, accountKey, usageKey } = identity;
-                // Credential floor: a blanked credential file means this home cannot
-                // authenticate, whatever `.claude.json` still says. Report it signed out
-                // so `agents view` prompts a re-login and rotation routes around it,
-                // instead of handing runs to an install that dies at spawn.
                 if (email && isClaudeCredentialFileBlank(base)) {
                     return { ...empty, lastActive };
                 }
-                // Plan tier is derived from .claude.json's organizationType, which carries
-                // the TRUE tier (claude_max → "Max", claude_pro → "Pro", claude_team →
-                // "Team") and is already in-hand from the config we just read — no Keychain
-                // prompt. billingType only distinguishes "has a Stripe subscription" and so
-                // mislabels every Max account as "Pro"; keep it as a fallback for older
-                // configs predating organizationType. (Reading subscriptionType from the
-                // keychain item would force a macOS Keychain ACL prompt on every `agents
-                // run`, so we deliberately avoid it — organizationType gives us the tier
-                // without that cost.)
                 let plan = formatClaudeOrgLabel(oa?.organizationType);
                 if (!plan) {
                     if (oa?.billingType === 'stripe_subscription') {
@@ -2030,16 +1361,8 @@ export async function getAccountInfo(agentId, home) {
                         plan = oa.billingType;
                     }
                 }
-                // usageStatus is NOT derived from cachedExtraUsageDisabledReason. That
-                // field reports why pay-as-you-go overage is off (out_of_credits = no
-                // overage credits purchased; org_level_disabled = admin turned overage
-                // off), which says nothing about whether the account is throttled — a
-                // Pro account at 5% weekly usage with overage disabled is fully usable.
-                // Real throttle state comes from the live usage windows; callers derive
-                // it via deriveUsageStatusFromSnapshot(). Here we only report whether
-                // the account is signed in at all. Overage state stays visible through
-                // overageCredits below.
                 const usageStatus = email ? 'available' : null;
+                // Overage credit display is independent of the subscription throttle status.
                 let overageCredits = null;
                 const orgId = oa?.organizationUuid;
                 const creditCache = orgId && data.overageCreditGrantCache?.[orgId];
@@ -2074,7 +1397,6 @@ export async function getAccountInfo(agentId, home) {
                 if (!decoded)
                     return { ...empty, lastActive };
                 const email = decoded.email || null;
-                // Plan and subscription from OpenAI auth claim
                 const authClaim = decoded['https://api.openai.com/auth'] || {};
                 const accountId = normalizeIdentityPart(authClaim.chatgpt_account_id);
                 const userId = normalizeIdentityPart(authClaim.chatgpt_user_id || authClaim.user_id);
@@ -2086,7 +1408,6 @@ export async function getAccountInfo(agentId, home) {
                 ]);
                 const rawPlan = authClaim.chatgpt_plan_type;
                 const plan = rawPlan ? rawPlan.charAt(0).toUpperCase() + rawPlan.slice(1) : null;
-                // Subscription status: expired = out_of_credits
                 let usageStatus = null;
                 const activeUntil = authClaim.chatgpt_subscription_active_until;
                 if (activeUntil) {
@@ -2108,12 +1429,6 @@ export async function getAccountInfo(agentId, home) {
                 };
             }
             case 'cursor': {
-                // Cursor CLI keeps account metadata in ~/.cursor/cli-config.json
-                // (authInfo: { email, userId, authId }) and its OAuth tokens SEPARATELY
-                // in ~/.cursor/auth.json ({ accessToken, refreshToken }). Presence
-                // of an access token is the signed-in signal; email/ids come from
-                // cli-config. authId is the OAuth subject (e.g. "google-oauth2|<n>") — the
-                // same value the usage endpoint keys on (see getCursorUsageInfo).
                 const cfgPath = resolveAccountCredentialPath(base, '.cursor', 'cli-config.json');
                 if (!cfgPath)
                     return { ...empty, lastActive };
@@ -2131,11 +1446,8 @@ export async function getAccountInfo(agentId, home) {
                             const tok = JSON.parse(fs.readFileSync(authPath, 'utf-8'));
                             hasToken = typeof tok?.accessToken === 'string' && tok.accessToken.length > 0;
                         }
-                        catch { /* unreadable token file */ }
+                        catch { }
                     }
-                    // cli-config survives logout and may describe a different keychain
-                    // account. Without this version's file token, its identity is stale
-                    // metadata rather than a usable managed login.
                     if (!hasToken)
                         return { ...empty, lastActive };
                     const accountKey = buildIdentityKey(agentId, [['user', accountId]]);
@@ -2145,13 +1457,6 @@ export async function getAccountInfo(agentId, home) {
                 return { ...empty, lastActive };
             }
             case 'grok': {
-                // Grok stores auth in ~/.grok/auth.json as a map keyed by
-                // "<oidc_issuer>::<client_id>" -> { email, user_id, refresh_token,
-                // create_time, expires_at, team_id, ... }. (Older builds wrote a flat
-                // object with a top-level email.) The old code only read a TOP-LEVEL
-                // `email`, so the current nested format always looked signed-out even
-                // when logged in. Read the newest account record: a refresh token means
-                // signed in, and we surface the email/ids like claude/codex.
                 const authPath = resolveAccountCredentialPath(base, '.grok', 'auth.json');
                 if (!authPath)
                     return { ...empty, lastActive };
@@ -2174,40 +1479,21 @@ export async function getAccountInfo(agentId, home) {
                 return { ...empty, lastActive };
             }
             case 'antigravity': {
-                // Antigravity (`agy`) stores a consumer Google OAuth grant (access +
-                // refresh token, no id_token) — presence of a refresh token is the only
-                // signed-in signal we can derive without a network call. Storage is
-                // platform-split via go-keyring:
-                //   - file ~/.gemini/antigravity-cli/antigravity-oauth-token (Linux
-                //     fallback when no Secret Service is available)
-                //   - macOS keychain / Linux libsecret (service gemini + user
-                //     antigravity) when a keyring daemon is present
-                // Check the file first, then the OS keyring probe.
                 const tokenPath = resolveAccountCredentialPath(base, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
                 if (tokenPath) {
                     const data = JSON.parse(await fs.promises.readFile(tokenPath, 'utf-8'));
                     if (typeof data?.token?.refresh_token === 'string' && data.token.refresh_token) {
-                        // A stable account/usage key (derived from the refresh token — see
-                        // readAuthAccountIdentity) lets `agents view` dedupe and cache the
-                        // per-model quota bars for this login.
                         const identity = readAuthAccountIdentity('antigravity', path.dirname(tokenPath));
                         return { ...empty, signedIn: true, lastActive, accountKey: identity, usageKey: identity };
                     }
                 }
                 if (await antigravityKeychainSignedIn()) {
-                    // Keyring-only login (the macOS case): the OS keyring holds exactly
-                    // ONE antigravity credential, so a stable singleton key identifies it
-                    // for usage-cache dedup without reading the secret value here.
                     const identity = buildIdentityKey('antigravity', [['sub', 'keychain']]);
                     return { ...empty, signedIn: true, lastActive, accountKey: identity, usageKey: identity };
                 }
                 return { ...empty, lastActive };
             }
             case 'kimi': {
-                // Kimi Code stores OAuth credentials at
-                // ~/.kimi-code/credentials/kimi-code.json. The access token is a JWT
-                // whose payload carries an opaque user_id (no email), so we report
-                // signed-in state plus a stable account key for usage dedup.
                 const credPath = resolveAccountCredentialPath(base, '.kimi-code', 'credentials', 'kimi-code.json');
                 if (!credPath)
                     return { ...empty, lastActive };
@@ -2221,15 +1507,6 @@ export async function getAccountInfo(agentId, home) {
                 return { ...empty, signedIn: true, accountId: userId, accountKey, lastActive };
             }
             case 'droid': {
-                // Factory Droid stores auth at ~/.factory/auth.v2.file (AES-256-GCM,
-                // decrypted with the on-disk ~/.factory/auth.v2.key). We decrypt locally
-                // — no network — and surface the email/org/role from the WorkOS
-                // access-token JWT, same as claude/codex/grok. If the credential can't be
-                // decrypted (a keyring-v2/legacy login with no on-disk key, or a decrypt
-                // failure) we fall back to the file-presence signed-in signal so the row
-                // still reads as logged in — the conservative floor antigravity/kimi use.
-                // `.factory` is the config dir on every platform (macOS/Linux
-                // ~/.factory, Windows %USERPROFILE%\.factory).
                 const decoded = decryptDroidCredential(base);
                 if (decoded?.email) {
                     const organizationId = decoded.orgId;
@@ -2244,24 +1521,16 @@ export async function getAccountInfo(agentId, home) {
                         lastActive,
                     };
                 }
+                // An unreadable encrypted payload still counts conservatively when its auth file exists.
                 const authPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
                 if (!authPath)
                     return { ...empty, lastActive };
                 return { ...empty, signedIn: true, lastActive };
             }
             case 'opencode': {
-                // OpenCode's auth.json is a record keyed by provider id ->
-                // { type: 'oauth'|'api'|'wellknown', ...secret fields }. The provider
-                // join is the identity key (see resolveOpenCodeIdentity), and an OAuth
-                // provider's token additionally carries the real account email and plan
-                // — so the row shows who is signed in rather than only a bare `id:` key.
-                // Secrets are never read out; only JWT claims are.
                 const identity = resolveOpenCodeIdentity(base);
                 if (!identity)
                     return { ...empty, lastActive };
-                // Keyed on providers, not email: OpenCode bills through whichever
-                // provider credentials are configured, so two installs sharing one
-                // email but different provider sets are genuinely different accounts.
                 const accountKey = buildIdentityKey(agentId, [['providers', identity.providers]]);
                 return {
                     ...empty,
@@ -2274,9 +1543,6 @@ export async function getAccountInfo(agentId, home) {
                 };
             }
             case 'muse': {
-                // Muse Code authenticates with META_API_KEY (env, highest priority) or
-                // a stored OAuth/API credential at ~/.config/muse/auth.json. Live file
-                // shape nests under providers.meta (access_token + optional user_email).
                 if (process.env.META_API_KEY?.trim() || process.env.MODEL_API_KEY?.trim()) {
                     const accountKey = buildIdentityKey(agentId, [['auth', 'env']]);
                     return { ...empty, signedIn: true, accountId: 'env', accountKey, lastActive };
@@ -2305,24 +1571,11 @@ export async function getAccountInfo(agentId, home) {
         }
     }
     catch {
-        /* auth/config file missing or unreadable */
         return { ...empty, lastActive };
     }
 }
-// Fresh window for the cached session walk. Matches USAGE_CACHE_FRESH_MS in
-// usage.ts (5 minutes) so a launch storm reuses both probes for the same period.
 const LAST_ACTIVE_CACHE_FRESH_MS = 5 * 60 * 1000;
 const getLastActiveCachePath = () => path.join(getCacheDir(), 'last-active.json');
-/**
- * Determine when the agent was last used by checking session file mtimes,
- * falling back to config mtime.
- *
- * The session walk stats every transcript under the home's session dir —
- * thousands of files on long-lived installs — and `agents run` rotation calls
- * this once per installed version on every launch. The walk result is cached
- * on disk for a short window so back-to-back launches skip it entirely.
- * Cache read/write is best-effort: any failure falls back to walking.
- */
 export function resolveLastActive(agentId, base, configPath, cachePath = getLastActiveCachePath(), now = new Date()) {
     const sessionDir = getSessionDir(agentId, base);
     const sessionExt = getSessionExtension(agentId);
@@ -2337,14 +1590,10 @@ export function resolveLastActive(agentId, base, configPath, cachePath = getLast
         if (fresh) {
             if (entry.mtimeMs !== null)
                 return new Date(entry.mtimeMs);
-            // Fresh entry with no sessions: fall through to the config mtime below.
         }
         else {
             const mtimeMs = latestFileMtimeMs(sessionDir, sessionExt);
             cache[key] = { mtimeMs, computedAt: now.getTime() };
-            // Stale entries are never served, so drop them on write — keeps homes
-            // that no longer exist (removed versions, test temp dirs) from
-            // accumulating in the file.
             for (const [k, v] of Object.entries(cache)) {
                 if (k !== key && !(typeof v?.computedAt === 'number' && now.getTime() - v.computedAt < LAST_ACTIVE_CACHE_FRESH_MS)) {
                     delete cache[k];
@@ -2364,7 +1613,6 @@ export function resolveLastActive(agentId, base, configPath, cachePath = getLast
         return null;
     }
 }
-/** Read the entire last-active cache file. Missing or corrupt file reads as empty. */
 function readLastActiveCacheFile(cachePath) {
     if (!fs.existsSync(cachePath))
         return {};
@@ -2376,29 +1624,21 @@ function readLastActiveCacheFile(cachePath) {
         return {};
     }
 }
-/** Write the entire last-active cache. Best-effort; a failed write just means the next call walks again. */
 function writeLastActiveCacheFile(cache, cachePath) {
     try {
         fs.mkdirSync(path.dirname(cachePath), { recursive: true });
         fs.writeFileSync(cachePath, JSON.stringify(cache), 'utf-8');
     }
     catch {
-        /* best-effort */
     }
 }
-/** Return the root directory where the agent stores session files, or null if unknown. */
 function getSessionDir(agentId, base) {
     const rel = AGENTS[agentId].sessionDir;
     return rel ? path.join(base, ...rel) : null;
 }
-/** Return the file extension used for session files by the given agent. */
 function getSessionExtension(agentId) {
     return AGENTS[agentId].sessionFileExt;
 }
-/**
- * Quick count of session files for an agent (without full DB scan).
- * Used during init to show approximate session count to user.
- */
 export function countSessionFiles(agentId) {
     const sessionDir = getSessionDir(agentId, HOME);
     const ext = getSessionExtension(agentId);
@@ -2418,13 +1658,11 @@ export function countSessionFiles(agentId) {
             }
         }
         catch {
-            // Permission denied or other error
         }
     };
     walk(sessionDir);
     return count;
 }
-/** Decode the payload section of a JWT token without verifying its signature. */
 export function decodeJwtPayload(token) {
     const payload = token.split('.')[1];
     if (!payload)
@@ -2436,7 +1674,6 @@ export function decodeJwtPayload(token) {
         return null;
     }
 }
-/** Extract the default organization ID from a Codex/OpenAI auth claim. */
 function getCodexDefaultOrgId(authClaim) {
     const organizations = authClaim?.organizations;
     if (!Array.isArray(organizations))
@@ -2444,14 +1681,12 @@ function getCodexDefaultOrgId(authClaim) {
     const first = organizations[0];
     return typeof first?.id === 'string' ? first.id : null;
 }
-/** Trim and normalize an identity string, returning null for empty or non-string values. */
 function normalizeIdentityPart(value) {
     if (typeof value !== 'string')
         return null;
     const trimmed = value.trim();
     return trimmed || null;
 }
-/** Build a composite identity key like "claude:account=abc:org=xyz" from labeled parts. */
 function buildIdentityKey(agentId, parts) {
     const encoded = parts
         .filter(([, value]) => value)
@@ -2460,7 +1695,6 @@ function buildIdentityKey(agentId, parts) {
         return null;
     return `${agentId}:${encoded.join(':')}`;
 }
-/** Register an MCP server with an agent's CLI via `mcp add`. */
 export async function registerMcp(agentId, name, command, scope = 'user', transport = 'stdio', options) {
     const agent = AGENTS[agentId];
     if (!supports(agentId, 'mcp').ok) {
@@ -2485,7 +1719,6 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
         return { success: false, error: 'CLI not installed' };
     }
     try {
-        // Use explicit binary path when provided (bypasses shim for version-managed agents)
         const bin = options?.binary || agent.cliCommand;
         let args;
         if (transport === 'http') {
@@ -2505,13 +1738,7 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
             const commandArgs = splitCommandLine(command);
             args = ['mcp', 'add', name, '--', ...commandArgs];
         }
-        // When home is specified, override HOME so MCP config writes to the version's config dir
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        // On Windows a bare command name / `.cmd` wrapper (the npm-installed agent
-        // CLI) can't be exec'd directly — it needs shell:true for PATHEXT/cmd. Off
-        // Windows this is always false, so the no-shell argv path is unchanged.
-        // RUSH-1752: when shell is needed, compose a fully-quoted command line and
-        // pass EMPTY argv so user-controlled MCP command/args never reach cmd.exe unescaped.
         const spec = execFileShellSpec(bin, args);
         await execFileAsync(spec.command, spec.args, { ...(env ? { env } : {}), shell: spec.shell });
         return { success: true };
@@ -2520,7 +1747,6 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
         return { success: false, error: err.message };
     }
 }
-/** Unregister (remove) a named MCP server from an agent's CLI config. */
 export async function unregisterMcp(agentId, name, options) {
     const agent = AGENTS[agentId];
     if (!supports(agentId, 'mcp').ok) {
@@ -2540,9 +1766,8 @@ export async function unregisterMcp(agentId, name, options) {
     }
     try {
         const bin = options?.binary || agent.cliCommand;
+        // HOME selects the version-owned MCP config for CLI-backed removal.
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        // RUSH-1752: same shell-safe path as registerMcp — attacker-controlled MCP
-        // `name` must not reach cmd.exe unescaped when shell:true is required.
         const spec = execFileShellSpec(bin, ['mcp', 'remove', name]);
         await execFileAsync(spec.command, spec.args, { ...(env ? { env } : {}), shell: spec.shell });
         return { success: true };
@@ -2551,10 +1776,6 @@ export async function unregisterMcp(agentId, name, options) {
         return { success: false, error: err.message };
     }
 }
-/**
- * Register an MCP server across multiple agent targets, including both direct
- * (non-version-managed) agents and specific version-managed installs.
- */
 export async function registerMcpToTargets(targets, name, command, scope = 'user', transport = 'stdio', options = {}) {
     const results = [];
     for (const agentId of targets.directAgents) {
@@ -2573,10 +1794,6 @@ export async function registerMcpToTargets(targets, name, command, scope = 'user
     }
     return results;
 }
-/**
- * Unregister an MCP server from multiple agent targets, including both direct
- * agents and specific version-managed installs.
- */
 export async function unregisterMcpFromTargets(targets, name) {
     const results = [];
     for (const agentId of targets.directAgents) {
@@ -2674,19 +1891,10 @@ function removeMcpFromConfig(agentId, name, home) {
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
     }
 }
-/**
- * Extract version from npm package specification.
- * Examples: @scope/package@latest -> latest
- *           @scope/package@1.2.3 -> 1.2.3
- *           some-package -> undefined
- */
 function extractNpmVersion(args) {
-    // Find npm package argument (looks like @scope/package@version or package@version)
     for (const arg of args) {
-        // Match @scope/package@version or package@version
         const match = arg.match(/@([^@]+)$|^([^@]+)@(.+)$/);
         if (match) {
-            // @scope/package@version pattern
             const versionMatch = arg.match(/@([^@/]+)$/);
             if (versionMatch) {
                 return versionMatch[1];
@@ -2695,16 +1903,8 @@ function extractNpmVersion(args) {
     }
     return undefined;
 }
-/**
- * Strip JSON comments for JSONC parsing.
- * Only removes comments outside of strings.
- *
- * Exported because the MCP writer needs the SAME parser the reader uses: a
- * naive `//`-to-end-of-line regex eats the `//` inside
- * `"$schema": "https://opencode.ai/config.json"`, which every opencode-generated
- * config carries.
- */
 export function stripJsonComments(content) {
+    // Strip comments only outside strings so schema and MCP URLs survive JSONC parsing.
     let result = '';
     let inString = false;
     let escape = false;
@@ -2731,21 +1931,18 @@ export function stripJsonComments(content) {
             continue;
         }
         if (!inString) {
-            // Check for single-line comment
             if (char === '/' && next === '/') {
-                // Skip until end of line
                 while (i < content.length && content[i] !== '\n') {
                     i++;
                 }
                 continue;
             }
-            // Check for multi-line comment
             if (char === '/' && next === '*') {
                 i += 2;
                 while (i < content.length && !(content[i] === '*' && content[i + 1] === '/')) {
                     i++;
                 }
-                i += 2; // Skip */
+                i += 2;
                 continue;
             }
         }
@@ -2754,32 +1951,22 @@ export function stripJsonComments(content) {
     }
     return result;
 }
-/**
- * Parse MCP servers from a JSON/JSONC config file.
- */
 function parseMcpFromJsonConfig(configPath) {
     if (!fs.existsSync(configPath)) {
         return {};
     }
     try {
         let content = fs.readFileSync(configPath, 'utf-8');
-        // Handle JSONC (JSON with comments)
         if (configPath.endsWith('.jsonc')) {
             content = stripJsonComments(content);
         }
         const config = JSON.parse(content);
-        // Claude uses mcpServers, others may use mcp_servers or mcp
         return config.mcpServers || config.mcp_servers || config.mcp || {};
     }
     catch {
-        /* JSON config corrupt or unreadable */
         return {};
     }
 }
-/**
- * Parse MCP servers from a TOML config file (Codex).
- * Codex stores MCPs as [mcp_servers.ServerName] sections.
- */
 function parseMcpFromTomlConfig(configPath) {
     if (!fs.existsSync(configPath)) {
         return {};
@@ -2787,12 +1974,10 @@ function parseMcpFromTomlConfig(configPath) {
     try {
         const content = fs.readFileSync(configPath, 'utf-8');
         const config = TOML.parse(content);
-        // Codex uses mcp_servers as a table with server names as keys
         const mcpServers = config.mcp_servers;
         return mcpServers || {};
     }
     catch {
-        /* TOML config corrupt or unreadable */
         return {};
     }
 }
@@ -2806,14 +1991,9 @@ function parseMcpFromYamlConfig(configPath) {
         return mcpServers || {};
     }
     catch {
-        /* YAML config corrupt or unreadable */
         return {};
     }
 }
-/**
- * Parse MCP servers from OpenCode's JSONC config.
- * OpenCode stores MCPs in the "mcp" object with different structure.
- */
 function parseMcpFromOpenCodeConfig(configPath) {
     if (!fs.existsSync(configPath)) {
         return {};
@@ -2824,18 +2004,15 @@ function parseMcpFromOpenCodeConfig(configPath) {
         const mcpConfig = config.mcp;
         if (!mcpConfig)
             return {};
-        // Convert OpenCode format to our McpConfigEntry format
         const result = {};
         for (const [name, entry] of Object.entries(mcpConfig)) {
             if (entry.type === 'local' && entry.command) {
-                // Local MCP: command is an array like ["npx", "-y", "@pkg@version"]
                 result[name] = {
                     command: entry.command[0],
                     args: entry.command.slice(1),
                 };
             }
             else if (entry.type === 'remote' && entry.url) {
-                // Remote MCP: HTTP URL
                 result[name] = {
                     url: entry.url,
                 };
@@ -2844,43 +2021,24 @@ function parseMcpFromOpenCodeConfig(configPath) {
         return result;
     }
     catch {
-        /* OpenCode JSONC config corrupt or unreadable */
         return {};
     }
 }
-/**
- * Get user-scoped MCP config path for an agent.
- *
- * All three MCP path resolvers read `MCP_TARGETS`, so the file the writer
- * targets, the file the parser reads, and the file the staleness detector
- * watches cannot drift apart. An agent with no MCP target keeps the historical
- * settings.json default so old configs still parse.
- */
 export function getUserMcpConfigPath(agentId) {
     return getMcpConfigPathForHome(agentId, HOME);
 }
-/**
- * Get MCP config path for a specific HOME directory (used for version-managed agents).
- */
 export function getMcpConfigPathForHome(agentId, home) {
     const target = MCP_TARGETS[agentId];
     if (target)
         return target.home(home);
     return path.join(home, agentConfigDirName(agentId), 'settings.json');
 }
-/**
- * Get project-scoped MCP config path for an agent.
- */
 export function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
     const target = MCP_TARGETS[agentId];
     if (target)
         return target.project(cwd);
     return path.join(cwd, `.${agentId}`, 'settings.json');
 }
-/**
- * Parse MCP servers from OpenClaw's JSON config.
- * OpenClaw stores MCPs under mcp.servers with a similar structure to other agents.
- */
 function parseMcpFromOpenClawConfig(configPath) {
     if (!fs.existsSync(configPath)) {
         return {};
@@ -2888,7 +2046,6 @@ function parseMcpFromOpenClawConfig(configPath) {
     try {
         const content = fs.readFileSync(configPath, 'utf-8');
         const config = JSON.parse(content);
-        // OpenClaw uses mcp.servers for MCP configuration
         const mcpServers = config.mcp?.servers;
         if (!mcpServers)
             return {};
@@ -2911,17 +2068,10 @@ function parseMcpFromOpenClawConfig(configPath) {
         return result;
     }
     catch {
-        /* OpenClaw JSON config corrupt or unreadable */
         return {};
     }
 }
-/**
- * Parse MCP config based on agent type.
- */
 export function parseMcpConfig(agentId, configPath) {
-    // Dispatch on the registry's declared format, not the agent id, so the parser
-    // can never disagree with the writer about a file's serialization -- grok's
-    // TOML config was previously read as JSON and always came back empty.
     switch (MCP_TARGETS[agentId]?.format) {
         case 'toml':
             return parseMcpFromTomlConfig(configPath);
@@ -2932,26 +2082,17 @@ export function parseMcpConfig(agentId, configPath) {
         case 'yaml':
             return parseMcpFromYamlConfig(configPath);
         default:
-            // claude-json / antigravity-json / muse-json all live in a JSON object;
-            // parseMcpFromJsonConfig accepts mcpServers | mcp_servers | mcp. Agents
-            // with no declared format fall here too, matching prior behavior.
             return parseMcpFromJsonConfig(configPath);
     }
 }
-/**
- * List installed MCP servers with scope information.
- * Pass options.home to read from a version-managed agent's home directory.
- */
 export function listInstalledMcpsWithScope(agentId, cwd = process.cwd(), options) {
     const results = [];
-    // Helper to build full command string
     const buildCommand = (config) => {
         if (config.command && config.args?.length) {
             return `${config.command} ${config.args.join(' ')}`;
         }
         return config.command || (config.args ? config.args.join(' ') : undefined);
     };
-    // User-scoped MCPs (version-aware when home is provided)
     const userConfigPath = options?.home
         ? getMcpConfigPathForHome(agentId, options.home)
         : getUserMcpConfigPath(agentId);
@@ -2964,11 +2105,9 @@ export function listInstalledMcpsWithScope(agentId, cwd = process.cwd(), options
             version: config.args ? extractNpmVersion(config.args) : undefined,
         });
     }
-    // Project-scoped MCPs
     const projectConfigPath = getProjectMcpConfigPath(agentId, cwd);
     const projectMcps = parseMcpConfig(agentId, projectConfigPath);
     for (const [name, config] of Object.entries(projectMcps)) {
-        // Skip if already in user scope (project can override, but we show both)
         results.push({
             name,
             scope: 'project',
@@ -2978,7 +2117,6 @@ export function listInstalledMcpsWithScope(agentId, cwd = process.cwd(), options
     }
     return results;
 }
-/** Map of agent name aliases and shorthand identifiers to canonical AgentId values. */
 const AGENT_NAME_ALIASES = {
     claude: 'claude',
     'claude-code': 'claude',
@@ -3026,14 +2164,8 @@ const AGENT_NAME_ALIASES = {
     'warp-agent': 'warp',
     'warp-cli': 'warp',
 };
-/**
- * Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId.
- * Tolerates a single typo (insertion/deletion/substitution/transposition) against
- * canonical ids and aliases — `cladue` -> claude, `kim` -> kimi, `codx` -> codex —
- * but only when the correction is unambiguous (all distance-1 candidates agree on
- * one agent). Two-letter shorthands are excluded as fuzzy candidates.
- */
 export function resolveAgentName(input) {
+    // Resolve exact names first; fuzzy 3+ character matches must be one edit and one target.
     const lower = input.toLowerCase();
     const exact = AGENT_NAME_ALIASES[lower] ?? (AGENTS[lower] ? lower : null);
     if (exact || lower.length < 3)
@@ -3049,19 +2181,11 @@ export function resolveAgentName(input) {
     }
     return hits.size === 1 ? hits.values().next().value : null;
 }
-/** Check whether the input string matches any known agent name or alias. */
 export function isAgentName(input) {
     return resolveAgentName(input) !== null;
 }
-/**
- * Split a CLI-provided `<agent>[@<version>][#<label>]` spec into its bare agent
- * id, optional exact version token, and optional account label, the same way
- * `agents run` does — NOT the
- * agent-spec qualifier engine (`@latest`/`@all`), which enumerates installed
- * versions for read/diagnostic commands, not a single launch target. Returns an
- * error message rather than throwing so callers decide exit-vs-continue.
- */
 export function parseAgentVersionSpec(raw) {
+    // This parses one run target, not the diagnostic selector grammar with @all/@latest.
     const labelParts = raw.split('#');
     if (labelParts.length > 2) {
         return { error: `Invalid agent spec '${raw}': at most one '#label' is allowed` };
@@ -3084,11 +2208,6 @@ export function parseAgentVersionSpec(raw) {
     }
     return { agent, ...(rawVersion ? { version: rawVersion } : {}), ...(rawLabel ? { label: rawLabel } : {}) };
 }
-/**
- * Build the deprecation notice lines for an agent, or null if it isn't
- * deprecated. Split from the printer so tests can assert the content without
- * capturing stdout. Lines are plain (uncolored) text.
- */
 export function deprecationNotice(agent) {
     const dep = AGENTS[agent].deprecated;
     if (!dep)
@@ -3126,11 +2245,6 @@ export function hardDeprecationNotice(agent) {
 export function hardDeprecationError(agent) {
     return hardDeprecationNotice(agent)?.join('\n') ?? `${AGENTS[agent].name} is no longer supported.`;
 }
-/**
- * Print a deprecation warning (yellow) if the agent's registry entry carries a
- * `deprecated` marker; no-op otherwise. Call from any user entry point that
- * acts on a chosen agent — install (`agents add`) and `agents teams add`.
- */
 export function warnAgentDeprecated(agent) {
     const lines = deprecationNotice(agent);
     if (!lines)
@@ -3138,7 +2252,6 @@ export function warnAgentDeprecated(agent) {
     for (const line of lines)
         console.log(chalk.yellow(line));
 }
-/** Format an error message for an unrecognized agent name, listing valid options. */
 export function formatAgentError(agentName, validAgents = ALL_AGENT_IDS) {
     return `Unknown agent '${agentName}'. Valid agents: ${validAgents.join(', ')}`;
 }