@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/shims.js

@@ -1,3 +1,13 @@
+/**
+ * Shim generation and config symlink management for agent version switching.
+ *
+ * Shims are small shell scripts placed in ~/.agents/shims/ that resolve the
+ * active agent version (project-level or user-default), then exec the real
+ * binary. Config isolation is achieved by symlinking ~/.{agent} into the
+ * per-version home directory. This module also handles versioned aliases
+ * (e.g., claude@2.0.65), PATH setup, conflict detection during migration,
+ * and resource diffing between versions.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -130,7 +140,7 @@ export async function promptConflictStrategy(conflictInfos) {
  * Generate the shim script content for an agent.
  *
  * The shim resolves the version in order:
- * 1. .agents-version in cwd (walk up to root)
+ * 1. agents.yaml in project root (walk up from $PWD, skip ~/.agents/agents.yaml)
  * 2. ~/.agents/agents.yaml default
  *
  * If version is specified but not installed, auto-installs it.
@@ -150,9 +160,21 @@ export async function promptConflictStrategy(conflictInfos) {
  *        shim hook for non-@-capable agents.
  *   v3 — sync/refresh-memory flag renamed `--version` → `--agent-version`
  *        so it no longer collides with commander's top-level `--version`.
+ *   v4 — project version marker changed from `.agents-version` to a
+ *        root-level `agents.yaml`; shim now skips ~/.agents/agents.yaml
+ *        when walking up for a project marker.
+ *   v5 — emit CODEX_HOME for codex shims so the versioned config (permissions,
+ *        sandbox_mode, rules/agents-deny.rules) is actually read by the codex
+ *        binary instead of $HOME/.codex.
+ *   v6 — hard-disable Codex startup update checks in the generated shims.
  */
-export const SHIM_SCHEMA_VERSION = 3;
+export const SHIM_SCHEMA_VERSION = 6;
+/** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
+/**
+ * Generate the full bash shim script for the given agent. The returned string
+ * is written to ~/.agents/shims/{cliCommand} and made executable.
+ */
 export function generateShimScript(agent) {
     const agentConfig = AGENTS[agent];
     const cliCommand = agentConfig.cliCommand;
@@ -164,7 +186,14 @@ export function generateShimScript(agent) {
 # live Claude account.
 export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
 `
-        : '';
+        : agent === 'codex'
+            ? `
+# Codex reads its config (approval_policy, sandbox_mode, MCP servers, rules)
+# from CODEX_HOME. Point it at the versioned home so permissions/rules
+# written by agents-cli actually take effect.
+export CODEX_HOME="$VERSION_DIR/home/${configDirName}"
+`
+            : '';
     // Agents that don't natively resolve @-imports in their memory file need
     // agents-cli to recompile when the user edits a rule/preset file. The
     // check is fast (sha256 of ~8 small files) and skips the recompile when
@@ -177,39 +206,31 @@ export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
 agents refresh-memory --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/null || true
 `
         : '';
+    const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # Shim for ${agentConfig.name}
 # ${SHIM_VERSION_MARKER} ${SHIM_SCHEMA_VERSION}
 
-AGENTS_DIR="$HOME/.agents"
+AGENTS_SYSTEM_DIR="$HOME/.agents-system"
+AGENTS_USER_DIR="$HOME/.agents"
 AGENT="${agent}"
 CLI_COMMAND="${cliCommand}"
 
-# Find .agents-version walking up from cwd
+# Find project agents.yaml walking up from cwd (skip $HOME/.agents-system/agents.yaml)
 find_project_version() {
   local dir="$PWD"
+  local user_agents_yaml="$AGENTS_SYSTEM_DIR/agents.yaml"
   while [ "$dir" != "/" ]; do
-    if [ -f "$dir/.agents-version" ]; then
-      # Parse YAML - handle both "agent: version" and "agent:\\n  - version"
+    local candidate="$dir/agents.yaml"
+    if [ -f "$candidate" ] && [ "$candidate" != "$user_agents_yaml" ]; then
+      # Parse agents: section — same shape as resolve_default_version()
       local version
       version=$(awk -v agent="$AGENT" '
-        $0 ~ "^" agent ":" {
-          # Check if value is on same line
-          if (match($0, /:[[:space:]]+[0-9]/)) {
-            gsub(/.*:[[:space:]]*["'"'"']?|["'"'"']?[[:space:]]*$/, "")
-            print
-            exit
-          }
-          # Value might be on next line (array format)
-          getline
-          if (/^[[:space:]]+-[[:space:]]/) {
-            gsub(/^[[:space:]]+-[[:space:]]*["'"'"']?|["'"'"']?[[:space:]]*$/, "")
-            print
-            exit
-          }
-        }
-      ' "$dir/.agents-version")
+        /^agents:/ { in_agents=1; next }
+        in_agents && /^[^ ]/ { in_agents=0 }
+        in_agents && $0 ~ "^  " agent ":" { gsub(/.*:[[:space:]]*["'"'"']?|["'"'"']?[[:space:]]*$/, ""); print; exit }
+      ' "$candidate")
       if [ -n "$version" ]; then
         echo "$version"
         return 0
@@ -222,7 +243,7 @@ find_project_version() {
 
 # Resolve version from agents.yaml (user default)
 resolve_default_version() {
-  local meta="$AGENTS_DIR/agents.yaml"
+  local meta="$AGENTS_USER_DIR/agents.yaml"
   if [ -f "$meta" ]; then
     awk -v agent="$AGENT" '
       /^agents:/ { in_agents=1; next }
@@ -232,7 +253,7 @@ resolve_default_version() {
   fi
 }
 
-# Find project-scoped .agents directory (stop at .git or .agents-version)
+# Find project-scoped .agents directory (stop at agents.yaml or .git)
 find_project_agents_dir() {
   local dir="$PWD"
   while [ "$dir" != "/" ]; do
@@ -240,7 +261,7 @@ find_project_agents_dir() {
       echo "$dir/.agents"
       return 0
     fi
-    if [ -f "$dir/.agents-version" ] || [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then
+    if [ -f "$dir/agents.yaml" ] || [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then
       break
     fi
     dir=$(dirname "$dir")
@@ -262,13 +283,13 @@ if [ -z "$VERSION" ]; then
   exit 1
 fi
 
-VERSION_DIR="$AGENTS_DIR/versions/$AGENT/$VERSION"
+VERSION_DIR="$AGENTS_SYSTEM_DIR/versions/$AGENT/$VERSION"
 BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 
 # Auto-install if not present
 if [ ! -x "$BINARY" ]; then
   if [ "$VERSION_SOURCE" = "project" ]; then
-    echo "agents: $AGENT@$VERSION required by .agents-version but not installed" >&2
+    echo "agents: $AGENT@$VERSION required by agents.yaml but not installed" >&2
 
     # Spinner animation
     spin() {
@@ -309,7 +330,7 @@ if [ -n "$PROJECT_AGENTS_DIR" ]; then
 fi
 ${refreshMemoryCall}${managedEnv}
 
-exec "$BINARY" "$@"
+exec "$BINARY"${launchArgs} "$@"
 `;
 }
 /**
@@ -337,25 +358,64 @@ export function removeShim(agent) {
     }
     return false;
 }
+/**
+ * Current versioned-alias schema. Bump whenever `generateVersionedAliasScript`
+ * changes in a way that requires existing on-disk aliases to be regenerated.
+ *
+ * History:
+ *   v1 — implicit (no marker); no CLAUDE_CONFIG_DIR export, so direct
+ *        `claude@X` invocations leaked into ~/.claude (the default version's
+ *        symlinked home) and `agents view` never saw the login.
+ *   v2 — emit CLAUDE_CONFIG_DIR for claude aliases so each version has its
+ *        own isolated config/OAuth slot; stamp a version marker so stale
+ *        aliases can be detected and regenerated.
+ *   v3 — emit CODEX_HOME for codex aliases so direct `codex@X` invocations
+ *        read the versioned permissions/rules instead of $HOME/.codex.
+ *   v4 — direct aliases read binaries and config homes from ~/.agents-system.
+ *   v5 — hard-disable Codex startup update checks in versioned aliases.
+ */
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 5;
+/** Internal marker string used to embed the schema version in versioned alias scripts. */
+const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
+// The version string is interpolated into a generated bash script and into
+// a filename. parseAgentSpec / parseVersion already validates this upstream,
+// but generators are also called from internal code paths (e.g., re-emit on
+// schema bump), so re-check here. Mirrors VERSION_RE in versions.ts.
+const ALIAS_VERSION_RE = /^[A-Za-z0-9._+-]{1,64}$/;
+function assertSafeVersion(version) {
+    if (!ALIAS_VERSION_RE.test(version)) {
+        throw new Error(`Refusing to generate shim for unsafe version: ${JSON.stringify(version)}`);
+    }
+}
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
  */
 export function generateVersionedAliasScript(agent, version) {
+    assertSafeVersion(version);
     const agentConfig = AGENTS[agent];
     const configDirName = `.${agent}`;
     const managedEnv = agent === 'claude'
         ? `
 # Claude stores OAuth credentials in the macOS keychain. Scope them to this
 # version's config directory so direct aliases also switch the live account.
-export CLAUDE_CONFIG_DIR="$HOME/.agents/versions/${agent}/${version}/home/${configDirName}"
+export CLAUDE_CONFIG_DIR="$HOME/.agents-system/versions/${agent}/${version}/home/${configDirName}"
 `
-        : '';
+        : agent === 'codex'
+            ? `
+# Codex reads its config (approval_policy, sandbox_mode, MCP servers, rules)
+# from CODEX_HOME. Point direct aliases at the versioned home so permissions
+# and rules written by agents-cli actually take effect.
+export CODEX_HOME="$HOME/.agents-system/versions/${agent}/${version}/home/${configDirName}"
+`
+            : '';
+    const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
+# ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}
 # Direct alias for ${agentConfig.name}@${version}
 
-BINARY="$HOME/.agents/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
+BINARY="$HOME/.agents-system/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
 
 if [ ! -x "$BINARY" ]; then
   echo "agents: ${agent}@${version} not installed" >&2
@@ -363,14 +423,64 @@ if [ ! -x "$BINARY" ]; then
 fi
 ${managedEnv}
 
-exec "$BINARY" "$@"
+exec "$BINARY"${launchArgs} "$@"
 `;
 }
+/**
+ * Read the schema version of an on-disk versioned alias. Returns null if the
+ * alias doesn't exist or is a pre-v2 alias (no marker — treated as stale).
+ */
+export function readVersionedAliasSchemaVersion(agent, version) {
+    const aliasPath = getVersionedAliasPath(agent, version);
+    if (!fs.existsSync(aliasPath))
+        return null;
+    try {
+        const content = fs.readFileSync(aliasPath, 'utf8');
+        const header = content.split('\n', 10).join('\n');
+        const match = header.match(new RegExp(VERSIONED_ALIAS_VERSION_MARKER + '\\s*(\\d+)'));
+        if (!match)
+            return null;
+        return Number(match[1]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True if the on-disk versioned alias matches the current schema version.
+ */
+export function isVersionedAliasCurrent(agent, version) {
+    return readVersionedAliasSchemaVersion(agent, version) === VERSIONED_ALIAS_SCHEMA_VERSION;
+}
+/**
+ * Regenerate a versioned alias if missing or stale. Mirrors ensureShimCurrent
+ * for the main shim — callers can surface a one-line notice when something
+ * was upgraded.
+ */
+export function ensureVersionedAliasCurrent(agent, version) {
+    const aliasPath = getVersionedAliasPath(agent, version);
+    if (!fs.existsSync(aliasPath)) {
+        createVersionedAlias(agent, version);
+        return 'created';
+    }
+    if (!isVersionedAliasCurrent(agent, version)) {
+        createVersionedAlias(agent, version);
+        return 'updated';
+    }
+    return 'current';
+}
+/**
+ * Get the filesystem path for a versioned alias script.
+ */
+export function getVersionedAliasPath(agent, version) {
+    return path.join(getShimsDir(), `${AGENTS[agent].cliCommand}@${version}`);
+}
 /**
  * Create a versioned alias for a specific agent version.
  * e.g., claude@2.0.65
  */
 export function createVersionedAlias(agent, version) {
+    assertSafeVersion(version);
     ensureAgentsDir();
     const shimsDir = getShimsDir();
     const agentConfig = AGENTS[agent];
@@ -535,6 +645,15 @@ export function switchHomeFileSymlinks(agent, version) {
     const versionsDir = getVersionsDir();
     const switched = [];
     const errors = [];
+    // For Claude, Claude's binary reads CLAUDE_CONFIG_DIR/.claude.json (INSIDE
+    // the per-version .claude dir) — not the home-level file this function
+    // manages. Reconcile all installed Claude versions so INSIDE is a symlink
+    // to OUTSIDE, making OUTSIDE the single source of truth.
+    if (agent === 'claude') {
+        const reconcile = ensureAllClaudeInsideSymlinks();
+        for (const e of reconcile.errors)
+            errors.push(e);
+    }
     for (const fileName of homeFiles) {
         const globalPath = path.join(home, fileName);
         const versionFilePath = path.join(versionsDir, agent, version, 'home', fileName);
@@ -578,7 +697,14 @@ export function switchHomeFileSymlinks(agent, version) {
             else if (stat.isFile()) {
                 // Real file — first-time migration
                 // Read the global file content
-                const globalContent = JSON.parse(fs.readFileSync(globalPath, 'utf-8'));
+                let globalContent;
+                try {
+                    globalContent = JSON.parse(fs.readFileSync(globalPath, 'utf-8'));
+                }
+                catch (err) {
+                    errors.push(`${fileName}: Could not parse ${globalPath}: ${err.message}`);
+                    continue;
+                }
                 // Merge auth into ALL installed version files for this agent
                 const agentVersionsDir = path.join(versionsDir, agent);
                 if (fs.existsSync(agentVersionsDir)) {
@@ -623,6 +749,108 @@ export function switchHomeFileSymlinks(agent, version) {
     }
     return { switched, errors };
 }
+/**
+ * Claude reads `.claude.json` at `$CLAUDE_CONFIG_DIR/.claude.json`. Our shim
+ * points CLAUDE_CONFIG_DIR at `<ver>/home/.claude`, so Claude's real config
+ * file lives at `<ver>/home/.claude/.claude.json` (INSIDE), while
+ * `switchHomeFileSymlinks` manages `<ver>/home/.claude.json` (OUTSIDE).
+ *
+ * To keep both views consistent we make INSIDE a symlink to OUTSIDE. Claude's
+ * atomic write (`Uf6`) resolves symlinks before the tmp+rename cycle, so the
+ * symlink survives across writes and OUTSIDE remains the single source of
+ * truth that agents-cli's home-file machinery already manages.
+ *
+ * This function idempotently reconciles one version:
+ *   - INSIDE missing: create symlink -> `../.claude.json` (create OUTSIDE if needed).
+ *   - INSIDE already symlink to OUTSIDE: no-op.
+ *   - INSIDE is a real file: it's the authoritative auth state (Claude was
+ *     writing to it). Move its content to OUTSIDE (merging with OUTSIDE,
+ *     INSIDE wins for `oauthAccount`), then replace INSIDE with the symlink.
+ *   - Symlink points elsewhere: replace it.
+ */
+export function ensureClaudeInsideSymlink(version) {
+    const versionsDir = getVersionsDir();
+    const versionHome = path.join(versionsDir, 'claude', version, 'home');
+    const outsidePath = path.join(versionHome, '.claude.json');
+    const insideDir = path.join(versionHome, '.claude');
+    const insidePath = path.join(insideDir, '.claude.json');
+    const linkTarget = '../.claude.json'; // relative so version dir can be moved
+    if (!fs.existsSync(insideDir)) {
+        fs.mkdirSync(insideDir, { recursive: true });
+    }
+    let insideStat = null;
+    try {
+        insideStat = fs.lstatSync(insidePath);
+    }
+    catch {
+        /* INSIDE does not exist */
+    }
+    if (insideStat?.isSymbolicLink()) {
+        const currentTarget = fs.readlinkSync(insidePath);
+        if (currentTarget === linkTarget)
+            return;
+        // Wrong target — replace.
+        if (!fs.existsSync(outsidePath))
+            fs.writeFileSync(outsidePath, '{}');
+        fs.unlinkSync(insidePath);
+        fs.symlinkSync(linkTarget, insidePath);
+        return;
+    }
+    if (insideStat?.isFile()) {
+        // INSIDE is the authoritative file — Claude has been reading/writing it.
+        // Merge INSIDE into OUTSIDE, with INSIDE winning on every field, then
+        // replace INSIDE with a symlink.
+        let insideContent = {};
+        try {
+            insideContent = JSON.parse(fs.readFileSync(insidePath, 'utf-8'));
+        }
+        catch {
+            /* INSIDE corrupt — treat as empty; OUTSIDE preserved as-is */
+        }
+        let outsideContent = {};
+        if (fs.existsSync(outsidePath)) {
+            try {
+                outsideContent = JSON.parse(fs.readFileSync(outsidePath, 'utf-8'));
+            }
+            catch {
+                /* OUTSIDE corrupt — drop it */
+            }
+        }
+        const merged = { ...outsideContent, ...insideContent };
+        fs.writeFileSync(outsidePath, JSON.stringify(merged, null, 2));
+        fs.unlinkSync(insidePath);
+        fs.symlinkSync(linkTarget, insidePath);
+        return;
+    }
+    // INSIDE missing — ensure OUTSIDE exists, then create symlink.
+    if (!fs.existsSync(outsidePath))
+        fs.writeFileSync(outsidePath, '{}');
+    fs.symlinkSync(linkTarget, insidePath);
+}
+/**
+ * Apply `ensureClaudeInsideSymlink` to every installed Claude version.
+ * Safe to call repeatedly; per-version calls are idempotent.
+ */
+export function ensureAllClaudeInsideSymlinks() {
+    const versionsDir = getVersionsDir();
+    const claudeVersionsDir = path.join(versionsDir, 'claude');
+    const migrated = [];
+    const errors = [];
+    if (!fs.existsSync(claudeVersionsDir))
+        return { migrated, errors };
+    for (const entry of fs.readdirSync(claudeVersionsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            ensureClaudeInsideSymlink(entry.name);
+            migrated.push(entry.name);
+        }
+        catch (err) {
+            errors.push(`${entry.name}: ${err.message}`);
+        }
+    }
+    return { migrated, errors };
+}
 /**
  * Get the current config symlink target version, if any.
  */
@@ -807,6 +1035,37 @@ export function getPathShadowingExecutable(agent) {
     }
     return null;
 }
+/**
+ * Check if the agent's CLI command is shadowed by a shell alias.
+ *
+ * Shell aliases live in the user's session and aren't visible from a Node.js
+ * child process. We do a best-effort scan of common RC files for `alias
+ * <command>=` patterns. Returns false when detection is inconclusive.
+ */
+export function hasAliasShadowingShim(agent) {
+    const cliCommand = AGENTS[agent].cliCommand;
+    const HOME = os.homedir();
+    const rcFiles = [
+        path.join(HOME, '.zshrc'),
+        path.join(HOME, '.bashrc'),
+        path.join(HOME, '.bash_profile'),
+        path.join(HOME, '.profile'),
+    ];
+    const pattern = new RegExp(`^\\s*alias\\s+${cliCommand}\\s*=`, 'm');
+    for (const rcFile of rcFiles) {
+        try {
+            if (!fs.existsSync(rcFile))
+                continue;
+            const content = fs.readFileSync(rcFile, 'utf-8');
+            if (pattern.test(content))
+                return true;
+        }
+        catch {
+            // unreadable rc file — skip
+        }
+    }
+    return false;
+}
 /**
  * Check if shims directory is in PATH.
  */
@@ -815,11 +1074,56 @@ export function isShimsInPath() {
     const pathDirs = (process.env.PATH || '').split(path.delimiter);
     return pathDirs.some((dir) => path.resolve(dir) === path.resolve(shimsDir));
 }
+function isShimPathCommandLine(line, shimsDir) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('#')) {
+        return false;
+    }
+    const normalized = trimmed.replace(/['"]/g, '');
+    const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const exactMarkers = [
+        shimsDir,
+        '$HOME/.agents-system/shims',
+        '${HOME}/.agents-system/shims',
+        '~/.agents-system/shims',
+        '$HOME/.agents/shims',
+        '${HOME}/.agents/shims',
+        '~/.agents/shims',
+    ];
+    const markerRegexes = exactMarkers.map((marker) => new RegExp(`${escapeRegex(marker)}(?=$|[:\\s])`));
+    const suffixRegexes = [
+        /\/\.agents-system\/shims(?=$|[:\s])/,
+        /\/\.agents\/shims(?=$|[:\s])/,
+    ];
+    const touchesShimPath = [...markerRegexes, ...suffixRegexes].some((pattern) => pattern.test(normalized));
+    if (!touchesShimPath) {
+        return false;
+    }
+    return trimmed.startsWith('export PATH=') || trimmed.startsWith('fish_add_path ');
+}
+function stripShimPathLines(content, shimsDir) {
+    const lines = content.split('\n');
+    const kept = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '# agents-cli: version-managed agent CLIs' &&
+            i + 1 < lines.length &&
+            isShimPathCommandLine(lines[i + 1], shimsDir)) {
+            i++;
+            continue;
+        }
+        if (isShimPathCommandLine(line, shimsDir)) {
+            continue;
+        }
+        kept.push(line);
+    }
+    return kept.join('\n').replace(/\n{3,}/g, '\n\n');
+}
 /**
  * Get the shell rc file path for the current shell.
  */
-function getShellRcFile() {
-    const shell = process.env.SHELL || '/bin/bash';
+function getShellRcFile(overrides) {
+    const shell = overrides?.shell || process.env.SHELL || '/bin/bash';
     const shellName = path.basename(shell);
     let rcFile;
     switch (shellName) {
@@ -836,7 +1140,7 @@ function getShellRcFile() {
     }
     return {
         rcFile,
-        rcPath: path.join(os.homedir(), rcFile),
+        rcPath: path.join(overrides?.homeDir || os.homedir(), rcFile),
         shell: shellName,
     };
 }
@@ -850,7 +1154,7 @@ export function getPathSetupInstructions() {
         return `Add to ~/.config/fish/config.fish:
   fish_add_path ${shimsDir}`;
     }
-    return `Add to ~/${rcFile} (BEFORE any nvm/node setup):
+    return `Add to ~/${rcFile} (AFTER any nvm/node setup):
   export PATH="${shimsDir}:$PATH"
 
 IMPORTANT: Shims must come FIRST in PATH to override global installs.
@@ -862,9 +1166,9 @@ Then restart your shell or run:
  * Add shims directory to shell PATH configuration.
  * Returns true if added, false if already present or failed.
  */
-export function addShimsToPath() {
-    const shimsDir = getShimsDir();
-    const { rcFile, rcPath, shell } = getShellRcFile();
+export function addShimsToPath(overrides) {
+    const shimsDir = overrides?.shimsDir || getShimsDir();
+    const { rcFile, rcPath, shell } = getShellRcFile(overrides);
     // Read current rc file content
     let content = '';
     try {
@@ -875,21 +1179,17 @@ export function addShimsToPath() {
     catch (err) {
         return { success: false, error: `Could not read ${rcFile}: ${err.message}` };
     }
-    // Check if shims path already in file
-    if (content.includes(shimsDir) || content.includes('$HOME/.agents/shims')) {
-        return { success: true, alreadyPresent: true, rcFile };
-    }
-    // Generate the export line
-    let exportLine;
+    // Generate the canonical PATH block.
+    let exportBlock;
     if (shell === 'fish') {
-        exportLine = `\n# agents-cli: version-managed agent CLIs\nfish_add_path ${shimsDir}\n`;
+        exportBlock = `# agents-cli: version-managed agent CLIs\nfish_add_path ${shimsDir}\n`;
     }
     else {
-        exportLine = `\n# agents-cli: version-managed agent CLIs\nexport PATH="${shimsDir}:$PATH"\n`;
+        exportBlock = `# agents-cli: version-managed agent CLIs\nexport PATH="${shimsDir}:$PATH"\n`;
     }
-    // Find insertion point - BEFORE nvm/node setup if possible
-    // Look for common patterns that should come AFTER our shims
-    const insertBeforePatterns = [
+    const contentWithoutShimLines = stripShimPathLines(content, shimsDir);
+    // Find insertion point - AFTER node/nvm/fnm setup if present, otherwise append.
+    const insertAfterPatterns = [
         /^export NVM_DIR=/m,
         /^source.*nvm/m,
         /^\[ -s.*nvm/m,
@@ -898,18 +1198,14 @@ export function addShimsToPath() {
         /^export PATH.*npm/m,
     ];
     let insertIndex = -1;
-    for (const pattern of insertBeforePatterns) {
-        const match = content.match(pattern);
-        if (match && match.index !== undefined) {
-            // Find start of this line
-            let lineStart = match.index;
-            while (lineStart > 0 && content[lineStart - 1] !== '\n') {
-                lineStart--;
-            }
-            if (insertIndex === -1 || lineStart < insertIndex) {
-                insertIndex = lineStart;
-            }
+    const lines = contentWithoutShimLines.split('\n');
+    let offset = 0;
+    for (const line of lines) {
+        const lineWithNewline = `${line}\n`;
+        if (insertAfterPatterns.some((pattern) => pattern.test(line))) {
+            insertIndex = offset + lineWithNewline.length;
         }
+        offset += lineWithNewline.length;
     }
     // Write the updated content
     try {
@@ -920,12 +1216,19 @@ export function addShimsToPath() {
         }
         let newContent;
         if (insertIndex >= 0) {
-            // Insert before nvm/node setup (handles index 0 correctly)
-            newContent = content.slice(0, insertIndex) + exportLine + content.slice(insertIndex);
+            // Insert after the last node/nvm/fnm-related line so our prepend wins.
+            const before = contentWithoutShimLines.slice(0, insertIndex);
+            const separator = before.length > 0 && !before.endsWith('\n\n') ? '\n' : '';
+            newContent = before + separator + exportBlock + contentWithoutShimLines.slice(insertIndex);
         }
         else {
             // Append to end
-            newContent = content + exportLine;
+            const separator = contentWithoutShimLines.length > 0 && !contentWithoutShimLines.endsWith('\n') ? '\n' : '';
+            newContent = contentWithoutShimLines + separator + exportBlock;
+        }
+        newContent = newContent.replace(/\n{2,}$/g, '\n');
+        if (newContent === content) {
+            return { success: true, alreadyPresent: true, rcFile };
         }
         fs.writeFileSync(rcPath, newContent, 'utf-8');
         return { success: true, rcFile };
@@ -934,6 +1237,17 @@ export function addShimsToPath() {
         return { success: false, error: `Could not write ${rcFile}: ${err.message}` };
     }
 }
+export function listAgentsWithInstalledVersions() {
+    const versionsDir = getVersionsDir();
+    if (!fs.existsSync(versionsDir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(versionsDir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isDirectory() && AGENTS[entry.name])
+        .map((entry) => entry.name)
+        .filter((agent) => fs.readdirSync(path.join(versionsDir, agent), { withFileTypes: true }).some((entry) => entry.isDirectory()));
+}
 /**
  * Create shims for all installed agents.
  */
@@ -1116,4 +1430,3 @@ export function copyResourcesToVersion(agent, fromVersion, toVersion, diff) {
         }
     }
 }
-//# sourceMappingURL=shims.js.map