@phnx-labs/agents-cli 1.20.71 → 1.20.73

package/dist/commands/skills.js

@@ -45,6 +45,7 @@ When to use:
         .command('list [agent]')
         .description('Show which skills are installed and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
+        .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .action(async (agentArg, options) => {
         const spinner = ora({ text: 'Loading...', isSilent: !process.stdout.isTTY }).start();
         const agentInput = agentArg || options.agent;
@@ -74,6 +75,7 @@ When to use:
             centralPath: getSkillsDir(),
             filterAgent,
             filterVersion,
+            json: options.json,
         });
     });
     skillsCmd

package/dist/commands/ssh.d.ts

@@ -10,5 +10,14 @@
  * rsync / `agents sessions --host` resolve the same logical names.
  */
 import type { Command } from 'commander';
+import { type CrabboxBox } from '../lib/crabbox/cli.js';
+/**
+ * Live "Leased boxes" section for `agents devices` (F4, RUSH-1923), computed
+ * from `crabboxList()` — these are ephemeral crabbox leases, NEVER written into
+ * the device registry. Returns [] when crabbox is unavailable / has no creds /
+ * reports no boxes, so the section is simply omitted. `nowSecs` is injected so
+ * the row formatting is deterministic in tests.
+ */
+export declare function renderLeasedBoxesSection(boxes: CrabboxBox[], nowSecs: number): string[];
 /** Register both `agents ssh` and `agents devices`. */
 export declare function registerSshCommands(program: Command): void;

package/dist/commands/ssh.js

@@ -19,6 +19,7 @@ import { getCliVersion } from '../lib/version.js';
 import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../lib/secrets/bundles.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { registerFleetCaptureCommand } from './fleet-capture.js';
+import { registerFleetApplyAlias } from './apply.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, } from '../lib/devices/registry.js';
 import { addControlToken } from '../lib/serve/token.js';
 import { DEFAULT_SERVE_PORT } from '../lib/serve/server.js';
@@ -40,7 +41,10 @@ import { checkAllClis } from '../lib/teams/agents.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
-import { formatCheckedAge, isDeadVerdict, probeLocalFleetAuth, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
+import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js';
+import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort } from './lease.js';
+import { authCellColor, formatCheckedAge, isDeadVerdict, probeLocalFleetAuth, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
+import { runFleetLogin } from '../lib/fleet/remote-login.js';
 /** One-line summary of a device for `list`. `isSelf` marks the machine this
  * command is running on so it stands out from the rest of the tailnet. */
 function deviceSummary(d, isSelf = false) {
@@ -130,6 +134,74 @@ function renderDeviceTable(reg, names, self, statsMap, full = false) {
     }
     return lines;
 }
+/**
+ * Live "Leased boxes" section for `agents devices` (F4, RUSH-1923), computed
+ * from `crabboxList()` — these are ephemeral crabbox leases, NEVER written into
+ * the device registry. Returns [] when crabbox is unavailable / has no creds /
+ * reports no boxes, so the section is simply omitted. `nowSecs` is injected so
+ * the row formatting is deterministic in tests.
+ */
+export function renderLeasedBoxesSection(boxes, nowSecs) {
+    if (boxes.length === 0)
+        return [];
+    const lines = [];
+    lines.push('');
+    lines.push(chalk.bold('Leased boxes') + chalk.gray(' (ephemeral · via crabbox)'));
+    lines.push('  ' +
+        chalk.gray('box'.padEnd(16)) +
+        chalk.gray('class'.padEnd(10)) +
+        chalk.gray('address'.padEnd(24)) +
+        chalk.gray('status'.padEnd(9)) +
+        chalk.gray('idle'.padEnd(12)) +
+        chalk.gray('expires'));
+    for (const b of boxes) {
+        const addr = boxAddress(b) ?? '—';
+        lines.push('  ' +
+            chalk.cyan(b.slug.padEnd(16)) +
+            (b.class ?? '?').padEnd(10) +
+            addr.padEnd(24) +
+            boxStatus(b).padEnd(9) +
+            chalk.gray(fmtIdleShort(b, nowSecs).padEnd(12)) +
+            chalk.gray(fmtExpiresShort(b, nowSecs)));
+    }
+    lines.push(chalk.gray('  Reuse a box with `agents run --box <slug>` · stop with `agents lease stop <slug>`'));
+    return lines;
+}
+/** The leased-box rows for the devices list, or [] when crabbox can't be read. */
+function loadLeasedBoxesSection() {
+    try {
+        const boxes = crabboxList({ secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE, timeoutMs: 5000 });
+        return renderLeasedBoxesSection(boxes, Math.floor(Date.now() / 1000));
+    }
+    catch {
+        return []; // crabbox not installed / no provider creds — omit the section
+    }
+}
+/**
+ * `agents ssh <slug>` targeting a leased crabbox box. crabbox provisions a
+ * per-lease identity key, so we ssh via crabbox's OWN emitted invocation
+ * (`crabboxSshArgv`) — a raw `ssh crabbox@ip` fails publickey. Returns false when
+ * `name` is not a known crabbox slug so the caller can fall through to the normal
+ * "Unknown device" error.
+ */
+function trySshLeasedBox(name, cmd) {
+    let box;
+    try {
+        box = crabboxFind(name, { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE, timeoutMs: 5000 });
+    }
+    catch {
+        return false; // crabbox unavailable — not a leased-box target
+    }
+    if (!box)
+        return false;
+    const sshArgv = crabboxSshArgv(name, { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE, timeoutMs: 8000 });
+    if (!sshArgv) {
+        console.error(chalk.red(`Leased box '${name}' is not reachable yet (status: ${boxStatus(box)}).`));
+        process.exit(1);
+    }
+    const res = spawnSync(sshArgv[0], [...sshArgv.slice(1), ...cmd], { stdio: 'inherit' });
+    process.exit(res.status ?? 1);
+}
 /** Resolve a device or exit with a clear error. */
 async function mustGetDevice(name) {
     const d = await getDevice(name);
@@ -423,17 +495,28 @@ async function runFleetPing(opts) {
     if (opts.strict && anyBad)
         process.exitCode = 1;
 }
-/** Color a per-host×agent cell: green all-live, red any revoked/expired, yellow degraded. */
+/** Resolve an {@link AuthCellColor} to a chalk painter. Single map for cells + labels. */
+const CELL_PAINT = {
+    green: chalk.green,
+    yellow: chalk.yellow,
+    red: chalk.red,
+    gray: chalk.gray,
+    dim: chalk.dim,
+};
+/**
+ * Color a per-host×agent cell. The numerator counts accounts that are usable
+ * right now — live-verified PLUS signed-in-but-unverifiable (codex/grok) — over
+ * the total, so a logged-in codex fleet reads "1/1", not a scary "0/1". Color is
+ * the shared {@link authCellColor}: red only for revoked (re-login), yellow for
+ * soft/expired (self-refreshes), gray for present-but-unverifiable, green when
+ * all live.
+ */
 function authCell(summary, width) {
     if (summary.total === 0)
         return chalk.dim('·'.padEnd(width));
-    const text = `${summary.live}/${summary.total}`;
-    const padded = text.padEnd(width);
-    if (summary.bad > 0)
-        return chalk.red(padded);
-    if (summary.warn > 0)
-        return chalk.yellow(padded);
-    return chalk.green(padded);
+    const ok = summary.live + summary.present;
+    const padded = `${ok}/${summary.total}`.padEnd(width);
+    return CELL_PAINT[authCellColor(summary)](padded);
 }
 /** Render the fleet auth matrix (device rows × agent columns) plus an optional per-account breakdown. */
 function renderAuthMatrix(results, opts) {
@@ -466,7 +549,7 @@ function renderAuthMatrix(results, opts) {
         lines.push(`  ${r.host.padEnd(nameW)}  ${cells.join(' ')}${note}`);
     }
     lines.push('');
-    lines.push(chalk.gray('  cell = live/total accounts · green all live · red revoked (re-login) · yellow expired/unverified/limited'));
+    lines.push(chalk.gray('  cell = signed-in/total accounts · green live · gray signed-in (unverifiable: codex/grok) · yellow expired (self-refreshes) · red revoked (re-login)'));
     if (opts?.verbose) {
         lines.push('');
         lines.push(chalk.bold('Accounts'));
@@ -475,9 +558,7 @@ function renderAuthMatrix(results, opts) {
                 continue;
             for (const row of r.rows.slice().sort((x, y) => (x.agent + x.version).localeCompare(y.agent + y.version))) {
                 const v = row.health.verdict;
-                const label = v === 'live' ? chalk.green(verdictLabel(v))
-                    : (v === 'revoked' || v === 'expired') ? chalk.red(verdictLabel(v))
-                        : chalk.yellow(verdictLabel(v));
+                const label = CELL_PAINT[verdictColor(v)](verdictLabel(v));
                 const acctRaw = row.account ?? '—';
                 const acct = row.account ? chalk.cyan(acctRaw.padEnd(28)) : chalk.dim(acctRaw.padEnd(28));
                 const detail = row.health.detail ? chalk.dim(` ${row.health.detail}`) : '';
@@ -488,6 +569,46 @@ function renderAuthMatrix(results, opts) {
     }
     return lines;
 }
+/** Render the final `fleet login` result summary in the house auth-matrix style. */
+function renderLoginMatrix(results) {
+    const lines = [chalk.bold('Fleet login')];
+    if (results.length === 0) {
+        lines.push(chalk.gray('  Nothing pending — every requested account is already logged in.'));
+        return lines;
+    }
+    const nameW = Math.max(6, ...results.map((r) => `${r.agent}@${r.device}`.length));
+    for (const r of results) {
+        const who = `${r.agent}@${r.device}`.padEnd(nameW);
+        let badge;
+        switch (r.state) {
+            case 'authorized':
+                badge = chalk.green('authorized');
+                break;
+            case 'ready':
+                badge = chalk.cyan('code ready');
+                break;
+            case 'driving':
+                badge = chalk.yellow('driving');
+                break;
+            case 'skipped':
+                badge = chalk.gray('not remotable');
+                break;
+            case 'error':
+                badge = chalk.red('error');
+                break;
+            default:
+                badge = chalk.gray(r.state);
+                break;
+        }
+        const note = r.detail ? chalk.dim(`  ${r.detail}`) : (r.reason && !r.remotable ? chalk.dim(`  ${r.reason}`) : '');
+        lines.push(`  ${who}  ${badge}${note}`);
+    }
+    const auth = results.filter((r) => r.state === 'authorized').length;
+    const remotable = results.filter((r) => r.remotable).length;
+    lines.push('');
+    lines.push(chalk.gray(`  ${auth}/${remotable} remotable logins authorized`));
+    return lines;
+}
 /** Register the `agents devices` command tree (also aliased as `fleet`). */
 function registerDevicesCommands(program) {
     const devicesCmd = program
@@ -529,6 +650,9 @@ Typical workflow:
     });
     // `agents fleet capture` — snapshot live state into agents.yaml fleet:.
     registerFleetCaptureCommand(devicesCmd);
+    // `agents fleet apply` — same reconcile engine as the top-level `agents apply`,
+    // surfaced under the fleet tree for discoverability.
+    registerFleetApplyAlias(devicesCmd);
     devicesCmd
         .command('register <name>')
         .description('Register a discovered (pending) node by name — used by the menu-bar "NEW DEVICES → Register" action.')
@@ -576,16 +700,7 @@ Typical workflow:
         }
         console.log(chalk.green(`No longer ignoring '${name}'`) + chalk.gray(' — run `agents devices sync` to register it.'));
     });
-    devicesCmd
-        .command('list')
-        .alias('ls')
-        .description('List registered devices with platform, address, reachability, and live resource headroom.')
-        .option('--json', 'output the registry as a JSON array (for scripts and hooks)')
-        .option('--no-stats', 'skip the live resource probe (instant; names/addresses only)')
-        .option('--refresh', 'force a live probe of every device, bypassing the cache')
-        .option('--live', 'alias of --refresh (shorter to type)')
-        .option('-f, --full', 'full mode: add per-device core count and free/total memory')
-        .action(async (opts) => {
+    const runList = async (opts = {}) => {
         const reg = await loadDevices();
         const names = Object.keys(reg).sort();
         if (opts.json) {
@@ -629,7 +744,26 @@ Typical workflow:
         if (freshness?.servedFromCache && freshness.oldestFetchedAt != null) {
             console.log(chalk.gray(`  updated ${formatCheckedAge(freshness.oldestFetchedAt)} — pass --refresh (--live) for a live probe`));
         }
-    });
+        // Ephemeral crabbox leases live alongside the registered fleet but are never
+        // written into the registry — surface them as their own live section. This is
+        // a live provider call, so honor --no-stats (the explicit "instant, no probes"
+        // opt-out) and bound it so a slow provider can't hang `agents devices`.
+        if (opts.stats !== false) {
+            for (const line of loadLeasedBoxesSection())
+                console.log(line);
+        }
+    };
+    devicesCmd.action(runList);
+    devicesCmd
+        .command('list')
+        .alias('ls')
+        .description('List registered devices with platform, address, reachability, and live resource headroom.')
+        .option('--json', 'output the registry as a JSON array (for scripts and hooks)')
+        .option('--no-stats', 'skip the live resource probe (instant; names/addresses only)')
+        .option('--refresh', 'force a live probe of every device, bypassing the cache')
+        .option('--live', 'alias of --refresh (shorter to type)')
+        .option('-f, --full', 'full mode: add per-device core count and free/total memory')
+        .action(runList);
     devicesCmd
         .command('status')
         .description('Show fleet health: warnings rollup, per-device sync drift, CLI readiness, version skew, and resource headroom.')
@@ -648,8 +782,41 @@ Typical workflow:
         .option('--local', 'probe only this host (used internally for fan-out)')
         .option('--verbose', 'show a per-account breakdown, not just the per-host rollup')
         .option('--strict', 'exit non-zero when any account is revoked (expired is soft — it self-refreshes)')
+        .action(async (opts, cmd) => {
+        // The root program also defines a global `--verbose` (startup self-heal
+        // detail), and commander binds a shared long flag to the program, not the
+        // leaf — so `fleet ping --verbose` never set opts.verbose and the
+        // per-account breakdown was silently unreachable. Read the effective value
+        // from the merged globals so the flag works at either level.
+        const verbose = opts.verbose ?? Boolean(cmd.optsWithGlobals().verbose);
+        await runFleetPing({ ...opts, verbose });
+    });
+    devicesCmd
+        .command('login')
+        .description('Log agent CLIs into fleet boxes over SSH: drive each box\'s device-code OAuth, scrape the URL + code, and surface every pending login in one local browser page. Default drives all codes at once; --interactive walks one box at a time (codes requested just-in-time so they don\'t expire).')
+        .option('--agents <csv>', 'only these agents (comma-separated); default: every agent with a device-code flow')
+        .option('--devices <csv>', 'only these devices (comma-separated); default: every online box')
+        .option('--all', 'target every device-code pair regardless of cached login state (cold cache / forced re-login)')
+        .option('--interactive', 'guided one-box-at-a-time wizard (codes requested just-in-time)')
+        .option('--json', 'output the final result matrix as JSON')
         .action(async (opts) => {
-        await runFleetPing(opts);
+        const csv = (s) => (s ? s.split(',').map((x) => x.trim()).filter(Boolean) : undefined);
+        const results = await runFleetLogin({
+            agents: csv(opts.agents),
+            devices: csv(opts.devices),
+            all: opts.all,
+            interactive: opts.interactive,
+            json: opts.json,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(results, null, 2));
+        }
+        else {
+            for (const line of renderLoginMatrix(results))
+                console.log(line);
+        }
+        if (results.some((r) => r.remotable && r.state !== 'authorized'))
+            process.exitCode = 1;
     });
     devicesCmd
         .command('show <name>')
@@ -849,6 +1016,9 @@ secrets bundle via an askpass shim — the password never touches argv.
         // A bare unregistered alias still errors as "Unknown device".
         const device = resolveDeviceTarget(name, await loadDevices());
         if (!device) {
+            // Not a registered device — it may be a leased crabbox box slug. ssh into
+            // it directly (crabbox@<tailnet|ip>:2222) before giving up.
+            trySshLeasedBox(name, cmd); // exits the process on a match
             console.error(chalk.red(`Unknown device '${name}'. See 'agents devices list'.`));
             process.exit(1);
         }
@@ -907,7 +1077,7 @@ async function runAskpass() {
         process.exit(1);
     }
     try {
-        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh', agentOnly: isHeadlessSecretsContext() });
+        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh', keys: [key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
         const value = env[key];
         if (value === undefined) {
             console.error(`askpass: key '${key}' not found in bundle '${bundle}'`);

package/dist/commands/status.js

@@ -13,6 +13,7 @@ import { AGENTS } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
 import { computeSyncStatus } from '../lib/sync-status.js';
 import { promptDriftSync } from '../lib/drift-sync.js';
+import { resolveSurface } from './utils.js';
 const agentName = (id) => AGENTS[id]?.name ?? id;
 function versionSummary(v) {
     if (!v.everSynced)
@@ -46,9 +47,14 @@ export function registerStatusCommand(program) {
       agents status --yes
     `,
     });
-    cmd.action(async (opts) => {
+    cmd.action(async (opts, command) => {
+        // Centralized surface read (the human/agent split in one place). Note we still
+        // pass the *raw* `opts.yes` to promptDriftSync below — it distinguishes an
+        // explicit `--yes` (act) from a non-TTY shell (report only), so `surface.assumeYes`
+        // (which conflates the two) would wrongly auto-reconcile in a plain pipe.
+        const surface = resolveSurface(command);
         const cwd = opts.cwd ?? process.cwd();
-        if (opts.json) {
+        if (surface.json) {
             const status = await computeSyncStatus({ cwd });
             console.log(JSON.stringify(status, null, 2));
             return;

package/dist/commands/subagents.js

@@ -53,7 +53,7 @@ When to use:
   - Team sharing: distribute subagent definitions via GitHub repos
 `);
     // Shared list implementation, registered as `list` and hidden `view` alias.
-    const runList = async () => {
+    const runList = async (opts) => {
         const rows = buildSubagentRows();
         await showResourceList({
             resourcePlural: 'subagents',
@@ -62,12 +62,14 @@ When to use:
             rows,
             emptyMessage: 'No subagents in ~/.agents/subagents/. Add one with: agents subagents add gh:user/repo',
             centralPath: getSubagentsDir(),
+            json: opts?.json,
         });
     };
     // agents subagents list
     subagentsCmd
         .command('list')
         .description('Show subagents in a table with sync status across agent versions')
+        .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .addHelpText('after', `
 Examples:
   # Interactive picker (TTY) or sync-status table (piped)

package/dist/commands/sync.js

@@ -544,7 +544,7 @@ function runLaunchMode(agent, version, cwd, quiet) {
     if (result.rulesCompiled)
         bits.push('rules');
     if (result.workspaceLinks > 0)
-        bits.push(`${result.workspaceLinks} workspace link(s)`);
+        bits.push(`${result.workspaceLinks} project resource(s)`);
     const mpCount = Object.keys(result.marketplaces).length;
     if (mpCount > 0) {
         const pluginCount = Object.values(result.marketplaces).reduce((acc, names) => acc + names.length, 0);

package/dist/commands/teams.js

@@ -7,6 +7,8 @@ import { AgentManager, AgentStatus, checkCliSignedIn, collectTeamsDoctorData, ge
 import { mailboxDir, enqueue } from '../lib/mailbox.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { emit } from '../lib/events.js';
+import { maybeShowStarNudge } from '../lib/star-nudge.js';
+import { shareRuntimeEnv } from '../lib/share/config.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
 import { debug } from '../lib/teams/debug.js';
 import { runPrWatch, DEFAULT_MAX_WAVES, } from '../lib/teams/pr-watch.js';
@@ -49,8 +51,6 @@ const VALID_AGENTS = Object.keys(AGENT_NAMES);
 const VALID_MODES = ['plan', 'edit', 'auto', 'skip', 'full'];
 const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'auto'];
 const VALID_CLOUD_PROVIDERS = ['rush', 'codex', 'factory'];
-// Auto-enable JSON mode when piped / not a TTY so AI agent consumers get
-// parseable output by default.
 function statusColor(status) {
     switch (status) {
         case 'pending': return chalk.blue;
@@ -1352,6 +1352,7 @@ export function registerTeamsCommands(program) {
                     repo: opts.repo,
                     branch: opts.branch,
                     model: a.model ?? undefined,
+                    env: shareRuntimeEnv({ agentOnly: true }),
                 };
                 const cloudTask = await prov.dispatch(dispatchOpts);
                 return { cloudSessionId: cloudTask.id };
@@ -1369,6 +1370,7 @@ export function registerTeamsCommands(program) {
                 repo: opts.repo,
                 branch: opts.branch,
                 model: opts.model,
+                env: shareRuntimeEnv({ agentOnly: true }),
             };
             try {
                 const cloudTask = await prov.dispatch(dispatchOpts);
@@ -1594,6 +1596,13 @@ export function registerTeamsCommands(program) {
         emit('teams.complete', { module: 'teams', team, stoppedBy: result.stoppedBy, waves: result.waves, durationMs: result.elapsed_ms });
         if (result.stoppedBy === 'drained') {
             console.log(chalk.green(`Factory drained in ${elapsed}s (${result.waves} waves).`));
+            // First-successful-team star nudge (one-time, non-nagging). "drained"
+            // only means nothing is pending/running — teammates may have failed — so
+            // gate on a clean drain (failed === 0). A team where every teammate
+            // failed is not the success this nudge celebrates.
+            if ((result.failed ?? 0) === 0) {
+                maybeShowStarNudge({ quiet: opts.json });
+            }
         }
         else if (result.stoppedBy === 'max-waves') {
             console.error(chalk.yellow(`Hit --max-waves=${maxWaves}; stopping. Re-run to continue.`));

package/dist/commands/uninstall.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `agents uninstall` — completely remove agents-cli and restore the user's
+ * original agent configs. The reverse of `agents setup`.
+ *
+ * Thin command layer: the restore/teardown logic lives in `lib/uninstall.ts`
+ * (planUninstall / executeUninstall) so it can be tested against a real temp
+ * HOME without the CLI wrapper.
+ */
+import type { Command } from 'commander';
+/** Register `agents uninstall`. */
+export declare function registerUninstallCommands(program: Command): void;

package/dist/commands/uninstall.js

@@ -0,0 +1,158 @@
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { setHelpSections } from '../lib/help.js';
+import { planUninstall, executeUninstall } from '../lib/uninstall.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/** Render the read-only plan so the user sees exactly what will change. */
+function printPlan(plan, purge) {
+    const restores = plan.configs.filter((c) => c.kind === 'restore-backup' || c.kind === 'restore-version-home');
+    const dangling = plan.configs.filter((c) => c.kind === 'remove-dangling');
+    const untouched = plan.configs.filter((c) => c.kind === 'leave-real' || c.kind === 'leave-foreign');
+    console.log(chalk.bold('\nagents uninstall — planned changes\n'));
+    if (restores.length > 0) {
+        console.log(chalk.green('Restore your original config (adopted by agents-cli):'));
+        for (const c of restores) {
+            const how = c.kind === 'restore-backup' ? 'from backup' : 'from version home';
+            console.log(chalk.gray(`  ${c.realPath}  ${chalk.dim(`(${how})`)}`));
+        }
+    }
+    if (dangling.length > 0) {
+        console.log(chalk.yellow('Remove dangling symlink (no original found to restore):'));
+        for (const c of dangling)
+            console.log(chalk.gray(`  ${c.realPath}`));
+    }
+    if (untouched.length > 0) {
+        console.log(chalk.cyan('Left untouched (real, un-adopted configs — never modified):'));
+        for (const c of untouched)
+            console.log(chalk.gray(`  ${c.realPath}`));
+    }
+    if (plan.homeFiles.length > 0) {
+        console.log(chalk.green('Restore home files:'));
+        for (const hf of plan.homeFiles)
+            console.log(chalk.gray(`  ${hf.realPath}`));
+    }
+    if (plan.launchers.length > 0) {
+        console.log(chalk.green('Release adopted launchers (restore native binaries on PATH):'));
+        console.log(chalk.gray(`  ${plan.launchers.join(', ')}`));
+    }
+    if (plan.rcFiles.length > 0) {
+        console.log(chalk.green('Remove the shim directory from PATH in:'));
+        for (const rc of plan.rcFiles)
+            console.log(chalk.gray(`  ${rc}`));
+    }
+    console.log(chalk.bold('\nData:'));
+    if (purge) {
+        console.log(chalk.red(`  Permanently delete ${plan.agentsDir} (installed versions, session history, secrets metadata).`));
+        if (plan.legacySymlink)
+            console.log(chalk.red(`  Permanently delete ${plan.legacySymlink}.`));
+    }
+    else {
+        console.log(chalk.gray(`  Move ${plan.agentsDir} aside to ${plan.agentsDir}.removed-<timestamp> (recoverable).`));
+        if (plan.legacySymlink)
+            console.log(chalk.gray(`  Remove the legacy symlink ${plan.legacySymlink}.`));
+        console.log(chalk.gray('  Use --purge to hard-delete instead.'));
+    }
+    console.log();
+}
+/** Report what actually happened, then the final manual npm step. */
+function printResult(result, cleanedPath) {
+    for (const r of result.restoredConfigs)
+        console.log(chalk.green(`Restored ${r.realPath}`));
+    for (const r of result.removedDanglingConfigs)
+        console.log(chalk.yellow(`Removed dangling symlink ${r.realPath}`));
+    for (const f of result.restoredHomeFiles)
+        console.log(chalk.green(`Restored ${f}`));
+    if (result.releasedLaunchers.length > 0)
+        console.log(chalk.green(`Released launchers: ${result.releasedLaunchers.join(', ')}`));
+    for (const rc of result.cleanedRcFiles)
+        console.log(chalk.green(`Cleaned shim PATH entry from ${rc}`));
+    if (result.agentsDir.disposition === 'moved') {
+        console.log(chalk.gray(`Moved ${result.agentsDir.path} to ${result.agentsDir.movedTo}`));
+    }
+    else if (result.agentsDir.disposition === 'purged') {
+        console.log(chalk.gray(`Deleted ${result.agentsDir.path}`));
+    }
+    for (const e of result.errors)
+        console.log(chalk.red(`  ! ${e}`));
+    if (result.purgeDowngraded) {
+        console.log(chalk.yellow(`\n--purge was downgraded to move-aside because a restore step errored — ${result.agentsDir.path} was kept so nothing is lost. Resolve the errors above, then delete ${result.agentsDir.movedTo} manually.`));
+    }
+    console.log(chalk.bold('\nFinish by removing the CLI package:'));
+    console.log(chalk.gray('  npm uninstall -g @phnx-labs/agents-cli    # or: bun remove -g @phnx-labs/agents-cli'));
+    if (cleanedPath) {
+        console.log(chalk.gray('Open a new shell (or re-source your rc file) so the removed PATH entry takes effect.'));
+    }
+    if (result.agentsDir.disposition === 'moved') {
+        console.log(chalk.gray(`Your data is still at ${result.agentsDir.movedTo} — delete it once you are sure.`));
+    }
+}
+/** Register `agents uninstall`. */
+export function registerUninstallCommands(program) {
+    const cmd = program
+        .command('uninstall')
+        .description('Completely remove agents-cli and restore your original agent configs. Reverses `agents setup`.')
+        .option('--purge', 'Hard-delete ~/.agents (installed versions, sessions, secrets metadata) instead of moving it aside')
+        .option('--dry-run', 'Show exactly what would change without modifying anything')
+        .option('-y, --yes', 'Skip the confirmation prompt (required to run non-interactively)');
+    setHelpSections(cmd, {
+        examples: `
+      # Preview everything that would change, without touching anything
+      agents uninstall --dry-run
+
+      # Restore your configs and move ~/.agents aside (recoverable)
+      agents uninstall
+
+      # Same, but hard-delete ~/.agents (no recovery)
+      agents uninstall --purge
+    `,
+        notes: `
+      - Restores every ~/.<agent> that agents-cli adopted; a real config it never adopted is left untouched.
+      - Releases adopted launchers and strips the shim directory from your shell PATH.
+      - Without --purge, ~/.agents is moved to ~/.agents.removed-<timestamp> so nothing is lost.
+      - The CLI cannot delete its own running binary; it prints the final 'npm uninstall -g' step for you.
+    `,
+    });
+    cmd.action(async (options) => {
+        // We are tearing ~/.agents down. Silence the JSONL audit log for the rest
+        // of this process so a late emit() (its events path is memoized to the old
+        // location) can't re-create ~/.agents after we move it aside.
+        process.env.AGENTS_DISABLE_EVENT_LOG = '1';
+        const plan = planUninstall();
+        if (!plan.isInstalled) {
+            console.log(chalk.gray('agents-cli is not set up (no ~/.agents directory) — nothing to uninstall.'));
+            return;
+        }
+        printPlan(plan, !!options.purge);
+        if (options.dryRun) {
+            console.log(chalk.gray('Dry run — nothing was changed.'));
+            return;
+        }
+        if (!options.yes) {
+            if (!isInteractiveTerminal()) {
+                console.log(chalk.red('Refusing to uninstall non-interactively. Re-run with --yes to confirm.'));
+                return;
+            }
+            try {
+                const ok = await confirm({
+                    message: options.purge
+                        ? 'Permanently remove agents-cli and restore your original configs?'
+                        : 'Remove agents-cli (data moved to a recoverable directory) and restore your original configs?',
+                    default: false,
+                });
+                if (!ok) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+                throw err;
+            }
+        }
+        const result = executeUninstall(plan, { purge: options.purge, timestamp: Date.now() });
+        printResult(result, result.cleanedRcFiles.length > 0);
+    });
+}