@phnx-labs/agents-cli 1.14.1 → 1.14.3

package/dist/lib/secrets/index.js

@@ -1,9 +1,11 @@
 /**
  * macOS Keychain integration for secure credential storage.
  *
- * Calls a compiled Swift helper (keychain-helper.swift) to store and retrieve
- * API keys and tokens via the Security framework, with kSecAttrSynchronizable
- * set so iCloud Keychain syncs them across the user's Macs.
+ * All reads/writes go through a signed Swift helper (keychain-helper.swift)
+ * compiled into AgentsKeychain.app. The .app embeds a provisioning profile
+ * that grants the application-identifier + keychain-access-groups entitlement
+ * macOS requires for kSecAttrSynchronizable writes (iCloud Keychain).
+ * For device-local writes the helper is invoked with the `nosync` arg.
  */
 import { fileURLToPath } from 'url';
 import { execFileSync, spawnSync } from 'child_process';
@@ -12,7 +14,7 @@ import * as os from 'os';
 import * as path from 'path';
 const SERVICE_PREFIX = 'agents-cli';
 const REF_PATTERN = /^(keychain|env|file|exec):(.+)$/s;
-/** Parse a bundle YAML value into either a literal string or a typed secret ref. */
+/** Parse a bundle value into either a literal string or a typed secret ref. */
 export function parseBundleValue(raw) {
     if (typeof raw === 'object' && raw !== null && typeof raw.value === 'string') {
         return { literal: raw.value };
@@ -53,58 +55,64 @@ function ensureKeychainHelper() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const binPath = path.join(here, 'AgentsKeychain.app', 'Contents', 'MacOS', 'AgentsKeychain');
     if (!fs.existsSync(binPath)) {
-        throw new Error(`iCloud Keychain helper missing at ${binPath}. ` +
-            'This npm package was built without the signed helper bundle. ' +
-            'Reinstall agents-cli, or create the bundle without --icloud-sync to use device-local storage.');
+        throw new Error(`Keychain helper missing at ${binPath}. ` +
+            'This npm package was built without the signed helper bundle. Reinstall agents-cli.');
     }
     return binPath;
 }
-// iCloud Keychain sync is opt-in per bundle. When sync=true we route through
-// the Swift helper (kSecAttrSynchronizable=true). When sync is false/undefined
-// we use /usr/bin/security, which is always present on macOS — so a user who
-// never opts in to iCloud sync never needs Xcode Command Line Tools.
+let backend = null;
+/** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
+export function setKeychainBackendForTest(b) {
+    const prev = backend;
+    backend = b;
+    return prev;
+}
+// Backend routing: non-sync items go through /usr/bin/security so they share
+// an ACL identity with items created by previous CLI versions (no prompts on
+// existing data). Sync items must go through the signed .app — only the .app
+// holds the keychain-access-groups entitlement macOS requires for
+// kSecAttrSynchronizable. Enumeration also goes through the .app because the
+// security CLI doesn't expose listing by service prefix.
 /** Check if a keychain item exists (macOS only). */
 export function hasKeychainToken(item, sync = false) {
+    if (backend)
+        return backend.has(item, sync);
     assertMacOS();
-    if (sync) {
-        const bin = ensureKeychainHelper();
-        return spawnSync(bin, ['has', item, os.userInfo().username], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        }).status === 0;
-    }
-    return spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+    // Try security first (no prompts for local items), fall back to binary for synced items.
+    if (spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).status === 0)
+        return true;
+    // Fallback: binary searches both synced and non-synced via kSecAttrSynchronizableAny
+    const bin = ensureKeychainHelper();
+    return spawnSync(bin, ['has', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
 /** Retrieve a secret value from the macOS Keychain. Throws if not found. */
 export function getKeychainToken(item, sync = false) {
+    if (backend)
+        return backend.get(item, sync);
     assertMacOS();
-    if (sync) {
-        const bin = ensureKeychainHelper();
-        const result = spawnSync(bin, ['get', item, os.userInfo().username], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        if (result.status === 1)
-            throw new Error(`Keychain item '${item}' not found.`);
-        if (result.status !== 0) {
-            const msg = result.stderr?.toString().trim();
-            throw new Error(msg || `Failed to read keychain item '${item}'.`);
-        }
-        const token = result.stdout?.toString().trim();
-        if (!token)
-            throw new Error(`Keychain item '${item}' exists but is empty.`);
-        return token;
+    // Try security first (no prompts for local items)
+    const secResult = spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (secResult.status === 0) {
+        const token = secResult.stdout?.toString().trim();
+        if (token)
+            return token;
     }
-    const result = spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+    // Fallback: binary searches both synced and non-synced via kSecAttrSynchronizableAny
+    const bin = ensureKeychainHelper();
+    const result = spawnSync(bin, ['get', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
-    if (result.status === 44)
+    if (result.status === 1)
         throw new Error(`Keychain item '${item}' not found.`);
     if (result.status !== 0) {
-        const stderr = result.stderr?.toString() || '';
-        if (/could not be found/i.test(stderr))
-            throw new Error(`Keychain item '${item}' not found.`);
-        throw new Error(`Failed to read keychain item '${item}': ${stderr.trim() || `exit ${result.status}`}`);
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to read keychain item '${item}'.`);
     }
     const token = result.stdout?.toString().trim();
     if (!token)
@@ -113,6 +121,10 @@ export function getKeychainToken(item, sync = false) {
 }
 /** Store or update a secret value in the macOS Keychain. iCloud-synced when sync=true. */
 export function setKeychainToken(item, value, sync = false) {
+    if (backend) {
+        backend.set(item, value, sync);
+        return;
+    }
     assertMacOS();
     if (!value || !value.trim())
         throw new Error('Secret value is empty.');
@@ -130,7 +142,7 @@ export function setKeychainToken(item, value, sync = false) {
         }
         return;
     }
-    // The `security -i` interactive form keeps the value out of argv (and `ps`).
+    // `security -i` keeps the value out of argv (and `ps`).
     const user = os.userInfo().username;
     const cmd = `add-generic-password -a ${quoteForSecurityCli(user)} -s ${quoteForSecurityCli(item)} -w ${quoteForSecurityCli(value)} -U\n`;
     const result = spawnSync('security', ['-i'], {
@@ -143,6 +155,8 @@ export function setKeychainToken(item, value, sync = false) {
 }
 /** Delete a keychain item. Returns true if it existed. */
 export function deleteKeychainToken(item, sync = false) {
+    if (backend)
+        return backend.delete(item, sync);
     assertMacOS();
     if (sync) {
         const bin = ensureKeychainHelper();
@@ -154,10 +168,25 @@ export function deleteKeychainToken(item, sync = false) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-// Quote a value for `security -i`'s shell-like tokenizer so it stays out of argv.
 function quoteForSecurityCli(s) {
     return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
 }
+/** Enumerate keychain item service names whose name starts with the given prefix. */
+export function listKeychainItems(prefix) {
+    if (backend)
+        return backend.list(prefix);
+    assertMacOS();
+    const bin = ensureKeychainHelper();
+    const result = spawnSync(bin, ['list', prefix], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to enumerate keychain items with prefix '${prefix}'.`);
+    }
+    const out = result.stdout?.toString() || '';
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
 function expandHome(p) {
     if (p.startsWith('~/') || p === '~') {
         return path.join(os.homedir(), p.slice(1));

package/dist/lib/session/active.js

@@ -2,12 +2,12 @@
  * Active-session detection across every context an agent can run in:
  *
  *   - `terminal` — agents launched from VS Code / Cursor / Codium via the
- *     agents-cli extension. Published to `~/.agents-system/runtime/live-terminals.json`
+ *     agents-cli extension. Published to `~/.agents/runtime/live-terminals.json`
  *     with PID + session UUID per entry.
  *   - `teams`    — agents spawned by `agents teams add`, tracked in
- *     `~/.agents-system/teams/agents/<id>/meta.json` with a PID the manager polls.
+ *     `~/.agents/teams/agents/<id>/meta.json` with a PID the manager polls.
  *   - `cloud`    — dispatched to Rush / Codex Cloud / Factory, tracked in
- *     the SQLite cache at `~/.agents-system/cloud/tasks.db`.
+ *     the SQLite cache at `~/.agents/cloud/tasks.db`.
  *   - `headless` — bare `claude` / `codex` / `gemini` / `cursor-agent` /
  *     `opencode` processes that don't belong to any of the above. Detected
  *     by `ps` minus the PIDs we've already attributed.
@@ -23,10 +23,10 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { listActiveTasks } from '../cloud/store.js';
 import { AgentManager } from '../teams/agents.js';
-import { getAgentsDir } from '../state.js';
+import { getUserAgentsDir } from '../state.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
-const LIVE_TERMINALS_FILE = path.join(getAgentsDir(), 'runtime', 'live-terminals.json');
+const LIVE_TERMINALS_FILE = path.join(getUserAgentsDir(), 'runtime', 'live-terminals.json');
 /**
  * A process is classified `running` if its session file was touched in the
  * last 2 minutes. Every Claude/Codex tool-call appends an event, so a

package/dist/lib/session/db.js

@@ -9,8 +9,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { getAgentsDir } from '../state.js';
-const SESSIONS_DIR = path.join(getAgentsDir(), 'sessions');
+import { getUserAgentsDir } from '../state.js';
+const SESSIONS_DIR = path.join(getUserAgentsDir(), 'sessions');
 const DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
 /** Current schema version; bumped when migrations are added. */
 const SCHEMA_VERSION = 5;
@@ -18,7 +18,7 @@ const SCHEMA_VERSION = 5;
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
  * (when `~/.claude` is a symlink to a versioned home) and
- * `~/.agents-system/versions/claude/<v>/home/.claude/projects/x.jsonl`. Keying the
+ * `~/.agents/versions/claude/<v>/home/.claude/projects/x.jsonl`. Keying the
  * ledger by the raw path means switching between these aliases (e.g. via
  * `agents use`) misses the cache and forces a full re-parse. Realpath collapses
  * all aliases to one stable key.
@@ -213,7 +213,7 @@ export function getScanStampsForPaths(filePaths) {
         return result;
     const db = getDB();
     // Multiple input paths can resolve to the same canonical key (e.g. the same
-    // session JSONL reachable via `~/.claude/...` and `~/.agents-system/versions/...`).
+    // session JSONL reachable via `~/.claude/...` and `~/.agents/versions/...`).
     // We query DB by canonical key, then fan results back out to every original
     // alias so callers can `.get(filePath)` with the path they passed in.
     const canonicalToOriginals = new Map();

package/dist/lib/session/discover.js

@@ -1451,12 +1451,12 @@ function normalizeVersion(version) {
     const trimmed = version?.trim();
     return trimmed ? trimmed : undefined;
 }
-/** Extract the version number from a managed ~/.agents-system/versions/<agent>/<version>/... path. */
+/** Extract the version number from a managed ~/.agents/versions/<agent>/<version>/... path. */
 function extractVersionFromManagedPath(agent, sourcePath) {
     if (!sourcePath)
         return undefined;
     const candidates = [sourcePath, safeRealpathSync(sourcePath) || ''];
-    const marker = `/.agents-system/versions/${agent}/`;
+    const marker = `/.agents/versions/${agent}/`;
     for (const candidate of candidates) {
         if (!candidate)
             continue;

package/dist/lib/session/render.js

@@ -424,6 +424,7 @@ export function renderSummary(events, cwd) {
     // Plan items
     const todoItems = [];
     let exitPlanContent = null;
+    let planFilePath = null;
     // Subagent spawns
     const subagents = [];
     // Errors
@@ -444,8 +445,14 @@ export function renderSummary(events, cwd) {
                     filesReadAbs.add(p);
             }
             else if (['Write', 'Edit', 'write_file', 'edit_file', 'create_file', 'replace', 'patch'].includes(tool)) {
-                if (p)
-                    (isInsideCwd(p) || !cwd ? filesModifiedAbs : filesModifiedExternal).add(p);
+                if (p) {
+                    if (p.includes('.claude/plans/') && p.endsWith('.md')) {
+                        planFilePath = p;
+                    }
+                    else {
+                        (isInsideCwd(p) || !cwd ? filesModifiedAbs : filesModifiedExternal).add(p);
+                    }
+                }
             }
             if (event.command) {
                 const cmd = event.command.replace(/\n/g, ' ').trim();
@@ -543,14 +550,19 @@ export function renderSummary(events, cwd) {
     if (firstUserMessage || attachments.length > 0)
         lines.push('');
     // 2. Plan
-    if (todoItems.length > 0 || exitPlanContent) {
+    if (todoItems.length > 0 || exitPlanContent || planFilePath) {
         lines.push(chalk.bold('Plan'));
+        if (planFilePath) {
+            const home = process.env.HOME ?? '';
+            const displayPath = home && planFilePath.startsWith(home) ? planFilePath.replace(home, '~') : planFilePath;
+            lines.push('  ' + chalk.cyan(displayPath));
+        }
         if (exitPlanContent) {
             const planLines = exitPlanContent.split('\n').slice(0, 10);
             for (const l of planLines)
                 lines.push('  ' + l);
         }
-        else {
+        else if (todoItems.length > 0) {
             for (const item of todoItems.slice(0, 20)) {
                 lines.push('  · ' + item);
             }
@@ -574,12 +586,14 @@ export function renderSummary(events, cwd) {
         lines.push('');
     }
     // 4b. External edits (files edited outside the project root — typically /tmp)
-    if (filesModifiedExternal.size > 0) {
-        const externalList = [...filesModifiedExternal].sort();
+    // Filter out plan files (already shown in Plan section)
+    const externalNonPlan = [...filesModifiedExternal].filter(p => !(p.includes('.claude/plans/') && p.endsWith('.md')));
+    if (externalNonPlan.length > 0) {
+        const externalList = externalNonPlan.sort();
         const home = process.env.HOME ?? '';
         const display = externalList.slice(0, 3).map(p => home && p.startsWith(home) ? p.replace(home, '~') : p);
         const more = externalList.length > 3 ? chalk.gray(` +${externalList.length - 3} more`) : '';
-        lines.push(chalk.gray(`External edits (${filesModifiedExternal.size}): ${display.join(', ')}${more}`));
+        lines.push(chalk.gray(`External edits (${externalList.length}): ${display.join(', ')}${more}`));
         lines.push('');
     }
     // 5. Read files

package/dist/lib/shims.d.ts

@@ -42,9 +42,9 @@ export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): P
  *
  * History:
  *   v1 — initial shim (implicit, no marker).
- *   v2 — `--version=...` form in sync/refresh-memory calls; refresh-memory
+ *   v2 — `--version=...` form in sync/refresh-rules calls; refresh-rules
  *        shim hook for non-@-capable agents.
- *   v3 — sync/refresh-memory flag renamed `--version` → `--agent-version`
+ *   v3 — sync/refresh-rules 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
@@ -53,8 +53,12 @@ export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): P
  *        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.
+ *   v7 — rename `agents refresh-memory` invocation to `agents refresh-rules`
+ *        and capability flag `memoryImports` → `rulesImports`.
+ *   v8 — versions moved from ~/.agents-system/versions to ~/.agents/versions
+ *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export declare const SHIM_SCHEMA_VERSION = 6;
+export declare const SHIM_SCHEMA_VERSION = 8;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -83,8 +87,10 @@ export declare function removeShim(agent: AgentId): boolean;
  *        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.
+ *   v6 — versions moved from ~/.agents-system/versions to ~/.agents/versions
+ *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 5;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 6;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -219,8 +225,26 @@ export declare function getShimPath(agent: AgentId): string;
 /**
  * Return the first executable path that would be launched for this agent when
  * resolving against PATH, excluding the managed shim itself.
+ *
+ * Legacy ~/.agents/shims/<cli> (from the pre-split single-root layout) is NOT
+ * treated as a shadow when a current managed shim exists at getShimPath() —
+ * that file is dead weight from the old layout and the repair flow removes it
+ * separately. Treating it as "shadowing" caused an infinite repair-prompt
+ * loop because addShimsToPath() only edits the rc file, never the legacy
+ * shim file itself.
  */
 export declare function getPathShadowingExecutable(agent: AgentId): string | null;
+/**
+ * Delete the legacy ~/.agents/shims/<cli> file if it exists, returning whether
+ * anything was removed. Pre-split installs put shims under ~/.agents/shims/;
+ * the new layout uses ~/.agents-system/shims/. The leftover file causes the
+ * repair-prompt loop reported in RUSH-664 — `getPathShadowingExecutable` flags
+ * it as a shadow but `addShimsToPath` only edits rc files, never the file
+ * itself. Removing it ends the loop.
+ */
+export declare function removeLegacyUserShim(agent: AgentId, overrides?: {
+    homeDir?: string;
+}): boolean;
 /**
  * Check if the agent's CLI command is shadowed by a shell alias.
  *

package/dist/lib/shims.js

@@ -156,9 +156,9 @@ export async function promptConflictStrategy(conflictInfos) {
  *
  * History:
  *   v1 — initial shim (implicit, no marker).
- *   v2 — `--version=...` form in sync/refresh-memory calls; refresh-memory
+ *   v2 — `--version=...` form in sync/refresh-rules calls; refresh-rules
  *        shim hook for non-@-capable agents.
- *   v3 — sync/refresh-memory flag renamed `--version` → `--agent-version`
+ *   v3 — sync/refresh-rules 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
@@ -167,8 +167,12 @@ export async function promptConflictStrategy(conflictInfos) {
  *        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.
+ *   v7 — rename `agents refresh-memory` invocation to `agents refresh-rules`
+ *        and capability flag `memoryImports` → `rulesImports`.
+ *   v8 — versions moved from ~/.agents-system/versions to ~/.agents/versions
+ *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export const SHIM_SCHEMA_VERSION = 6;
+export const SHIM_SCHEMA_VERSION = 8;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 /**
@@ -194,16 +198,16 @@ export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
 export CODEX_HOME="$VERSION_DIR/home/${configDirName}"
 `
             : '';
-    // Agents that don't natively resolve @-imports in their memory file need
+    // Agents that don't natively resolve @-imports in their rules 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
     // sources haven't changed.
-    const refreshMemoryCall = !agentConfig.capabilities.memoryImports
+    const refreshRulesCall = !agentConfig.capabilities.rulesImports
         ? `
-# Recompile memory if any rule/preset source has changed since last sync.
+# Recompile rules if any rule/preset source has changed since last sync.
 # Fast-path check (~10-20ms) when nothing changed; full recompile only on
 # actual diff. Non-blocking failure — if the refresh errors, we still launch.
-agents refresh-memory --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/null || true
+agents refresh-rules --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/null || true
 `
         : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
@@ -283,7 +287,7 @@ if [ -z "$VERSION" ]; then
   exit 1
 fi
 
-VERSION_DIR="$AGENTS_SYSTEM_DIR/versions/$AGENT/$VERSION"
+VERSION_DIR="$AGENTS_USER_DIR/versions/$AGENT/$VERSION"
 BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 
 # Auto-install if not present
@@ -328,7 +332,7 @@ PROJECT_AGENTS_DIR=$(find_project_agents_dir)
 if [ -n "$PROJECT_AGENTS_DIR" ]; then
   agents sync --agent "$AGENT" --agent-version "$VERSION" --project-dir "$PROJECT_AGENTS_DIR" --quiet >/dev/null 2>&1
 fi
-${refreshMemoryCall}${managedEnv}
+${refreshRulesCall}${managedEnv}
 
 exec "$BINARY"${launchArgs} "$@"
 `;
@@ -373,8 +377,10 @@ export function removeShim(agent) {
  *        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.
+ *   v6 — versions moved from ~/.agents-system/versions to ~/.agents/versions
+ *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 5;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 6;
 /** 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
@@ -399,14 +405,14 @@ export function generateVersionedAliasScript(agent, version) {
         ? `
 # 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-system/versions/${agent}/${version}/home/${configDirName}"
+export CLAUDE_CONFIG_DIR="$HOME/.agents/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}"
+export CODEX_HOME="$HOME/.agents/versions/${agent}/${version}/home/${configDirName}"
 `
             : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
@@ -415,7 +421,7 @@ export CODEX_HOME="$HOME/.agents-system/versions/${agent}/${version}/home/${conf
 # ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}
 # Direct alias for ${agentConfig.name}@${version}
 
-BINARY="$HOME/.agents-system/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
+BINARY="$HOME/.agents/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
 
 if [ ! -x "$BINARY" ]; then
   echo "agents: ${agent}@${version} not installed" >&2
@@ -1021,20 +1027,72 @@ export function getShimPath(agent) {
 /**
  * Return the first executable path that would be launched for this agent when
  * resolving against PATH, excluding the managed shim itself.
+ *
+ * Legacy ~/.agents/shims/<cli> (from the pre-split single-root layout) is NOT
+ * treated as a shadow when a current managed shim exists at getShimPath() —
+ * that file is dead weight from the old layout and the repair flow removes it
+ * separately. Treating it as "shadowing" caused an infinite repair-prompt
+ * loop because addShimsToPath() only edits the rc file, never the legacy
+ * shim file itself.
  */
 export function getPathShadowingExecutable(agent) {
     const pathDirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
     const shimPath = path.resolve(getShimPath(agent));
     const cliCommand = AGENTS[agent].cliCommand;
+    const legacyUserShim = path.resolve(path.join(os.homedir(), '.agents', 'shims', cliCommand));
+    const managedShimExists = fs.existsSync(shimPath);
     for (const dir of pathDirs) {
         const candidate = path.resolve(dir, cliCommand);
         if (!fs.existsSync(candidate)) {
             continue;
         }
-        return candidate === shimPath ? null : candidate;
+        if (candidate === shimPath)
+            return null;
+        if (candidate === legacyUserShim && managedShimExists) {
+            // Legacy file from the pre-split layout. Don't treat as shadow — the
+            // repair flow deletes it via removeLegacyUserShim instead. Continue
+            // scanning so a real binary later in PATH is still detected.
+            continue;
+        }
+        return candidate;
     }
     return null;
 }
+/**
+ * Delete the legacy ~/.agents/shims/<cli> file if it exists, returning whether
+ * anything was removed. Pre-split installs put shims under ~/.agents/shims/;
+ * the new layout uses ~/.agents-system/shims/. The leftover file causes the
+ * repair-prompt loop reported in RUSH-664 — `getPathShadowingExecutable` flags
+ * it as a shadow but `addShimsToPath` only edits rc files, never the file
+ * itself. Removing it ends the loop.
+ */
+export function removeLegacyUserShim(agent, overrides) {
+    const cliCommand = AGENTS[agent].cliCommand;
+    const homeDir = overrides?.homeDir || os.homedir();
+    const legacyPath = path.join(homeDir, '.agents', 'shims', cliCommand);
+    if (!fs.existsSync(legacyPath))
+        return false;
+    // Belt-and-suspenders: only remove if the current managed shim location is
+    // different (it always should be — getShimsDir() returns the system dir —
+    // but guard against future refactors that might collapse the two).
+    const currentShim = path.resolve(getShimPath(agent));
+    if (path.resolve(legacyPath) === currentShim)
+        return false;
+    try {
+        fs.unlinkSync(legacyPath);
+        // Best-effort: clean up the legacy shims dir if empty.
+        try {
+            const legacyDir = path.dirname(legacyPath);
+            if (fs.readdirSync(legacyDir).length === 0)
+                fs.rmdirSync(legacyDir);
+        }
+        catch { /* best-effort */ }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Check if the agent's CLI command is shadowed by a shell alias.
  *