@phnx-labs/agents-cli 1.20.71 → 1.20.72

package/dist/commands/versions.js

@@ -8,9 +8,9 @@ import { AGENTS, ALL_AGENT_IDS, accountOrgBadge, getAccountEmail, getAccountInfo
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
-import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, isOldestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
+import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, isOldestInstalled, getGlobalDefault, setGlobalDefault, markVersionIsolated, isVersionIsolated, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
 import { carryForwardSettings } from '../lib/settings-manifest.js';
-import { createShim, createVersionedAlias, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
+import { createShim, createVersionedAlias, supportsIsolatedInstall, CONFIG_ENV_ISOLATED_AGENTS, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { tryAutoPull } from '../lib/git.js';
 import { getAgentsDir, getTrashVersionsDir } from '../lib/state.js';
@@ -98,8 +98,30 @@ function warnIfShimShadowed(agent) {
     console.log(chalk.green(`  Added shim directory to ${result.location}.`));
     console.log(chalk.gray(`  ${result.reloadHint}`));
 }
+/**
+ * Install an isolated copy of an agent version: a fully self-contained install
+ * that never touches the user's existing setup.
+ *
+ * Unlike a normal install it does NOT set (or offer to set) the global default,
+ * does NOT create/replace the bare `<agent>` shim, does NOT back up or symlink
+ * the user's real `~/.<agent>`, and does NOT carry over settings or resources.
+ * It only creates the versioned alias (so the copy is launchable) and records
+ * the isolated marker. Invoke the copy explicitly with `agents run <agent>@<v>`.
+ */
+function finalizeIsolatedInstall(agent, version) {
+    const agentConfig = AGENTS[agent];
+    const label = agentLabel(agentConfig.id);
+    createVersionedAlias(agent, version);
+    markVersionIsolated(agent, version);
+    console.log(chalk.green(`  Installed ${label}@${version} as an isolated copy.`));
+    console.log(chalk.gray(`  Your existing ${agentConfig.configDir} and default ${label} are untouched.`));
+    console.log(chalk.gray(`  Run it:     agents run ${agent}@${version} "your prompt"`));
+    console.log(chalk.gray(`  It has its own config and login — sign in the first time you run it.`));
+    console.log(chalk.gray(`  Remove it:  agents remove ${agent}@${version} --isolated`));
+}
 async function versionPruneAction(specs, options, commandName) {
     const isProject = options.project;
+    const isIsolated = options.isolated;
     const moved = [];
     for (const spec of specs) {
         const parsed = parseAgentSpec(spec);
@@ -110,6 +132,12 @@ async function versionPruneAction(specs, options, commandName) {
         }
         const { agent, version } = parsed;
         const agentConfig = AGENTS[agent];
+        // --isolated only ever applies to agents that can BE installed isolated;
+        // for the rest no isolated version can exist, so say so plainly.
+        if (isIsolated && !supportsIsolatedInstall(agent)) {
+            console.log(chalk.gray(`${agentLabel(agentConfig.id)} has no isolated installs (--isolated is not supported for it).`));
+            continue;
+        }
         // Script-installed agents (droid, grok) can have a *literal* `latest`
         // version dir on disk when the post-install version probe failed. An
         // explicit `<agent>@latest` should remove that dir directly rather than
@@ -117,9 +145,14 @@ async function versionPruneAction(specs, options, commandName) {
         // so treat an installed literal `latest` as a concrete pinned version.
         const isLiteralLatestInstalled = version === 'latest' && spec.includes('@') && isVersionInstalled(agent, 'latest');
         if (!isLiteralLatestInstalled && (version === 'latest' || version === 'oldest' || !spec.includes('@'))) {
-            const versions = listInstalledVersions(agent);
+            // With --isolated, only isolated installs are eligible for the picker, so
+            // a normal/default install can never be selected here by accident.
+            const versions = listInstalledVersions(agent)
+                .filter((v) => !isIsolated || isVersionIsolated(agent, v));
             if (versions.length === 0) {
-                console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));
+                console.log(chalk.gray(isIsolated
+                    ? `No isolated ${agentLabel(agentConfig.id)} installs`
+                    : `No versions of ${agentLabel(agentConfig.id)} installed`));
                 continue;
             }
             if (!isInteractiveTerminal()) {
@@ -157,6 +190,9 @@ async function versionPruneAction(specs, options, commandName) {
                     }
                     fixSessionFilePaths(agent, v, versionDir);
                     console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${v} to trash`));
+                    if (isIsolated) {
+                        console.log(chalk.gray(`  Your real ${agentConfig.configDir} and default ${agentLabel(agentConfig.id)} were untouched.`));
+                    }
                     moved.push({ agent, version: v });
                 }
                 // Default reassignment/clearing is handled at the source in
@@ -177,6 +213,13 @@ async function versionPruneAction(specs, options, commandName) {
         else if (!isVersionInstalled(agent, version)) {
             console.log(chalk.gray(`${agentLabel(agentConfig.id)}@${version} not installed`));
         }
+        else if (isIsolated && !isVersionIsolated(agent, version)) {
+            // Safety guard: `--isolated` refuses to remove a normal/default install,
+            // so an accidental `remove <agent>@<default> --isolated` can never delete
+            // the user's primary version or disturb their real ~/.<agent>.
+            console.log(chalk.yellow(`${agentLabel(agentConfig.id)}@${version} is not an isolated install; refusing to remove it under --isolated.`));
+            console.log(chalk.gray(`  Drop --isolated to remove a normal version: agents ${commandName} ${agent}@${version}`));
+        }
         else {
             const versionDir = getVersionDir(agent, version);
             const removed = removeVersion(agent, version);
@@ -186,6 +229,9 @@ async function versionPruneAction(specs, options, commandName) {
             }
             fixSessionFilePaths(agent, version, versionDir);
             console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${version} to trash`));
+            if (isIsolated) {
+                console.log(chalk.gray(`  Your real ${agentConfig.configDir} and default ${agentLabel(agentConfig.id)} were untouched.`));
+            }
             moved.push({ agent, version });
             const remaining = listInstalledVersions(agent);
             if (remaining.length === 0) {
@@ -212,7 +258,8 @@ function configureVersionPruneCommand(cmd, commandName) {
         .description(isAlias
         ? 'Alias for agents prune. Uninstalls agent CLI versions.'
         : 'Uninstall agent CLI versions. Moves version data to trash for recovery.')
-        .option('-p, --project', 'Also clear the pinned version from .agents/agents.yaml in the current project');
+        .option('-p, --project', 'Also clear the pinned version from .agents/agents.yaml in the current project')
+        .option('--isolated', 'Only act on isolated installs (created with `agents add --isolated`). Refuses to remove a normal/default install and never touches your real ~/.<agent>.');
     setHelpSections(cmd, {
         examples: `
       # Prune a specific version
@@ -223,11 +270,15 @@ function configureVersionPruneCommand(cmd, commandName) {
 
       # Prune and also clear the project pin
       agents ${commandName} claude@2.0.50 --project
+
+      # Cleanly remove an isolated copy, leaving your normal install alone
+      agents ${commandName} claude@2.1.112 --isolated
     `,
         notes: `
       - Pruned version directories move to trash with their home/ data intact.
       - Session file paths are rewritten so session history remains readable.
       - Removing the default version unsets the default; run 'agents use' to pick a new one.
+      - --isolated restricts the operation to isolated installs and refuses to remove a normal/default version, so your existing setup is never disturbed.
       - Reinstall any time with 'agents add'.
     `,
     });
@@ -239,6 +290,7 @@ export function registerVersionsCommands(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 project-root agents.yaml')
+        .option('--isolated', 'Install a fully self-contained copy that never touches your existing ~/.<agent> or default. Launch it explicitly with `agents run <agent>@<version>`. Cannot be combined with --project.')
         .option('-y, --yes', 'Auto-accept defaults without prompting (useful for scripts and CI)');
     setHelpSections(addCmd, {
         examples: `
@@ -256,16 +308,26 @@ export function registerVersionsCommands(program) {
 
       # Lock a version to this project only (won't affect global default)
       agents add claude@2.1.100 --project
+
+      # Install a clean, separate copy that leaves your existing setup alone
+      agents add claude@2.1.112 --isolated
     `,
         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.
+      - --isolated installs a self-contained copy: it never sets the default, never creates the bare '<agent>' shim, and never backs up or symlinks your real ~/.<agent>. Run it with 'agents run <agent>@<version>' and remove it with 'agents remove <agent>@<version> --isolated'. Mutually exclusive with --project.
     `,
     });
     addCmd.action(async (specs, options) => {
         const isProject = options.project;
+        const isIsolated = options.isolated;
         const skipPrompts = options.yes || !isInteractiveTerminal();
+        if (isIsolated && isProject) {
+            console.log(chalk.red('--isolated and --project cannot be combined.'));
+            console.log(chalk.gray('An isolated copy is global-but-separate; a project pin selects a shared install for one directory.'));
+            return;
+        }
         for (const spec of specs) {
             const parsed = parseAgentSpec(spec);
             if (!parsed) {
@@ -276,6 +338,16 @@ export function registerVersionsCommands(program) {
             const { agent, version } = parsed;
             const agentConfig = AGENTS[agent];
             warnAgentDeprecated(agent);
+            // Isolation relies on a config-dir env var to redirect the copy away
+            // from the user's real ~/.<agent>. Agents without one isolate only by
+            // adopting ~/.<agent> (which --isolated skips), so an isolated copy
+            // would silently read/write the real config. Refuse rather than lie.
+            if (isIsolated && !supportsIsolatedInstall(agent)) {
+                console.log(chalk.red(`${agentLabel(agentConfig.id)} does not support --isolated installs.`));
+                console.log(chalk.gray(`  It has no config-directory env var, so it can only isolate by adopting ${agentConfig.configDir} — which --isolated deliberately avoids.`));
+                console.log(chalk.gray(`  Supported with --isolated: ${CONFIG_ENV_ISOLATED_AGENTS.join(', ')}.`));
+                continue;
+            }
             if (!agentConfig.npmPackage && !agentConfig.installScript) {
                 console.log(chalk.yellow(`${agentLabel(agentConfig.id)} has no npm package. Install manually.`));
                 continue;
@@ -301,6 +373,19 @@ export function registerVersionsCommands(program) {
                 alreadyInstalled = isVersionInstalled(agent, version);
             }
             if (alreadyInstalled) {
+                if (isIsolated) {
+                    if (!isVersionIsolated(agent, installedAsVersion)) {
+                        // A normal and an isolated install of the SAME version share one
+                        // on-disk dir, so they can't coexist. Refuse rather than silently
+                        // convert the user's existing (possibly default) install.
+                        console.log(chalk.yellow(`${agentLabel(agentConfig.id)}@${installedAsVersion} is already installed as a normal (default-eligible) version.`));
+                        console.log(chalk.gray(`  Remove it first (agents remove ${agent}@${installedAsVersion}) then re-add with --isolated, or pick a different version.`));
+                        continue;
+                    }
+                    // Already isolated: re-affirm the alias + marker idempotently.
+                    finalizeIsolatedInstall(agent, installedAsVersion);
+                    continue;
+                }
                 console.log(chalk.gray(`${agentLabel(agentConfig.id)}@${installedAsVersion} already installed`));
                 // Ensure shim exists (in case it was deleted or needs updating)
                 createShim(agent);
@@ -312,15 +397,23 @@ export function registerVersionsCommands(program) {
                 });
                 if (result.success) {
                     spinner.succeed(`Installed ${agentLabel(agentConfig.id)}@${result.installedVersion}`);
+                    const installedVersion = result.installedVersion || version;
+                    // Track the concrete version so a `--project` pin records it instead
+                    // of the `latest`/`oldest` alias.
+                    installedAsVersion = installedVersion;
+                    // Isolated installs stop here: no bare shim, no settings carry-over,
+                    // no resource sync, no default switch, no PATH edits. Just a
+                    // launchable versioned alias + the isolated marker, leaving the
+                    // user's real ~/.<agent> and default untouched.
+                    if (isIsolated) {
+                        finalizeIsolatedInstall(agent, installedVersion);
+                        continue;
+                    }
                     // Create shim if first install
                     if (!shimExists(agent)) {
                         createShim(agent);
                         console.log(chalk.gray(`  Created shim: ${getShimsDir()}/${agentConfig.cliCommand}`));
                     }
-                    const installedVersion = result.installedVersion || version;
-                    // Track the concrete version so a `--project` pin records it instead
-                    // of the `latest`/`oldest` alias.
-                    installedAsVersion = installedVersion;
                     // Seed the fresh version home with user settings from the current
                     // default version (settings.json, keybindings, codex config/auth).
                     // Gap-filling only — never overwrites what the new home has.
@@ -540,8 +633,11 @@ export function registerVersionsCommands(program) {
             const agentConfig = AGENTS[agentId];
             let selectedVersion = version;
             if (!version) {
-                // Interactive version picker
-                const versions = listInstalledVersions(agentId);
+                // Interactive version picker. Isolated installs are walled off from the
+                // real ~/.<agent> on purpose, so they must never be selectable here —
+                // setting one as the default would repoint the real config at it. Filter
+                // them out (same as the `remove` picker), leaving only usable versions.
+                const versions = listInstalledVersions(agentId).filter((v) => !isVersionIsolated(agentId, v));
                 if (versions.length === 0) {
                     console.log(chalk.red(`No versions of ${agentLabel(agentConfig.id)} installed`));
                     console.log(chalk.gray(`Run: agents add ${agentId}@latest`));
@@ -602,6 +698,19 @@ export function registerVersionsCommands(program) {
             }
             // selectedVersion is guaranteed to be defined after the check above
             const finalVersion = selectedVersion;
+            // An isolated install is deliberately walled off from the real
+            // ~/.<agent>. `agents use` would repoint the real config symlink at it
+            // (switchConfigSymlink) and carry settings forward INTO it
+            // (carryForwardSettings) — a direct breach of the isolation guarantee.
+            // Refuse for both the explicit `use <agent>@<isolated>` path (the picker
+            // above already filters isolated versions out of the interactive path).
+            // Isolated copies are launched explicitly via `agents run <agent>@<v>`.
+            if (isVersionIsolated(agentId, finalVersion)) {
+                console.log(chalk.red(`${agentLabel(agentConfig.id)}@${finalVersion} is an isolated install and can't be set as your active version.`));
+                console.log(chalk.gray(`Isolated copies stay walled off from your real ${agentConfig.configDir}. Run it directly: agents run ${agentId}@${finalVersion}`));
+                console.log(chalk.gray(`To install this version normally: agents add ${agentId}@${finalVersion}`));
+                return;
+            }
             if (options.project) {
                 // Set in project manifest
                 const projectManifestDir = path.join(process.cwd(), '.agents');

package/dist/index.js

@@ -50,7 +50,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadShare, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -738,6 +738,7 @@ async function registerAllEagerCommands() {
     await reg(loadPush);
     await reg(loadRepo);
     await reg(loadSetup);
+    await reg(loadUninstall);
 }
 /** Calculate the Levenshtein edit distance between two strings. */
 function levenshtein(a, b) {
@@ -865,8 +866,9 @@ if (firstRun) {
     process.exit(0);
 }
 // Every command requires the system repo to be cloned first. `setup` is the
-// only exemption — it's the command that does the cloning.
-const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help']);
+// command that does the cloning; `uninstall` is its reverse and must run even
+// from a broken/half-setup state (that is exactly when you want to tear down).
+const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help', 'uninstall']);
 // Fold legacy ~/.agents-system/ into ~/.agents/.system/ BEFORE ensureInitialized
 // runs. ensureInitialized checks for .git inside the new path; if the user is
 // upgrading from a layout where .git lives under the legacy path, the check

package/dist/lib/daemon.d.ts

@@ -7,6 +7,15 @@
  * log output, reload (SIGHUP), and graceful shutdown are handled here.
  */
 import { getAgentsBinPath } from './cli-entry.js';
+/**
+ * RUSH-1817: decide whether the daemon should (re)take over hosting the secrets
+ * broker. The startup host decision is one-shot; this drives the periodic
+ * self-heal re-check. Take over ONLY when the daemon is not already hosting AND
+ * no healthy broker answers a ping — i.e. a standalone the daemon deferred to at
+ * start has since died or crash-looped. Never take over while our in-process
+ * broker is hosting, and never clobber a reachable (healthy) broker.
+ */
+export declare function shouldTakeOverBroker(isHosting: boolean, brokerReachable: boolean): boolean;
 /** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export declare function readDaemonPid(): number | null;
 /** Write the daemon PID to the pid file. */

package/dist/lib/daemon.js

@@ -38,6 +38,17 @@ const WEDGE_THRESHOLD_TICKS = 3;
 // session (which expires between runs and produces intermittent 401s).
 const DAEMON_OAUTH_BUNDLE = 'claude';
 const DAEMON_OAUTH_KEY = 'CLAUDE_CODE_OAUTH_TOKEN';
+/**
+ * RUSH-1817: decide whether the daemon should (re)take over hosting the secrets
+ * broker. The startup host decision is one-shot; this drives the periodic
+ * self-heal re-check. Take over ONLY when the daemon is not already hosting AND
+ * no healthy broker answers a ping — i.e. a standalone the daemon deferred to at
+ * start has since died or crash-looped. Never take over while our in-process
+ * broker is hosting, and never clobber a reachable (healthy) broker.
+ */
+export function shouldTakeOverBroker(isHosting, brokerReachable) {
+    return !isHosting && !brokerReachable;
+}
 function getDaemonDir() {
     const dir = getDaemonDirRoot();
     fs.mkdirSync(dir, { recursive: true });
@@ -661,6 +672,37 @@ export async function runDaemon() {
     };
     const fleetCacheInterval = setInterval(() => { void runFleetCacheWarm(); }, 3 * 60_000);
     const fleetCacheKickoff = setTimeout(() => { void runFleetCacheWarm(); }, 60_000);
+    // RUSH-1817: the startup host decision above is one-shot. If a standalone
+    // broker answered agentPing() at daemon start, the daemon declined to host —
+    // but should that standalone later die or crash-loop, nothing takes over and
+    // every `agents secrets unlock|export|start` fails until a manual restart
+    // (this wedged all keychain-backed secrets on zion and blocked a release).
+    // Re-probe on a cadence: whenever the daemon is NOT itself hosting AND no
+    // healthy broker answers a ping, take over hosting. startHostedBroker binds
+    // the socket only when it is free, so a take-over never races a live broker.
+    let selfHealingBroker = false;
+    const runBrokerSelfHeal = async () => {
+        if (selfHealingBroker)
+            return;
+        selfHealingBroker = true;
+        try {
+            const { agentPing, startHostedBroker } = await import('./secrets/agent.js');
+            const reachable = (await agentPing()).reachable;
+            if (!shouldTakeOverBroker(hostedBroker != null, reachable))
+                return;
+            hostedBroker = await startHostedBroker();
+            if (hostedBroker) {
+                log('WARN', 'Secrets broker was unreachable; daemon took over hosting (self-heal)');
+            }
+        }
+        catch (err) {
+            log('WARN', `Secrets broker self-heal skipped: ${err.message}`);
+        }
+        finally {
+            selfHealingBroker = false;
+        }
+    };
+    const brokerSelfHealInterval = setInterval(() => { void runBrokerSelfHeal(); }, 60_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -695,6 +737,7 @@ export async function runDaemon() {
         clearTimeout(launchHealthKickoff);
         clearInterval(fleetCacheInterval);
         clearTimeout(fleetCacheKickoff);
+        clearInterval(brokerSelfHealInterval);
         hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();

package/dist/lib/hosts/logs.d.ts

@@ -10,6 +10,7 @@
  * runs to be discoverable there first; until then the bounded tail is the safe
  * concise default.) Kept in one place so the two commands can never drift.
  */
+import { type HostTask } from './tasks.js';
 export interface HostLogResult {
     /** False when no host task with this id exists (caller may fall through to sessions). */
     found: boolean;
@@ -21,5 +22,16 @@ export interface HostLogResult {
  * default; `full` dumps the entire raw combined-stdout log.
  */
 export declare function showHostTaskLog(id: string, follow: boolean, full?: boolean): Promise<HostLogResult>;
+/**
+ * Machine-readable form of a host-dispatch task's log — the task record plus its
+ * combined stdout. Powers `agents logs <id> --json` for the host-task branch.
+ * Reconciles a still-'running' record from the remote `.exit` first, like the
+ * text path does.
+ */
+export declare function hostTaskLogJson(id: string): {
+    found: boolean;
+    task?: HostTask;
+    log?: string | null;
+};
 /** Last `n` lines of `text`, prefixed with an elision note when truncated. */
 export declare function tailLines(text: string, n: number): string;

package/dist/lib/hosts/logs.js

@@ -54,6 +54,24 @@ export async function showHostTaskLog(id, follow, full = false) {
     process.stdout.write(full ? raw : tailLines(raw, HOST_LOG_TAIL_LINES));
     return { found: true, exitCode: 0 };
 }
+/**
+ * Machine-readable form of a host-dispatch task's log — the task record plus its
+ * combined stdout. Powers `agents logs <id> --json` for the host-task branch.
+ * Reconciles a still-'running' record from the remote `.exit` first, like the
+ * text path does.
+ */
+export function hostTaskLogJson(id) {
+    const task = loadTask(id);
+    if (!task)
+        return { found: false };
+    // reconcileTask returns the healed record; it does NOT mutate its argument in
+    // place. Emit the reconciled task so a run that finished between dispatch and
+    // this one-shot read surfaces its terminal status/exitCode, not a stale
+    // 'running'. (The text path can discard the return — it only reads the log by
+    // id — but this JSON payload carries task.status straight to the consumer.)
+    const reconciled = reconcileTask(task);
+    return { found: true, task: reconciled, log: readTaskLog(reconciled) };
+}
 /** Read the task's combined-stdout — local mirror first, else fetch+cache remote. */
 function readTaskLog(task) {
     try {

package/dist/lib/shims.d.ts

@@ -153,6 +153,27 @@ export declare function removeShim(agent: AgentId): boolean;
  *        self-update under the shim).
  */
 export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 13;
+/**
+ * Agents whose config directory can be relocated by an environment variable
+ * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).
+ *
+ * Only these can be installed with `agents add --isolated`: the versioned alias
+ * points that env var at the copy's private home, so the copy never reads or
+ * writes the user's real `~/.<agent>`. Every other agent isolates ONLY by
+ * adopting `~/.<agent>` via a symlink — which an isolated install deliberately
+ * skips — so an isolated copy would silently fall back to (and mutate) the real
+ * config dir. For those agents `--isolated` is refused up front.
+ *
+ * KEEP IN SYNC with the `managedEnv` switch in `generateVersionedAliasScript`.
+ * The colocated test `shims.isolation-capability.test.ts` enforces this.
+ */
+export declare const CONFIG_ENV_ISOLATED_AGENTS: readonly AgentId[];
+/**
+ * Whether an agent supports a clean `--isolated` install — i.e. its config
+ * location can be redirected by an env var so the isolated copy stays fully
+ * separate from the user's real `~/.<agent>`. See {@link CONFIG_ENV_ISOLATED_AGENTS}.
+ */
+export declare function supportsIsolatedInstall(agent: AgentId): boolean;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -209,6 +230,11 @@ export declare function removeVersionedAlias(agent: AgentId, version: string): b
  * Check if a versioned alias exists (the on-disk artifact for this platform).
  */
 export declare function versionedAliasExists(agent: AgentId, version: string): boolean;
+/**
+ * Get the path to the agent's config directory in HOME.
+ * e.g., ~/.claude for claude, ~/.codex for codex
+ */
+export declare function getAgentConfigPath(agent: AgentId): string;
 /**
  * Read the user's configured Codex model from their active `~/.codex/config.toml`.
  *
@@ -449,6 +475,7 @@ export declare function hasAliasShadowingShim(agent: AgentId, overrides?: {
  * Check if shims directory is in PATH.
  */
 export declare function isShimsInPath(): boolean;
+export declare function stripShimPathLines(content: string, shimsDir: string): string;
 /**
  * Get shell configuration instructions for adding shims to PATH.
  */

package/dist/lib/shims.js

@@ -785,6 +785,29 @@ function assertSafeVersion(version) {
         throw new Error(`Refusing to generate shim for unsafe version: ${JSON.stringify(version)}`);
     }
 }
+/**
+ * Agents whose config directory can be relocated by an environment variable
+ * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).
+ *
+ * Only these can be installed with `agents add --isolated`: the versioned alias
+ * points that env var at the copy's private home, so the copy never reads or
+ * writes the user's real `~/.<agent>`. Every other agent isolates ONLY by
+ * adopting `~/.<agent>` via a symlink — which an isolated install deliberately
+ * skips — so an isolated copy would silently fall back to (and mutate) the real
+ * config dir. For those agents `--isolated` is refused up front.
+ *
+ * KEEP IN SYNC with the `managedEnv` switch in `generateVersionedAliasScript`.
+ * The colocated test `shims.isolation-capability.test.ts` enforces this.
+ */
+export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi'];
+/**
+ * Whether an agent supports a clean `--isolated` install — i.e. its config
+ * location can be redirected by an env var so the isolated copy stays fully
+ * separate from the user's real `~/.<agent>`. See {@link CONFIG_ENV_ISOLATED_AGENTS}.
+ */
+export function supportsIsolatedInstall(agent) {
+    return CONFIG_ENV_ISOLATED_AGENTS.includes(agent);
+}
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -1039,7 +1062,7 @@ export function versionedAliasExists(agent, version) {
  * Get the path to the agent's config directory in HOME.
  * e.g., ~/.claude for claude, ~/.codex for codex
  */
-function getAgentConfigPath(agent) {
+export function getAgentConfigPath(agent) {
     const agentConfig = AGENTS[agent];
     const home = process.env.AGENTS_REAL_HOME || os.homedir();
     return agentConfig.configDir.replace(os.homedir(), home);
@@ -1567,7 +1590,10 @@ export function getConfigSymlinkVersion(agent) {
         if (!stat.isSymbolicLink()) {
             return null;
         }
-        const target = fs.readlinkSync(configPath);
+        // Normalize separators so this matches on Windows too — readlinkSync there
+        // returns backslash paths, which the forward-slash-only regex never matched
+        // (misclassifying an owned symlink as foreign, e.g. in `agents uninstall`).
+        const target = fs.readlinkSync(configPath).replace(/\\/g, '/');
         // Extract version from path like ~/.agents/versions/claude/2.0.65/home/.claude
         const match = target.match(/versions\/[^/]+\/([^/]+)\/home/);
         return match ? match[1] : null;
@@ -2194,7 +2220,7 @@ function isShimPathCommandLine(line, shimsDir) {
     }
     return trimmed.startsWith('export PATH=') || trimmed.startsWith('fish_add_path ');
 }
-function stripShimPathLines(content, shimsDir) {
+export function stripShimPathLines(content, shimsDir) {
     const lines = content.split('\n');
     const kept = [];
     for (let i = 0; i < lines.length; i++) {

package/dist/lib/startup/command-registry.d.ts

@@ -85,6 +85,7 @@ export declare const loadPull: ModuleLoader;
 export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;
 export declare const loadSetup: ModuleLoader;
+export declare const loadUninstall: ModuleLoader;
 export declare const loadSessions: ModuleLoader;
 export declare const loadTeams: ModuleLoader;
 export declare const loadCloud: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -63,6 +63,7 @@ export const loadPull = async () => (await import('../../commands/pull.js')).reg
 export const loadPush = async () => (await import('../../commands/push.js')).registerPushCommand;
 export const loadRepo = async () => (await import('../../commands/repo.js')).registerRepoCommands;
 export const loadSetup = async () => (await import('../../commands/setup.js')).registerSetupCommand;
+export const loadUninstall = async () => (await import('../../commands/uninstall.js')).registerUninstallCommands;
 export const loadSessions = async () => (await import('../../commands/sessions.js')).registerSessionsCommands;
 export const loadTeams = async () => (await import('../../commands/teams.js')).registerTeamsCommands;
 export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
@@ -174,6 +175,7 @@ export const COMMAND_LOADERS = {
     repos: [loadRepo],
     repo: [loadRepo],
     setup: [loadSetup],
+    uninstall: [loadUninstall],
     sessions: [loadSessions],
     teams: [loadTeams],
     cloud: [loadCloud],

package/dist/lib/uninstall.d.ts

@@ -0,0 +1,84 @@
+import type { AgentId } from './types.js';
+/** What the uninstall intends to do with one agent's config directory. */
+export type ConfigAction = {
+    agent: AgentId;
+    realPath: string;
+    kind: 'restore-backup';
+    source: string;
+} | {
+    agent: AgentId;
+    realPath: string;
+    kind: 'restore-version-home';
+    source: string;
+} | {
+    agent: AgentId;
+    realPath: string;
+    kind: 'remove-dangling';
+} | {
+    agent: AgentId;
+    realPath: string;
+    kind: 'leave-real';
+} | {
+    agent: AgentId;
+    realPath: string;
+    kind: 'leave-foreign';
+} | {
+    agent: AgentId;
+    realPath: string;
+    kind: 'absent';
+};
+/** A home-level file symlink (e.g. `~/.claude.json`) agents-cli owns. */
+export interface HomeFileAction {
+    realPath: string;
+    /** Resolved symlink target whose contents are copied back to `realPath`. */
+    source: string;
+}
+/** The full, read-only plan describing what an uninstall would change. */
+export interface UninstallPlan {
+    isInstalled: boolean;
+    agentsDir: string;
+    legacySymlink: string | null;
+    configs: ConfigAction[];
+    homeFiles: HomeFileAction[];
+    launchers: string[];
+    rcFiles: string[];
+}
+/** Structured result of an executed uninstall (for reporting). */
+export interface UninstallResult {
+    restoredConfigs: Array<{
+        agent: AgentId;
+        realPath: string;
+    }>;
+    removedDanglingConfigs: Array<{
+        agent: AgentId;
+        realPath: string;
+    }>;
+    restoredHomeFiles: string[];
+    releasedLaunchers: string[];
+    cleanedRcFiles: string[];
+    agentsDir: {
+        path: string;
+        disposition: 'moved' | 'purged' | 'absent';
+        movedTo?: string;
+    };
+    legacySymlinkRemoved: boolean;
+    /** True when `--purge` was requested but downgraded to move-aside after errors. */
+    purgeDowngraded: boolean;
+    errors: string[];
+}
+/**
+ * Build a read-only plan of everything a complete uninstall would change.
+ * Performs no mutations; safe to run for `--dry-run` and to print for confirm.
+ */
+export declare function planUninstall(): UninstallPlan;
+/**
+ * Execute a plan built by {@link planUninstall}. Restores adopted config dirs
+ * and home files, releases adopted launchers, strips shim PATH lines, then
+ * disposes of `~/.agents` — moved aside to `~/.agents.removed-<ts>` (recoverable)
+ * by default, or hard-deleted when `purge` is set. Config restore always runs
+ * before disposal because the backups live inside `~/.agents`.
+ */
+export declare function executeUninstall(plan: UninstallPlan, opts: {
+    purge?: boolean;
+    timestamp: number;
+}): UninstallResult;