@phnx-labs/agents-cli 1.18.5 → 1.19.0

package/dist/commands/versions.js

@@ -12,6 +12,7 @@ import { createShim, createVersionedAlias, removeShim, shimExists, getShimsDir,
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { tryAutoPull } from '../lib/git.js';
 import { getAgentsDir } from '../lib/state.js';
+import { setHelpSections } from '../lib/help.js';
 /**
  * Helper to get actual installed version for an agent.
  * Returns the latest installed version, or throws if none installed.
@@ -79,34 +80,32 @@ function warnIfShimShadowed(agent) {
 }
 /** Register `agents add`, `agents remove`, `agents use`, and `agents list` (deprecated). */
 export function registerVersionsCommands(program) {
-    program
+    const addCmd = program
         .command('add <specs...>')
         .description('Download and install agent CLI versions. Enables subsidized API usage through managed binaries.')
-        .option('-p, --project', 'Lock this version to the current project directory only, stored in .agents/agents.yaml')
-        .option('-y, --yes', 'Auto-accept defaults without prompting (useful for scripts and CI)')
-        .addHelpText('after', `
-Examples:
-  # Fresh install of the latest Claude CLI
-  agents add claude@latest
-
-  # Install specific version (use this when you need reproducibility)
-  agents add claude@2.1.112
+        .option('-p, --project', 'Lock this version to the current project directory only, stored in project-root agents.yaml')
+        .option('-y, --yes', 'Auto-accept defaults without prompting (useful for scripts and CI)');
+    setHelpSections(addCmd, {
+        examples: `
+      # Install the latest version of an agent
+      agents add claude@latest
 
-  # Install multiple agents at once
-  agents add claude@latest codex@0.116.0
+      # Install a specific version (reproducibility)
+      agents add claude@2.1.112
 
-  # Pin a version to this project only (won't affect global default)
-  agents add claude@2.1.100 --project
+      # Install multiple agents at once
+      agents add claude@latest codex@0.116.0
 
-When to use:
-  - First time setup: install the agent CLI you want to use
-  - Upgrading: install a newer version (old versions remain available)
-  - Multi-account: install different versions for different accounts (each version has its own auth)
-  - Project-specific: lock a version for a repo with --project
-
-Note: The first version you install becomes the default automatically.
-`)
-        .action(async (specs, options) => {
+      # Lock a version to this project only (won't affect global default)
+      agents add claude@2.1.100 --project
+    `,
+        notes: `
+      - The first version you install becomes the default automatically.
+      - 'add' does NOT change the default if a default already exists. Use 'agents use' to switch.
+      - Multi-account: each installed version has separate auth, so you can install the same agent twice for two accounts.
+    `,
+    });
+    addCmd.action(async (specs, options) => {
         const isProject = options.project;
         const skipPrompts = options.yes || !isInteractiveTerminal();
         for (const spec of specs) {
@@ -228,7 +227,7 @@ Note: The first version you install becomes the default automatically.
                             await setDefaultVersion(agent, installedVersion);
                         }
                         else if (skipPrompts) {
-                            await setDefaultVersion(agent, installedVersion);
+                            console.log(chalk.gray(`  Default remains ${agentLabel(agentConfig.id)}@${currentDefault}. Run 'agents use ${agent}@${installedVersion}' to switch.`));
                         }
                         else {
                             try {
@@ -297,31 +296,27 @@ Note: The first version you install becomes the default automatically.
             }
         }
     });
-    program
+    const removeCmd = program
         .command('remove <specs...>')
-        .description('Uninstall agent CLI versions from your system. Frees up disk space and removes auth tokens.')
-        .option('-p, --project', 'Also clear the pinned version from .agents/agents.yaml in the current project')
-        .addHelpText('after', `
-Examples:
-  # Remove a specific version
-  agents remove claude@2.0.50
-
-  # Remove without specifying version (opens interactive picker)
-  agents remove claude
+        .description('Uninstall agent CLI versions. Frees disk space and removes the version\'s auth token.')
+        .option('-p, --project', 'Also clear the pinned version from .agents/agents.yaml in the current project');
+    setHelpSections(removeCmd, {
+        examples: `
+      # Remove a specific version
+      agents remove claude@2.0.50
 
-  # Remove and also clear project pin
-  agents remove claude@2.0.50 --project
+      # Pick interactively if you omit the version
+      agents remove claude
 
-When to use:
-  - Freeing disk space by removing old unused versions
-  - Cleaning up after testing a version you no longer need
-  - Removing a version tied to an account you've deactivated
-
-Notes:
-  - Removing the default version will unset the default; run 'agents use' to pick a new one
-  - You can always reinstall with 'agents add' later
-`)
-        .action(async (specs, options) => {
+      # Remove and also clear the project pin
+      agents remove claude@2.0.50 --project
+    `,
+        notes: `
+      - Removing the default version unsets the default; run 'agents use' to pick a new one.
+      - Reinstall any time with 'agents add'.
+    `,
+    });
+    removeCmd.action(async (specs, options) => {
         const isProject = options.project;
         for (const spec of specs) {
             const parsed = parseAgentSpec(spec);
@@ -418,32 +413,29 @@ Notes:
             }
         }
     });
-    program
+    const useCmd = program
         .command('use <agent> [version]')
-        .description('Switch the active version for an agent. This is how you set defaults globally or per-project.')
+        .description('Switch the active version for an agent. This is the only command that sets the default.')
         .option('-p, --project', 'Pin to this project directory only (stored in .agents/agents.yaml)')
-        .option('-y, --yes', 'Auto-sync resources without prompting')
-        .addHelpText('after', `
-Examples:
-  # Set global default (interactive picker if version omitted)
-  agents use claude
-  agents use claude@2.1.112
+        .option('-y, --yes', 'Auto-sync resources without prompting');
+    setHelpSections(useCmd, {
+        examples: `
+      # Set global default (interactive picker if version omitted)
+      agents use claude
+      agents use claude@2.1.112
 
-  # Lock this project to a specific version (overrides global default when in this directory)
-  agents use claude@2.1.100 --project
+      # Pin this project to a version (overrides the global default in this directory)
+      agents use claude@2.1.100 --project
 
-  # Switch accounts (each version can be logged into a different account)
-  agents use claude@2.1.50
-
-When to use:
-  - After installing: 'agents add' does NOT set the default; 'use' does
-  - Switching accounts: each installed version has separate auth; 'use' switches which one is active
-  - Project overrides: set a different version for a specific project with --project
-  - Testing: quickly switch between versions without reinstalling
-
-Important: This is the ONLY command that sets the default version. If you want a version to be active, you must run 'agents use'.
-`)
-        .action(async (agentArg, versionArg, options) => {
+      # Switch accounts — each installed version has its own auth
+      agents use claude@2.1.50
+    `,
+        notes: `
+      - 'agents add' installs but does NOT set the default. Always follow with 'agents use'.
+      - --project pins to the current directory only via .agents/agents.yaml.
+    `,
+    });
+    useCmd.action(async (agentArg, versionArg, options) => {
         try {
             const skipPrompts = options.yes || !isInteractiveTerminal();
             // Auto-pull ~/.agents-system if it's a git repo with remote (silent on success)

package/dist/commands/worktree.d.ts

@@ -0,0 +1,20 @@
+/**
+ * agents worktree -- provision, release, and prune per-terminal git worktrees.
+ *
+ * Used by surfaces that want to spawn each agent terminal in an isolated
+ * working tree (Companion extension opt-in toggle). Mirrors the in-process
+ * worktree helpers in lib/teams/worktree.ts but exposes them as a CLI so
+ * other processes (IDE extensions, shell aliases, hooks) can call them.
+ *
+ *   agents worktree provision <terminal-id>   -> prints absolute worktree path
+ *   agents worktree release   <terminal-id>   -> removes if clean + merged
+ *   agents worktree prune                     -> removes every clean+merged one
+ *
+ * Worktrees live at <repo>/.history/worktrees/<terminal-id>, on a branch
+ * named agent/<terminal-id>. The branch starts at HEAD of the parent repo.
+ * .history/ mirrors the agents-cli runtime-state convention at ~/.agents/.history/
+ * but scoped to the repo. .agents/ is reserved for project resources
+ * (skills, hooks, commands) per the agents-cli DotAgents repo layout.
+ */
+import type { Command } from 'commander';
+export declare function registerWorktreeCommands(program: Command): void;

package/dist/commands/worktree.js

@@ -0,0 +1,242 @@
+import chalk from 'chalk';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import { setHelpSections } from '../lib/help.js';
+const execFileAsync = promisify(execFile);
+const WORKTREE_SUBDIR = path.join('.history', 'worktrees');
+const BRANCH_PREFIX = 'agent/';
+function die(msg, code = 1) {
+    console.error(chalk.red(msg));
+    process.exit(code);
+}
+function isValidTerminalId(id) {
+    // Allow letters, digits, dot, dash, underscore. Reject anything else so a
+    // hostile or buggy caller can't inject path traversal or shell metachars.
+    return /^[A-Za-z0-9._-]+$/.test(id) && id.length > 0 && id.length <= 128;
+}
+async function gitRoot(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        die(`Not inside a git repo: ${cwd}`);
+    }
+}
+function worktreePathFor(root, terminalId) {
+    return path.join(root, WORKTREE_SUBDIR, terminalId);
+}
+function branchNameFor(terminalId) {
+    return `${BRANCH_PREFIX}${terminalId}`;
+}
+async function inspect(root, terminalId) {
+    const wt = worktreePathFor(root, terminalId);
+    const branch = branchNameFor(terminalId);
+    const exists = fsSync.existsSync(wt);
+    if (!exists) {
+        return { exists: false, dirty: false, aheadOfUpstream: false, hasUpstream: false, branchMerged: false };
+    }
+    let dirty = false;
+    try {
+        const { stdout } = await execFileAsync('git', ['status', '--porcelain'], { cwd: wt });
+        dirty = stdout.trim().length > 0;
+    }
+    catch {
+        dirty = true; // err on the side of caution
+    }
+    let hasUpstream = false;
+    let aheadOfUpstream = false;
+    try {
+        await execFileAsync('git', ['rev-parse', '--abbrev-ref', '@{u}'], { cwd: wt });
+        hasUpstream = true;
+        const { stdout } = await execFileAsync('git', ['rev-list', '--count', '@{u}..HEAD'], { cwd: wt });
+        aheadOfUpstream = parseInt(stdout.trim(), 10) > 0;
+    }
+    catch {
+        hasUpstream = false; // never pushed -- treat as "has commits we'd lose"
+    }
+    let branchMerged = false;
+    try {
+        const { stdout } = await execFileAsync('git', ['branch', '--merged', 'origin/main', '--list', branch], { cwd: root });
+        branchMerged = stdout.trim().length > 0;
+    }
+    catch {
+        branchMerged = false;
+    }
+    return { exists, dirty, aheadOfUpstream, hasUpstream, branchMerged };
+}
+async function provision(root, terminalId) {
+    const wt = worktreePathFor(root, terminalId);
+    const branch = branchNameFor(terminalId);
+    if (fsSync.existsSync(wt))
+        return wt;
+    await fs.mkdir(path.dirname(wt), { recursive: true });
+    // If the branch already exists (e.g. left over from a previous run), reuse
+    // it instead of failing. Surfaces typically reuse a terminal-id when
+    // restoring a session.
+    let branchExists = false;
+    try {
+        await execFileAsync('git', ['rev-parse', '--verify', `refs/heads/${branch}`], { cwd: root });
+        branchExists = true;
+    }
+    catch {
+        branchExists = false;
+    }
+    const args = branchExists
+        ? ['worktree', 'add', wt, branch]
+        : ['worktree', 'add', '-b', branch, wt, 'HEAD'];
+    await execFileAsync('git', args, { cwd: root });
+    return wt;
+}
+async function release(root, terminalId, force) {
+    const wt = worktreePathFor(root, terminalId);
+    const branch = branchNameFor(terminalId);
+    if (!fsSync.existsSync(wt)) {
+        // Already gone; treat as success but tell the caller.
+        return { removed: false, reason: 'worktree does not exist' };
+    }
+    if (!force) {
+        const report = await inspect(root, terminalId);
+        if (report.dirty)
+            return { removed: false, reason: 'worktree has uncommitted changes' };
+        if (!report.hasUpstream) {
+            // Local-only commits exist if HEAD differs from origin/main.
+            try {
+                const { stdout } = await execFileAsync('git', ['rev-list', '--count', 'origin/main..HEAD'], { cwd: wt });
+                if (parseInt(stdout.trim(), 10) > 0) {
+                    return { removed: false, reason: 'branch has local commits not on origin/main' };
+                }
+            }
+            catch {
+                return { removed: false, reason: 'cannot verify branch state vs origin/main' };
+            }
+        }
+        if (report.aheadOfUpstream)
+            return { removed: false, reason: 'branch has unpushed commits' };
+    }
+    try {
+        await execFileAsync('git', ['worktree', 'remove', force ? '--force' : '', wt].filter(Boolean), { cwd: root });
+    }
+    catch (err) {
+        if (err.message?.includes('is not a working tree')) {
+            await execFileAsync('git', ['worktree', 'prune'], { cwd: root });
+        }
+        else {
+            throw err;
+        }
+    }
+    // Delete the branch if it's safe to do so. -d (lowercase) refuses to drop
+    // an unmerged branch by itself, which is exactly the safety net we want.
+    try {
+        await execFileAsync('git', ['branch', '-d', branch], { cwd: root });
+    }
+    catch {
+        // Branch may not exist or may not be merged. We already validated above;
+        // leaving the branch behind is preferable to silently dropping commits.
+    }
+    return { removed: true };
+}
+async function listAgentWorktrees(root) {
+    const dir = path.join(root, WORKTREE_SUBDIR);
+    if (!fsSync.existsSync(dir))
+        return [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter(e => e.isDirectory()).map(e => e.name);
+}
+export function registerWorktreeCommands(program) {
+    const wt = program
+        .command('worktree')
+        .description('Provision, release, and prune per-terminal git worktrees for agent isolation.');
+    setHelpSections(wt, {
+        examples: `
+      # Create (or reuse) an isolated worktree for an agent terminal — prints the path
+      agents worktree provision CC-1747509823-3
+
+      # Remove the worktree if it's clean and merged/pushed
+      agents worktree release CC-1747509823-3
+
+      # Preview what 'prune' would release across all agent worktrees
+      agents worktree prune --dry-run
+
+      # Release every agent worktree that's safe to remove
+      agents worktree prune
+    `,
+        notes: `
+      Worktrees live at <repo>/.history/worktrees/<terminal-id> on branch agent/<terminal-id>.
+      Use --force on 'release' to skip safety checks (DANGEROUS — discards unpushed work).
+    `,
+    });
+    wt.command('provision <terminal-id>')
+        .description('Create (or reuse) an isolated worktree for an agent terminal. Prints the absolute path.')
+        .option('--root <path>', 'Repo root (defaults to current working directory)')
+        .action(async (terminalId, opts) => {
+        if (!isValidTerminalId(terminalId)) {
+            die(`Invalid terminal-id: ${terminalId} (allowed: [A-Za-z0-9._-], <=128 chars)`);
+        }
+        const root = await gitRoot(opts.root ?? process.cwd());
+        const wtPath = await provision(root, terminalId);
+        console.log(wtPath);
+    });
+    wt.command('release <terminal-id>')
+        .description('Remove the worktree if clean and the branch is merged or has no unpushed commits.')
+        .option('--root <path>', 'Repo root (defaults to current working directory)')
+        .option('--force', 'Skip safety checks (DANGEROUS: discards unpushed work)')
+        .action(async (terminalId, opts) => {
+        if (!isValidTerminalId(terminalId)) {
+            die(`Invalid terminal-id: ${terminalId} (allowed: [A-Za-z0-9._-], <=128 chars)`);
+        }
+        const root = await gitRoot(opts.root ?? process.cwd());
+        const result = await release(root, terminalId, Boolean(opts.force));
+        if (result.removed) {
+            console.log(chalk.green(`removed ${worktreePathFor(root, terminalId)}`));
+        }
+        else {
+            console.log(chalk.yellow(`kept ${worktreePathFor(root, terminalId)} (${result.reason})`));
+        }
+    });
+    wt.command('prune')
+        .description('Try to release every agent worktree under .history/worktrees/. Skips dirty or unpushed ones.')
+        .option('--root <path>', 'Repo root (defaults to current working directory)')
+        .option('--dry-run', 'Report what would be removed without touching anything')
+        .action(async (opts) => {
+        const root = await gitRoot(opts.root ?? process.cwd());
+        const ids = await listAgentWorktrees(root);
+        if (ids.length === 0) {
+            console.log(chalk.gray('no agent worktrees to prune'));
+            return;
+        }
+        for (const id of ids) {
+            if (!isValidTerminalId(id)) {
+                console.log(chalk.yellow(`skip ${id} (name not in expected format)`));
+                continue;
+            }
+            if (opts.dryRun) {
+                const report = await inspect(root, id);
+                const blocker = report.dirty
+                    ? 'dirty'
+                    : report.aheadOfUpstream
+                        ? 'unpushed'
+                        : !report.hasUpstream
+                            ? 'never pushed'
+                            : null;
+                if (blocker) {
+                    console.log(chalk.yellow(`keep   ${id} (${blocker})`));
+                }
+                else {
+                    console.log(chalk.green(`remove ${id}`));
+                }
+                continue;
+            }
+            const result = await release(root, id, false);
+            if (result.removed) {
+                console.log(chalk.green(`removed ${id}`));
+            }
+            else {
+                console.log(chalk.yellow(`kept    ${id} (${result.reason})`));
+            }
+        }
+    });
+}

package/dist/computer.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/computer.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerComputerSubcommands } from './commands/computer.js';
+const program = new Command();
+program.name('computer').description('Drive macOS apps via Accessibility — list, screenshot, click, type');
+registerComputerSubcommands(program);
+program.parse();

package/dist/index.js

@@ -23,6 +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';
 // 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>
@@ -78,11 +79,13 @@ import { registerDoctorCommand } from './commands/doctor.js';
 import { registerSubagentsCommands } from './commands/subagents.js';
 import { registerPluginsCommands } from './commands/plugins.js';
 import { registerWorkflowsCommands } from './commands/workflows.js';
+import { registerWorktreeCommands } from './commands/worktree.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerRefreshRulesCommand } from './commands/refresh-rules.js';
 import { registerDriveCommands } from './commands/drive.js';
 import { registerPtyCommands } from './commands/pty.js';
 import { registerBrowserCommand } from './commands/browser.js';
+import { registerComputerCommand } from './commands/computer.js';
 import { registerProfilesCommands } from './commands/profiles.js';
 import { registerSecretsCommands } from './commands/secrets.js';
 import { registerFactoryCommands } from './commands/factory.js';
@@ -268,10 +271,36 @@ function saveUpdateCheck(latestVersion) {
         /* best-effort cache update */
     }
 }
+/** Fetch the exact latest npm version plus its registry integrity hash. */
+async function fetchLatestNpmPackageMetadata(timeoutMs = 5000) {
+    const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`, {
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+        throw new Error('Could not reach npm registry');
+    }
+    const data = await response.json();
+    if (typeof data.version !== 'string' || typeof data.dist?.integrity !== 'string') {
+        throw new Error('npm registry response did not include version and integrity');
+    }
+    return { version: data.version, integrity: data.dist.integrity };
+}
+function printResolvedPackage(metadata) {
+    console.log(chalk.gray(`Resolved: ${NPM_PACKAGE_NAME}@${metadata.version}`));
+    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);
+}
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {
     if (!isInteractiveTerminal()) {
-        console.error(chalk.yellow(`Update available: ${VERSION} -> ${latestVersion}. Run: npm install -g @phnx-labs/agents-cli@latest`));
+        console.error(chalk.yellow(`Update available: ${VERSION} -> ${latestVersion}. Run: agents upgrade --yes`));
         return;
     }
     const answer = await select({
@@ -299,14 +328,24 @@ async function promptUpgrade(latestVersion) {
         return;
     }
     if (answer === 'now') {
-        const { execFile, spawnSync } = await import('child_process');
-        const { promisify } = await import('util');
-        const execFileAsync = promisify(execFile);
-        const spinner = ora('Upgrading...').start();
+        const { spawnSync } = await import('child_process');
+        let spinner = ora('Resolving package metadata...').start();
         try {
-            await execFileAsync('npm', ['install', '-g', '@phnx-labs/agents-cli@latest']);
-            spinner.succeed(`Upgraded to ${latestVersion}`);
-            await showWhatsNew(VERSION, latestVersion);
+            const metadata = await fetchLatestNpmPackageMetadata();
+            spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${metadata.version}`);
+            printResolvedPackage(metadata);
+            const approved = await confirm({
+                message: `Install ${NPM_PACKAGE_NAME}@${metadata.version}?`,
+                default: false,
+            });
+            if (!approved) {
+                console.log(chalk.gray('Upgrade cancelled'));
+                return;
+            }
+            spinner = ora('Upgrading...').start();
+            await installResolvedPackage(metadata);
+            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), {
@@ -317,7 +356,7 @@ async function promptUpgrade(latestVersion) {
         }
         catch {
             spinner.fail('Upgrade failed');
-            console.log(chalk.gray('Run manually: npm install -g @phnx-labs/agents-cli@latest'));
+            console.log(chalk.gray('Run manually: agents upgrade --yes'));
         }
         console.log();
     }
@@ -493,6 +532,7 @@ registerMcpCommands(program);
 registerSubagentsCommands(program);
 registerPluginsCommands(program);
 registerWorkflowsCommands(program);
+registerWorktreeCommands(program);
 registerVersionsCommands(program);
 registerImportCommand(program);
 registerPackagesCommands(program);
@@ -525,6 +565,7 @@ registerUsageCommand(program);
 registerAliasCommand(program);
 registerPtyCommands(program);
 registerBrowserCommand(program);
+registerComputerCommand(program);
 // Deprecated 'jobs' and 'cron' aliases for 'routines'
 for (const alias of ['jobs', 'cron']) {
     program
@@ -541,18 +582,12 @@ for (const alias of ['jobs', 'cron']) {
 program
     .command('upgrade')
     .description('Upgrade agents-cli to the latest version')
-    .action(async () => {
-    const spinner = ora('Checking for updates...').start();
+    .option('-y, --yes', 'Install without an interactive confirmation prompt')
+    .action(async (options) => {
+    let spinner = ora('Checking for updates...').start();
     try {
-        const response = await fetch('https://registry.npmjs.org/@phnx-labs/agents-cli/latest', {
-            signal: AbortSignal.timeout(5000),
-        });
-        if (!response.ok) {
-            spinner.fail('Could not reach npm registry');
-            process.exit(1);
-        }
-        const data = (await response.json());
-        const latestVersion = data.version;
+        const metadata = await fetchLatestNpmPackageMetadata();
+        const latestVersion = metadata.version;
         if (latestVersion === VERSION) {
             spinner.succeed(`Already on latest version (${VERSION})`);
             return;
@@ -561,17 +596,26 @@ program
             spinner.succeed(`Already ahead of latest (${VERSION} >= ${latestVersion})`);
             return;
         }
-        spinner.text = `Upgrading ${VERSION} -> ${latestVersion}...`;
-        const { execFile } = await import('child_process');
-        const { promisify } = await import('util');
-        const execFileAsync = promisify(execFile);
-        await execFileAsync('npm', ['install', '-g', '@phnx-labs/agents-cli@latest']);
+        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${latestVersion}`);
+        printResolvedPackage(metadata);
+        if (isInteractiveTerminal() && !options.yes) {
+            const approved = await confirm({
+                message: `Install ${NPM_PACKAGE_NAME}@${latestVersion}?`,
+                default: false,
+            });
+            if (!approved) {
+                console.log(chalk.gray('Upgrade cancelled'));
+                return;
+            }
+        }
+        spinner = ora(`Upgrading ${VERSION} -> ${latestVersion}...`).start();
+        await installResolvedPackage(metadata);
         spinner.succeed(`Upgraded to ${latestVersion}`);
         await showWhatsNew(VERSION, latestVersion);
     }
     catch (err) {
         spinner.fail('Upgrade failed');
-        console.log(chalk.gray('Run manually: npm install -g @phnx-labs/agents-cli@latest'));
+        console.log(chalk.gray('Run manually: agents upgrade --yes'));
     }
 });
 registerPullCommand(program);

package/dist/lib/agents.d.ts

@@ -102,6 +102,7 @@ export declare function isMcpRegistered(agentId: AgentId, mcpName: string): Prom
 export declare function registerMcp(agentId: AgentId, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
     home?: string;
     binary?: string;
+    headers?: Record<string, string>;
 }): Promise<{
     success: boolean;
     error?: string;
@@ -128,7 +129,9 @@ export interface McpTargetOperationResult {
 export declare function registerMcpToTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
-}, name: string, command: string, scope?: 'user' | 'project', transport?: string): Promise<McpTargetOperationResult[]>;
+}, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
+    headers?: Record<string, string>;
+}): Promise<McpTargetOperationResult[]>;
 /**
  * Unregister an MCP server from multiple agent targets, including both direct
  * agents and specific version-managed installs.