@phnx-labs/agents-cli 1.20.70 → 1.20.72

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.
  */

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/commands.d.ts

@@ -89,6 +89,16 @@ export interface VersionCommandDiff {
 /**
  * Compare a version home's commands against central. Returns the reconciliation diff.
  */
+/**
+ * Flattened names of plugin-bundled commands (`<plugin>-<command>`), matching
+ * exactly how `syncPluginToVersion` installs a plugin's `commands/<cmd>.md` as a
+ * command-skill (plugins.ts → `installCommandSkillToVersion(agentDir,
+ * `${plugin.name}-${cmd}`, …)`). These are source-managed by their plugin, so
+ * the orphan detector must NOT flag them — else `prune cleanup` proposes
+ * deleting live plugin commands (swarm-plan, code-review, …). Scans user +
+ * system + extra marketplaces (no project layer), matching the trusted sources.
+ */
+export declare function listPluginCommandNames(): Set<string>;
 export declare function diffVersionCommands(agent: AgentId, version: string): VersionCommandDiff;
 /**
  * Install a single command from central into a specific version home.

package/dist/lib/commands.js

@@ -14,6 +14,7 @@ import { capableAgents, isCapable, supports } from './capabilities.js';
 import { markdownToToml } from './convert.js';
 import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
+import { discoverPlugins } from './plugins.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
 import { installGooseCommandToVersion, listGooseCommandsInVersion, gooseCommandMatches, removeGooseCommandFromVersion, } from './goose-commands.js';
 function compareVersions(a, b) {
@@ -311,8 +312,26 @@ function versionCommandMatches(agent, version, commandName) {
 /**
  * Compare a version home's commands against central. Returns the reconciliation diff.
  */
+/**
+ * Flattened names of plugin-bundled commands (`<plugin>-<command>`), matching
+ * exactly how `syncPluginToVersion` installs a plugin's `commands/<cmd>.md` as a
+ * command-skill (plugins.ts → `installCommandSkillToVersion(agentDir,
+ * `${plugin.name}-${cmd}`, …)`). These are source-managed by their plugin, so
+ * the orphan detector must NOT flag them — else `prune cleanup` proposes
+ * deleting live plugin commands (swarm-plan, code-review, …). Scans user +
+ * system + extra marketplaces (no project layer), matching the trusted sources.
+ */
+export function listPluginCommandNames() {
+    const names = new Set();
+    for (const plugin of discoverPlugins()) {
+        for (const cmd of plugin.commands)
+            names.add(`${plugin.name}-${cmd}`);
+    }
+    return names;
+}
 export function diffVersionCommands(agent, version) {
     const central = new Set(listCentralCommands());
+    const pluginCommands = listPluginCommandNames();
     const installed = new Set(listCommandsInVersionHome(agent, version));
     const toAdd = [];
     const toUpdate = [];
@@ -335,15 +354,20 @@ export function diffVersionCommands(agent, version) {
         }
     }
     for (const name of installed) {
-        if (!central.has(name)) {
-            orphans.push(name);
+        if (central.has(name)) {
+            const sourcePath = path.join(getCommandsDir(), `${name}.md`);
+            const metadata = parseCommandMetadata(sourcePath);
+            if (!commandAppliesTo(agent, version, metadata).ok) {
+                toRemove.push(name);
+            }
             continue;
         }
-        const sourcePath = path.join(getCommandsDir(), `${name}.md`);
-        const metadata = parseCommandMetadata(sourcePath);
-        if (!commandAppliesTo(agent, version, metadata).ok) {
-            toRemove.push(name);
-        }
+        // A plugin-bundled command (installed as `<plugin>-<cmd>`) is source-managed
+        // by its plugin — not an orphan. Only a name with no central AND no plugin
+        // source is genuinely unmanaged.
+        if (pluginCommands.has(name))
+            continue;
+        orphans.push(name);
     }
     return {
         agent,

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/devices/connect.d.ts

@@ -8,6 +8,19 @@ export declare const ASKPASS_KEY_ENV = "AGENTS_SSH_KEY";
  * it against the shared injection guard. Throws if the device has no address.
  */
 export declare function sshTargetFor(device: DeviceProfile): string;
+/**
+ * The address a fleet fan-out probe should hand to `ssh` for a device: the
+ * registry's known-good Tailscale dnsName/IP (via {@link sshTargetFor}) when
+ * present, else the bare name (an address-less manual device dials by name as
+ * before — never worse than the old behaviour).
+ *
+ * Prefer the registry address so a stale `~/.ssh/config` alias can never shadow
+ * it: dialing the bare device name lets ssh resolve it through the user's config,
+ * where a hand-written `Host <name>` block with a DHCP-drifted LAN IP silently
+ * shadows the correct entry, times out, and makes a reachable box look dead.
+ * Pure/testable.
+ */
+export declare function fleetDialTarget(device: DeviceProfile): string;
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile

package/dist/lib/devices/connect.js

@@ -38,6 +38,26 @@ export function sshTargetFor(device) {
     assertValidSshTarget(target);
     return target;
 }
+/**
+ * The address a fleet fan-out probe should hand to `ssh` for a device: the
+ * registry's known-good Tailscale dnsName/IP (via {@link sshTargetFor}) when
+ * present, else the bare name (an address-less manual device dials by name as
+ * before — never worse than the old behaviour).
+ *
+ * Prefer the registry address so a stale `~/.ssh/config` alias can never shadow
+ * it: dialing the bare device name lets ssh resolve it through the user's config,
+ * where a hand-written `Host <name>` block with a DHCP-drifted LAN IP silently
+ * shadows the correct entry, times out, and makes a reachable box look dead.
+ * Pure/testable.
+ */
+export function fleetDialTarget(device) {
+    try {
+        return sshTargetFor(device);
+    }
+    catch {
+        return device.user ? `${device.user}@${device.name}` : device.name;
+    }
+}
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile

package/dist/lib/devices/fleet.d.ts

@@ -70,17 +70,50 @@ export declare function runOnDevice(device: DeviceProfile, cmd: string[], opts?:
     stdout: string;
     stderr: string;
 };
+/**
+ * Run `cmd` on THIS machine directly — no ssh. Used by {@link runFleet} for the
+ * self target: a box frequently can't ssh to itself (no self-authorized key, as
+ * `agents fleet update` hit trying to reach zion from zion) and doesn't need to —
+ * `agents upgrade` etc. runs identically as a local process. Mirrors
+ * {@link runOnDevice}'s return shape and never throws. The argv is space-joined
+ * and evaluated by a shell — matching the POSIX-shell ssh path (so PATH-resolved
+ * `agents`, quoting, and `;`/`&&` behave the same). It does NOT replicate the
+ * powershell-device encoding runOnDevice uses (`connect.ts` base64 path): a
+ * Windows self runs under the default OS shell (cmd.exe), which still resolves
+ * `agents` on PATH for the only self commands that matter (`agents upgrade …`).
+ */
+export declare function runLocalCommand(cmd: string[], opts?: {
+    timeoutMs?: number;
+}): {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+};
 /**
  * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
  * Rejects anything that is not a plain npm version/tag token so a version pin
  * cannot inject shell metacharacters into the remote command line.
  */
 export declare function upgradeCommand(version?: string): string[];
+export interface RunFleetOptions {
+    /**
+     * Name of THIS machine. Its target runs the command **locally** (no ssh) — a
+     * box can't reliably ssh to itself and doesn't need to. Omit to ssh every
+     * target (the old behaviour). Callers pass `machineId()`.
+     */
+    self?: string;
+    /** Injectable ssh runner (tests). */
+    runner?: typeof runOnDevice;
+    /** Injectable local runner (tests). */
+    localRunner?: typeof runLocalCommand;
+}
 /**
  * Execute a command across planned targets. Pure orchestration over
- * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
- * the runner are recorded as `failed` so one bad device never aborts the rest.
+ * {@link runOnDevice} / {@link runLocalCommand}; testable by injecting either.
+ * The `self` target runs locally so `agents fleet update` upgrades this machine
+ * too instead of failing to ssh to itself. Per-device throws from a runner are
+ * recorded as `failed` so one bad device never aborts the rest.
  */
-export declare function runFleet(targets: FleetTarget[], cmd: string[], runner?: typeof runOnDevice): FleetRunResult[];
+export declare function runFleet(targets: FleetTarget[], cmd: string[], opts?: RunFleetOptions): FleetRunResult[];
 /** Run one async probe per device in parallel, preserving input order. */
 export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>): Promise<FanOutDeviceResult<T>[]>;