@phnx-labs/agents-cli 1.20.71 → 1.20.72

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## 1.20.71
+## 1.20.72
+
+- **Stop `agents doctor` from reporting phantom drift and `agents prune` from
+  deleting source-managed resources.** Three reconciler false positives are
+  fixed: the instruction file (`CLAUDE.md`/`AGENTS.md`) is now compared against
+  the composed active-preset output the rules writer actually emits — not the raw
+  whole-repo `rules/AGENTS.md` — so a correctly-synced home no longer shows as
+  permanent drift; plugin-bundled commands installed as `<plugin>-<command>`
+  command-skills (e.g. `swarm-plan`, `code-review`) are no longer flagged as
+  orphans/extras that `prune cleanup` would delete; and command-as-skill wrappers
+  (the `agents_command` marker) are no longer miscounted as skills and surfaced as
+  deletable skill orphans. Source: `apps/cli/src/lib/staleness/`,
+  `apps/cli/src/lib/commands.ts`, `apps/cli/src/lib/skills.ts`.
 
 - **Capture your whole fleet into `agents.yaml`, then rebuild it anywhere with
   `agents apply` (#1305).** New `agents fleet capture` (alias `agents devices
@@ -20,6 +32,17 @@
 
 - **`agents fleet status` no longer hangs on a stale `~/.ssh/config`.** The fleet probes (version / doctor / `fleet ping`) now dial each device at its registry Tailscale address (`dnsName`/IP) instead of the bare host name — so a hand-written `Host <name>` block carrying a drifted LAN IP can no longer shadow the correct entry and make a reachable box look dead. It also fails fast: a device the stats probe already found unreachable is skipped straight to an unreachable row instead of eating a 15s+30s version+doctor timeout. Source: `apps/cli/src/commands/ssh.ts`.
 
+- **No more macOS keychain password prompt from an interactive command.** Writing a non-`agents-cli.` keychain item (e.g. a refreshed Claude OAuth token during `agents view`, or an `agents secrets add`) via `/usr/bin/security add-generic-password -w` piped the value over stdin — but `readpassphrase(3)` reads the *controlling terminal* when one exists, so in an interactive shell `security` prompted the user ("password data for new item:") and hung to the timeout, ignoring the piped value. The write now runs `detached` (a new session with no controlling terminal) so the piped stdin is always used. Verified under a pty. Source: `apps/cli/src/lib/secrets/index.ts`.
+
+- **`agents logs <id> --json` now reports the true final status of a host task.**
+  For a run that finished remotely between dispatch and the one-shot `--json`
+  read, the payload emitted a stale `status: "running"` with no `exitCode` — even
+  though the completed log was already present — because `hostTaskLogJson`
+  discarded the reconciled record `reconcileTask` returns (it heals a new object
+  rather than mutating in place). It now emits the reconciled task, so a polling
+  agent sees `completed`/`failed` + `exitCode` + `finishedAt`. Source:
+  `apps/cli/src/lib/hosts/logs.ts`.
+
 - **Fix the macOS menu-bar auto-heal so upgrades actually restart the helper.**
   `agents` has an on-startup self-heal that re-copies `MenubarHelper.app` when
   the CLI version changes, but on modern macOS `launchctl bootstrap` fails when
@@ -60,6 +83,8 @@
 
 - **`agents share` cover capture finds Playwright's `chrome-headless-shell` packages.** `scanCaches()` only knew the classic `chrome-mac/Chromium.app` and `Google Chrome for Testing` layouts, so on machines whose Playwright cache holds only the newer `chromium_headless_shell-*` packages (a raw `chrome-headless-shell` binary, not an `.app` bundle) — and no system Chrome/Brave/Edge — the OG cover capture silently returned null and shared plans published without a preview card. The scan now matches `chrome-headless-shell-mac-arm64`, `chrome-headless-shell-mac-x64`, and `chrome-headless-shell-linux64` layouts alongside the existing ones. Source: `apps/cli/src/lib/share/capture.ts`, `apps/cli/src/lib/share/capture.test.ts`.
 
+- **New `agents uninstall` — cleanly reverse adoption and restore your original setup.** Installing agents-cli *adopts* your agent config: it moves `~/.<agent>` aside and replaces it with a symlink into the version homes, adopts the launcher on `PATH`, and adds the shim dir to your shell rc — but until now nothing put any of that back, so removing the CLI stranded your original config under `~/.agents/.history/backups/` and left `~/.claude` a dangling symlink. `agents uninstall` is the reverse of `agents setup`: it restores every adopted `~/.<agent>` (from the timestamped backup, or the version home for imported installs), restores owned home files, releases adopted launchers, strips the shim dir from every shell rc, then disposes of `~/.agents` — moved aside to `~/.agents.removed-<ts>` (recoverable) by default, or hard-deleted with `--purge`. A config agents-cli never adopted is never touched (ownership is decided structurally by `getConfigSymlinkVersion`, the same check `removeVersion` uses); `--dry-run` prints the full plan without changing anything; and if any restore step errors, `--purge` self-downgrades to the recoverable move-aside so a swallowed error can never take your only copy. Works on macOS, Linux, and Windows (junctions and cross-volume `~/.agents` handled). Source: `apps/cli/src/lib/uninstall.ts`, `apps/cli/src/commands/uninstall.ts`.
+
 ## 1.20.70
 
 - **Fix `agents setup computer` / `agents computer setup` refusing to install a

package/dist/commands/commands.js

@@ -43,6 +43,7 @@ When to use:
 `);
     commandsCmd
         .command('list [agent]')
+        .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .description('Show which slash commands are installed and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
         .action(async (agentArg, options) => {
@@ -73,6 +74,7 @@ When to use:
             centralPath: getCommandsDir(),
             filterAgent,
             filterVersion,
+            json: options.json,
         });
     });
     commandsCmd

package/dist/commands/logs.js

@@ -23,9 +23,9 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
-import { parseAgentFilter, renderSessionLog } from './sessions.js';
+import { parseAgentFilter, renderSessionLog, renderSessionLogJson } from './sessions.js';
 import { streamSessionTail, isTailable } from './sessions-tail.js';
-import { showHostTaskLog } from '../lib/hosts/logs.js';
+import { showHostTaskLog, hostTaskLogJson } from '../lib/hosts/logs.js';
 import { listTasks } from '../lib/hosts/tasks.js';
 import { itemPicker } from '../lib/picker.js';
 import { query, stats, getLogsPath, rotate, levelFor, } from '../lib/events.js';
@@ -43,8 +43,20 @@ function candidateLabel(c) {
     const title = s.label || s.topic || '';
     return `${chalk.gray('sess')} ${s.shortId.padEnd(9)} ${(s.agent + ver).padEnd(14)} ${chalk.gray(s.timestamp.slice(0, 16))}  ${title.slice(0, 40)}`;
 }
+/** Emit a host-dispatch task's log as JSON: `{ kind, task, log }`. */
+function emitHostTaskJson(id) {
+    const hj = hostTaskLogJson(id);
+    if (!hj.found)
+        return false;
+    process.stdout.write(JSON.stringify({ kind: 'task', task: hj.task, log: hj.log ?? null }, null, 2) + '\n');
+    return true;
+}
 /** Show a resolved session — follow (tail), concise summary, or (`full`) transcript. */
-async function showSession(session, follow, full) {
+async function showSession(session, follow, full, json = false) {
+    if (json) {
+        await renderSessionLogJson(session);
+        return;
+    }
     if (follow) {
         if (!isTailable(session.agent)) {
             console.error(chalk.red(`Tailing is supported for claude and codex sessions only (got ${session.agent}).`));
@@ -55,17 +67,33 @@ async function showSession(session, follow, full) {
     }
     await renderSessionLog(session, full ? 'markdown' : 'summary');
 }
-async function showCandidate(c, follow, full) {
+async function showCandidate(c, follow, full, json = false) {
     if (c.kind === 'task') {
+        if (json) {
+            emitHostTaskJson(c.task.id);
+            return;
+        }
         const res = await showHostTaskLog(c.task.id, follow, full);
         if (res.exitCode !== undefined)
             process.exitCode = res.exitCode;
         return;
     }
-    await showSession(c.session, follow, full);
+    await showSession(c.session, follow, full, json);
 }
 /** Resolve an explicit id/--session: host task first, then a session. */
-async function showById(id, follow, full) {
+async function showById(id, follow, full, json = false) {
+    if (json) {
+        if (emitHostTaskJson(id))
+            return;
+        const sessions = await discoverSessions({ all: true, limit: 5000 });
+        const matches = resolveSessionById(sessions, id);
+        if (matches.length === 0) {
+            console.error(chalk.red(`No run or session found matching "${id}".`));
+            process.exit(1);
+        }
+        await renderSessionLogJson(matches[0]);
+        return;
+    }
     const hostRes = await showHostTaskLog(id, follow, full);
     if (hostRes.found) {
         if (hostRes.exitCode !== undefined)
@@ -85,7 +113,7 @@ async function runLogs(id, opts) {
     const full = !!opts.full;
     const directId = opts.session ?? id;
     if (directId) {
-        await showById(directId, follow, full);
+        await showById(directId, follow, full, !!opts.json);
         return;
     }
     const { agent, version } = parseAgentFilter(opts.agent);
@@ -110,7 +138,7 @@ async function runLogs(id, opts) {
         process.exit(1);
     }
     if (candidates.length === 1) {
-        await showCandidate(candidates[0], follow, full);
+        await showCandidate(candidates[0], follow, full, !!opts.json);
         return;
     }
     // Multiple sessions matched → picker if interactive, else a list to pick from.
@@ -134,7 +162,7 @@ async function runLogs(id, opts) {
     });
     if (!picked)
         return;
-    await showCandidate(picked.item, follow, full);
+    await showCandidate(picked.item, follow, full, !!opts.json);
 }
 function parseSince(s) {
     const m = s.match(/^(\d+)([smhdw])$/);
@@ -343,6 +371,7 @@ export function registerLogsCommand(program) {
         .option('--session <id>', 'Select a session/run by id (same as the positional id)')
         .option('-f, --follow', 'Follow live output')
         .option('-m, --full', 'Show the full raw transcript / stdout instead of the concise summary')
+        .option('--json', 'Machine-readable JSON: a host task as { kind, task, log }, a session as the redacted { session, events } (same shape as `sessions <id> --json`)')
         .action((id, opts) => runLogs(id, opts));
     logsCmd
         .command('audit')

package/dist/commands/mcp.js

@@ -147,6 +147,7 @@ When to use:
         .command('list [agent]')
         .description('Show which MCP servers are registered 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;
@@ -176,6 +177,7 @@ When to use:
             centralPath: getMcpDir(),
             filterAgent,
             filterVersion,
+            json: options.json,
         });
     });
     mcpCmd

package/dist/commands/resource-view.d.ts

@@ -33,6 +33,8 @@ export interface ResourceViewOptions {
     /** When the user specified agent or agent@version, we scope per-agent. */
     filterAgent?: AgentId;
     filterVersion?: string;
+    /** Emit machine-readable JSON instead of the picker/table (for agents/scripts). */
+    json?: boolean;
 }
 /** Display a resource list: interactive picker in TTY mode, plain table otherwise. */
 export declare function showResourceList(opts: ResourceViewOptions): Promise<void>;

package/dist/commands/resource-view.js

@@ -14,6 +14,14 @@ import { isInteractiveTerminal, isPromptCancelled, printWithPager } from './util
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
 /** Display a resource list: interactive picker in TTY mode, plain table otherwise. */
 export async function showResourceList(opts) {
+    if (opts.json) {
+        // Strip the non-serializable buildDetail thunk; emit the row metadata plus
+        // each resource's per-agent-version sync targets. One shared JSON contract
+        // for every resource `list` built on this helper.
+        const rows = opts.rows.map(({ buildDetail, ...row }) => row);
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
     if (opts.rows.length === 0) {
         console.log(chalk.gray(opts.emptyMessage));
         return;

package/dist/commands/sessions.d.ts

@@ -155,6 +155,12 @@ export declare function buildOverviewGroups(pool: SessionMeta[], perProjectCap:
  * (`agents logs <id> --full`). Reuses the shared `renderSession` renderer.
  */
 export declare function renderSessionLog(session: SessionMeta, mode?: ViewMode): Promise<void>;
+/**
+ * Emit one session exactly as `agents sessions <id> --json` does — the same
+ * redact-by-default `{ session, events }` shape — so `agents logs <id> --json`
+ * shares one machine-readable session contract instead of inventing another.
+ */
+export declare function renderSessionLogJson(session: SessionMeta): Promise<void>;
 /** Column-visibility flags for the picker row, computed once over the whole pool. */
 export interface PickerColumns {
     /** Render the machine column (only when the pool spans more than one machine). */

package/dist/commands/sessions.js

@@ -1422,6 +1422,14 @@ function resolveViewMode(options, filters) {
 export async function renderSessionLog(session, mode = 'summary') {
     await renderSession(session, mode, {});
 }
+/**
+ * Emit one session exactly as `agents sessions <id> --json` does — the same
+ * redact-by-default `{ session, events }` shape — so `agents logs <id> --json`
+ * shares one machine-readable session contract instead of inventing another.
+ */
+export async function renderSessionLogJson(session) {
+    await renderSession(session, 'json', {});
+}
 async function renderSession(session, mode, filters, options = {}) {
     // OpenCode stores sessions in SQLite; filePath is "db_path#session_id"
     const realPath = session.filePath.split('#')[0];

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/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/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);
+    });
+}

package/dist/commands/utils.d.ts

@@ -4,6 +4,7 @@
  * Small helpers used across multiple commands: prompt cancellation detection,
  * table formatting, spinner management, and platform-specific workarounds.
  */
+import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
 import { type InstalledAgentTargetResult, type VersionSelectionResult } from '../lib/versions.js';
 /**
@@ -22,6 +23,34 @@ export declare function isPromptCancelled(err: unknown): boolean;
  * True when stdin/stdout are attached to a real terminal.
  */
 export declare function isInteractiveTerminal(): boolean;
+/** The resolved I/O surface for one command invocation — the human/agent split. */
+export interface Surface {
+    /** Machine-readable output was requested (`--json`). */
+    json: boolean;
+    /** Skip confirmation prompts — explicit `--yes`/`-y`, or a non-interactive shell. */
+    assumeYes: boolean;
+    /** Suppress non-essential human chrome (`--quiet`). */
+    quiet: boolean;
+    /**
+     * Safe to show an interactive picker/prompt: a real terminal AND not asking for
+     * `--json` (a JSON consumer is a machine and never wants a picker).
+     */
+    interactive: boolean;
+}
+/**
+ * Compute a command's I/O surface once, in one place, instead of each command
+ * re-deriving the human-vs-agent split (and raw-sniffing `process.std*.isTTY`
+ * with inconsistent stream choices — the audit's R4). Reads the merged option
+ * set via `optsWithGlobals()`, so it sees the command's own flags and any
+ * inherited global ones, and folds in the terminal state:
+ *
+ *   - `assumeYes` = explicit `--yes` OR a non-interactive shell (no one to prompt).
+ *   - `interactive` = a real TTY AND not `--json`.
+ *
+ * Adopt incrementally: a command switches its ad-hoc `isTTY`/`options.yes` checks
+ * to a single `const s = resolveSurface(cmd)` without changing its flag surface.
+ */
+export declare function resolveSurface(cmd: Command): Surface;
 /**
  * Exit with a clean message when a picker would be required in a non-interactive shell.
  */

package/dist/commands/utils.js

@@ -45,6 +45,30 @@ export function isPromptCancelled(err) {
 export function isInteractiveTerminal() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+/**
+ * Compute a command's I/O surface once, in one place, instead of each command
+ * re-deriving the human-vs-agent split (and raw-sniffing `process.std*.isTTY`
+ * with inconsistent stream choices — the audit's R4). Reads the merged option
+ * set via `optsWithGlobals()`, so it sees the command's own flags and any
+ * inherited global ones, and folds in the terminal state:
+ *
+ *   - `assumeYes` = explicit `--yes` OR a non-interactive shell (no one to prompt).
+ *   - `interactive` = a real TTY AND not `--json`.
+ *
+ * Adopt incrementally: a command switches its ad-hoc `isTTY`/`options.yes` checks
+ * to a single `const s = resolveSurface(cmd)` without changing its flag surface.
+ */
+export function resolveSurface(cmd) {
+    const opts = cmd.optsWithGlobals();
+    const tty = isInteractiveTerminal();
+    const json = opts.json === true;
+    return {
+        json,
+        assumeYes: opts.yes === true || !tty,
+        quiet: opts.quiet === true,
+        interactive: tty && !json,
+    };
+}
 /**
  * Exit with a clean message when a picker would be required in a non-interactive shell.
  */