@phnx-labs/agents-cli 1.20.73 → 1.20.74

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## 1.20.74
+
+- **Project resource manifests are now portable across Windows and POSIX.** The
+  managed-resource manifest `.agents-managed.json` recorded its paths with the
+  host's native separator, so a sync run on Windows wrote entries like
+  `skills\myskill`. That file lives in the version-controlled project `.agents`
+  dir and travels between machines, and the cleanup pass matches manifest entries
+  with `path.sep` — so a manifest written on Windows silently failed to match on
+  macOS or Linux and left previously managed files behind on the next sync (and
+  vice versa). Manifest paths are now normalized to POSIX separators on write and
+  on read, which also repairs manifests written by earlier Windows builds. Source:
+  `apps/cli/src/lib/project-resources.ts`.
+
+- **`agents import <agent> --isolated` — bring your existing setup into a sandbox.**
+  Isolation was a cold start: a new isolated copy began empty, and the only way to get
+  settings into it was by hand. A plain `agents import` is the opposite of what is
+  wanted here — it *adopts*, moving `~/.<agent>` into a version home, symlinking the
+  original away, setting the global default and creating a shim (and is now refused
+  outright for an isolated-only agent). `--isolated` copies instead: your settings land
+  in the isolated home, your real config stays exactly where it is, and the version is
+  finalized the way `agents add --isolated` does — versioned alias and marker, no
+  default, no bare shim, no config symlink. Credentials are skipped by default and
+  named in the output rather than silently included, since an isolated copy signs in as
+  its own principal; `--with-auth` opts in. Symlinks into `~/.agents` are dropped so the
+  copy does not depend on the CLI's tree. Source: `apps/cli/src/lib/import.ts`,
+  `apps/cli/src/commands/import.ts`.
+
+- **`agents use <agent>@<isolated>` now works, and a bare `agents run <agent>` reaches
+  your isolated copy.** Isolated installs were unreachable by name: `resolveVersion`
+  ended at the global default, and an isolated install deliberately never becomes one —
+  so `agents use` refused, and an isolated-only user had to type the full
+  `agents run codex@0.144.6` every time while a bare `agents run codex` fell through to
+  whatever `codex` meant on PATH. `use` now records an **isolated default** instead of
+  refusing, and resolution falls back to it (`project pin -> global default -> isolated
+  default`). Strictly a fallback, so nothing changes for anyone who has a global
+  default. The pointer lives in `isolatedAgents:` in `agents.yaml`, never in the global
+  `agents:` map — that separation is what keeps `getGlobalDefault` incapable of
+  returning an isolated version, and with it the launcher, bare shim, config symlink and
+  self-heal `shadowing` check all stay out of reach. It is verified on read and
+  re-pointed (or cleared) on removal, so it can never resolve to a version that is gone.
+  `agents view` labels it `(isolated default)`. Source: `apps/cli/src/lib/versions.ts`,
+  `apps/cli/src/commands/versions.ts`, `apps/cli/src/commands/view.ts`.
+
+- **`agents export <agent>[@<version>]` — take an isolated install's config with you.**
+  `--isolated` was a one-way door: it builds a self-contained home under the version
+  dir and nothing ever brings that work back, so a user who configured a sandboxed copy
+  for a week had to copy files by hand to promote it — or to leave. Export is additive
+  by default: it copies only paths you don't already have, and a collision is **not**
+  silently skipped — the incoming file is written beside yours as
+  `<name>.from-agents-cli` so you can `--diff` it and take the parts you want. Your
+  files are never modified. `--replace` promotes a sandbox wholesale (yours is moved to
+  `backups/<agent>/<ts>`, and it is the only mode that asks for confirmation);
+  `--staged` dumps the tree into `~/.<agent>/.agents-export-<ts>/` and activates
+  nothing. Every mode strips symlinks pointing back into `~/.agents` so the result
+  keeps working after agents-cli is gone, keeps your own symlinks, and writes a receipt
+  to `~/.<agent>/.agents-cli-export.json` recording exactly what came from the export —
+  which makes "which of these files are mine?" answerable and the whole thing
+  reversible. A `~/.<agent>` that agents-cli already adopted is refused, since writing
+  there would mutate that version's home rather than your config. File *contents* are
+  never auto-merged: the TOML parser here drops comments across parse+stringify, so
+  unioning keys would silently delete them. Source: `apps/cli/src/lib/export.ts`,
+  `apps/cli/src/commands/export.ts`, `apps/cli/src/lib/config-transfer.ts`.
+
+- **An isolated-only agent can no longer be adopted by anything.** `--isolated` used to
+  be defined by what it *doesn't* do — no global default, no bare shim, no config
+  symlink, no PATH edit — which meant every code path that could adopt an agent had to
+  remember to check first. It leaked three times that way. Protection is now derived
+  from the `.isolated` markers on disk (`isIsolationProtected`: at least one installed
+  version, and every one isolated) and enforced inside the five primitives that can
+  cross the boundary — `setGlobalDefault`, `createShim`, `switchConfigSymlink`,
+  `switchHomeFileSymlinks`, `adoptShadowingLauncher` — so refusal is a property of the
+  code rather than a convention. There is no mode to set and none to forget: installing
+  with `--isolated` *is* the opt-in, it is per-agent, and the escape hatch is inherent
+  (remove the isolated copies and the agent is ordinary again). `agents add`,
+  `agents import` and `doctor --adopt` refuse with guidance rather than a stack trace —
+  `import` is additionally checked at its entry point, because it registers the adopted
+  install as a normal version *before* adopting, which would otherwise un-protect the
+  agent underneath the primitive gate. Clearing a global default stays allowed, since
+  removal legitimately clears one as an agent becomes isolated-only. A completeness test
+  pins the primitive list and scans for any new ungated mutator. Source:
+  `apps/cli/src/lib/shims.ts`, `apps/cli/src/lib/versions.ts`,
+  `apps/cli/src/lib/isolation-boundary-report.ts`.
+
+- **`agents view` no longer hides your own CLI behind an isolated install.** The listing
+  was either/or per agent: any managed version at all suppressed the "Not Managed by
+  Agents CLI" block, so a single `agents add <agent>@<v> --isolated` made the user's
+  globally-installed CLI disappear from the one command they'd run to confirm
+  `--isolated` had left it alone. Nothing on disk was ever touched — the isolation
+  boundary holds — but the report read exactly like the damage it was supposed to rule
+  out. Isolated copies now render alongside the global install and are tagged
+  `9.9.4 (isolated)`; a normal (non-isolated) version still takes the launcher over and
+  still suppresses the global row, since that row would just be our own shim. The global
+  row is also resolved from PATH now (`getUnmanagedCliState`) instead of from the version
+  dirs, which could otherwise report an isolated copy — deliberately unreachable from
+  PATH — as `(global)`. Source: `apps/cli/src/commands/view.ts`, `apps/cli/src/lib/agents.ts`.
+
 ## 1.20.73
 
 - **`agents cli install <binary-cli>` no longer hardcodes `/usr/local/bin` (#1103).**

package/dist/commands/doctor.js

@@ -1,3 +1,5 @@
+import { IsolationBoundaryError } from '../lib/shims.js';
+import { explainIsolationBoundary } from '../lib/isolation-boundary-report.js';
 import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
@@ -690,7 +692,17 @@ export function registerDoctorCommand(program) {
             // adoptShadowingLauncher resolves the launcher itself (PATH shadow, then
             // the durable ~/.local/bin symlink), so it forces the take-over even when
             // this shell's PATH already has the shim first.
-            const result = adoptShadowingLauncher(agent);
+            let result;
+            try {
+                result = adoptShadowingLauncher(agent);
+            }
+            catch (err) {
+                if (err instanceof IsolationBoundaryError) {
+                    explainIsolationBoundary(err);
+                    process.exit(1);
+                }
+                throw err;
+            }
             if (result.adopted) {
                 console.log(chalk.green(`Adopted ${AGENTS[agent].cliCommand} launcher (${result.launcher} -> shim). Original recorded for --release; version management now wins regardless of PATH order.`));
             }

package/dist/commands/export.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `agents export <agent>[@<version>]` — copy an isolated install's config out to the
+ * user's real `~/.<agent>`.
+ *
+ * The exit door for `--isolated`. Default is additive: your files are never modified,
+ * and anything that collides is written beside yours so you can diff and take what you
+ * want. A receipt records what came from the export, so "which of these are mine?" has
+ * an answer and the whole thing can be undone.
+ */
+import type { Command } from 'commander';
+export declare function registerExportCommand(program: Command): void;

package/dist/commands/export.js

@@ -0,0 +1,215 @@
+import chalk from 'chalk';
+import { execFileSync } from 'child_process';
+import { confirm, select } from '@inquirer/prompts';
+import { AGENTS, agentLabel, formatAgentError, resolveAgentName } from '../lib/agents.js';
+import { listInstalledVersions, isVersionIsolated } from '../lib/versions.js';
+import { planExport, executeExport, CONFLICT_SUFFIX } from '../lib/export.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+function isolatedVersions(agent) {
+    return listInstalledVersions(agent).filter((v) => isVersionIsolated(agent, v));
+}
+/** Explain a blocker in terms of what the user should do instead. */
+function reportBlocker(plan) {
+    const label = agentLabel(plan.agent);
+    const b = plan.blocker;
+    switch (b.kind) {
+        case 'not-installed':
+            console.log(chalk.red(`${label}@${plan.version} is not installed.`));
+            console.log(chalk.gray(`  Installed: ${listInstalledVersions(plan.agent).join(', ') || 'none'}`));
+            break;
+        case 'not-isolated':
+            console.log(chalk.yellow(`${label}@${plan.version} is not an isolated install.`));
+            console.log(chalk.gray(`  A normal install's config already IS ${plan.dest} (adoption symlinks it),`));
+            console.log(chalk.gray('  so there is nothing to export. To un-adopt it, use: agents uninstall'));
+            break;
+        case 'no-config':
+            console.log(chalk.yellow(`${label}@${plan.version} has no config to export yet (${b.source} is empty).`));
+            console.log(chalk.gray(`  Run it once first: agents run ${plan.agent}@${plan.version}`));
+            break;
+        case 'dest-adopted':
+            console.log(chalk.red(`${b.realPath} is managed by agents-cli (adopted by ${label}@${b.adoptedVersion}).`));
+            console.log(chalk.gray('  Exporting would write into that version\'s home, not your real config.'));
+            console.log(chalk.gray(`  Release it first: agents uninstall  (or agents remove ${plan.agent}@${b.adoptedVersion})`));
+            break;
+    }
+}
+/** Unified diff between the user's file and the incoming one, via git. */
+function printDiff(existing, incoming) {
+    try {
+        execFileSync('git', ['diff', '--no-index', '--color', '--', existing, incoming], {
+            stdio: ['ignore', 'inherit', 'ignore'],
+        });
+    }
+    catch {
+        // git diff --no-index exits 1 when files differ; output already streamed.
+    }
+}
+function printPlan(plan, opts) {
+    const label = agentLabel(plan.agent);
+    console.log(chalk.bold(`Export ${label}@${plan.version} -> ${plan.dest}  ${chalk.gray(`[${plan.mode}]`)}\n`));
+    console.log(`  ${chalk.gray('from')}  ${plan.source}`);
+    console.log(`  ${chalk.gray('to')}    ${plan.stagedPath ?? plan.dest}`);
+    console.log();
+    if (plan.mode === 'replace') {
+        console.log(chalk.yellow(`  Replacing ${plan.dest} wholesale — ${plan.writes.length} file(s).`));
+        if (plan.backupPath)
+            console.log(chalk.gray(`  Your current config moves to: ${plan.backupPath}`));
+        else if (plan.destKind === 'foreign-symlink') {
+            console.log(chalk.yellow(`  ${plan.dest} is a symlink agents-cli does not own; it will be removed.`));
+            console.log(chalk.gray('  Its target is left untouched.'));
+        }
+    }
+    else if (plan.mode === 'staged') {
+        console.log(chalk.gray(`  Writing ${plan.writes.length} file(s) into ${plan.stagedPath}.`));
+        console.log(chalk.gray('  Nothing is activated — your config is untouched.'));
+    }
+    else {
+        if (plan.writes.length > 0) {
+            console.log(chalk.green(`  ${plan.writes.length} new file(s) will be added:`));
+            for (const w of plan.writes.slice(0, 15))
+                console.log(chalk.gray(`      + ${w.rel}`));
+            if (plan.writes.length > 15)
+                console.log(chalk.gray(`      + ${plan.writes.length - 15} more`));
+        }
+        else {
+            console.log(chalk.gray('  No new files to add.'));
+        }
+        if (plan.conflicts.length > 0) {
+            console.log();
+            console.log(chalk.yellow(`  ${plan.conflicts.length} file(s) you already have — YOURS ARE NOT MODIFIED.`));
+            console.log(chalk.gray(`  The incoming version is written beside each as *${CONFLICT_SUFFIX}:`));
+            for (const c of plan.conflicts.slice(0, 15))
+                console.log(chalk.gray(`      ~ ${c.rel}`));
+            if (plan.conflicts.length > 15)
+                console.log(chalk.gray(`      ~ ${plan.conflicts.length - 15} more`));
+        }
+    }
+    if (opts.diff && plan.conflicts.length > 0) {
+        for (const c of plan.conflicts) {
+            console.log(chalk.bold(`\n─── ${c.rel} ───`));
+            printDiff(c.existing, c.source);
+        }
+    }
+    console.log(chalk.gray(`\n  Receipt: ${plan.receiptPath}`));
+}
+export function registerExportCommand(program) {
+    program
+        .command('export <spec>')
+        .description('Copy an isolated install\'s config out to your real ~/.<agent>')
+        .option('--replace', 'Replace your config wholesale (yours is backed up) instead of merging')
+        .option('--staged', 'Write into ~/.<agent>/.agents-export-<ts>/ and activate nothing')
+        .option('--diff', 'Show a unified diff for each file you already have')
+        .option('--dry-run', 'Show what would change without writing anything')
+        .option('-y, --yes', 'Skip the confirmation prompt')
+        .addHelpText('after', `
+Modes:
+  (default)   merge   — additive. Your files are NEVER modified. Anything that
+                        collides is written beside yours as <name>${CONFLICT_SUFFIX}
+                        so you can diff and take the parts you want.
+  --replace           — the isolated config becomes ~/.<agent>; yours is moved to
+                        backups/<agent>/<ts>. For promoting a sandbox wholesale.
+  --staged            — dump the tree into ~/.<agent>/.agents-export-<ts>/ and
+                        activate nothing. For inspecting first.
+
+Every mode writes a receipt to ~/.<agent>/.agents-cli-export.json listing exactly
+what came from the export — so you can tell your settings from the CLI's, and undo it.
+
+Examples:
+  agents export codex --dry-run          # see the plan
+  agents export codex --diff             # ...and the deltas on colliding files
+  agents export codex                    # additive; nothing of yours changes
+  agents export codex@0.144.6 --replace  # promote the sandbox wholesale
+
+Note: file CONTENTS are never auto-merged. The TOML parser here does not preserve
+comments, so merging keys would silently delete them. You get both files and a diff.
+`)
+        .action(async (spec, options) => {
+        if (options.replace && options.staged) {
+            console.error(chalk.red('--replace and --staged are mutually exclusive; pass only one.'));
+            process.exit(1);
+        }
+        const mode = options.replace ? 'replace' : options.staged ? 'staged' : 'merge';
+        const [rawAgent, rawVersion] = spec.split('@');
+        const agent = resolveAgentName(rawAgent);
+        if (!agent) {
+            console.error(chalk.red(formatAgentError(rawAgent)));
+            process.exit(1);
+        }
+        let version = rawVersion;
+        if (!version) {
+            const candidates = isolatedVersions(agent);
+            if (candidates.length === 0) {
+                console.log(chalk.yellow(`No isolated ${agentLabel(agent)} installs to export.`));
+                console.log(chalk.gray(`  Create one with: agents add ${agent}@<version> --isolated`));
+                return;
+            }
+            if (candidates.length === 1) {
+                version = candidates[0];
+            }
+            else if (isInteractiveTerminal()) {
+                version = await select({
+                    message: `Which isolated ${agentLabel(agent)} version?`,
+                    choices: candidates.map((v) => ({ name: v, value: v })),
+                }).catch((err) => {
+                    if (isPromptCancelled(err))
+                        process.exit(130);
+                    throw err;
+                });
+            }
+            else {
+                console.error(chalk.red(`${agentLabel(agent)} has several isolated installs; name one.`));
+                console.error(chalk.gray(`  ${candidates.map((v) => `agents export ${agent}@${v}`).join('\n  ')}`));
+                process.exit(1);
+            }
+        }
+        const timestamp = Date.now();
+        const plan = planExport(agent, version, timestamp, mode);
+        if (plan.blocker) {
+            reportBlocker(plan);
+            process.exit(1);
+        }
+        printPlan(plan, { diff: options.diff });
+        if (options.dryRun) {
+            console.log(chalk.gray('\nDry run — nothing was written.'));
+            return;
+        }
+        // Only `--replace` can destroy anything, so it is the only mode that demands
+        // confirmation. merge and staged are additive by construction.
+        if (mode === 'replace' && !options.yes) {
+            if (!isInteractiveTerminal()) {
+                console.error(chalk.red('\nRefusing to replace your config without confirmation in a non-interactive shell.'));
+                console.error(chalk.gray('  Re-run with --yes once you have checked --dry-run.'));
+                process.exit(1);
+            }
+            const ok = await confirm({ message: `Replace ${plan.dest}?`, default: false }).catch((err) => {
+                if (isPromptCancelled(err))
+                    process.exit(130);
+                throw err;
+            });
+            if (!ok) {
+                console.log(chalk.gray('Aborted.'));
+                return;
+            }
+        }
+        const result = executeExport(plan, timestamp);
+        if (!result.exported) {
+            console.error(chalk.red(`Export failed: ${result.errors.join('; ')}`));
+            process.exit(1);
+        }
+        console.log();
+        if (result.written.length > 0)
+            console.log(chalk.green(`Added ${result.written.length} file(s) to ${result.dest}`));
+        if (result.conflicts.length > 0) {
+            console.log(chalk.yellow(`${result.conflicts.length} of your file(s) were left untouched; incoming copies written as *${CONFLICT_SUFFIX}`));
+            console.log(chalk.gray(`  Compare them with: agents export ${agent}@${version} --diff --dry-run`));
+        }
+        if (result.backupPath)
+            console.log(chalk.gray(`Previous config kept at: ${result.backupPath}`));
+        if (result.stagedPath)
+            console.log(chalk.gray(`Staged (nothing activated): ${result.stagedPath}`));
+        console.log(chalk.gray(`Receipt: ${result.receiptPath}`));
+        if (mode !== 'staged') {
+            console.log(chalk.gray(`  ${AGENTS[plan.agent].cliCommand} reads this config directly.`));
+        }
+    });
+}

package/dist/commands/import.js

@@ -20,6 +20,9 @@
  * In all forms, the agent's config dir (e.g. ~/.openclaw) is also moved under
  * management — same behavior as the first-run `agents setup` import flow.
  */
+import { withIsolationBoundary } from '../lib/isolation-boundary-report.js';
+import { assertIsolationBoundary, createVersionedAlias } from '../lib/shims.js';
+import { markVersionIsolated } from '../lib/versions.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -29,7 +32,7 @@ import { confirm } from '@inquirer/prompts';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
 import { AGENTS, getCliPath, getCliVersion, agentLabel, resolveAgentName } from '../lib/agents.js';
 import { getVersionDir } from '../lib/versions.js';
-import { finalizeImport, importAgentBinary, importAgentConfig, importInstallScriptBinary, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
+import { finalizeImport, importAgentBinary, importAgentConfig, importInstallScriptBinary, seedIsolatedConfigFromLocal, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
 async function runImport(agentArg, opts) {
     const agentId = resolveAgentName(agentArg);
@@ -39,6 +42,16 @@ async function runImport(agentArg, opts) {
         process.exit(1);
     }
     const agent = AGENTS[agentId];
+    // Import registers the adopted install as a NORMAL version and only then sets the
+    // default / creates the shim / repoints the config. By that point the agent has a
+    // non-isolated version, so it is no longer protected and the primitive gates —
+    // which read the state as it is at call time — would let the adoption through.
+    // The boundary has to be checked against the state BEFORE the import mutates it.
+    // --isolated adopts nothing, so the boundary does not apply to it — it is in fact
+    // the supported way to bring a local install in while protection is on.
+    if (!opts.isolated) {
+        assertIsolationBoundary(agentId, 'adopt your existing install');
+    }
     // installScript-based agents (Grok, Antigravity, Cursor, Kiro, Goose, Roo)
     // don't have an npm package; their binary lives wherever the curl/brew
     // installer dropped it. We adopt by symlinking that PATH binary directly
@@ -191,7 +204,27 @@ async function runImport(agentArg, opts) {
     // user-visible side effect (renaming ~/.<agent>/), so if it fails we don't
     // want a stranded symlink farm. Binary registration is cheap and reversible
     // — if it fails after config, the next `agents import` call retries cleanly.
-    const willImportConfig = configDirExists && !configAlreadyManaged;
+    const willImportConfig = configDirExists && !configAlreadyManaged && !opts.isolated;
+    if (opts.isolated && configDirExists) {
+        // COPY the user's settings in; never move, never symlink. The original stays
+        // exactly where it is — that is what separates this from adoption.
+        const seedSpinner = ora(`Copying ${agent.configDir} into the isolated copy...`).start();
+        const seed = seedIsolatedConfigFromLocal(agentId, version, { withAuth: opts.withAuth });
+        if (seed.error) {
+            seedSpinner.fail(`Config: ${seed.error}`);
+            process.exit(1);
+        }
+        else if (seed.seeded) {
+            seedSpinner.succeed(`Settings copied (${seed.from} -> ${seed.to}); your original is untouched`);
+            if (seed.skippedAuth.length > 0) {
+                console.log(chalk.gray(`  Credentials NOT copied: ${seed.skippedAuth.join(', ')}`));
+                console.log(chalk.gray('  The copy signs in separately. Use --with-auth to copy them too.'));
+            }
+        }
+        else {
+            seedSpinner.info('No existing config to copy.');
+        }
+    }
     if (willImportConfig) {
         const cfgSpinner = ora(`Importing config dir for ${agentLabel(agentId)} v${version}...`).start();
         const cfgResult = await importAgentConfig(agentId, version);
@@ -224,6 +257,19 @@ async function runImport(agentArg, opts) {
     // Wire the imported version into the resolver: global default, main shim,
     // versioned alias, home-file symlinks. Idempotent — safe to call even if
     // importAgentConfig already set the global default.
+    if (opts.isolated) {
+        // The isolated finalizer: launchable alias + marker, and nothing else. No global
+        // default, no bare shim, no config symlink — the same shape as
+        // `agents add --isolated`.
+        createVersionedAlias(agentId, version);
+        markVersionIsolated(agentId, version);
+        console.log();
+        console.log(chalk.green(`${agentLabel(agentId)} v${version} imported as an isolated copy.`));
+        console.log(chalk.gray(`  Your ${agent.configDir} and ${agent.cliCommand} launcher are untouched.`));
+        console.log(chalk.gray(`  Run it:  agents run ${agentId}@${version}`));
+        console.log(chalk.gray(`  Or make it the default isolated copy:  agents use ${agentId}@${version}`));
+        return;
+    }
     const finalizeSpinner = ora(`Wiring ${agentLabel(agentId)} v${version} as the active version...`).start();
     try {
         finalizeImport(agentId, version);
@@ -244,6 +290,8 @@ export function registerImportCommand(program) {
         .description('Import an existing unmanaged agent install into agents-cli')
         .option('--version <version>', 'Pin a version label (otherwise read from package.json)')
         .option('--from-path <path>', 'Path to the npm package dir (otherwise auto-detected from PATH)')
+        .option('--isolated', 'Copy the install into a self-contained isolated version instead of adopting it')
+        .option('--with-auth', 'With --isolated, also copy credentials into the sandbox (skipped by default)')
         .option('-y, --yes', 'Skip the confirmation prompt')
         .addHelpText('after', `
 Examples:
@@ -265,5 +313,5 @@ When to use:
   npm-style packages (claude, codex, gemini, opencode, openclaw) and
   installScript-based agents (grok, antigravity, cursor, kiro, goose).
 `)
-        .action(runImport);
+        .action((...args) => withIsolationBoundary(() => runImport(...args)));
 }

package/dist/commands/setup.js

@@ -16,7 +16,7 @@ import { isGitRepo, cloneIntoExisting, pullRepo } from '../lib/git.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
 import { AGENTS, agentConfigDirName, getUnmanagedAgentInstalls, countSessionFiles, agentLabel } from '../lib/agents.js';
 import { setGlobalDefault } from '../lib/versions.js';
-import { ensureShimCurrent, switchHomeFileSymlinks, isShimsInPath, addShimsToPath, getPathSetupInstructions } from '../lib/shims.js';
+import { ensureShimCurrent, switchHomeFileSymlinks, isShimsInPath, addShimsToPath, getPathSetupInstructions, assertIsolationBoundary } from '../lib/shims.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSetupBrowserCommand, runBrowserWizard } from './setup-browser.js';
 import { registerSetupComputerCommand, runComputerWizard } from './setup-computer.js';
@@ -29,6 +29,11 @@ const HOME = os.homedir();
  */
 async function importAgent(agentId, version) {
     const agent = AGENTS[agentId];
+    // setup has its own hand-rolled adoption (rename + symlink inline, rather than
+    // calling switchConfigSymlink), so the primitive gates never see it. Check the
+    // boundary here, before the first mkdirSync — which would otherwise create the
+    // scaffolding this very check reads.
+    assertIsolationBoundary(agentId, 'adopt your existing install');
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
     const versionHome = path.join(versionsDir, agentId, version, 'home');

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, markVersionIsolated, isVersionIsolated, 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, setIsolatedDefault, 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, supportsIsolatedInstall, CONFIG_ENV_ISOLATED_AGENTS, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
+import { createShim, createVersionedAlias, supportsIsolatedInstall, isIsolationProtected, 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';
@@ -342,6 +342,20 @@ export function registerVersionsCommands(program) {
             // 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.
+            // A normal install of a currently isolated-only agent would adopt it: set the
+            // global default, create the bare shim, and repoint the real ~/.<agent>. The
+            // primitives refuse that outright, so catch it here — before spending a
+            // network install on something that cannot finish — and say what to do.
+            if (!isIsolated && isIsolationProtected(agent)) {
+                console.log(chalk.red(`${agentLabel(agentConfig.id)} is installed only as isolated copies.`));
+                console.log(chalk.gray(`  A normal install would adopt ${agentConfig.configDir} and your ${agentConfig.cliCommand} launcher.`));
+                console.log(chalk.gray(`  Keep the sandbox:  agents add ${agent}@${version ?? 'latest'} --isolated`));
+                console.log(chalk.gray('  Or manage it normally by removing the isolated copies first:'));
+                for (const v of listInstalledVersions(agent)) {
+                    console.log(chalk.gray(`    agents remove ${agent}@${v} --isolated`));
+                }
+                continue;
+            }
             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.`));
@@ -705,10 +719,27 @@ export function registerVersionsCommands(program) {
             // 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>`.
+            // ...so `use` is scoped to the sandbox rather than refused. Setting the
+            // ISOLATED default records which copy a bare `agents run <agent>` should
+            // reach, and touches none of the five adopting side effects above. The
+            // pointer lives in `meta.isolatedAgents`, never in `meta.agents`, so
+            // `getGlobalDefault` still cannot return an isolated version.
             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}`));
+                if (options.project) {
+                    console.log(chalk.yellow(`${agentLabel(agentConfig.id)}@${finalVersion} is an isolated install; --project pins are for shared versions.`));
+                    console.log(chalk.gray(`Run it directly instead: agents run ${agentId}@${finalVersion}`));
+                    return;
+                }
+                setIsolatedDefault(agentId, finalVersion);
+                console.log(chalk.green(`Set ${agentLabel(agentConfig.id)}@${finalVersion} as your default ISOLATED copy.`));
+                console.log(chalk.gray(`  agents run ${agentId}   now reaches it (no @version needed).`));
+                const globalDefault = getGlobalDefault(agentId);
+                if (globalDefault) {
+                    console.log(chalk.gray(`  Your default ${agentConfig.cliCommand} is still ${globalDefault}; ${agentConfig.configDir} is untouched.`));
+                }
+                else {
+                    console.log(chalk.gray(`  ${agentConfig.configDir} and your ${agentConfig.cliCommand} launcher are untouched.`));
+                }
                 return;
             }
             if (options.project) {