@phnx-labs/agents-cli 1.20.8 → 1.20.10

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+**`agents inspect .` reads the project `.agents/`, and plugin drill-down shows bundled skills**
+
+- `agents inspect .` (and any path to a repo root) now resolves to the project's nested `.agents/` tree when that tree is a populated DotAgents root, instead of the project root itself. Previously a top-level `agents.yaml` version-pin or an unrelated source `skills/` dir at the repo root was mistaken for a DotAgents root, so `inspect .` reported the wrong directory's resources (e.g. `plugins 0` while the real `.agents/plugins/` held a plugin). A bare `.agents`-named dir still resolves to itself, and standalone clones / extra repos that keep resources at the top level (using `.agents/` only for worktrees) are unaffected — their nested `.agents/` is not a DotAgents root, so the top level still wins.
+- `agents inspect <repo> --plugins` now reads plugin bundles through the plugin discoverer: the list shows each plugin's manifest description, and drilling into one (`--plugins <name>`) reports its bundled skills, commands, subagents, hooks, MCP servers, and version. Previously plugins were treated as opaque directories with no description and no view into what they ship.
+
+**Single-typo agent names auto-correct everywhere, not just `agents run`**
+
+- `agents view cladue` used to print `Unknown agent 'cladue'` even though `agents run cladue` auto-corrected. `resolveAgentName` — the canonical resolver behind `view`, `usage`, `inspect`, `doctor`, `sync`, `models`, `skills`, `hooks`, `import`, `sessions --agent`, and every `agent@version` spec (`agents add claud@latest`, `agents use codx@2.1.170`) — now falls back to Damerau-Levenshtein distance-1 matching against canonical ids and multi-letter aliases: `cladue` -> `claude` (transposition), `kim` -> `kimi`, `codx` -> `codex`, `gemni` -> `gemini`.
+- Corrections apply only when unambiguous: every distance-1 candidate must agree on one agent. `kiri` (one edit from both `kiro` and `kimi`) and inputs under 3 characters still error. `agents run` keeps its existing exact -> profile -> workflow -> fuzzy precedence, so a profile named `claud` still beats the typo correction.
+- Fixes `kimi` being listed as a valid agent but missing from the alias map — `agents view kimi` previously errored. Added `kimi` / `kimi-code` entries.
+
 ## 1.20.7
 
 **`agents inspect` — DotAgents repo targets (#256)**

package/README.md

@@ -122,7 +122,7 @@ agents run codex "Fix the issues Claude found"
 agents run gemini "Write tests for the fixed code"
 ```
 
-Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced.
+Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced. Single-typo names auto-correct across every command — `agents view cladue` resolves to `claude`, `agents add codx@latest` to `codex`.
 
 ### Rate-limited? Keep working.
 

package/dist/commands/daemon.js

@@ -5,7 +5,6 @@
  * aliases for `agents routines` scheduler lifecycle commands. Scheduled
  * for removal in v2.0.
  */
-import { spawn } from 'child_process';
 import chalk from 'chalk';
 import * as path from 'path';
 import { startDaemon, stopDaemon, isDaemonRunning, readDaemonPid, readDaemonLog, runDaemon, } from '../lib/daemon.js';
@@ -92,12 +91,13 @@ you never need to start it manually.
         warnDeprecated('logs', 'agents routines scheduler-logs');
         if (options.follow) {
             const { getDaemonDir } = await import('../lib/state.js');
+            const { followFile } = await import('../lib/log-follow.js');
             const logPath = path.join(getDaemonDir(), 'logs.jsonl');
-            const child = spawn('tail', ['-f', logPath], { stdio: ['ignore', 'pipe', 'pipe'] });
-            child.stdout.pipe(process.stdout);
-            child.stderr.pipe(process.stderr);
-            child.on('exit', () => process.exit(0));
-            process.on('SIGINT', () => { child.kill(); process.exit(0); });
+            const recent = readDaemonLog(parseInt(options.lines, 10));
+            if (recent)
+                console.log(recent);
+            const stop = followFile(logPath, (text) => process.stdout.write(text), { fromEnd: true });
+            process.on('SIGINT', () => { stop(); process.exit(0); });
             return;
         }
         const lines = parseInt(options.lines, 10);

package/dist/commands/import.js

@@ -27,20 +27,17 @@ import * as os from 'os';
 import * as path from 'path';
 import { confirm } from '@inquirer/prompts';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
-import { AGENTS, getCliPath, getCliVersion, agentLabel } from '../lib/agents.js';
+import { AGENTS, getCliPath, getCliVersion, agentLabel, resolveAgentName } from '../lib/agents.js';
 import { getVersionDir } from '../lib/versions.js';
 import { finalizeImport, importAgentBinary, importAgentConfig, importInstallScriptBinary, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
-function isValidAgentId(value) {
-    return ALL_AGENT_IDS.includes(value);
-}
 async function runImport(agentArg, opts) {
-    if (!isValidAgentId(agentArg)) {
+    const agentId = resolveAgentName(agentArg);
+    if (!agentId) {
         console.error(chalk.red(`Unknown agent: ${agentArg}`));
         console.error(chalk.gray(`Known agents: ${ALL_AGENT_IDS.join(', ')}`));
         process.exit(1);
     }
-    const agentId = agentArg;
     const agent = AGENTS[agentId];
     // installScript-based agents (Grok, Antigravity, Cursor, Kiro, Goose, Roo)
     // don't have an npm package; their binary lives wherever the curl/brew

package/dist/commands/inspect.d.ts

@@ -24,6 +24,8 @@ interface ResourceItem {
     linkTarget: string;
     /** One-line description (frontmatter `description:` or first non-frontmatter line). */
     description: string;
+    /** Extra detail rows surfaced in detail mode (e.g. a plugin's bundled skills/commands). */
+    extra?: Array<[string, string]>;
 }
 interface InspectOptions {
     brief?: boolean;

package/dist/commands/inspect.js

@@ -17,13 +17,13 @@ import * as os from 'os';
 import * as path from 'path';
 import chalk from 'chalk';
 import * as yaml from 'yaml';
-import { AGENTS, getCliState } from '../lib/agents.js';
+import { AGENTS, getCliState, resolveAgentName } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
-import { discoverPlugins } from '../lib/plugins.js';
+import { discoverPlugins, discoverPluginsInDir } from '../lib/plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
 import { damerauLevenshtein } from '../lib/fuzzy.js';
 /** Resource kinds the inspect command can drill into. */
@@ -63,12 +63,16 @@ export async function inspectAction(target, options) {
             await inspectRepo(repo, options);
             return;
         }
-        const extras = getEnabledExtraRepos();
-        console.error(chalk.red(`Unknown target: ${target}`));
-        console.error(chalk.gray(`Agents: ${Object.keys(AGENTS).join(', ')}`));
-        const aliases = extras.length > 0 ? `, ${extras.map(e => e.alias).join(', ')}` : '';
-        console.error(chalk.gray(`Repos:  user, system, project${aliases} — or a path to a repo with a .agents/ dir`));
-        process.exit(1);
+        // Repo targets take precedence over typo correction; only fall through to
+        // parseTarget when the key resolves to an agent (alias or single-edit fix).
+        if (!resolveAgentName(agentKey)) {
+            const extras = getEnabledExtraRepos();
+            console.error(chalk.red(`Unknown target: ${target}`));
+            console.error(chalk.gray(`Agents: ${Object.keys(AGENTS).join(', ')}`));
+            const aliases = extras.length > 0 ? `, ${extras.map(e => e.alias).join(', ')}` : '';
+            console.error(chalk.gray(`Repos:  user, system, project${aliases} — or a path to a repo with a .agents/ dir`));
+            process.exit(1);
+        }
     }
     const { agent, version } = parseTarget(target);
     const versionHome = getVersionHomePath(agent, version);
@@ -93,7 +97,12 @@ export async function inspectAction(target, options) {
 }
 function parseTarget(target) {
     const [rawAgent, rawVersion] = target.split('@');
-    const agent = (rawAgent || '').toLowerCase();
+    const agent = resolveAgentName(rawAgent || '');
+    if (!agent) {
+        console.error(chalk.red(`Unknown agent: ${rawAgent}`));
+        console.error(chalk.gray(`Known agents: ${Object.keys(AGENTS).join(', ')}`));
+        process.exit(1);
+    }
     let version = rawVersion;
     if (!version || version === 'default') {
         const meta = readMeta();
@@ -152,18 +161,23 @@ export function resolveRepoTarget(target, cwd) {
     const stat = safeStat(abs);
     if (!stat || !stat.isDirectory())
         return null;
-    // A dir that is itself a DotAgents root wins over its nested .agents/ —
-    // extra repos like ~/.agents-extras keep resources at the top level and use
-    // .agents/ only for worktrees.
+    // A dir literally named `.agents` is the root itself.
+    if (path.basename(abs) === '.agents') {
+        return { label: path.basename(path.dirname(abs)), root: abs };
+    }
+    // A nested `.agents/` that is a populated DotAgents root wins over `abs` — the
+    // project case (`agents inspect .` from a repo root whose resources live under
+    // `.agents/`, while the repo's own top-level `skills/`, `agents.yaml` pin, etc.
+    // are unrelated source, not a DotAgents tree).
+    const nested = path.join(abs, '.agents');
+    if (isDotAgentsRoot(nested)) {
+        return { label: path.basename(abs), root: nested };
+    }
+    // Otherwise treat `abs` itself as the root: standalone clones and extra repos
+    // like ~/.agents-extras keep resources at the top level and use `.agents/`
+    // only for worktrees (so their nested `.agents/` is not a DotAgents root).
     if (isDotAgentsRoot(abs)) {
-        const label = path.basename(abs) === '.agents' ? path.basename(path.dirname(abs)) : path.basename(abs);
-        return { label, root: abs };
-    }
-    if (path.basename(abs) !== '.agents') {
-        const nested = path.join(abs, '.agents');
-        if (safeStat(nested)?.isDirectory()) {
-            return { label: path.basename(abs), root: nested };
-        }
+        return { label: path.basename(abs), root: abs };
     }
     return null;
 }
@@ -195,6 +209,14 @@ async function inspectRepo(repo, options) {
 }
 /** List one resource kind from a single repo root — no layering, no overrides. */
 export function collectRepoKind(repo, kind) {
+    // Plugins are bundles with a manifest + nested skills/commands/hooks — read
+    // them through the plugin discoverer so the manifest description and bundled
+    // resources surface, rather than treating each as an opaque directory.
+    if (kind === 'plugins') {
+        return discoverPluginsInDir(path.join(repo.root, 'plugins'))
+            .map(p => pluginToItem(p, repo.label))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
     const dir = path.join(repo.root, kind);
     let entries;
     try {
@@ -477,14 +499,35 @@ function collectKind(agent, versionHome, kind) {
     }
 }
 function pluginItems() {
-    const plugins = discoverPlugins();
-    return plugins.map(p => ({
-        name: p.name,
-        source: 'user',
-        path: p.root,
-        linkTarget: linkTarget(p.root),
-        description: p.manifest.description ?? '',
-    }));
+    return discoverPlugins().map(p => pluginToItem(p, 'user'));
+}
+/**
+ * Map a discovered plugin to a resource item, surfacing the manifest description
+ * and the bundle's nested resources (skills, commands, hooks, ...) as detail rows.
+ */
+function pluginToItem(plugin, source) {
+    const extra = [];
+    const list = (names) => names.length <= 8 ? names.join(', ') : `${names.slice(0, 8).join(', ')}, +${names.length - 8} more`;
+    if (plugin.skills.length)
+        extra.push(['skills', `${plugin.skills.length}  (${list(plugin.skills)})`]);
+    if (plugin.commands.length)
+        extra.push(['commands', `${plugin.commands.length}  (${list(plugin.commands)})`]);
+    if (plugin.agentDefs.length)
+        extra.push(['subagents', `${plugin.agentDefs.length}  (${list(plugin.agentDefs)})`]);
+    if (plugin.hooks.length)
+        extra.push(['hooks', String(plugin.hooks.length)]);
+    if (plugin.mcpServers.length)
+        extra.push(['mcp', list(plugin.mcpServers)]);
+    if (plugin.manifest.version)
+        extra.push(['version', plugin.manifest.version]);
+    return {
+        name: plugin.name,
+        source,
+        path: plugin.root,
+        linkTarget: linkTarget(plugin.root),
+        description: plugin.manifest.description ?? '',
+        extra,
+    };
 }
 function entriesFromAgentResources(agent, versionHome, kind) {
     const res = getAgentResources(agent, { home: versionHome });
@@ -553,6 +596,10 @@ function buildDetailRows(item, kind) {
                 rows.push(['tools', fm.tools.join(', ')]);
         }
     }
+    // Plugin bundles carry their nested resources as pre-built rows.
+    if (kind === 'plugins' && item.extra) {
+        rows.push(...item.extra);
+    }
     return rows;
 }
 function findMatches(items, query) {

package/dist/commands/models.js

@@ -7,6 +7,7 @@
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
+import { homeDir } from '../lib/platform/index.js';
 import { resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
@@ -166,5 +167,5 @@ function printCatalog(agent, version, isDefault, options) {
 }
 /** Abbreviate a path by replacing the home directory with ~. */
 function shortPath(p) {
-    return p.replace(process.env.HOME || '~', '~');
+    return p.replace(homeDir(), '~');
 }

package/dist/commands/plugins.js

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
+import { homeDir } from '../lib/platform/index.js';
 import { input } from '@inquirer/prompts';
 import { agentLabel } from '../lib/agents.js';
 import { capableAgents, isCapable } from '../lib/capabilities.js';
@@ -21,7 +22,7 @@ import { safeJoin } from '../lib/paths.js';
 import { discoverMarketplaces } from '../lib/plugin-marketplace.js';
 /** Replace the home directory prefix with ~ for display. */
 function formatPath(p) {
-    const home = process.env.HOME || '';
+    const home = homeDir();
     if (home && p.startsWith(home)) {
         return '~' + p.slice(home.length);
     }
@@ -355,7 +356,7 @@ Examples:
             });
         }
         const name = nameArg;
-        const pluginsDir = path.join(process.env.HOME || '', '.agents', 'plugins');
+        const pluginsDir = path.join(homeDir(), '.agents', 'plugins');
         const pluginRoot = safeJoin(pluginsDir, name);
         // Use discovered plugin when present; fall back to name+root if source is already gone
         const plugin = getPlugin(name);

package/dist/commands/refresh-rules.js

@@ -6,7 +6,7 @@
  * Recompiles only when source files have changed.
  */
 import chalk from 'chalk';
-import { AGENTS } from '../lib/agents.js';
+import { AGENTS, resolveAgentName } from '../lib/agents.js';
 import { isVersionInstalled } from '../lib/versions.js';
 import { ensureRulesFresh, supportsRulesImports } from '../lib/rules/compile.js';
 /**
@@ -23,12 +23,12 @@ export function registerRefreshRulesCommand(program) {
         .requiredOption('--agent-version <version>', 'Installed version whose rules file should be refreshed')
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
         .action((opts) => {
-        const agentId = opts.agent;
+        const agentId = resolveAgentName(opts.agent);
         const version = opts.agentVersion;
         const quiet = !!opts.quiet;
-        if (!AGENTS[agentId]) {
+        if (!agentId) {
             if (!quiet)
-                console.error(chalk.red(`Unknown agent '${agentId}'`));
+                console.error(chalk.red(`Unknown agent '${opts.agent}'`));
             process.exitCode = 1;
             return;
         }

package/dist/commands/routines.js

@@ -14,6 +14,7 @@ import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemo
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, } from '../lib/routines.js';
 import { getRoutinesDir } from '../lib/state.js';
+import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
 import { executeJob, executeJobDetached } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
@@ -385,7 +386,7 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.gray(`Created new job file: ${newPath}`));
         }
         const targetPath = jobPath || path.join(getRoutinesDir(), `${name}.yml`);
-        const editor = process.env.EDITOR || process.env.VISUAL || 'vi';
+        const editor = process.env.EDITOR || process.env.VISUAL || (IS_WINDOWS ? 'notepad' : 'vi');
         const editorParts = editor.split(/\s+/).filter(Boolean);
         const editorBin = editorParts[0];
         const editorArgs = [...editorParts.slice(1), targetPath];
@@ -691,14 +692,14 @@ export function registerRoutinesCommands(program) {
         .option('-f, --follow', 'Stream log output in real time (like tail -f)')
         .action(async (options) => {
         if (options.follow) {
-            const { spawn } = await import('child_process');
             const { getDaemonDir } = await import('../lib/state.js');
+            const { followFile } = await import('../lib/log-follow.js');
             const logPath = path.join(getDaemonDir(), 'logs.jsonl');
-            const child = spawn('tail', ['-f', logPath]);
-            child.stdout?.pipe(process.stdout);
-            child.stderr?.pipe(process.stderr);
-            child.on('exit', () => process.exit(0));
-            process.on('SIGINT', () => { child.kill(); process.exit(0); });
+            const recent = readDaemonLog(parseInt(options.lines, 10));
+            if (recent)
+                console.log(recent);
+            const stop = followFile(logPath, (text) => process.stdout.write(text), { fromEnd: true });
+            process.on('SIGINT', () => { stop(); process.exit(0); });
             return;
         }
         const lines = parseInt(options.lines, 10);

package/dist/commands/sessions.js

@@ -23,6 +23,7 @@ import { parseSession } from '../lib/session/parse.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { colorAgent, resolveAgentName } from '../lib/agents.js';
+import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker } from './sessions-picker.js';
@@ -822,8 +823,22 @@ function parseAgentFilter(agentName) {
     if (!agentName)
         return {};
     const [name, version] = agentName.split('@', 2);
-    const agent = name;
-    if (!SESSION_AGENTS.includes(agent)) {
+    let agent = SESSION_AGENTS.includes(name)
+        ? name
+        : null;
+    if (!agent) {
+        // Aliases and single-typo corrections (cladue -> claude). SESSION_AGENTS
+        // includes ids (rush, hermes) that resolveAgentName doesn't know, so fall
+        // back to fuzzy-matching the session list directly.
+        const resolved = resolveAgentName(name);
+        if (resolved && SESSION_AGENTS.includes(resolved)) {
+            agent = resolved;
+        }
+        else {
+            agent = fuzzyMatch(name, SESSION_AGENTS, FUZZY_PRESETS.agents);
+        }
+    }
+    if (!agent) {
         console.error(chalk.red(`Unknown agent: ${name}. Use: ${SESSION_AGENTS.join(', ')}`));
         process.exit(1);
     }

package/dist/commands/subagents.js

@@ -10,6 +10,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import { agentLabel } from '../lib/agents.js';
+import { homeDir } from '../lib/platform/index.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverSubagentsFromRepo, installSubagentCentrally, listInstalledSubagents, getInstalledSubagent, listSubagentsForAgent, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
@@ -19,7 +20,7 @@ import { requireDestructiveArg, promptRemovalTargets, parseCommaSeparatedList, r
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Replace the home directory prefix with ~ for display. */
 function formatPath(p) {
-    const home = process.env.HOME || '';
+    const home = homeDir();
     if (home && p.startsWith(home)) {
         return '~' + p.slice(home.length);
     }

package/dist/commands/usage.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, } from '../lib/agents.js';
+import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/versions.js';
 import { formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
 /** Agents whose CLI surfaces usage data we can read today. */
@@ -15,9 +15,17 @@ Examples:
   agents usage codex        Show usage for Codex only
 `)
         .action(async (agentFilter) => {
-        const filter = agentFilter;
+        let filter;
+        if (agentFilter) {
+            const resolved = resolveAgentName(agentFilter);
+            if (!resolved) {
+                console.error(chalk.red(formatAgentError(agentFilter)));
+                process.exit(1);
+            }
+            filter = resolved;
+        }
         const targets = filter
-            ? [filter].filter((id) => ALL_AGENT_IDS.includes(id))
+            ? [filter]
             : ALL_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
         if (targets.length === 0) {
             console.log(chalk.gray('No agents installed. Run `agents add <agent>` first.'));

package/dist/index.js

@@ -23,7 +23,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = path.join(__dirname, '..', 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
-const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
+import { NPM_PACKAGE_NAME, deriveGlobalPrefix, installPackageIntoPrefix, verifyInstalledVersion, refreshAliasShims, } from './lib/self-update.js';
 // Detect dev/working-tree builds and default the noisy startup steps off.
 // Three cases trip this:
 //   1. Dev install (scripts/install.sh) — package.json version stamped 0.0.0-dev.<sha>
@@ -268,17 +268,52 @@ async function showWhatsNew(fromVersion, toVersion) {
     }
 }
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir } from './lib/state.js';
+import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir, getRuntimeStateDir } from './lib/state.js';
+import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, findAgentsCliInstalls, } from './lib/self-update.js';
 const UPDATE_CHECK_FILE = getUpdateCheckPath();
-/** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
-function readUpdateCache() {
+/**
+ * Warn once when PATH resolves `agents` to a different agents-cli install
+ * than the copy that is currently running (or to several). Divergent installs
+ * are how self-updates "succeed" without changing the command the user types.
+ * The warning re-fires only when the set of install roots changes; dev builds
+ * (0.0.0-dev) are ignored because side-by-side dev installs are a supported
+ * workflow.
+ */
+function maybeWarnMultiInstall() {
+    const sentinel = path.join(getRuntimeStateDir(), 'multi-install-warned');
+    const runningRoot = path.resolve(__dirname, '..');
+    const byRoot = new Map();
+    byRoot.set(runningRoot, { version: VERSION, note: 'running' });
+    for (const install of findAgentsCliInstalls(process.env.PATH || '')) {
+        if (install.version.startsWith('0.0.0-dev'))
+            continue;
+        if (!byRoot.has(install.packageRoot)) {
+            byRoot.set(install.packageRoot, { version: install.version, note: `agents on PATH: ${install.binPath}` });
+        }
+    }
+    if (byRoot.size < 2) {
+        try {
+            fs.unlinkSync(sentinel);
+        }
+        catch { /* nothing recorded */ }
+        return;
+    }
+    const key = [...byRoot.keys()].sort().join('\n');
     try {
-        return JSON.parse(fs.readFileSync(UPDATE_CHECK_FILE, 'utf-8'));
+        if (fs.readFileSync(sentinel, 'utf-8') === key)
+            return;
     }
-    catch {
-        /* cache file missing or corrupt */
-        return null;
+    catch { /* not warned for this set yet */ }
+    console.error(chalk.yellow('Multiple agents-cli installs detected:'));
+    for (const [root, info] of byRoot) {
+        console.error(chalk.gray(`  ${root}  ${info.version}  (${info.note})`));
+    }
+    console.error(chalk.gray('Upgrades apply to the running copy. Remove a stale copy with: npm uninstall -g --prefix <prefix> @phnx-labs/agents-cli'));
+    try {
+        fs.mkdirSync(path.dirname(sentinel), { recursive: true });
+        fs.writeFileSync(sentinel, key);
     }
+    catch { /* best-effort; worst case the warning repeats */ }
 }
 /** Determine whether enough time has elapsed since the last registry fetch. */
 function shouldFetchLatest(cache) {
@@ -286,18 +321,6 @@ function shouldFetchLatest(cache) {
         return true;
     return Date.now() - cache.lastCheck > UPDATE_CHECK_INTERVAL_MS;
 }
-/** Persist the latest known version and current timestamp to the update-check cache. */
-function saveUpdateCheck(latestVersion) {
-    try {
-        const dir = path.dirname(UPDATE_CHECK_FILE);
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(UPDATE_CHECK_FILE, JSON.stringify({ lastCheck: Date.now(), latestVersion }));
-    }
-    catch {
-        /* best-effort cache update */
-    }
-}
 /** Fetch the exact latest npm version plus its registry integrity hash. */
 async function fetchNpmPackageMetadata(versionOrTag = 'latest', timeoutMs = 5000) {
     const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/${versionOrTag}`, {
@@ -320,12 +343,11 @@ function printResolvedPackage(metadata) {
     console.log(chalk.gray(`Integrity: ${metadata.integrity}`));
 }
 async function installResolvedPackage(metadata) {
-    const { execFile } = await import('child_process');
-    const { promisify } = await import('util');
-    const execFileAsync = promisify(execFile);
-    const installArgs = ['install', '-g', '@phnx-labs/agents-cli', '--ignore-scripts'];
-    installArgs[2] = `${NPM_PACKAGE_NAME}@${metadata.version}`;
-    await execFileAsync('npm', installArgs);
+    const packageRoot = path.resolve(__dirname, '..');
+    const prefix = deriveGlobalPrefix(packageRoot);
+    await installPackageIntoPrefix(`${NPM_PACKAGE_NAME}@${metadata.version}`, prefix);
+    verifyInstalledVersion(packageRoot, metadata.version);
+    refreshAliasShims(packageRoot);
 }
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {
@@ -342,19 +364,7 @@ async function promptUpgrade(latestVersion) {
         ],
     });
     if (answer === 'dismiss') {
-        try {
-            const dir = path.dirname(UPDATE_CHECK_FILE);
-            if (!fs.existsSync(dir))
-                fs.mkdirSync(dir, { recursive: true });
-            const existing = readUpdateCache();
-            fs.writeFileSync(UPDATE_CHECK_FILE, JSON.stringify({
-                ...existing,
-                lastCheck: existing?.lastCheck ?? Date.now(),
-                latestVersion,
-                dismissed: latestVersion,
-            }));
-        }
-        catch { /* best-effort */ }
+        dismissUpdateVersion(UPDATE_CHECK_FILE, latestVersion);
         return;
     }
     if (answer === 'now') {
@@ -362,6 +372,10 @@ async function promptUpgrade(latestVersion) {
         let spinner = ora('Resolving package metadata...').start();
         try {
             const metadata = await fetchNpmPackageMetadata();
+            // The prompt showed the cached latest, which can lag the registry (the
+            // 24h window) — sync the cache to what was actually resolved so later
+            // prompts and the install agree on the same version.
+            saveUpdateCheck(UPDATE_CHECK_FILE, metadata.version);
             spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${metadata.version}`);
             printResolvedPackage(metadata);
             const approved = await confirm({
@@ -377,15 +391,20 @@ async function promptUpgrade(latestVersion) {
             spinner.succeed(`Upgraded to ${metadata.version}`);
             await showWhatsNew(VERSION, metadata.version);
             console.log();
-            // Re-exec with new version and exit
-            const result = spawnSync('agents', process.argv.slice(2), {
+            // Re-exec the verified install's entrypoint and exit. PATH lookup of
+            // `agents` could resolve a different copy (dev build, another prefix)
+            // than the one that was just upgraded.
+            const entrypoint = path.resolve(__dirname, '..', 'dist', 'index.js');
+            const result = spawnSync(process.execPath, [entrypoint, ...process.argv.slice(2)], {
                 stdio: 'inherit',
                 shell: false,
             });
             process.exit(result.status ?? 0);
         }
-        catch {
-            spinner.fail('Upgrade failed');
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            spinner.fail(`Upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
             console.log(chalk.gray('Run manually: agents upgrade --yes'));
         }
         console.log();
@@ -405,7 +424,7 @@ function refreshUpdateCacheInBackground() {
         .then((response) => (response.ok ? response.json() : null))
         .then((data) => {
         if (data && typeof data.version === 'string') {
-            saveUpdateCheck(data.version);
+            saveUpdateCheck(UPDATE_CHECK_FILE, data.version);
         }
     })
         .catch(() => {
@@ -416,7 +435,8 @@ function refreshUpdateCacheInBackground() {
 async function checkForUpdates() {
     if (process.env.AGENTS_CLI_DISABLE_AUTO_UPDATE)
         return;
-    const cache = readUpdateCache();
+    maybeWarnMultiInstall();
+    const cache = readUpdateCache(UPDATE_CHECK_FILE);
     // Kick off network refresh in background if stale. Does not block.
     if (shouldFetchLatest(cache)) {
         refreshUpdateCacheInBackground();
@@ -424,7 +444,7 @@ async function checkForUpdates() {
     // Prompt based on current cache (may be from a previous run's background refresh).
     // Skip if the user dismissed this exact version — they'll be prompted again when
     // a newer version appears.
-    if (cache?.latestVersion && cache.latestVersion !== VERSION && compareVersions(cache.latestVersion, VERSION) > 0 && cache.latestVersion !== cache.dismissed) {
+    if (shouldPromptUpgrade(cache, VERSION)) {
         try {
             await promptUpgrade(cache.latestVersion);
         }
@@ -699,7 +719,9 @@ program
         }
     }
     catch (err) {
-        spinner.fail('Upgrade failed');
+        if (isPromptCancelled(err))
+            return;
+        spinner.fail(`Upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
         console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
     }
 });