@phnx-labs/agents-cli 1.22.41 → 1.22.42

package/dist/lib/harness/adapters/opencode.js

@@ -0,0 +1,14 @@
+// OpenCode has no exec-time config-dir env pin (buildExecEnv's `else` strips the
+// foreign keys — the registry fallback preserves that). It reads config-directory
+// resources from OPENCODE_CONFIG_DIR, pinned in the generated shim.
+export const opencodeAdapter = {
+    id: 'opencode',
+    shimConfigEnvBash() {
+        return `
+# OpenCode reads plugins, agents, commands, and other config-directory
+# resources from OPENCODE_CONFIG_DIR. Point it at the versioned global config
+# tree where agents-cli syncs OpenCode resources.
+export OPENCODE_CONFIG_DIR="$VERSION_DIR/home/.config/opencode"
+`;
+    },
+};

package/dist/lib/harness/exec-config-version.d.ts

@@ -0,0 +1,8 @@
+import type { AgentId } from '../types.js';
+export interface ResolvedConfigVersion {
+    /** The version to pin, or null when unresolved / not installed. */
+    version: string | null;
+    /** The version home for that version, or null. */
+    versionHome: string | null;
+}
+export declare function resolveConfigVersion(agent: AgentId, cwd: string, optionsVersion?: string): ResolvedConfigVersion;

package/dist/lib/harness/exec-config-version.js

@@ -0,0 +1,22 @@
+/**
+ * Shared version resolution for the exec-time config-dir env pin. Every
+ * config-dir harness branch in the old buildExecEnv computed this identically:
+ * an explicit `--version` is used unconditionally; an auto-resolved version is
+ * only pinned when it is actually installed on disk.
+ *
+ * The caller (buildExecEnv) invokes this and passes the result into the adapter
+ * via ExecConfigEnvCtx — the adapters MUST NOT import installations/versions
+ * themselves, because that module imports shims.ts and shims.ts imports the
+ * harness barrel, which would close an import cycle (versions → shims → harness →
+ * adapter → versions). That cycle forced esbuild/tsx to emit CJS for part of the
+ * graph and broke sqlite.ts's top-level await in subprocess-spawning tests.
+ */
+import { getVersionHomePath, isVersionInstalled, resolveVersion } from '../installations/versions.js';
+export function resolveConfigVersion(agent, cwd, optionsVersion) {
+    const resolvedVersion = optionsVersion ?? resolveVersion(agent, cwd);
+    const version = optionsVersion
+        ? resolvedVersion
+        : (resolvedVersion && isVersionInstalled(agent, resolvedVersion) ? resolvedVersion : null);
+    const versionHome = version ? getVersionHomePath(agent, version) : null;
+    return { version: version ?? null, versionHome };
+}

package/dist/lib/harness/index.d.ts

@@ -0,0 +1 @@
+export { type HarnessAdapter, type ExecConfigEnvCtx, type ShimConfigEnvCtx, type ExecLaunchArgsCtx, type RoutineLaunchCtx, CONFIG_DIR_ENV_KEYS, stripForeignConfigDir, registerHarnessAdapter, resolveHarnessAdapter, listHarnessAdapters, } from './adapter.js';

package/dist/lib/harness/index.js

@@ -0,0 +1,34 @@
+/**
+ * Harness adapter barrel — importing this registers every built-in adapter, the
+ * same pattern as lib/channels/providers/index.ts. Consumers import
+ * `resolveHarnessAdapter` from here (not from ./adapter.js directly) so the
+ * registration side-effect has run before the first resolve.
+ *
+ * A harness with no config-env / launch quirks needs no adapter file: every
+ * `AgentId` still resolves (to the id-only default), so call sites never
+ * name-check a harness.
+ */
+import { registerHarnessAdapter } from './adapter.js';
+import { claudeAdapter } from './adapters/claude.js';
+import { codexAdapter } from './adapters/codex.js';
+import { copilotAdapter } from './adapters/copilot.js';
+import { kimiAdapter } from './adapters/kimi.js';
+import { museAdapter } from './adapters/muse.js';
+import { cursorAdapter } from './adapters/cursor.js';
+import { grokAdapter } from './adapters/grok.js';
+import { opencodeAdapter } from './adapters/opencode.js';
+import { droidAdapter } from './adapters/droid.js';
+for (const adapter of [
+    claudeAdapter,
+    codexAdapter,
+    copilotAdapter,
+    kimiAdapter,
+    museAdapter,
+    cursorAdapter,
+    grokAdapter,
+    opencodeAdapter,
+    droidAdapter,
+]) {
+    registerHarnessAdapter(adapter);
+}
+export { CONFIG_DIR_ENV_KEYS, stripForeignConfigDir, registerHarnessAdapter, resolveHarnessAdapter, listHarnessAdapters, } from './adapter.js';

package/dist/lib/{hooks.d.ts → hooks/install.d.ts}

@@ -28,7 +28,7 @@ export declare function toPortableCommand(absPath: string, home?: string, sep?:
  * outside version homes are user-owned and remain untouched.
  */
 export declare function deduplicateVersionHookCommands(commands: string[], activeVersionHome: string): string[];
-import type { AgentId, HookCacheConfig, HookMatches, InstalledHook, ManifestHook } from './types.js';
+import type { AgentId, HookCacheConfig, HookMatches, InstalledHook, ManifestHook } from '../types.js';
 export type HookEntry = {
     name: string;
     scriptPath: string;

package/dist/lib/{hooks.js → hooks/install.js}

@@ -16,10 +16,10 @@ import * as TOML from 'smol-toml';
 import { execFile, execFileSync } from 'child_process';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
-import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
-import { supports, explainSkip, capableAgents } from './capabilities.js';
-import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPerfDir } from './state.js';
-import { collectSubruleHooksFromState } from './rules/compose.js';
+import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from '../agents.js';
+import { supports, explainSkip, capableAgents } from '../capabilities.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPerfDir } from '../state.js';
+import { collectSubruleHooksFromState } from '../rules/compose.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
 /**
  * Resolve a hook script's absolute path. Checks user dir first, then enabled
@@ -267,9 +267,9 @@ function collapseVersionHookEntries(entries, activeVersionHome) {
         return true;
     });
 }
-import { getEffectiveHome, getGlobalDefault, getVersionHomePath, isVersionIsolated, listInstalledVersions, resolveVersion, } from './installations/versions.js';
-import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
-import { getHookShimsDir } from './state.js';
+import { getEffectiveHome, getGlobalDefault, getVersionHomePath, isVersionIsolated, listInstalledVersions, resolveVersion, } from '../installations/versions.js';
+import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './cache.js';
+import { getHookShimsDir } from '../state.js';
 function hookContentHash(scriptPath) {
     return crypto.createHash('sha256').update(fs.readFileSync(scriptPath)).digest('hex');
 }
@@ -3250,13 +3250,13 @@ function registerHooksForHermes(versionHome, manifest, resolveScript, managedPre
 const execFileAsync = promisify(execFile);
 function resolveSessionTrackerRoot() {
     const here = path.dirname(fileURLToPath(import.meta.url));
-    // Built/installed layout: dist/lib/ -> dist/session-tracker
-    const built = path.resolve(here, '..', 'session-tracker');
+    // Built/installed layout: dist/lib/hooks/ -> dist/session-tracker
+    const built = path.resolve(here, '..', '..', 'session-tracker');
     if (fs.existsSync(path.join(built, 'dist', 'hook.sh'))) {
         return built;
     }
-    // Source layout: apps/cli/src/lib/ -> repo root -> packages/session-tracker
-    const source = path.resolve(here, '..', '..', '..', '..', 'packages', 'session-tracker');
+    // Source layout: apps/cli/src/lib/hooks/ -> repo root -> packages/session-tracker
+    const source = path.resolve(here, '..', '..', '..', '..', '..', 'packages', 'session-tracker');
     if (fs.existsSync(path.join(source, 'src', 'hook.sh'))) {
         return source;
     }

package/dist/lib/import.js

@@ -22,7 +22,7 @@ import * as path from 'path';
 import { AGENTS, resolveNativeBinaryPath } from './agents.js';
 import { getUserAgentsDir, getVersionsDir } from './state.js';
 import { setGlobalDefault } from './installations/versions.js';
-import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks, assertIsolationBoundary } from './shims.js';
+import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks, assertIsolationBoundary } from './installations/shims.js';
 const IMPORT_VERSION_RE = /^(?:latest|[A-Za-z0-9._+-]{1,64})$/;
 export function isValidImportVersion(version) {
     return IMPORT_VERSION_RE.test(version);

package/dist/lib/installations/index.d.ts

@@ -7,8 +7,8 @@
  * it, so the internal split can change without breaking callers (the Cursor
  * per-installation isolation track consumes exactly this).
  */
-export { INSTALLATION_RECORD_FILE, INSTALLATION_SCHEMA, type Installation, type InstallationRelease, type UpdateOutcome, type UpdateStrategyId, } from './types.js';
-export { createInstallation, ensureInstallation, installationDir, installationRecordPath, listInstallationLabels, listInstallations, mintInstallationId, readInstallation, recordRelease, writeInstallation, } from './store.js';
-export { InstallationAmbiguousError, InstallationNotFoundError, describeInstallation, resolveInstallation, type ResolveInstallationOptions, } from './resolve.js';
-export { assertValidRelease, selectUpdateStrategy, supportsPinnedUpdate, type UpdateStrategy, } from './strategies.js';
+export { type Installation, type InstallationRelease, type UpdateOutcome, type UpdateStrategyId, } from './types.js';
+export { createInstallation, listInstallations, recordRelease, } from './store.js';
+export { describeInstallation, resolveInstallation, type ResolveInstallationOptions, } from './resolve.js';
+export { selectUpdateStrategy, supportsPinnedUpdate, type UpdateStrategy, } from './strategies.js';
 export { updateInstallation, type UpdateInstallationOptions } from './update.js';

package/dist/lib/installations/index.js

@@ -7,8 +7,7 @@
  * it, so the internal split can change without breaking callers (the Cursor
  * per-installation isolation track consumes exactly this).
  */
-export { INSTALLATION_RECORD_FILE, INSTALLATION_SCHEMA, } from './types.js';
-export { createInstallation, ensureInstallation, installationDir, installationRecordPath, listInstallationLabels, listInstallations, mintInstallationId, readInstallation, recordRelease, writeInstallation, } from './store.js';
-export { InstallationAmbiguousError, InstallationNotFoundError, describeInstallation, resolveInstallation, } from './resolve.js';
-export { assertValidRelease, selectUpdateStrategy, supportsPinnedUpdate, } from './strategies.js';
+export { createInstallation, listInstallations, recordRelease, } from './store.js';
+export { describeInstallation, resolveInstallation, } from './resolve.js';
+export { selectUpdateStrategy, supportsPinnedUpdate, } from './strategies.js';
 export { updateInstallation } from './update.js';

package/dist/lib/installations/migrate.js

@@ -23,7 +23,7 @@ import { evaluateActivationReadiness } from '../routine-readiness.js';
 import { migrateDeviceConfigStores } from '../devices/config-migration.js';
 // Two constants only, never the read/write API — migrations still operate on raw
 // YAML so they never take the meta lock or prime the meta cache mid-migration.
-import { DEFAULT_BROWSER_PROFILE_NAME } from '../browser/profiles.js';
+import { LEGACY_DEFAULT_BROWSER_PROFILE_NAME } from '../browser/profiles.js';
 import { META_HEADER as DEVICE_META_HEADER } from '../state.js';
 import { COMPILED_HEADER_PROJECT } from '../rules/compile.js';
 const HOME = process.env.HOME ?? os.homedir();
@@ -1763,7 +1763,7 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
     const browser = central.browser;
     if (!browser || typeof browser !== 'object' || Array.isArray(browser))
         return;
-    const entry = browser[DEFAULT_BROWSER_PROFILE_NAME];
+    const entry = browser[LEGACY_DEFAULT_BROWSER_PROFILE_NAME];
     if (entry === undefined)
         return;
     // Device file first — a crash before central is rewritten leaves a harmless
@@ -1777,15 +1777,15 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
     const deviceBrowser = (deviceDoc.browser && typeof deviceDoc.browser === 'object' && !Array.isArray(deviceDoc.browser))
         ? deviceDoc.browser
         : {};
-    if (deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] === undefined) {
-        deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] = entry;
+    if (deviceBrowser[LEGACY_DEFAULT_BROWSER_PROFILE_NAME] === undefined) {
+        deviceBrowser[LEGACY_DEFAULT_BROWSER_PROFILE_NAME] = entry;
         deviceDoc.browser = deviceBrowser;
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
         atomicWriteFileSync(devicePath, DEVICE_META_HEADER + yaml.stringify(deviceDoc));
     }
     // Then strip it from the synced file, dropping `browser:` entirely when the
     // machine-local entry was its only member.
-    doc.deleteIn(['browser', DEFAULT_BROWSER_PROFILE_NAME]);
+    doc.deleteIn(['browser', LEGACY_DEFAULT_BROWSER_PROFILE_NAME]);
     if (Object.keys(browser).length === 1) {
         const itemsOf = () => (doc.contents?.items) ?? [];
         const idx = itemsOf().findIndex((pair) => pair.key?.value === 'browser');
@@ -1806,7 +1806,7 @@ export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR
     // the identical case (state.ts, `isEmpty ? META_HEADER : stringifyDoc(doc)`).
     const remaining = Object.keys(doc.toJSON() ?? {}).length;
     atomicWriteFileSync(metaFile, remaining === 0 ? DEVICE_META_HEADER : stringifyDoc(doc));
-    console.error(`Migrated agents.yaml: browser '${DEFAULT_BROWSER_PROFILE_NAME}' profile -> devices/${machine}/agents.yaml`);
+    console.error(`Migrated agents.yaml: browser '${LEGACY_DEFAULT_BROWSER_PROFILE_NAME}' profile -> devices/${machine}/agents.yaml`);
 }
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`

package/dist/lib/{shims.d.ts → installations/shims.d.ts}

@@ -1,5 +1,5 @@
-import type { AgentId } from './types.js';
-import { getShimsDir } from './state.js';
+import type { AgentId } from '../types.js';
+import { getShimsDir } from '../state.js';
 export { getShimsDir };
 /**
  * Strategy for handling file conflicts during config migration.

package/dist/lib/{shims.js → installations/shims.js}

@@ -13,12 +13,12 @@ import * as path from 'path';
 import * as os from 'os';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
-import { IS_WINDOWS, prependToWindowsUserPath } from './platform/index.js';
-import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgentsDir } from './state.js';
+import { IS_WINDOWS, prependToWindowsUserPath } from '../platform/index.js';
+import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgentsDir } from '../state.js';
 export { getShimsDir };
-import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from './agents.js';
-import { codexHomeShimBash } from './codex-home.js';
-import { codexPolicyArgs } from './codex-policy.js';
+import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from '../agents.js';
+import { codexHomeShimBash } from '../codex-home.js';
+import { resolveHarnessAdapter } from '../harness/index.js';
 /**
  * Files and directories to always skip during conflict detection and migration.
  * These are never user config that should be migrated.
@@ -296,52 +296,8 @@ const GROK_RESOLVE_BINARY_FN = `_resolve_grok_binary() {
   done
   printf '%s\\n' "$best"
 }`;
-function codexShimLaunchArgs() {
-    return [
-        '-c',
-        'check_for_update_on_startup=false',
-        ...codexPolicyArgs('edit'),
-    ].map(shellQuote).join(' ');
-}
-/**
- * The `exec` tail for a generated shim. For most agents this is a plain
- * `exec "$BINARY"<launchArgs> "$@"`.
- *
- * Codex is special: its `workspace-write` sandbox hardcodes any `.agents/` (and
- * `.codex/`) directory read-only, but agents-cli keeps every worktree at
- * `<repo>/.agents/worktrees/<slug>`, so an in-repo build under a static
- * shim would hit `EROFS`. The `agents run codex` path fixes this by adding
- * `<repo>/.agents` to the profile's `workspace_roots` (see codexEditWritableRoots
- * / repoAgentsDirForCwd), but a static shim has no cwd at generation time. So the
- * shim resolves the repo's `.agents` from `$PWD` at RUN time — worktree-aware,
- * mirroring repoAgentsDirForCwd — and passes it via Codex's own `--add-dir`
- * (verified to compose with the `agents-edit` profile). The resolution is inline
- * bash because the shim is the launch hot path and must not spawn Node to compute
- * one directory. `--add-dir` is added only when the resolved `.agents` exists.
- */
-function shimExecTail(agent, launchArgs) {
-    if (agent !== 'codex')
-        return `exec "$BINARY"${launchArgs} "$@"`;
-    return `_repo_agents=""
-case "$PWD" in
-  */.agents/worktrees/*) _repo_agents="\${PWD%%/.agents/worktrees/*}/.agents" ;;
-  *)
-    _d="$PWD"
-    # Stop before $HOME so a dotfiles repo at $HOME is not treated as the project
-    # root (mirrors repoRootForCwd's home exclusion in project-key.ts).
-    while [ -n "$_d" ] && [ "$_d" != "/" ] && [ "$_d" != "$HOME" ]; do
-      if [ -e "$_d/.git" ]; then _repo_agents="$_d/.agents"; break; fi
-      _d=$(dirname "$_d")
-    done
-    ;;
-esac
-if [ -n "$_repo_agents" ] && [ -d "$_repo_agents" ]; then
-  exec "$BINARY"${launchArgs} --add-dir "$_repo_agents" "$@"
-fi
-exec "$BINARY"${launchArgs} "$@"`;
-}
 function getAgentsBinForGeneratedShim() {
-    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'index.js');
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'index.js');
 }
 /**
  * Generate the full bash shim script for the given agent. The returned string
@@ -356,66 +312,8 @@ export function generateShimScript(agent) {
     // subpath so per-version HOME symlinks reach the right place.
     const configDirName = path.relative(os.homedir(), agentConfig.configDir);
     const agentsBin = shellQuote(getAgentsBinForGeneratedShim());
-    const managedEnv = agent === 'claude'
-        ? `
-# Claude stores OAuth credentials in the macOS keychain. Scope them to the
-# selected version's config directory so switching versions also switches the
-# live Claude account.
-export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
-# Managed installs are pinned in a per-version dir; Claude Code's background
-# auto-updater would rewrite the pinned binary in place. Disable it so a pin
-# stays a pin. An explicit user value always wins.
-export DISABLE_AUTOUPDATER="\${DISABLE_AUTOUPDATER:-1}"
-# On Linux sandboxes (no keychain), fall back to a per-version token file.
-# The env var always wins if already set; no-op on macOS.
-if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -f "\$CLAUDE_CONFIG_DIR/.oauth_token" ]; then
-  CLAUDE_CODE_OAUTH_TOKEN=\$(cat "\$CLAUDE_CONFIG_DIR/.oauth_token")
-  export CLAUDE_CODE_OAUTH_TOKEN
-fi
-`
-        : agent === 'codex'
-            ? codexHomeShimBash(`$VERSION_DIR/home/${configDirName}`, `$AGENTS_USER_DIR/.codex-homes/$VERSION`)
-            : agent === 'copilot'
-                ? `
-# GitHub Copilot CLI honors COPILOT_HOME to relocate its config and state
-# (settings.json, mcp-config.json, session-state/, logs/, plugins/). Point
-# it at the versioned home so MCP servers, custom agents, and session
-# history are isolated per copilot version.
-export COPILOT_HOME="$VERSION_DIR/home/${configDirName}"
-`
-                : agent === 'grok'
-                    ? `
-# Grok Build uses GROK_HOME to isolate its entire configuration tree
-# (skills, hooks, plugins, agents, memory, sessions, config.toml, MCP, etc.).
-# This gives agents-cli full versioned isolation + resource sync for grok.
-export GROK_HOME="$VERSION_DIR/home/.grok"
-`
-                    : agent === 'opencode'
-                        ? `
-# OpenCode reads plugins, agents, commands, and other config-directory
-# resources from OPENCODE_CONFIG_DIR. Point it at the versioned global config
-# tree where agents-cli syncs OpenCode resources.
-export OPENCODE_CONFIG_DIR="$VERSION_DIR/home/.config/opencode"
-`
-                        : agent === 'kimi'
-                            ? `
-# Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
-# mcp.json, sessions, skills, hooks). Point it at the versioned home.
-export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
-`
-                            : agent === 'muse'
-                                ? `
-# Muse Code has no MUSE_CONFIG_DIR. It resolves config via XDG:
-#   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
-#   $XDG_DATA_HOME/muse    (sessions, plugins)
-# Pin XDG into the version home so managed runs never walk the adopt-time
-# ~/.config/muse -> version-home symlink — Muse refuses agent-definition
-# sources that are SymlinkOrReparse (exit 1). Same idea as CLAUDE_CONFIG_DIR.
-export XDG_CONFIG_HOME="$VERSION_DIR/home/.config"
-export XDG_DATA_HOME="$VERSION_DIR/home/.local/share"
-`
-                                : '';
-    const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
+    const managedEnv = resolveHarnessAdapter(agent).shimConfigEnvBash?.({ configDirName }) ?? '';
+    const launchArgs = resolveHarnessAdapter(agent).shimLaunchArgs?.() ?? '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # Shim for ${agentConfig.name}
@@ -831,7 +729,7 @@ if [ "\$LAUNCH_SKIP" = "0" ]; then
   "\$AGENTS_BIN" sync --agent "\$AGENT" --agent-version "\$VERSION" --launch --cwd "\$PWD" --quiet 2>/dev/null || true
 fi
 
-${shimExecTail(agent, launchArgs)}
+${resolveHarnessAdapter(agent).shimExecTail?.(launchArgs) ?? `exec "$BINARY"${launchArgs} "$@"`}
 `;
 }
 /**
@@ -1145,7 +1043,7 @@ export XDG_DATA_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.
 export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
 `
                                     : '';
-    const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
+    const launchArgs = resolveHarnessAdapter(agent).shimLaunchArgs?.() ?? '';
     // Resolve the binary the same way the main shim does (see generateShimScript).
     // Grok and Droid do NOT ship into node_modules/.bin — Grok downloads a native
     // binary to ~/.grok/downloads and Droid (Factory AI) installs a standalone
@@ -1231,7 +1129,7 @@ if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
 fi
 ${managedEnv}
 
-${shimExecTail(agent, launchArgs)}
+${resolveHarnessAdapter(agent).shimExecTail?.(launchArgs) ?? `exec "$BINARY"${launchArgs} "$@"`}
 `;
 }
 /**
@@ -1639,7 +1537,7 @@ export async function switchConfigSymlink(agent, version) {
             // Dynamic import so loading shims.ts doesn't transitively open the
             // sessions DB — many tests partially mock state.js and would break.
             try {
-                const { updateSessionFilePaths } = await import('./session/db.js');
+                const { updateSessionFilePaths } = await import('../session/db.js');
                 updateSessionFilePaths(configPath, finalBackupPath);
             }
             catch (err) {

package/dist/lib/installations/store.d.ts

@@ -10,10 +10,12 @@ import { type Installation } from './types.js';
  * follow. It is also why the file name is registered in versions.ts's
  * `PRESERVED_ON_CLEAN_REINSTALL` — a repair reinstall must not mint a new id.
  *
- * Deliberately depends on nothing but `state`/`fs-atomic`/`primitives` so
- * versions.ts can import it without an import cycle.
+ * Path/enumeration plus frozen installation records. Depends on Node builtins,
+ * installations-local modules, and base lib (`state`/`fs-atomic`/`primitives`/
+ * `agents`/`shims`/`platform`) — never `plugins/`, `rules/`, `session/`, or
+ * `devices/`, so those modules can import this file without an import cycle.
  */
-/** Directory holding one installation. Mirrors versions.ts `getVersionDir`. */
+/** Directory holding one installation. Same path as {@link getVersionDir}. */
 export declare function installationDir(agent: AgentId, label: string): string;
 export declare function installationRecordPath(agent: AgentId, label: string): string;
 /** Mint an opaque installation id. Random, never derived from the release. */
@@ -54,3 +56,139 @@ export declare function listInstallationLabels(agent: AgentId): string[];
  * that disappears mid-scan is skipped rather than failing the whole listing.
  */
 export declare function listInstallations(agent: AgentId): Installation[];
+/**
+ * Get the directory where a specific version is installed.
+ */
+export declare function getVersionDir(agent: AgentId, version: string): string;
+/**
+ * Pick the real grok binary among `grok-*` entries in `downloadsDir` when NO
+ * filename carries the pinned version string. Grok self-updates its binary in
+ * place while running under the shim, so a version-home's downloads dir can
+ * accumulate several `grok-*` files whose names have drifted away from that
+ * version-home's pinned version (RUSH-2459: on yosemite-s0, version-home
+ * `0.2.82` held `grok-1.0.0-linux-aarch64` after grok self-updated, plus a
+ * stale, unrelated 99-byte `grok-0.2.118-linux-aarch64` wrapper script that
+ * happened to sort alphabetically first).
+ *
+ * Never blindly take whatever `fs.readdirSync` returns first — that is exactly
+ * the bug this replaces. Instead: exclude anything under
+ * {@link MIN_GROK_BINARY_BYTES} (rejects wrapper/alias artifacts on size
+ * alone, no content sniffing needed) and, among the survivors, prefer the most
+ * recently modified — the file grok's self-updater actually wrote last.
+ * Returns null (fail loud, never guess) when nothing survives the size filter.
+ */
+export declare function resolveGrokFallbackBinary(downloadsDir: string): string | null;
+/**
+ * Get the binary path for a specific agent version.
+ */
+export declare function getBinaryPath(agent: AgentId, version: string): string;
+/**
+ * Does this agent resolve to ONE global binary that is the same file regardless
+ * of the `version` argument? (droid → always `~/.local/bin/droid`.) Computed
+ * generically by probing `getBinaryPath` with two distinct versions rather than
+ * hardcoding an agent id, so it stays correct if another global-binary agent is
+ * added.
+ *
+ * This is the narrower cousin of `isSelfUpdatingAgent`: every global-binary
+ * agent is self-updating, but grok is self-updating WITHOUT a global binary — it
+ * stores a real per-version binary copy under each version-home
+ * (`versions/grok/<v>/home/.grok/downloads/grok-<v>`), so its version-homes are
+ * genuinely distinct and must NOT be collapsed. Gate the single-binary
+ * collapse/live-version logic on THIS predicate; gate pin-refusal / "switch
+ * profile" copy on `isSelfUpdatingAgent`.
+ */
+export declare function isGlobalBinaryAgent(agent: AgentId): boolean;
+/** Drop the live-version cache (call after an install/remove that changes the
+ * running binary, e.g. `agents add droid@latest`). */
+export declare function invalidateLiveVersionCache(agent?: AgentId): void;
+/**
+ * Resolve the version the ONE globally-installed binary actually reports via
+ * `<cli> --version`, cached for {@link LIVE_VERSION_TTL_MS}. For a self-updating
+ * global-binary agent (droid) this is the single source of truth for "which
+ * version is installed" — the on-disk version-dir NAMES are just stale labels
+ * left behind by successive `agents add`/self-update cycles. Returns null when
+ * the binary isn't on PATH or the probe fails.
+ */
+export declare function getCliVersionFromPath(agent: AgentId): Promise<string | null>;
+export declare function getLiveVersion(agent: AgentId): Promise<string | null>;
+/**
+ * Synchronous, non-blocking read of the live-version cache — returns the value
+ * only if a recent {@link getLiveVersion} call already warmed it, else null.
+ * `listInstalledVersions` is sync and must not shell out, so it prefers this
+ * warm value (accurate) and otherwise falls back to the newest on-disk dir.
+ */
+export declare function getCachedLiveVersion(agent: AgentId): string | null;
+/**
+ * Get the isolated HOME directory for a specific agent version.
+ * Each version has its own config isolation (like jobs sandbox).
+ */
+export declare function getVersionHomePath(agent: AgentId, version: string): string;
+/**
+ * Check if a specific version is installed.
+ *
+ * Probes the actual launch binary (the same executable the shims run), not just
+ * the version dir or the node_modules/.bin/<cli> wrapper. For npm agents that
+ * means statting the package's real `bin` target (getPackageBinaryPath), so a
+ * present-but-gutted install (vendor auto-updater destroyed the binary) reports
+ * as NOT installed and `agents add` re-runs its install step to repair it.
+ */
+export declare function isVersionInstalled(agent: AgentId, version: string): boolean;
+/** Drop the installed-versions cache (call after install/remove mutations). */
+export declare function invalidateInstalledVersionsCache(agent?: AgentId): void;
+/**
+ * Choose the single canonical version-dir to represent a self-updating
+ * global-binary agent (droid). All its version dirs map to ONE binary, so
+ * exactly one is real; the rest are stale labels. Prefer, in order: the dir the
+ * live config symlink points at (what actually runs), the recorded global
+ * default, the live `--version` (when the cache is warm), else the newest dir.
+ * `versions` MUST be sorted ascending. Callers guarantee it is non-empty.
+ */
+export declare function pickCanonicalGlobalBinaryVersion(agent: AgentId, versions: string[]): string;
+/**
+ * List all installed versions for an agent (cached by versions-dir mtime).
+ *
+ * For a self-updating global-binary agent (droid) every version dir resolves to
+ * the SAME binary, so this collapses them to a single canonical entry — one
+ * install, one row in `agents view`, never the phantom set of semver dir names.
+ */
+export declare function listInstalledVersions(agent: AgentId): string[];
+/**
+ * Get the global default version for an agent.
+ */
+export declare function getGlobalDefault(agent: AgentId): string | null;
+/**
+ * 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;
+/**
+ * Mark an installed version as an isolated install (`agents add --isolated`).
+ *
+ * Isolated versions are fully self-contained: they never become the global
+ * default and never own the user's real `~/.<agent>` config directory. This
+ * flag is what keeps every "adopting" code path away from them.
+ */
+export declare function markVersionIsolated(agent: AgentId, version: string): void;
+/**
+ * Whether a version was installed as an isolated install (`agents add --isolated`).
+ *
+ * Used to exclude such versions from global-default promotion and from any
+ * flow that would touch the user's real `~/.<agent>` directory, and to gate the
+ * `--isolated` safety check on `agents remove`.
+ */
+export declare function isVersionIsolated(agent: AgentId, version: string): boolean;
+/**
+ * Get version specified in a project-root agents.yaml (not the user ~/.agents/.system/agents.yaml).
+ */
+export declare function getProjectVersion(agent: AgentId, startPath: string): string | null;
+/**
+ * Get the resolved version for an agent in the current context.
+ * Checks project manifest first, then global default.
+ */
+export declare function resolveVersion(agent: AgentId, projectPath?: string): string | null;
+/**
+ * Get the effective HOME directory for an agent.
+ * If version-managed with a resolved version, returns the version's home directory.
+ * Otherwise returns the real HOME.
+ */
+export declare function getEffectiveHome(agentId: AgentId): string;