@phnx-labs/agents-cli 1.20.12 → 1.20.14

package/dist/lib/plugins.js

@@ -105,6 +105,29 @@ export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user
         hasSettings: pluginHasNonPermissionSettings(pluginRoot),
     };
 }
+/**
+ * Ordered, non-empty resource groups a plugin packages. Single source of truth
+ * for the breakdown shown by the plugin picker, `agents inspect --plugins`, and
+ * its detail view. Empty categories are omitted; `settings` appears only when
+ * the plugin merges non-permission settings.
+ */
+export function pluginResourceGroups(plugin) {
+    const groups = [
+        { label: 'skills', items: plugin.skills.map((s) => `/${plugin.name}:${s}`) },
+        { label: 'commands', items: plugin.commands.map((c) => `/${plugin.name}:${c}`) },
+        { label: 'subagents', items: plugin.agentDefs },
+        { label: 'hooks', items: plugin.hooks },
+        { label: 'mcp', items: plugin.mcpServers },
+        { label: 'lsp', items: plugin.lspServers },
+        { label: 'monitors', items: plugin.monitors },
+        { label: 'bin', items: plugin.bin },
+        { label: 'scripts', items: plugin.scripts },
+    ];
+    const out = groups.filter((g) => g.items.length > 0);
+    if (plugin.hasSettings)
+        out.push({ label: 'settings', items: ['settings.json'] });
+    return out;
+}
 export function inspectPluginCapabilities(pluginRoot) {
     const manifest = loadPluginManifest(pluginRoot);
     const plugin = manifest ? buildDiscoveredPlugin(pluginRoot, manifest) : null;
@@ -190,13 +213,25 @@ function discoverPluginSkills(pluginRoot) {
         .filter(d => d.isDirectory() && !d.name.startsWith('.'))
         .map(d => d.name);
 }
-function discoverPluginHooks(pluginRoot) {
+/**
+ * The lifecycle events a plugin hooks into, read from hooks/hooks.json.
+ *
+ * The official plugin format wraps the event map under a `hooks` key
+ * (`{ description, hooks: { SessionStart: [...], PreToolUse: [...] } }`), so the
+ * meaningful keys are the events — NOT the top-level keys (`description`,
+ * `hooks`). Older/flat files put the event names at the top level directly; we
+ * read whichever object actually holds the event map.
+ */
+export function discoverPluginHooks(pluginRoot) {
     const hooksFile = path.join(pluginRoot, 'hooks', 'hooks.json');
     if (!fs.existsSync(hooksFile))
         return [];
     try {
         const content = JSON.parse(fs.readFileSync(hooksFile, 'utf-8'));
-        return Object.keys(content);
+        const eventMap = content.hooks && typeof content.hooks === 'object' && !Array.isArray(content.hooks)
+            ? content.hooks
+            : content;
+        return Object.keys(eventMap);
     }
     catch {
         return [];

package/dist/lib/project-launch.js

@@ -47,6 +47,7 @@ import * as path from 'path';
 import { supports } from './capabilities.js';
 import { getEnabledExtraRepos, getExtraPluginsDir, getPluginsDir, getProjectAgentsDir, getProjectPluginsDir, getSystemPluginsDir, } from './state.js';
 import { getVersionHomePath } from './versions.js';
+import { transformSubagentForClaude } from './subagents.js';
 import { compileRulesForProject } from './rules/compile.js';
 import { discoverPluginsInDir, hasPluginExecSurfaces, inspectPluginCapabilities } from './plugins.js';
 import { MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, addPluginToSettings, copyPluginToMarketplace, marketplaceNameFor, marketplaceRoot, pluginInstallDir, registerMarketplace, removePluginFromSettings, syncMarketplaceManifest, } from './plugin-marketplace.js';
@@ -114,10 +115,22 @@ function touchLaunchSentinel(agent, version, cwd) {
     }
 }
 const CLAUDE_MIRROR_PLANS = [
-    { srcSubdir: 'subagents', destSubdir: 'agents', entriesAreDirs: false },
-    { srcSubdir: 'commands', destSubdir: 'commands', entriesAreDirs: false },
-    { srcSubdir: 'skills', destSubdir: 'skills', entriesAreDirs: true },
+    { srcSubdir: 'subagents', destSubdir: 'agents', mode: 'subagent-write' },
+    { srcSubdir: 'commands', destSubdir: 'commands', mode: 'file-symlink' },
+    { srcSubdir: 'skills', destSubdir: 'skills', mode: 'dir-symlink' },
 ];
+/**
+ * Marker prepended-as-trailing-comment to every subagent file WE generate.
+ * It's an HTML comment — invisible to the markdown the agent reads — placed on
+ * the last line so it never disturbs the leading `---` frontmatter block.
+ *
+ * Ownership rule (the one don't-clobber decision for written, non-symlink
+ * files): we only overwrite a `.claude/agents/<name>.md` whose content carries
+ * this marker. A user-authored file (no marker) or a symlink at the dest is
+ * left untouched. A marker beats an mtime/sidecar sentinel because it travels
+ * with the file across copies and git, and needs no out-of-band state.
+ */
+const GENERATED_SUBAGENT_MARKER = '<!-- agents-cli:generated-subagent';
 function mirrorWorkspaceResources(cwd, agent) {
     // v1: claude-only. Other agents have workspace conventions we haven't
     // mapped (amp: ~/.config/amp; antigravity: ~/.gemini/antigravity-cli;
@@ -147,13 +160,20 @@ function mirrorWorkspaceResources(cwd, agent) {
             continue;
         const destDir = path.join(agentWorkspaceDir, plan.destSubdir);
         fs.mkdirSync(destDir, { recursive: true });
+        // Subagents flatten N source files into one written .md — not a symlink.
+        if (plan.mode === 'subagent-write') {
+            const r = writeProjectSubagents(srcDir, destDir, cwd);
+            links += r.links;
+            skipped.push(...r.skipped);
+            continue;
+        }
         const entries = fs.readdirSync(srcDir, { withFileTypes: true });
         for (const entry of entries) {
             if (entry.name.startsWith('.'))
                 continue;
-            if (plan.entriesAreDirs && !entry.isDirectory())
+            if (plan.mode === 'dir-symlink' && !entry.isDirectory())
                 continue;
-            if (!plan.entriesAreDirs && !entry.isFile() && !entry.isSymbolicLink())
+            if (plan.mode === 'file-symlink' && !entry.isFile() && !entry.isSymbolicLink())
                 continue;
             const srcPath = path.join(srcDir, entry.name);
             const destPath = path.join(destDir, entry.name);
@@ -167,6 +187,91 @@ function mirrorWorkspaceResources(cwd, agent) {
     }
     return { links, skipped };
 }
+/**
+ * Mirror project subagents into `<cwd>/.claude/agents/`. The canonical source
+ * shape is a DIRECTORY containing AGENT.md (e.g. `.agents/subagents/probe/AGENT.md`)
+ * — confirmed by the detector (versions.ts) and lister (subagents.ts). Each
+ * such directory is flattened via transformSubagentForClaude (the exact writer
+ * the version-home sync uses) into a single `<name>.md`, then written under an
+ * ownership marker so a re-launch refreshes our file but never clobbers a
+ * user-authored one.
+ *
+ * Returns the same {links, skipped} shape the symlink path reports, so the
+ * caller's accounting is uniform across resource kinds.
+ */
+function writeProjectSubagents(srcDir, destDir, cwd) {
+    let links = 0;
+    const skipped = [];
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (!entry.isDirectory())
+            continue;
+        const subagentDir = path.join(srcDir, entry.name);
+        if (!fs.existsSync(path.join(subagentDir, 'AGENT.md')))
+            continue;
+        const destPath = path.join(destDir, `${entry.name}.md`);
+        if (writeSubagentIfOwned(subagentDir, destPath)) {
+            links += 1;
+        }
+        else {
+            skipped.push(path.relative(cwd, destPath));
+        }
+    }
+    return { links, skipped };
+}
+/**
+ * Write a flattened subagent file at `destPath`, refusing to clobber user state.
+ *
+ *   - dest missing            → write fresh.
+ *   - dest is our generation  → overwrite (refresh; carries GENERATED_SUBAGENT_MARKER).
+ *   - dest is a symlink / any
+ *     non-regular file         → SKIP (user state we don't own).
+ *   - dest is a regular file
+ *     without our marker        → SKIP (hand-authored .claude/agents/<name>.md).
+ *
+ * Returns true when our file is present (written now or already current),
+ * false when we left a user-owned dest alone.
+ */
+function writeSubagentIfOwned(subagentDir, destPath) {
+    let existing = null;
+    let destLstat = null;
+    try {
+        destLstat = fs.lstatSync(destPath);
+    }
+    catch { /* missing — write fresh */ }
+    if (destLstat) {
+        if (!destLstat.isFile())
+            return false; // symlink/dir/etc. — user state
+        try {
+            existing = fs.readFileSync(destPath, 'utf-8');
+        }
+        catch {
+            return false;
+        }
+        if (!existing.includes(GENERATED_SUBAGENT_MARKER))
+            return false; // hand-authored
+    }
+    let body;
+    try {
+        body = transformSubagentForClaude(subagentDir);
+    }
+    catch {
+        return false; // malformed AGENT.md — don't write a broken file
+    }
+    const content = `${body}\n\n${GENERATED_SUBAGENT_MARKER} — edit .agents/subagents/${path.basename(subagentDir)}/ instead -->\n`;
+    // Skip-fast: identical content already on disk → no write (keeps mtime stable).
+    if (existing === content)
+        return true;
+    try {
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+        fs.writeFileSync(destPath, content);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
 /**
  * Create or refresh a symlink at `destPath` pointing at `srcPath`. Returns
  * true if we wrote (or already had) the link, false if we skipped because

package/dist/lib/registry.js

@@ -61,6 +61,13 @@ export function removeRegistry(type, name) {
     }
     return false;
 }
+/**
+ * Cap every registry network call. Without this a slow or unreachable registry
+ * hangs the calling command indefinitely (`agents add`, `agents mcp`, package
+ * resolution) — and makes CI flake when the registry is unreachable. On timeout
+ * the fetch aborts, callers fall back to their git/no-match path.
+ */
+const REGISTRY_FETCH_TIMEOUT_MS = 8000;
 async function fetchMcpRegistry(url, query, limit = 20, apiKey) {
     const params = new URLSearchParams();
     if (query)
@@ -73,7 +80,10 @@ async function fetchMcpRegistry(url, query, limit = 20, apiKey) {
     if (apiKey) {
         headers['Authorization'] = `Bearer ${apiKey}`;
     }
-    const response = await fetch(fullUrl, { headers });
+    const response = await fetch(fullUrl, {
+        headers,
+        signal: AbortSignal.timeout(REGISTRY_FETCH_TIMEOUT_MS),
+    });
     if (!response.ok) {
         throw new Error(`Registry request failed: ${response.status} ${response.statusText}`);
     }
@@ -191,7 +201,10 @@ async function fetchSkillIndex(url, apiKey) {
     const headers = { Accept: 'application/json' };
     if (apiKey)
         headers['Authorization'] = `Bearer ${apiKey}`;
-    const response = await fetch(url, { headers });
+    const response = await fetch(url, {
+        headers,
+        signal: AbortSignal.timeout(REGISTRY_FETCH_TIMEOUT_MS),
+    });
     if (!response.ok) {
         throw new Error(`Registry request failed: ${response.status} ${response.statusText}`);
     }

package/dist/lib/rotate.d.ts

@@ -11,6 +11,13 @@ export interface RotateCandidate {
     agent: AgentId;
     version: string;
     email: string | null;
+    /**
+     * Per-org usage/quota key (e.g. `claude:org=<orgUuid>`) — the unit rate
+     * limits are actually measured in. Distinct orgs signed in under the same
+     * email have distinct keys, so this is the correct dedup boundary; null when
+     * no usage identity is available (then we fall back to email).
+     */
+    usageKey: string | null;
     usageStatus: AccountInfo['usageStatus'];
     usageSnapshot: UsageSnapshot | null;
     authValid: boolean;

package/dist/lib/rotate.js

@@ -105,19 +105,29 @@ function compareCandidates(a, b) {
         return ta - tb;
     return Math.random() - 0.5;
 }
+/**
+ * Identity a candidate dedups on. Quota is tracked per-org, so two versions
+ * that share an org are the same rate-limit bucket and must collapse — but two
+ * orgs under the same email (e.g. Enterprise + Personal on one Google identity)
+ * are genuinely separate buckets and must stay distinct. Prefer the org usage
+ * key; fall back to email only when no usage identity is available.
+ */
+function candidateIdentity(c) {
+    return c.usageKey ?? c.email;
+}
 function dedupeAndSortCandidates(candidates) {
-    const byEmail = new Map();
+    const byIdentity = new Map();
     for (const c of candidates) {
-        const email = c.email;
-        const existing = byEmail.get(email);
+        const id = candidateIdentity(c);
+        const existing = byIdentity.get(id);
         if (!existing) {
-            byEmail.set(email, c);
+            byIdentity.set(id, c);
             continue;
         }
         if (compareCandidates(c, existing) < 0)
-            byEmail.set(email, c);
+            byIdentity.set(id, c);
     }
-    return [...byEmail.values()].sort(compareCandidates);
+    return [...byIdentity.values()].sort(compareCandidates);
 }
 /**
  * Pick a healthy candidate using weighted random by remaining capacity.
@@ -252,7 +262,7 @@ async function collectRunCandidates(agent) {
         const usageSnapshot = usageKey
             ? usageByKey.get(usageKey)?.snapshot ?? null
             : null;
-        return { ...candidate, usageSnapshot };
+        return { ...candidate, usageKey, usageSnapshot };
     });
 }
 /**

package/dist/lib/runner.js

@@ -22,6 +22,7 @@ const AGENT_COMMANDS = {
     codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
     kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
+    droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
 };
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
@@ -105,6 +106,19 @@ export function buildJobCommand(config, resolvedPrompt) {
         }
         appendModelAndReasoning(cmd, config);
     }
+    if (config.agent === 'droid') {
+        // droid exec defaults to read-only (plan). Escalate autonomy per mode.
+        if (mode === 'edit') {
+            cmd.push('--auto', 'low');
+        }
+        else if (mode === 'auto') {
+            cmd.push('--auto', 'high');
+        }
+        else if (mode === 'skip') {
+            cmd.push('--skip-permissions-unsafe');
+        }
+        appendModelAndReasoning(cmd, config);
+    }
     return cmd;
 }
 /**

package/dist/lib/sandbox.js

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
-import { getRoutinesDir } from './state.js';
+import { getRoutinesDir, getUserAgentsDir } from './state.js';
 function resolveRealHome() {
     const home = os.homedir();
     try {
@@ -58,7 +58,10 @@ function tomlString(value) {
 }
 /** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export function buildSpawnEnv(overlayHome, extraEnv) {
-    const env = { HOME: overlayHome };
+    const env = {
+        HOME: overlayHome,
+        AGENTS_USER_DIR: getUserAgentsDir(),
+    };
     for (const key of ENV_ALLOWLIST) {
         if (process.env[key]) {
             env[key] = process.env[key];

package/dist/lib/settings-manifest.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Settings carry-forward between version homes.
+ *
+ * Every installed version gets an isolated `home/`, so user-authored
+ * preferences (settings.json, config.toml, keybindings, auth) written while
+ * running one version do not exist in a freshly installed one. Resources
+ * managed in ~/.agents/ (commands, skills, hooks, rules, MCP YAML, plugins,
+ * subagents) are synced into every version home by syncResourcesToVersion and
+ * are deliberately NOT listed here — copying them would fight that sync.
+ *
+ * The manifest below classifies the remaining per-agent files, and
+ * carryForwardSettings() fills gaps in a target version home from a source
+ * version home. It never overwrites a value the target already has: scalars
+ * keep the target's value, objects merge recursively, arrays union. That makes
+ * the operation idempotent and safe to run on every `agents add` / `agents use`.
+ */
+import type { AgentId } from './types.js';
+export interface CarryForwardResult {
+    /** Manifest rel paths that were created or updated in the target home. */
+    applied: string[];
+    /** Backup directory holding pre-merge copies of modified target files, if any. */
+    backupDir?: string;
+}
+/**
+ * Fill gaps in `target` from `source` without overwriting target values:
+ * missing keys are copied, plain objects recurse, and everything else —
+ * scalars AND arrays — keeps the target's value. Arrays deliberately do not
+ * union: other writers (factory sync, hooks registration) mutate array entries
+ * in place, so a union would keep re-appending stale pre-mutation copies from
+ * the source on every carry (e.g. a user hook duplicated after the system
+ * hooks were merged into it). Returns a new object.
+ */
+export declare function fillGaps(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Carry user settings forward from one version home into another. Both paths
+ * are version-home roots (the directory containing `.claude/` / `.codex/`).
+ * Only fills gaps — never overwrites target values — so it is idempotent.
+ */
+export declare function carryForwardSettings(agent: AgentId, fromHome: string, toHome: string): CarryForwardResult;

package/dist/lib/settings-manifest.js

@@ -0,0 +1,163 @@
+/**
+ * Settings carry-forward between version homes.
+ *
+ * Every installed version gets an isolated `home/`, so user-authored
+ * preferences (settings.json, config.toml, keybindings, auth) written while
+ * running one version do not exist in a freshly installed one. Resources
+ * managed in ~/.agents/ (commands, skills, hooks, rules, MCP YAML, plugins,
+ * subagents) are synced into every version home by syncResourcesToVersion and
+ * are deliberately NOT listed here — copying them would fight that sync.
+ *
+ * The manifest below classifies the remaining per-agent files, and
+ * carryForwardSettings() fills gaps in a target version home from a source
+ * version home. It never overwrites a value the target already has: scalars
+ * keep the target's value, objects merge recursively, arrays union. That makes
+ * the operation idempotent and safe to run on every `agents add` / `agents use`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as TOML from 'smol-toml';
+import { getBackupsDir } from './state.js';
+const SETTINGS_MANIFEST = {
+    claude: [
+        { rel: '.claude/settings.json', strategy: 'json-merge' },
+        { rel: '.claude/settings.local.json', strategy: 'copy-if-absent' },
+        { rel: '.claude/keybindings.json', strategy: 'copy-if-absent' },
+    ],
+    codex: [
+        {
+            rel: '.codex/config.toml',
+            strategy: 'toml-merge',
+            stateKeys: ['notice', 'windows_wsl_setup_acknowledged'],
+        },
+        { rel: '.codex/auth.json', strategy: 'copy-if-absent', restrictMode: true },
+        { rel: '.codex/instructions.md', strategy: 'copy-if-absent' },
+        { rel: '.codex/hooks.json', strategy: 'copy-if-absent' },
+        { rel: '.codex/prompts', strategy: 'dir-entries' },
+        { rel: '.codex/rules', strategy: 'dir-entries' },
+    ],
+};
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Fill gaps in `target` from `source` without overwriting target values:
+ * missing keys are copied, plain objects recurse, and everything else —
+ * scalars AND arrays — keeps the target's value. Arrays deliberately do not
+ * union: other writers (factory sync, hooks registration) mutate array entries
+ * in place, so a union would keep re-appending stale pre-mutation copies from
+ * the source on every carry (e.g. a user hook duplicated after the system
+ * hooks were merged into it). Returns a new object.
+ */
+export function fillGaps(target, source) {
+    const out = { ...target };
+    for (const [key, sourceValue] of Object.entries(source)) {
+        if (!(key in out)) {
+            out[key] = sourceValue;
+            continue;
+        }
+        const targetValue = out[key];
+        if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+            out[key] = fillGaps(targetValue, sourceValue);
+        }
+        // scalar, array, or type mismatch: target wins
+    }
+    return out;
+}
+function stripStateKeys(obj, stateKeys) {
+    if (!stateKeys?.length)
+        return obj;
+    const out = { ...obj };
+    for (const key of stateKeys)
+        delete out[key];
+    return out;
+}
+function backupFile(backupRoot, home, rel) {
+    const src = path.join(home, rel);
+    const dest = path.join(backupRoot, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+}
+/**
+ * Carry user settings forward from one version home into another. Both paths
+ * are version-home roots (the directory containing `.claude/` / `.codex/`).
+ * Only fills gaps — never overwrites target values — so it is idempotent.
+ */
+export function carryForwardSettings(agent, fromHome, toHome) {
+    const manifest = SETTINGS_MANIFEST[agent];
+    const result = { applied: [] };
+    if (!manifest || !fs.existsSync(fromHome) || fromHome === toHome)
+        return result;
+    const backupRoot = path.join(getBackupsDir(), 'settings-carry', agent, new Date().toISOString().replace(/[:.]/g, '-'));
+    for (const entry of manifest) {
+        const sourcePath = path.join(fromHome, entry.rel);
+        const targetPath = path.join(toHome, entry.rel);
+        if (!fs.existsSync(sourcePath))
+            continue;
+        try {
+            switch (entry.strategy) {
+                case 'copy-if-absent': {
+                    if (fs.existsSync(targetPath))
+                        break;
+                    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                    fs.copyFileSync(sourcePath, targetPath);
+                    if (entry.restrictMode)
+                        fs.chmodSync(targetPath, 0o600);
+                    result.applied.push(entry.rel);
+                    break;
+                }
+                case 'dir-entries': {
+                    if (!fs.statSync(sourcePath).isDirectory())
+                        break;
+                    let copied = false;
+                    fs.mkdirSync(targetPath, { recursive: true });
+                    for (const name of fs.readdirSync(sourcePath)) {
+                        const childTarget = path.join(targetPath, name);
+                        if (fs.existsSync(childTarget))
+                            continue;
+                        fs.cpSync(path.join(sourcePath, name), childTarget, { recursive: true });
+                        copied = true;
+                    }
+                    if (copied)
+                        result.applied.push(entry.rel);
+                    break;
+                }
+                case 'json-merge':
+                case 'toml-merge': {
+                    const parse = entry.strategy === 'json-merge'
+                        ? (text) => JSON.parse(text)
+                        : (text) => TOML.parse(text);
+                    const stringify = entry.strategy === 'json-merge'
+                        ? (obj) => JSON.stringify(obj, null, 2) + '\n'
+                        : (obj) => TOML.stringify(obj) + '\n';
+                    const source = stripStateKeys(parse(fs.readFileSync(sourcePath, 'utf-8')), entry.stateKeys);
+                    if (!fs.existsSync(targetPath)) {
+                        if (Object.keys(source).length === 0)
+                            break;
+                        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                        fs.writeFileSync(targetPath, stringify(source), 'utf-8');
+                        result.applied.push(entry.rel);
+                        break;
+                    }
+                    const targetText = fs.readFileSync(targetPath, 'utf-8');
+                    const targetObj = parse(targetText);
+                    const merged = fillGaps(targetObj, source);
+                    // Compare parsed content, not text: other writers format differently,
+                    // and a semantic no-op must not trigger a rewrite/backup every switch.
+                    if (JSON.stringify(merged) === JSON.stringify(targetObj))
+                        break;
+                    backupFile(backupRoot, toHome, entry.rel);
+                    result.backupDir = backupRoot;
+                    fs.writeFileSync(targetPath, stringify(merged), 'utf-8');
+                    result.applied.push(entry.rel);
+                    break;
+                }
+            }
+        }
+        catch {
+            // A malformed source or target file must not break install/use.
+            // Leave the target untouched for this entry and move on.
+        }
+    }
+    return result;
+}

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 17;
+export declare const SHIM_SCHEMA_VERSION = 18;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -11,10 +11,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
-import { IS_WINDOWS } from './platform/index.js';
+import { IS_WINDOWS, prependToWindowsUserPath } from './platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
 import { AGENTS } from './agents.js';
@@ -203,7 +202,7 @@ async function promptConflictStrategy(conflictInfos) {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export const SHIM_SCHEMA_VERSION = 17;
+export const SHIM_SCHEMA_VERSION = 18;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -273,7 +272,7 @@ export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
 # Shim for ${agentConfig.name}
 # ${SHIM_VERSION_MARKER} ${SHIM_SCHEMA_VERSION}
 
-AGENTS_USER_DIR="$HOME/.agents"
+AGENTS_USER_DIR="\${AGENTS_USER_DIR:-$HOME/.agents}"
 AGENTS_BIN=${agentsBin}
 AGENT="${agent}"
 CLI_COMMAND="${cliCommand}"
@@ -1579,36 +1578,22 @@ export function addShimsToPath(overrides) {
  * Register the shims dir on the Windows User PATH via the .NET environment API,
  * which writes the registry AND broadcasts WM_SETTINGCHANGE — the correct analog
  * of editing a shell rc file (no `setx` truncation, no manual step). Idempotent:
- * a no-op when the dir is already present. The shims dir is passed via an env var
- * so it is never interpolated into the PowerShell script text.
+ * a no-op when the shims dir is already first in the User PATH. Moves it to the
+ * front when it exists but is in the wrong position (e.g. appended by an old
+ * install) so it overrides any npm/global installs that appear later. The shims
+ * dir is passed via an env var so it is never interpolated into the script text.
  */
 function addShimsToWindowsUserPath(shimsDir) {
-    const script = [
-        '$d = $env:AGENTS_SHIMS_DIR',
-        "$u = [Environment]::GetEnvironmentVariable('Path','User')",
-        "if ($null -eq $u) { $u = '' }",
-        "$parts = @($u -split ';' | Where-Object { $_ -ne '' })",
-        "if ($parts -contains $d) { 'present' } else {",
-        "  [Environment]::SetEnvironmentVariable('Path', (($parts + $d) -join ';'), 'User')",
-        "  'added'",
-        '}',
-    ].join('\n');
-    try {
-        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
-            encoding: 'utf-8',
-            env: { ...process.env, AGENTS_SHIMS_DIR: shimsDir },
-            stdio: ['ignore', 'pipe', 'pipe'],
-        }).trim();
-        return {
-            success: true,
-            alreadyPresent: out.includes('present'),
-            location: 'your user PATH',
-            reloadHint: 'Open a new terminal for the change to take effect.',
-        };
-    }
-    catch (err) {
-        return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };
+    const r = prependToWindowsUserPath(shimsDir);
+    if (!r.success) {
+        return { success: false, error: r.error };
     }
+    return {
+        success: true,
+        alreadyPresent: r.alreadyPresent,
+        location: 'your user PATH',
+        reloadHint: 'Open a new terminal for the change to take effect.',
+    };
 }
 export function listAgentsWithInstalledVersions() {
     const versionsDir = getVersionsDir();