@phnx-labs/agents-cli 1.20.73 → 1.20.74

package/dist/lib/export.js

@@ -0,0 +1,269 @@
+/**
+ * `agents export` — copy an ISOLATED install's config back out to the user's real
+ * `~/.<agent>`, so they can keep their settings and delete agents-cli entirely.
+ *
+ * Isolation is currently a one-way door: `agents add <agent>@<v> --isolated` builds a
+ * self-contained home under the version dir, and nothing ever brings that work back.
+ * Reversibility is what makes a sandbox safe to try.
+ *
+ * Three modes, because "export" means different things depending on which config you
+ * consider authoritative:
+ *
+ *   merge (default) — additive. Copy only paths the user doesn't already have. A
+ *                     collision is NOT silently skipped: the incoming file is written
+ *                     beside theirs as `<name>.from-agents-cli` so they can diff and
+ *                     take the parts they want. Nothing of theirs is ever modified.
+ *   replace         — the isolated config becomes `~/.<agent>`; theirs moves to
+ *                     `backups/<agent>/<ts>`. For when you've been living in the
+ *                     sandbox and want to promote it wholesale.
+ *   staged          — write the whole tree to `~/.<agent>/.agents-export-<ts>/` and
+ *                     activate nothing. For inspecting first.
+ *
+ * Every mode leaves a receipt at `~/.<agent>/.agents-cli-export.json` recording what
+ * came from the export. That is what makes provenance answerable ("which of these
+ * files are mine?") and the whole operation reversible.
+ *
+ * Deliberately NOT implemented: key-level merging of file *contents*. The TOML
+ * library here does not preserve comments across parse+stringify, so auto-merging a
+ * `config.toml` would silently delete the user's comments. Handing over both files
+ * and a diff is honest; rewriting their config behind a "merge" flag is not.
+ *
+ * Split into a read-only {@link planExport} and a mutating {@link executeExport} so
+ * `--dry-run` and the real run share one code path, mirroring `lib/uninstall.ts`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS } from './agents.js';
+import { getAgentConfigPath, getConfigSymlinkVersion } from './shims.js';
+import { getVersionHomePath, isVersionIsolated, isVersionInstalled } from './versions.js';
+import { getUserAgentsDir, getBackupsDir } from './state.js';
+import { copyDirStrippingAgentsSymlinks, moveDirCrossDevice } from './config-transfer.js';
+/** Filename of the provenance receipt written into the agent's config dir. */
+export const RECEIPT_NAME = '.agents-cli-export.json';
+/** Suffix for the incoming copy of a file the user already has. */
+export const CONFLICT_SUFFIX = '.from-agents-cli';
+/** The config dir's basename (`.codex`), used to locate it inside a version home. */
+function configBasename(agent) {
+    return path.basename(AGENTS[agent].configDir);
+}
+/**
+ * Every regular file under `root`, as paths relative to it. Symlinks pointing back
+ * into `~/.agents` are omitted for the same reason `copyDirStrippingAgentsSymlinks`
+ * drops them: they dangle the moment `~/.agents` is disposed, and an export that
+ * leaves dangling links is not an export.
+ */
+function walkFiles(root, agentsDir, rel = '') {
+    const inside = agentsDir + path.sep;
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const childRel = rel ? path.join(rel, entry.name) : entry.name;
+        const abs = path.join(root, childRel);
+        if (entry.isSymbolicLink()) {
+            try {
+                const tgt = path.resolve(path.dirname(abs), fs.readlinkSync(abs));
+                if (tgt === agentsDir || tgt.startsWith(inside))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            out.push(childRel);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            out.push(...walkFiles(root, agentsDir, childRel));
+            continue;
+        }
+        out.push(childRel);
+    }
+    return out;
+}
+/** Build a read-only plan. Performs no mutations. */
+export function planExport(agent, version, timestamp, mode = 'merge') {
+    const source = path.join(getVersionHomePath(agent, version), configBasename(agent));
+    const dest = getAgentConfigPath(agent);
+    const base = {
+        agent,
+        version,
+        mode,
+        source,
+        dest,
+        destKind: 'absent',
+        writes: [],
+        conflicts: [],
+        backupPath: null,
+        stagedPath: null,
+        receiptPath: path.join(dest, RECEIPT_NAME),
+    };
+    if (!isVersionInstalled(agent, version))
+        return { ...base, blocker: { kind: 'not-installed' } };
+    if (!isVersionIsolated(agent, version))
+        return { ...base, blocker: { kind: 'not-isolated' } };
+    if (!fs.existsSync(source))
+        return { ...base, blocker: { kind: 'no-config', source } };
+    // Refuse when `~/.<agent>` is a symlink agents-cli owns: the agent has a normal
+    // install that adopted it, so writing there would land inside a version home
+    // rather than in the user's real config, and silently mutate that other install.
+    const adopted = getConfigSymlinkVersion(agent);
+    if (adopted !== null) {
+        return { ...base, blocker: { kind: 'dest-adopted', realPath: dest, adoptedVersion: adopted } };
+    }
+    let destKind = 'absent';
+    try {
+        destKind = fs.lstatSync(dest).isSymbolicLink() ? 'foreign-symlink' : 'real-dir';
+    }
+    catch {
+        destKind = 'absent';
+    }
+    const agentsDir = getUserAgentsDir();
+    const rels = walkFiles(source, agentsDir).sort();
+    if (mode === 'staged') {
+        const stagedPath = path.join(dest, `.agents-export-${timestamp}`);
+        return {
+            ...base,
+            destKind,
+            stagedPath,
+            writes: rels.map((rel) => ({
+                rel,
+                source: path.join(source, rel),
+                target: path.join(stagedPath, rel),
+            })),
+            blocker: null,
+        };
+    }
+    if (mode === 'replace') {
+        return {
+            ...base,
+            destKind,
+            backupPath: destKind === 'real-dir' ? path.join(getBackupsDir(), agent, String(timestamp)) : null,
+            writes: rels.map((rel) => ({
+                rel,
+                source: path.join(source, rel),
+                target: path.join(dest, rel),
+            })),
+            blocker: null,
+        };
+    }
+    // merge: additive. Anything the user already has becomes a conflict written
+    // alongside, so their file is never the thing that changes.
+    const writes = [];
+    const conflicts = [];
+    for (const rel of rels) {
+        const target = path.join(dest, rel);
+        let exists = false;
+        try {
+            fs.lstatSync(target);
+            exists = true;
+        }
+        catch {
+            exists = false;
+        }
+        if (exists) {
+            conflicts.push({
+                rel,
+                source: path.join(source, rel),
+                target: target + CONFLICT_SUFFIX,
+                existing: target,
+            });
+        }
+        else {
+            writes.push({ rel, source: path.join(source, rel), target });
+        }
+    }
+    return { ...base, destKind, writes, conflicts, blocker: null };
+}
+/** Copy one file, creating parent dirs. Symlinks are recreated, not followed. */
+function placeFile(entry) {
+    fs.mkdirSync(path.dirname(entry.target), { recursive: true });
+    const st = fs.lstatSync(entry.source);
+    if (st.isSymbolicLink()) {
+        const link = fs.readlinkSync(entry.source);
+        try {
+            fs.unlinkSync(entry.target);
+        }
+        catch {
+            /* nothing there */
+        }
+        fs.symlinkSync(link, entry.target);
+        return;
+    }
+    fs.copyFileSync(entry.source, entry.target);
+}
+function writeReceipt(plan, result, timestamp) {
+    const receipt = {
+        exportedAt: new Date(timestamp).toISOString(),
+        from: `${plan.agent}@${plan.version} (isolated)`,
+        mode: plan.mode,
+        written: result.written,
+        conflicts: result.conflicts,
+        ...(result.backupPath ? { backupPath: result.backupPath } : {}),
+        ...(result.stagedPath ? { stagedAt: result.stagedPath } : {}),
+        note: plan.mode === 'merge'
+            ? `Files under "written" came from this export. Paths under "conflicts" already existed and were NOT modified — the incoming version sits beside yours with the ${CONFLICT_SUFFIX} suffix.`
+            : plan.mode === 'replace'
+                ? 'This config was replaced wholesale by the export; the previous one is at backupPath.'
+                : 'Nothing was activated — the exported tree sits under stagedAt.',
+    };
+    fs.mkdirSync(path.dirname(plan.receiptPath), { recursive: true });
+    fs.writeFileSync(plan.receiptPath, JSON.stringify(receipt, null, 2) + '\n');
+}
+/** Execute a plan from {@link planExport}. */
+export function executeExport(plan, timestamp) {
+    const result = {
+        exported: false,
+        dest: plan.dest,
+        written: [],
+        conflicts: [],
+        backupPath: null,
+        stagedPath: null,
+        receiptPath: null,
+        errors: [],
+    };
+    if (plan.blocker) {
+        result.errors.push(`refusing to export: ${plan.blocker.kind}`);
+        return result;
+    }
+    try {
+        if (plan.mode === 'replace') {
+            if (plan.backupPath) {
+                fs.mkdirSync(path.dirname(plan.backupPath), { recursive: true });
+                moveDirCrossDevice(plan.dest, plan.backupPath);
+                result.backupPath = plan.backupPath;
+            }
+            else if (plan.destKind === 'foreign-symlink') {
+                // Not ours to back up, but it must go or cpSync would write through it.
+                fs.unlinkSync(plan.dest);
+            }
+            copyDirStrippingAgentsSymlinks(plan.source, plan.dest, getUserAgentsDir());
+            result.written = plan.writes.map((w) => w.rel);
+        }
+        else {
+            // merge and staged both place individual files; neither disturbs anything
+            // the user already has.
+            for (const entry of plan.writes) {
+                placeFile(entry);
+                result.written.push(entry.rel);
+            }
+            for (const entry of plan.conflicts) {
+                placeFile(entry);
+                result.conflicts.push({ path: entry.rel, theirs: entry.target });
+            }
+            if (plan.stagedPath)
+                result.stagedPath = plan.stagedPath;
+        }
+        writeReceipt(plan, result, timestamp);
+        result.receiptPath = plan.receiptPath;
+        result.exported = true;
+    }
+    catch (err) {
+        result.errors.push(err instanceof Error ? err.message : String(err));
+    }
+    return result;
+}

package/dist/lib/import.d.ts

@@ -111,3 +111,26 @@ export declare function importInstallScriptBinary(spec: AgentBinarySpec, version
  *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
  */
 export declare function resolvePackageDirFromBinary(binaryPath: string): string | null;
+/**
+ * Seed an ISOLATED version's home from the user's real `~/.<agent>` — the mirror of
+ * {@link importAgentConfig}, which adopts.
+ *
+ * The difference is the whole point: this COPIES and leaves the original in place,
+ * never symlinks it, never sets a default, never creates a shim. So an isolated copy
+ * can start from the setup the user already has instead of from nothing, which was
+ * the only way to get a working sandbox before.
+ *
+ * Credentials are skipped by default and reported, not silently included. An isolated
+ * copy is a separate principal — `agents add --isolated` already tells the user to
+ * sign in on first run — and copying tokens into it should be a choice, not a side
+ * effect of wanting your settings. `--with-auth` opts in.
+ */
+export declare function seedIsolatedConfigFromLocal(agentId: AgentId, version: string, opts?: {
+    withAuth?: boolean;
+}): {
+    seeded: boolean;
+    from: string;
+    to: string;
+    skippedAuth: string[];
+    error?: string;
+};

package/dist/lib/import.js

@@ -20,9 +20,9 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { AGENTS } from './agents.js';
-import { getVersionsDir } from './state.js';
+import { getUserAgentsDir, getVersionsDir } from './state.js';
 import { setGlobalDefault } from './versions.js';
-import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks } from './shims.js';
+import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks, assertIsolationBoundary } from './shims.js';
 const IMPORT_VERSION_RE = /^(?:latest|[A-Za-z0-9._+-]{1,64})$/;
 export function isValidImportVersion(version) {
     return IMPORT_VERSION_RE.test(version);
@@ -39,6 +39,12 @@ export async function importAgentConfig(agentId, version) {
     if (!isValidImportVersion(version)) {
         return { success: false, error: `Invalid version: ${JSON.stringify(version)}` };
     }
+    // Adoption, done inline rather than via switchConfigSymlink — so it needs the gate
+    // directly. commands/import.ts checks at its entry point too (it must: it registers
+    // a normal version first, which would un-protect the agent before this runs), but
+    // an exported function that moves the user's real config must not depend on every
+    // future caller remembering.
+    assertIsolationBoundary(agentId, 'adopt your existing install');
     const agent = AGENTS[agentId];
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
@@ -237,3 +243,69 @@ export function resolvePackageDirFromBinary(binaryPath) {
         return null;
     }
 }
+/**
+ * Seed an ISOLATED version's home from the user's real `~/.<agent>` — the mirror of
+ * {@link importAgentConfig}, which adopts.
+ *
+ * The difference is the whole point: this COPIES and leaves the original in place,
+ * never symlinks it, never sets a default, never creates a shim. So an isolated copy
+ * can start from the setup the user already has instead of from nothing, which was
+ * the only way to get a working sandbox before.
+ *
+ * Credentials are skipped by default and reported, not silently included. An isolated
+ * copy is a separate principal — `agents add --isolated` already tells the user to
+ * sign in on first run — and copying tokens into it should be a choice, not a side
+ * effect of wanting your settings. `--with-auth` opts in.
+ */
+export function seedIsolatedConfigFromLocal(agentId, version, opts = {}) {
+    const agent = AGENTS[agentId];
+    const configDir = agent.configDir;
+    const versionHome = path.join(getVersionsDir(), agentId, version, 'home');
+    // Mirror importAgentConfig's derivation so nested config dirs (e.g. Antigravity's
+    // ~/.gemini/antigravity-cli) land where the shim expects them.
+    const dest = path.join(versionHome, path.relative(os.homedir(), configDir));
+    const result = { seeded: false, from: configDir, to: dest, skippedAuth: [] };
+    if (!fs.existsSync(configDir))
+        return result;
+    // Known credential paths, relative to the config dir. `authFiles` covers the agents
+    // that declare them for cross-version carry; the rest are verified filenames for
+    // agents that do not declare any (codex `auth.json`, claude `.credentials.json`).
+    const authRel = new Set([
+        ...(agent.authFiles ?? []),
+        'auth.json',
+        '.credentials.json',
+        'credentials.json',
+    ]);
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        const agentsDir = getUserAgentsDir();
+        const inside = agentsDir + path.sep;
+        fs.cpSync(configDir, dest, {
+            recursive: true,
+            filter: (src) => {
+                const rel = path.relative(configDir, src);
+                if (!opts.withAuth && rel && (authRel.has(rel) || rel.startsWith('credentials' + path.sep))) {
+                    result.skippedAuth.push(rel);
+                    return false;
+                }
+                // Same rule as the export path: a link into ~/.agents would dangle for a copy
+                // that is supposed to stand on its own.
+                try {
+                    const st = fs.lstatSync(src);
+                    if (st.isSymbolicLink()) {
+                        const tgt = path.resolve(path.dirname(src), fs.readlinkSync(src));
+                        if (tgt === agentsDir || tgt.startsWith(inside))
+                            return false;
+                    }
+                }
+                catch { /* let cpSync surface unreadable entries */ }
+                return true;
+            },
+        });
+        result.seeded = true;
+    }
+    catch (err) {
+        return { ...result, error: err.message };
+    }
+    return result;
+}

package/dist/lib/isolation-boundary-report.d.ts

@@ -0,0 +1,10 @@
+import { IsolationBoundaryError } from './shims.js';
+/**
+ * Turn an {@link IsolationBoundaryError} into guidance. The boundary is enforced by a
+ * throw so it cannot be forgotten; this is what keeps that from surfacing as a stack
+ * trace. The remedy is always the same shape, because the protection is derived from
+ * the isolated copies themselves: drop them and the agent is ordinary again.
+ */
+export declare function explainIsolationBoundary(err: IsolationBoundaryError): void;
+/** Run `fn`, converting a boundary refusal into guidance + a non-zero exit. */
+export declare function withIsolationBoundary<T>(fn: () => Promise<T> | T): Promise<T | undefined>;

package/dist/lib/isolation-boundary-report.js

@@ -0,0 +1,35 @@
+import chalk from 'chalk';
+import { IsolationBoundaryError } from './shims.js';
+import { listInstalledVersions } from './versions.js';
+/**
+ * Turn an {@link IsolationBoundaryError} into guidance. The boundary is enforced by a
+ * throw so it cannot be forgotten; this is what keeps that from surfacing as a stack
+ * trace. The remedy is always the same shape, because the protection is derived from
+ * the isolated copies themselves: drop them and the agent is ordinary again.
+ */
+export function explainIsolationBoundary(err) {
+    const versions = listInstalledVersions(err.agent);
+    console.error(chalk.red(`\n${err.agent} is installed only as isolated copies.`));
+    console.error(chalk.gray(`  Refused: ${err.operation} — that is exactly what --isolated promises not to do.`));
+    console.error(chalk.gray('\n  To keep the sandbox and act inside it:'));
+    console.error(chalk.gray(`    agents add ${err.agent}@<version> --isolated    # another isolated copy`));
+    console.error(chalk.gray(`    agents use ${err.agent}@<version>               # pick which one 'agents run ${err.agent}' uses`));
+    console.error(chalk.gray(`    agents export ${err.agent}                      # copy its config out to your real config dir`));
+    console.error(chalk.gray('\n  To manage this agent normally instead, remove the isolated copies first:'));
+    for (const v of versions) {
+        console.error(chalk.gray(`    agents remove ${err.agent}@${v} --isolated`));
+    }
+}
+/** Run `fn`, converting a boundary refusal into guidance + a non-zero exit. */
+export async function withIsolationBoundary(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof IsolationBoundaryError) {
+            explainIsolationBoundary(err);
+            process.exit(1);
+        }
+        throw err;
+    }
+}

package/dist/lib/project-resources.js

@@ -41,7 +41,7 @@ function loadProjectManifest(agentRoot) {
             return null;
         if (!raw.paths.every((p) => typeof p === 'string' && p.length > 0))
             return null;
-        return raw;
+        return { ...raw, paths: raw.paths.map(toPosixRel) };
     }
     catch {
         return null;
@@ -106,10 +106,22 @@ function projectEntries(projectAgentsDir, kind) {
         return [];
     }
 }
+/**
+ * Manifest paths are persisted to `.agents-managed.json`, which lives in the
+ * version-controlled project dir and therefore travels between machines. Store
+ * them POSIX-style: `path.join` yields `skills\myskill` on Windows, and a
+ * manifest carrying that would silently fail to match — and so fail to clean up
+ * its managed files — when the same project is synced on macOS or Linux.
+ * Normalizing on both write and read also repairs manifests written by earlier
+ * Windows builds.
+ */
+function toPosixRel(rel) {
+    return rel.replace(/\\/g, '/');
+}
 function record(kind, name, relPaths, result, manifestPaths) {
     result.synced.push(`${kind}/${name}`);
     for (const rel of relPaths)
-        manifestPaths.add(rel);
+        manifestPaths.add(toPosixRel(rel));
 }
 function skip(dest, projectRoot, result) {
     const rel = path.relative(projectRoot, dest);
@@ -209,8 +221,8 @@ function syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, age
         return;
     const all = readProjectSubagents(projectAgentsDir);
     const dir = target.dir(projectRoot);
-    const targetDirRel = path.relative(agentRoot, dir);
-    const hadManagedTarget = manifest?.paths.some((rel) => rel === targetDirRel || rel.startsWith(targetDirRel + path.sep)) ?? false;
+    const targetDirRel = toPosixRel(path.relative(agentRoot, dir));
+    const hadManagedTarget = manifest?.paths.some((rel) => rel === targetDirRel || rel.startsWith(targetDirRel + '/')) ?? false;
     for (const sub of all.values()) {
         const occupied = target.occupied(dir, sub.name);
         const existing = occupied.find((entry) => pathExists(entry.path));
@@ -234,7 +246,10 @@ function syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, age
     if (target.finalize && (syncedNames.length > 0 || hadManagedTarget)) {
         target.finalize(dir, syncedNames);
         for (const entry of target.finalizeOccupied?.(dir) ?? []) {
-            manifestPaths.add(path.relative(agentRoot, entry.path));
+            // Same normalization as record(): this is the one manifest write that
+            // doesn't funnel through it (the parent subagent index, e.g. Kimi's
+            // agents/_agents-cli.yaml).
+            manifestPaths.add(toPosixRel(path.relative(agentRoot, entry.path)));
         }
     }
 }

package/dist/lib/shims.d.ts

@@ -508,6 +508,32 @@ export declare function addShimsToPath(overrides?: {
     shimsDir?: string;
 }): ShimPathResult;
 export declare function listAgentsWithInstalledVersions(): AgentId[];
+/**
+ * Thrown when an operation would carry an isolated-only agent across the isolation
+ * boundary. Callers that can explain the situation catch it and print guidance; the
+ * throw is what makes the boundary a property of the code rather than a convention
+ * every future call site has to remember.
+ */
+export declare class IsolationBoundaryError extends Error {
+    readonly agent: AgentId;
+    readonly operation: string;
+    constructor(agent: AgentId, operation: string);
+}
+/**
+ * True when EVERY installed version of `agent` is isolated (and at least one is).
+ *
+ * This is the switch: installing with `--isolated` is itself the act of opting in,
+ * so there is no mode to set and none to forget. It is per-agent, so an isolated
+ * codex constrains nothing about claude. And the escape hatch is inherent — remove
+ * the isolated copies and the agent is ordinary again, which means the state that
+ * grants protection is the same state you delete to drop it.
+ *
+ * An agent with any NORMAL version is not protected: that install already owns the
+ * launcher and the real `~/.<agent>`, so there is no boundary left to defend.
+ */
+export declare function isIsolationProtected(agent: AgentId): boolean;
+/** Refuse `operation` when `agent` is isolated-only. */
+export declare function assertIsolationBoundary(agent: AgentId, operation: string): void;
 export declare function listAgentsWithNonIsolatedInstalledVersions(): AgentId[];
 /**
  * Resource diff between two versions. Each field lists resources present in

package/dist/lib/shims.js

@@ -661,6 +661,9 @@ export function shimTargetsFor(platform) {
  * Create a shim for an agent.
  */
 export function createShim(agent) {
+    // A bare shim puts agents-cli first on PATH for this agent — the opposite of what
+    // an isolated-only install promises.
+    assertIsolationBoundary(agent, 'create the bare shim');
     ensureAgentsDir();
     const shimsDir = getShimsDir();
     const agentConfig = AGENTS[agent];
@@ -1322,6 +1325,8 @@ export function carryForwardAuthFiles(agent, toConfigDir) {
     }
 }
 export async function switchConfigSymlink(agent, version) {
+    // Moves the user's real ~/.<agent> aside and symlinks it into a version home.
+    assertIsolationBoundary(agent, 'repoint your real config directory');
     const configPath = getAgentConfigPath(agent);
     const versionConfigPath = getVersionConfigPath(agent, version);
     // Ensure version config directory exists
@@ -1426,6 +1431,8 @@ export async function switchConfigSymlink(agent, version) {
  * ALL installed versions so they inherit the current account.
  */
 export function switchHomeFileSymlinks(agent, version) {
+    // Same, for home-level files such as ~/.claude.json.
+    assertIsolationBoundary(agent, 'repoint your home-level config files');
     const agentConfig = AGENTS[agent];
     const homeFiles = agentConfig.homeFiles;
     if (!homeFiles || homeFiles.length === 0)
@@ -2076,6 +2083,9 @@ function canonicalOrNull(p) {
  * - Never records our own shim as the "original" (would loop).
  */
 export function adoptShadowingLauncher(agent, overrides) {
+    // Repoints the user's OWN launcher symlink at our shim — the most invasive thing
+    // in the codebase, and the one with no isolated-scoped equivalent at all.
+    assertIsolationBoundary(agent, 'adopt your launcher');
     const shimsDir = overrides?.shimsDir ?? getShimsDir();
     const shimPath = path.join(shimsDir, AGENTS[agent].cliCommand);
     const shimReal = canonical(shimPath);
@@ -2431,6 +2441,64 @@ export function listAgentsWithInstalledVersions() {
 function isInstalledVersionIsolated(agent, version) {
     return fs.existsSync(path.join(getVersionsDir(), agent, version, '.isolated'));
 }
+/**
+ * Thrown when an operation would carry an isolated-only agent across the isolation
+ * boundary. Callers that can explain the situation catch it and print guidance; the
+ * throw is what makes the boundary a property of the code rather than a convention
+ * every future call site has to remember.
+ */
+export class IsolationBoundaryError extends Error {
+    agent;
+    operation;
+    constructor(agent, operation) {
+        super(`${agent} is installed only as isolated copies; "${operation}" would adopt it into your local setup.`);
+        this.agent = agent;
+        this.operation = operation;
+        this.name = 'IsolationBoundaryError';
+    }
+}
+/**
+ * True when EVERY installed version of `agent` is isolated (and at least one is).
+ *
+ * This is the switch: installing with `--isolated` is itself the act of opting in,
+ * so there is no mode to set and none to forget. It is per-agent, so an isolated
+ * codex constrains nothing about claude. And the escape hatch is inherent — remove
+ * the isolated copies and the agent is ordinary again, which means the state that
+ * grants protection is the same state you delete to drop it.
+ *
+ * An agent with any NORMAL version is not protected: that install already owns the
+ * launcher and the real `~/.<agent>`, so there is no boundary left to defend.
+ */
+export function isIsolationProtected(agent) {
+    const agentVersionsDir = path.join(getVersionsDir(), agent);
+    let dirs;
+    try {
+        dirs = fs.readdirSync(agentVersionsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return false;
+    }
+    // Count only directories that are actually an install. A bare version dir is
+    // scaffolding, not a non-isolated version — and treating it as one would disable
+    // protection at exactly the wrong moment: an adopting path that does
+    // `mkdirSync(<version>/home)` before adopting would flip this to false with its own
+    // first line and then walk straight through the gates. Ignoring scaffolding biases
+    // the predicate toward protecting, which is the safe direction to fail in.
+    const installed = dirs.filter((v) => {
+        const dir = path.join(agentVersionsDir, v);
+        return fs.existsSync(path.join(dir, 'node_modules')) || fs.existsSync(path.join(dir, 'package.json'));
+    });
+    if (installed.length === 0)
+        return false;
+    return installed.every((v) => isInstalledVersionIsolated(agent, v));
+}
+/** Refuse `operation` when `agent` is isolated-only. */
+export function assertIsolationBoundary(agent, operation) {
+    if (isIsolationProtected(agent))
+        throw new IsolationBoundaryError(agent, operation);
+}
 export function listAgentsWithNonIsolatedInstalledVersions() {
     const versionsDir = getVersionsDir();
     if (!fs.existsSync(versionsDir)) {

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

@@ -41,6 +41,7 @@ export declare const loadWorkflows: ModuleLoader;
 export declare const loadWorktree: ModuleLoader;
 export declare const loadVersions: ModuleLoader;
 export declare const loadImport: ModuleLoader;
+export declare const loadExport: ModuleLoader;
 export declare const loadPackages: ModuleLoader;
 export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;

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

@@ -19,6 +19,7 @@ export const loadWorkflows = async () => (await import('../../commands/workflows
 export const loadWorktree = async () => (await import('../../commands/worktree.js')).registerWorktreeCommands;
 export const loadVersions = async () => (await import('../../commands/versions.js')).registerVersionsCommands;
 export const loadImport = async () => (await import('../../commands/import.js')).registerImportCommand;
+export const loadExport = async () => (await import('../../commands/export.js')).registerExportCommand;
 export const loadPackages = async () => (await import('../../commands/packages.js')).registerPackagesCommands;
 export const loadRoutines = async () => (await import('../../commands/routines.js')).registerRoutinesCommands;
 export const loadMonitors = async () => (await import('../../commands/monitors.js')).registerMonitorsCommands;
@@ -127,6 +128,7 @@ export const COMMAND_LOADERS = {
     purge: [loadVersions],
     prune: [loadVersions, loadPrune],
     import: [loadImport],
+    export: [loadExport],
     registry: [loadPackages],
     search: [loadPackages],
     install: [loadPackages],