@phnx-labs/agents-cli 1.20.73 → 1.20.74

package/dist/lib/state.js

@@ -606,18 +606,25 @@ function writeIfChanged(filePath, content) {
  * `agents:` / `versions:` are not written (no empty committed files).
  */
 function writeMetaUnlocked(meta) {
-    const { agents, versions, defaultBrowserProfile, ...central } = meta;
+    const { agents, isolatedAgents, versions, defaultBrowserProfile, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
     // never removes pins/versions from central before they're persisted elsewhere.
     const devicePath = getDeviceMetaPath();
     const hasAgents = !!agents && Object.keys(agents).length > 0;
+    // The isolated pointer names a version installed on THIS machine, exactly like a
+    // global pin, so it belongs beside `agents:` in the device file rather than in the
+    // central doc that syncs — otherwise another machine inherits a pointer to a copy
+    // it does not have.
+    const hasIsolatedAgents = !!isolatedAgents && Object.keys(isolatedAgents).length > 0;
     const hasDefaultBrowser = !!defaultBrowserProfile;
-    if (hasAgents || hasDefaultBrowser) {
+    if (hasAgents || hasIsolatedAgents || hasDefaultBrowser) {
         // Device-local doc carries `agents:` pins and `defaultBrowserProfile:` — both
         // are per-machine and must never land in central agents.yaml (which syncs).
         const deviceDoc = {};
         if (hasAgents)
             deviceDoc.agents = agents;
+        if (hasIsolatedAgents)
+            deviceDoc.isolatedAgents = isolatedAgents;
         if (hasDefaultBrowser)
             deviceDoc.defaultBrowserProfile = defaultBrowserProfile;
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
@@ -640,8 +647,9 @@ function writeMetaUnlocked(meta) {
 }
 /**
  * Overlay this machine's local state onto a central-portable Meta:
- *   - `agents:` from the device file (device wins; the union both preserves the
- *     one-level merge and self-heals a pre-migration central that still has pins)
+ *   - `agents:` and `isolatedAgents:` from the device file (device wins; the union
+ *     both preserves the one-level merge and self-heals a pre-migration central that
+ *     still has pins)
  *   - `defaultBrowserProfile:` from the device file (device is the sole source;
  *     the field is stripped from central on write, so nothing to merge against)
  *   - `versions:` from the history JSON (wholesale replace; falls back to
@@ -654,6 +662,8 @@ function overlayMachineLocal(meta) {
             const dm = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
             if (dm?.agents)
                 meta.agents = { ...meta.agents, ...dm.agents };
+            if (dm?.isolatedAgents)
+                meta.isolatedAgents = { ...meta.isolatedAgents, ...dm.isolatedAgents };
             if (dm?.defaultBrowserProfile)
                 meta.defaultBrowserProfile = dm.defaultBrowserProfile;
         }

package/dist/lib/types.d.ts

@@ -692,6 +692,17 @@ export interface BrandConfig {
 /** Top-level structure of ~/.agents/.system/agents.yaml -- the CLI's persistent state. */
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
+    /**
+     * Per-agent preferred ISOLATED version — which copy a bare `agents run <agent>`
+     * resolves to when the agent has no global default.
+     *
+     * Kept separate from `agents` on purpose. An entry there is the global default,
+     * which owns the launcher, the bare shim and the real `~/.<agent>` config
+     * symlink, and arms the self-heal `shadowing` check. An isolated copy must never
+     * acquire any of that, so it cannot be recorded in the same place — the
+     * separation is what keeps `getGlobalDefault` incapable of returning one.
+     */
+    isolatedAgents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
     /**
      * `agents run --lease` config. `secretsBundle` names the keychain secrets bundle

package/dist/lib/uninstall.js

@@ -20,6 +20,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS } from './agents.js';
 import { getAgentConfigPath, getConfigSymlinkVersion, stripShimPathLines, releaseAdoptedLauncher, } from './shims.js';
+import { moveDirCrossDevice, copyDirStrippingAgentsSymlinks } from './config-transfer.js';
 import { getUserAgentsDir, getBackupsDir, getHistoryDir, getShimsDir, getLegacySystemAgentsDir, } from './state.js';
 /** Home dir honoring the AGENTS_REAL_HOME test/override, mirroring shims.ts. */
 function realHome() {
@@ -60,51 +61,6 @@ function symlinkTarget(p) {
 function removeLink(p) {
     fs.unlinkSync(p);
 }
-/**
- * Move `source` onto `dest` across possibly-different volumes. `renameSync` is
- * atomic but throws EXDEV when `~/.agents` lives on a different filesystem than
- * `$HOME`; fall back to copy-then-remove so the restore still completes. The
- * source (a backup inside `~/.agents`) is removed only after the copy succeeds,
- * so a mid-copy failure never destroys the sole surviving copy.
- */
-function moveDirCrossDevice(source, dest) {
-    try {
-        fs.renameSync(source, dest);
-    }
-    catch (err) {
-        if (err.code !== 'EXDEV')
-            throw err;
-        fs.cpSync(source, dest, { recursive: true });
-        fs.rmSync(source, { recursive: true, force: true });
-    }
-}
-/**
- * Copy `source` to `dest`, dropping any symlink whose target resolves back into
- * `~/.agents`. Adoption syncs managed resources (skills/commands) into the
- * version home as symlinks into `~/.agents`; copying them verbatim would leave
- * the restored config full of links that dangle the moment `~/.agents` is
- * disposed. Stripping them yields a clean, self-contained restore.
- */
-function copyDirStrippingAgentsSymlinks(source, dest, agentsDir) {
-    const inside = agentsDir + path.sep;
-    fs.cpSync(source, dest, {
-        recursive: true,
-        filter: (src) => {
-            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 {
-                /* unreadable entry — let cpSync surface it on the real copy */
-            }
-            return true;
-        },
-    });
-}
 /** Classify one agent's config dir without mutating anything. */
 function planConfig(agent) {
     const realPath = getAgentConfigPath(agent);

package/dist/lib/versions.d.ts

@@ -216,6 +216,19 @@ export declare function getGlobalDefault(agent: AgentId): string | null;
  * Set the global default version for an agent.
  */
 export declare function setGlobalDefault(agent: AgentId, version: string | undefined): void;
+/**
+ * Get the preferred ISOLATED version for an agent — the copy a bare
+ * `agents run <agent>` falls back to when there is no global default.
+ */
+export declare function getIsolatedDefault(agent: AgentId): string | null;
+/**
+ * Set (or clear, with `undefined`) the preferred isolated version.
+ *
+ * Deliberately does NOT touch the launcher, the bare shim, the `~/.<agent>` config
+ * symlink or the global default — the five things `setDefaultVersion` does. This is
+ * a pointer inside the sandbox, so it stays inside the sandbox.
+ */
+export declare function setIsolatedDefault(agent: AgentId, version: string | undefined): void;
 /**
  * Mark an installed version as an isolated install (`agents add --isolated`).
  *

package/dist/lib/versions.js

@@ -32,7 +32,7 @@ import { VERSION_RE, compareVersions } from './agent-spec/primitives.js';
 import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath, isSelfUpdatingAgent } from './agents.js';
 import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { parseMcpServerConfig, isProjectMcpTrusted } from './mcp.js';
-import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
+import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, } from './shims.js';
 import { importInstallScriptBinary } from './import.js';
 import { IS_WINDOWS, composeWin32CommandLine } from './platform/index.js';
 import { listInstalledSubagents } from './subagents.js';
@@ -1186,6 +1186,14 @@ export function getGlobalDefault(agent) {
  * Set the global default version for an agent.
  */
 export function setGlobalDefault(agent, version) {
+    // A global default is what owns the launcher and arms the self-heal `shadowing`
+    // check, so recording one for an isolated-only agent is the root of the original
+    // breach. Clearing is always allowed — `removeVersion` legitimately clears a
+    // default as the last non-isolated version goes away, which is the very moment
+    // an agent BECOMES isolated-only.
+    if (version !== undefined) {
+        assertIsolationBoundary(agent, 'set a global default');
+    }
     const meta = readMeta();
     if (!meta.agents) {
         meta.agents = {};
@@ -1199,6 +1207,34 @@ export function setGlobalDefault(agent, version) {
     }
     writeMeta(meta);
 }
+/**
+ * Get the preferred ISOLATED version for an agent — the copy a bare
+ * `agents run <agent>` falls back to when there is no global default.
+ */
+export function getIsolatedDefault(agent) {
+    const meta = readMeta();
+    return meta.isolatedAgents?.[agent] || null;
+}
+/**
+ * Set (or clear, with `undefined`) the preferred isolated version.
+ *
+ * Deliberately does NOT touch the launcher, the bare shim, the `~/.<agent>` config
+ * symlink or the global default — the five things `setDefaultVersion` does. This is
+ * a pointer inside the sandbox, so it stays inside the sandbox.
+ */
+export function setIsolatedDefault(agent, version) {
+    const meta = readMeta();
+    if (!meta.isolatedAgents) {
+        meta.isolatedAgents = {};
+    }
+    if (version === undefined) {
+        delete meta.isolatedAgents[agent];
+    }
+    else {
+        meta.isolatedAgents[agent] = version;
+    }
+    writeMeta(meta);
+}
 /**
  * Path to the sentinel file that marks a version as an isolated install.
  *
@@ -1784,6 +1820,13 @@ export function removeVersion(agent, version) {
             console.log(chalk.yellow(`Removed the last non-isolated ${agent} version and cleared its default. Reinstall with: agents add ${agent}, then set one with: agents use ${agent}@<version>`));
         }
     }
+    // Same for the isolated pointer: a removed version must not stay the answer to a
+    // bare `agents run <agent>`. Prefer the newest remaining isolated copy so removing
+    // one of several does not silently drop the user back to their PATH binary.
+    if (getIsolatedDefault(agent) === version) {
+        const survivors = listInstalledVersions(agent).filter((v) => isVersionIsolated(agent, v));
+        setIsolatedDefault(agent, survivors.length > 0 ? survivors[survivors.length - 1] : undefined);
+    }
     // Clean up dangling config symlink if it pointed to the removed version
     const symlinkVersion = getConfigSymlinkVersion(agent);
     if (symlinkVersion === version) {
@@ -1855,7 +1898,23 @@ export function resolveVersion(agent, projectPath) {
         }
     }
     // Fall back to global default
-    return getGlobalDefault(agent);
+    const globalDefault = getGlobalDefault(agent);
+    if (globalDefault)
+        return globalDefault;
+    // Last resort: the preferred isolated copy. Strictly a fallback — a global
+    // default always wins, so nothing changes for anyone who has one. Without this,
+    // an isolated-only user cannot reach their installs by bare name at all: the
+    // resolution chain ended here, so `agents run codex` fell through to whatever
+    // `codex` meant on PATH, and only `agents run codex@<version>` worked.
+    //
+    // The pointer is verified on read. It survives in agents.yaml across a trash +
+    // restore cycle, but a version removed for good would otherwise leave a dangling
+    // pin that resolves to a directory that is not there.
+    const isolated = getIsolatedDefault(agent);
+    if (isolated && isVersionInstalled(agent, isolated) && isVersionIsolated(agent, isolated)) {
+        return isolated;
+    }
+    return null;
 }
 /**
  * Normalize a user-supplied @version token across CLI subcommands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.73",
+  "version": "1.20.74",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",