@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/dist/lib/loop.js

@@ -49,7 +49,19 @@ export function loopSignalPath(runDir) {
  * agent both recalls the prior turn AND knows what to do this iteration.
  */
 export function buildLoopContinuePrompt(prevSessionId, entrypoint) {
-    return `/continue ${prevSessionId}\n\n${entrypoint}`;
+    return buildContinuePrompt(prevSessionId, entrypoint);
+}
+/**
+ * The universal (Tier-2) resume directive: a `/continue <id>` first message that
+ * tells the agent to load the prior transcript via `agents sessions <id>` and
+ * pick up. Works for ANY agent that ships the `/continue` command — the resume
+ * path for agents without a native `--resume` (gemini, grok, opencode, …). An
+ * optional follow-on prompt is appended after a blank line; omitted when empty so
+ * a bare resume sends just the directive.
+ */
+export function buildContinuePrompt(sessionId, prompt) {
+    const directive = `/continue ${sessionId}`;
+    return prompt && prompt.trim() ? `${directive}\n\n${prompt}` : directive;
 }
 /**
  * Resolve a loop interval string to milliseconds. `"0"` is an explicit

package/dist/lib/mcp.js

@@ -13,6 +13,7 @@ import * as yaml from 'yaml';
 import { execFileSync } from 'child_process';
 import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir } from './state.js';
 import { getBinaryPath, getVersionHomePath } from './versions.js';
+import { IS_WINDOWS, needsWindowsShell } from './platform/index.js';
 import { AGENTS } from './agents.js';
 import { isCapable } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
@@ -217,6 +218,7 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
+            shell: needsWindowsShell(binaryPath),
         });
     }
     else {
@@ -225,6 +227,7 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
+            shell: needsWindowsShell(binaryPath),
         });
     }
 }
@@ -245,6 +248,7 @@ function installMcpViaCodex(binaryPath, server, versionHome) {
             stdio: 'pipe',
             timeout: 30000,
             env: { ...process.env, HOME: versionHome },
+            shell: needsWindowsShell(binaryPath),
         });
     }
     // Note: Codex may not support HTTP MCPs
@@ -274,7 +278,7 @@ function registerMcpCommand(agentId, name, commandSpec, scope, transport, option
             ? ['mcp', 'add', '--transport', transport, '--scope', scope, name, '--', ...commandArgs]
             : ['mcp', 'add', name, '--', ...commandArgs];
         const env = options.home ? { ...process.env, HOME: options.home } : process.env;
-        execFileSync(bin, args, { stdio: 'pipe', timeout: 30000, env });
+        execFileSync(bin, args, { stdio: 'pipe', timeout: 30000, env, shell: needsWindowsShell(bin) });
         return { success: true };
     }
     catch (err) {
@@ -442,9 +446,14 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
     }
     const applied = [];
     const errors = [];
-    // Get binary path for CLI-based agents
+    // Get binary path for CLI-based agents. On Windows npm drops a `.cmd` launcher
+    // next to the extensionless POSIX wrapper in node_modules/.bin; prefer it so
+    // the CLI is actually executable (the bare wrapper is a shell script).
     const cliCommand = AGENTS[agentId].cliCommand;
-    const binaryPath = path.join(getVersionsDir(), agentId, version, 'node_modules', '.bin', cliCommand);
+    let binaryPath = path.join(getVersionsDir(), agentId, version, 'node_modules', '.bin', cliCommand);
+    if (IS_WINDOWS && fs.existsSync(binaryPath + '.cmd')) {
+        binaryPath += '.cmd';
+    }
     for (const server of servers) {
         try {
             if (agentId === 'claude') {

package/dist/lib/migrate.js

@@ -9,6 +9,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
+import { createLink } from './platform/index.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -57,7 +58,7 @@ export function foldLegacySystemRepo() {
         try {
             fs.renameSync(LEGACY_SYSTEM_DIR, SYSTEM_DIR);
             try {
-                fs.symlinkSync(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
+                createLink(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
             }
             catch { /* best-effort */ }
             console.error('Folded ~/.agents-system/ into ~/.agents/.system/ (left back-compat symlink)');
@@ -71,7 +72,7 @@ export function foldLegacySystemRepo() {
         copyDirSkipExisting(LEGACY_SYSTEM_DIR, SYSTEM_DIR);
         fs.rmSync(LEGACY_SYSTEM_DIR, { recursive: true, force: true });
         try {
-            fs.symlinkSync(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
+            createLink(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
         }
         catch { /* best-effort */ }
         console.error('Merged ~/.agents-system/ into ~/.agents/.system/ (left back-compat symlink)');
@@ -698,14 +699,14 @@ function repairAgentConfigSymlinks() {
                 continue; // already correct
             try {
                 fs.unlinkSync(symlinkPath);
-                fs.symlinkSync(userTarget, symlinkPath);
+                createLink(userTarget, symlinkPath);
                 repaired++;
             }
             catch { /* best-effort */ }
         }
         else if (!stat) {
             try {
-                fs.symlinkSync(userTarget, symlinkPath);
+                createLink(userTarget, symlinkPath);
                 repaired++;
             }
             catch { /* best-effort */ }
@@ -798,8 +799,11 @@ export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_D
             const realBinary = findInPath(cli);
             try {
                 fs.unlinkSync(binLink);
+                // createLink: a real symlink where the OS allows it (POSIX, and Windows
+                // with the symlink privilege), copy-fallback otherwise — so the repair
+                // lands a working binary on Windows runners without the symlink right.
                 if (realBinary)
-                    fs.symlinkSync(realBinary, binLink);
+                    createLink(realBinary, binLink);
                 repaired++;
             }
             catch { /* best-effort */ }

package/dist/lib/platform/exec.d.ts

@@ -1,5 +1,15 @@
 /** PATH-search command for the platform: `where` on Windows, else `which`. */
 export declare function whichCommand(platform?: NodeJS.Platform): string;
+/**
+ * Does spawning `binary` require `shell: true` on this platform?
+ *
+ * On Windows a `.cmd`/`.bat` wrapper (npm.cmd, bun.cmd, the agent shims) cannot
+ * be exec'd directly — `spawn`/`execFile` look for a literal executable and miss
+ * the PATHEXT/cmd-interpreter step, surfacing as `ENOENT`/`EINVAL`. A bare
+ * command name (not an absolute path) needs the same PATHEXT resolution. Both
+ * cases require the shell. Always false off Windows, where direct exec is right.
+ */
+export declare function needsWindowsShell(binary: string, platform?: NodeJS.Platform): boolean;
 /**
  * Resolve an executable name to its absolute path via the OS PATH search, or
  * `null` if not found. On Windows `where` can return several lines (one per

package/dist/lib/platform/exec.js

@@ -2,10 +2,27 @@
  * Executable resolution, platform-aware.
  */
 import { execFileSync } from 'child_process';
+import * as path from 'path';
 /** PATH-search command for the platform: `where` on Windows, else `which`. */
 export function whichCommand(platform = process.platform) {
     return platform === 'win32' ? 'where' : 'which';
 }
+/**
+ * Does spawning `binary` require `shell: true` on this platform?
+ *
+ * On Windows a `.cmd`/`.bat` wrapper (npm.cmd, bun.cmd, the agent shims) cannot
+ * be exec'd directly — `spawn`/`execFile` look for a literal executable and miss
+ * the PATHEXT/cmd-interpreter step, surfacing as `ENOENT`/`EINVAL`. A bare
+ * command name (not an absolute path) needs the same PATHEXT resolution. Both
+ * cases require the shell. Always false off Windows, where direct exec is right.
+ */
+export function needsWindowsShell(binary, platform = process.platform) {
+    if (platform !== 'win32')
+        return false;
+    // path.win32.isAbsolute, not path.isAbsolute: the latter uses the HOST's rules,
+    // so a Windows path would read as relative when this runs on a Linux CI host.
+    return !path.win32.isAbsolute(binary) || /\.(cmd|bat)$/i.test(binary);
+}
 /**
  * Resolve an executable name to its absolute path via the OS PATH search, or
  * `null` if not found. On Windows `where` can return several lines (one per

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

@@ -17,6 +17,7 @@ export declare const IS_MACOS: boolean;
 export declare const IS_LINUX: boolean;
 export * from './paths.js';
 export * from './exec.js';
+export * from './links.js';
 export * from './process.js';
 export * from './ipc.js';
 export * from './winpath.js';

package/dist/lib/platform/index.js

@@ -17,6 +17,7 @@ export const IS_MACOS = process.platform === 'darwin';
 export const IS_LINUX = process.platform === 'linux';
 export * from './paths.js';
 export * from './exec.js';
+export * from './links.js';
 export * from './process.js';
 export * from './ipc.js';
 export * from './winpath.js';

package/dist/lib/platform/links.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Create a link at `dst` pointing to `src`, portable across platforms.
+ *
+ * - **Directory** target: junction on Windows (no Developer Mode needed), plain
+ *   symlink on POSIX.
+ * - **File** target: symlink, falling back to `copyFileSync` when Windows
+ *   refuses the symlink (`EPERM`/`ENOSYS` — no Developer Mode). The copy is a
+ *   point-in-time snapshot, not a live link; acceptable for the immutable
+ *   targets we link (binaries, config files).
+ *
+ * `dst` must not already exist. Callers that replace atomically should link to a
+ * temp name and `rename` over the destination, exactly as before — the copy
+ * fallback is non-atomic, so the temp+rename stays the caller's responsibility.
+ */
+export declare function createLink(src: string, dst: string): void;

package/dist/lib/platform/links.js

@@ -0,0 +1,42 @@
+/**
+ * Filesystem linking, platform-aware.
+ *
+ * POSIX symlinks have no portable equivalent on Windows: directory symlinks and
+ * file symlinks both require either Administrator or Developer Mode, while
+ * *junctions* (directories only) need no elevation. `createLink` picks the form
+ * that works without privilege — junction for directories — and falls back to a
+ * copy for file links when the OS refuses the symlink.
+ */
+import * as fs from 'fs';
+/**
+ * Create a link at `dst` pointing to `src`, portable across platforms.
+ *
+ * - **Directory** target: junction on Windows (no Developer Mode needed), plain
+ *   symlink on POSIX.
+ * - **File** target: symlink, falling back to `copyFileSync` when Windows
+ *   refuses the symlink (`EPERM`/`ENOSYS` — no Developer Mode). The copy is a
+ *   point-in-time snapshot, not a live link; acceptable for the immutable
+ *   targets we link (binaries, config files).
+ *
+ * `dst` must not already exist. Callers that replace atomically should link to a
+ * temp name and `rename` over the destination, exactly as before — the copy
+ * fallback is non-atomic, so the temp+rename stays the caller's responsibility.
+ */
+export function createLink(src, dst) {
+    const win = process.platform === 'win32';
+    const isDir = fs.statSync(src).isDirectory();
+    // Type is ignored on POSIX; on Windows, junction (dir) avoids the elevation a
+    // dir symlink would need, and 'file' is the explicit file-symlink form.
+    const type = win ? (isDir ? 'junction' : 'file') : undefined;
+    try {
+        fs.symlinkSync(src, dst, type);
+    }
+    catch (err) {
+        const code = err.code;
+        if (win && !isDir && (code === 'EPERM' || code === 'ENOSYS')) {
+            fs.copyFileSync(src, dst);
+            return;
+        }
+        throw err;
+    }
+}

package/dist/lib/platform/paths.d.ts

@@ -27,3 +27,21 @@ export declare function homeDir(): string;
  * whether to apply it (typically gated on win32).
  */
 export declare function isWindowsAbsolutePath(p: string): boolean;
+/**
+ * Fold backslashes to forward slashes. Use when a path is going into a string
+ * that must read the same on every OS — a doc-comparable display path, a regex
+ * subject, a forward-slash-keyed lookup. Pure string transform; on POSIX input
+ * (no backslashes) it returns the value unchanged.
+ */
+export declare function toPosix(p: string): string;
+/**
+ * Derive a filesystem-safe key/slug from an absolute path. Drops the Windows
+ * drive colon (`:` is illegal in NTFS filenames / is the ADS separator) and
+ * folds path separators and spaces to `_`. For a POSIX path this produces the
+ * exact historical slug (`/a/b c` -> `_a_b_c`), so existing on-disk keys are
+ * unchanged; on Windows `C:\a\b` -> `C_a_b` instead of an unusable name.
+ *
+ * Shell mirror (keep byte-identical in any bash shim that recomputes this key):
+ *   printf '%s' "$P" | tr -d ':' | tr '\\/ ' '_'
+ */
+export declare function toPortableKey(p: string): string;

package/dist/lib/platform/paths.js

@@ -56,3 +56,25 @@ export function homeDir() {
 export function isWindowsAbsolutePath(p) {
     return WIN_DRIVE_RE.test(p) || p.startsWith('\\\\');
 }
+/**
+ * Fold backslashes to forward slashes. Use when a path is going into a string
+ * that must read the same on every OS — a doc-comparable display path, a regex
+ * subject, a forward-slash-keyed lookup. Pure string transform; on POSIX input
+ * (no backslashes) it returns the value unchanged.
+ */
+export function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Derive a filesystem-safe key/slug from an absolute path. Drops the Windows
+ * drive colon (`:` is illegal in NTFS filenames / is the ADS separator) and
+ * folds path separators and spaces to `_`. For a POSIX path this produces the
+ * exact historical slug (`/a/b c` -> `_a_b_c`), so existing on-disk keys are
+ * unchanged; on Windows `C:\a\b` -> `C_a_b` instead of an unusable name.
+ *
+ * Shell mirror (keep byte-identical in any bash shim that recomputes this key):
+ *   printf '%s' "$P" | tr -d ':' | tr '\\/ ' '_'
+ */
+export function toPortableKey(p) {
+    return p.replace(/^([a-zA-Z]):/, '$1').replace(/[\\/ ]/g, '_');
+}

package/dist/lib/platform/posixpath.d.ts

@@ -0,0 +1,28 @@
+/** The XDG user-bin dir, `~/.local/bin`. */
+export declare function localBinDir(home?: string): string;
+export interface SymlinkResult {
+    /** A usable symlink to `target` exists at the path after this call. */
+    ok: boolean;
+    /** True only when this call created the symlink (false = already correct, or left untouched). */
+    created: boolean;
+    /** Why an existing entry was left untouched (set only when ok is false). */
+    skippedReason?: string;
+    path: string;
+}
+/**
+ * Ensure `<dir>/<name>` is a symlink to `target`, NEVER clobbering a
+ * pre-existing real file or a symlink that already points elsewhere — most
+ * importantly a developer's `scripts/install.sh` dev build at
+ * `~/.local/bin/agents`. Only an absent path, or a symlink already pointing at
+ * `target`, is created/treated as ok. Idempotent.
+ */
+export declare function ensureLocalBinSymlink(name: string, target: string, dir?: string): SymlinkResult;
+/**
+ * Does a fresh `bash -lc` resolve `cmd` on its PATH? This is the real question
+ * for the consumers we heal. Best-effort: any probe failure returns false so
+ * the caller heals rather than wrongly assuming success. `command -v` is a
+ * POSIX builtin.
+ */
+export declare function loginShellResolves(cmd: string): boolean;
+/** Is `dir` on a fresh `bash -lc` PATH? Best-effort; a probe failure returns false. */
+export declare function dirOnLoginPath(dir: string): boolean;

package/dist/lib/platform/posixpath.js

@@ -0,0 +1,153 @@
+/**
+ * POSIX login-PATH primitives for making the `agents` command resolvable.
+ *
+ * The Unix analog of winpath.ts. `agents`/`ag` land on PATH only via npm's
+ * bin symlink into the npm global-bin dir; under nvm (and other per-user node
+ * prefixes) that dir is absent from a *non-interactive login* shell's PATH, so
+ * `bash -lc 'agents …'` fails with command-not-found. That breaks every
+ * consumer that drives a login shell on the box: `agents secrets export --host`
+ * (which runs `bash -lc 'agents secrets import …'` on the remote) and the
+ * routines daemon (`src/lib/daemon.ts`, which falls back to bare `agents`).
+ *
+ * The fix mirrors the Windows postinstall branch (which registers npm's
+ * global-bin dir on the user PATH): symlink the entrypoint into ~/.local/bin —
+ * the XDG user-bin dir that mainstream distros auto-add to the login PATH when
+ * it exists (Debian/Ubuntu via ~/.profile, Fedora via /etc/profile.d) — and,
+ * where it is not yet on PATH, the caller adds it.
+ *
+ * Leaf module — imports only child_process / fs / os / path so it is cheap to
+ * load from the npm lifecycle script without pulling the rest of the CLI.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** The XDG user-bin dir, `~/.local/bin`. */
+export function localBinDir(home = os.homedir()) {
+    return path.join(home, '.local', 'bin');
+}
+/**
+ * Ensure `<dir>/<name>` is a symlink to `target`, NEVER clobbering a
+ * pre-existing real file or a symlink that already points elsewhere — most
+ * importantly a developer's `scripts/install.sh` dev build at
+ * `~/.local/bin/agents`. Only an absent path, or a symlink already pointing at
+ * `target`, is created/treated as ok. Idempotent.
+ */
+export function ensureLocalBinSymlink(name, target, dir = localBinDir()) {
+    const linkPath = path.join(dir, name);
+    const want = path.resolve(target);
+    let current = null;
+    try {
+        current = fs.readlinkSync(linkPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EINVAL') {
+            // The path exists but is not a symlink — a real file/dir. Never clobber.
+            return { ok: false, created: false, skippedReason: 'a non-symlink file already exists here', path: linkPath };
+        }
+        if (code !== 'ENOENT') {
+            return { ok: false, created: false, skippedReason: err.message, path: linkPath };
+        }
+        // ENOENT — nothing there; fall through to create.
+    }
+    if (current !== null) {
+        const resolved = path.isAbsolute(current) ? current : path.resolve(dir, current);
+        if (resolved === want)
+            return { ok: true, created: false, path: linkPath };
+        // Points somewhere else (e.g. a dev build) — the existing link wins.
+        return { ok: false, created: false, skippedReason: `symlink already points to ${current}`, path: linkPath };
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.symlinkSync(target, linkPath);
+    return { ok: true, created: true, path: linkPath };
+}
+/**
+ * Absolute path to `bash`. We probe bash specifically — NOT the user's $SHELL —
+ * because the consumers we are healing run `bash -lc` regardless of login shell:
+ * `secrets export --host` builds `bash -lc 'agents secrets import …'` for the
+ * remote, and the routines daemon resolves `agents` the same way. On a box whose
+ * login shell is zsh, zsh's login PATH may lack ~/.local/bin while bash's
+ * includes it (Debian/Ubuntu ~/.profile) — so probing $SHELL would give the
+ * wrong answer for what the consumer actually sees. Resolve from the *current*
+ * PATH (the install process has one) and fall back to /bin/bash.
+ */
+function bashPath() {
+    const found = (process.env.PATH || '')
+        .split(path.delimiter)
+        .map((d) => (d ? path.join(d, 'bash') : ''))
+        .find((p) => {
+        if (!p)
+            return false;
+        try {
+            fs.accessSync(p, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    return found || '/bin/bash';
+}
+/**
+ * Environment for the probe shell that reproduces a *fresh* `bash -lc` — the
+ * PATH that `ssh host 'bash -lc …'` and the routines daemon actually get — and
+ * NOT the nvm/npm-augmented PATH of the install process.
+ *
+ * This is the crux: `npm i -g` (and a dev `bun run`) execute under nvm, so the
+ * caller's PATH already contains nvm's bin. A spawned shell inherits that PATH,
+ * so it would resolve `agents` and the heal would skip — during the very nvm
+ * install it exists to fix. We strip PATH (and nvm's hint vars) so the login
+ * profile rebuilds PATH from scratch, exactly as an incoming SSH command shell
+ * does. Login bash still sources /etc/profile + ~/.profile (which adds
+ * ~/.local/bin) but bails out of ~/.bashrc's nvm block early because it is
+ * non-interactive — which is precisely why bare `agents` is missing there.
+ */
+function loginProbeEnv() {
+    const env = { ...process.env };
+    delete env.PATH;
+    delete env.NVM_BIN;
+    delete env.NVM_INC;
+    for (const k of Object.keys(env))
+        if (k.startsWith('npm_'))
+            delete env[k];
+    return env;
+}
+/**
+ * Does a fresh `bash -lc` resolve `cmd` on its PATH? This is the real question
+ * for the consumers we heal. Best-effort: any probe failure returns false so
+ * the caller heals rather than wrongly assuming success. `command -v` is a
+ * POSIX builtin.
+ */
+export function loginShellResolves(cmd) {
+    try {
+        const res = spawnSync(bashPath(), ['-lc', `command -v ${cmd}`], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 5000,
+            env: loginProbeEnv(),
+        });
+        return res.status === 0 && !!res.stdout && res.stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Is `dir` on a fresh `bash -lc` PATH? Best-effort; a probe failure returns false. */
+export function dirOnLoginPath(dir) {
+    try {
+        const res = spawnSync(bashPath(), ['-lc', 'printf %s "$PATH"'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 5000,
+            env: loginProbeEnv(),
+        });
+        if (res.status !== 0 || !res.stdout)
+            return false;
+        const want = path.resolve(dir);
+        return res.stdout.split(':').some((p) => p && path.resolve(p) === want);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/plugin-marketplace.d.ts

@@ -113,6 +113,24 @@ export declare function copyPluginToMarketplace(plugin: DiscoveredPlugin, spec:
  * check would false-positive.
  */
 export declare function validateClaudePluginManifest(manifest: unknown): string[];
+/**
+ * The repairable fields present-and-invalid in a parsed manifest. Drives both
+ * the dry-run preview (heal/doctor --fix) and the actual write below.
+ */
+export declare function repairableManifestFields(manifest: unknown): string[];
+/**
+ * Auto-repair a plugin's SOURCE plugin.json in place: delete any `skills`/
+ * `commands` field that holds bare names (Claude Code silently rejects the
+ * ENTIRE plugin otherwise). Claude auto-discovers both from their directories,
+ * so deletion is the canonical, lossless fix — exactly what the validator's
+ * warning already recommends. Returns the fields it dropped (empty = no change).
+ *
+ * Writes to the source manifest (not the regenerated marketplace copy) so the
+ * fix survives the next sync. Pass `{ dryRun }` to preview without writing.
+ */
+export declare function repairPluginManifestFile(manifestPath: string, opts?: {
+    dryRun?: boolean;
+}): string[];
 /**
  * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the plugins
  * already installed under <marketplace>/plugins/. Always run after add or remove

package/dist/lib/plugin-marketplace.js

@@ -28,7 +28,7 @@
 import * as fs from 'fs';
 import { agentConfigDirName } from './agents.js';
 import * as path from 'path';
-import { getPluginsDir, getEnabledExtraRepos, getProjectPluginsDir } from './state.js';
+import { getPluginsDir, getEnabledExtraRepos, getProjectPluginsDir, getSystemPluginsDir } from './state.js';
 /**
  * Canonical name for the user-repo marketplace (~/.agents/plugins/). Kept as an
  * exported constant for callers that operate on the user repo directly and for
@@ -76,6 +76,19 @@ function descriptionFor(spec) {
  */
 export function discoverMarketplaces(opts = {}) {
     const out = [];
+    // System repo — npm-shipped defaults (~/.agents/.system/plugins/) → the
+    // "agents-system" marketplace. Listed FIRST so it has the lowest precedence:
+    // consumers that dedupe by plugin name keep the LAST occurrence, letting
+    // user / extra / project plugins of the same name override a system one (same
+    // direction collectPluginScopes() in project-launch.ts uses). Without this,
+    // `agents sync` never discovers system plugins, so cleanOrphanedPluginSkills
+    // trashes whatever a project launch installed under agents-system and the
+    // marketplace gets unregistered on the next sync.
+    const systemRoot = getSystemPluginsDir();
+    if (dirExists(systemRoot)) {
+        const spec = { kind: 'system', root: systemRoot };
+        out.push({ spec, name: marketplaceNameFor(spec), pluginsRoot: systemRoot, description: descriptionFor(spec) });
+    }
     // User repo — always the canonical "agents-cli" marketplace.
     const userRoot = getPluginsDir();
     if (dirExists(userRoot)) {
@@ -233,6 +246,59 @@ export function validateClaudePluginManifest(manifest) {
     }
     return warnings;
 }
+/**
+ * Fields safe to auto-repair by deletion. Scoped to `skills`/`commands` only —
+ * NOT `agents`: agents-cli overloads `agents` in plugin.json as its own
+ * `AgentId[]` targeting list (bare names like "claude"), so stripping it would
+ * destroy real metadata. (`validateClaudePluginManifest` still WARNS on a bare
+ * `agents` field; repairing it is a separate, deliberate non-goal here.)
+ */
+const REPAIRABLE_PATH_FIELDS = ['skills', 'commands'];
+/** True when a manifest field holds bare-name entries Claude Code rejects. */
+function fieldHasBareEntries(value) {
+    if (value === undefined || value === null)
+        return false;
+    const entries = Array.isArray(value) ? value : [value];
+    return entries.some((e) => typeof e !== 'string' || !e.startsWith('./'));
+}
+/**
+ * The repairable fields present-and-invalid in a parsed manifest. Drives both
+ * the dry-run preview (heal/doctor --fix) and the actual write below.
+ */
+export function repairableManifestFields(manifest) {
+    if (!manifest || typeof manifest !== 'object')
+        return [];
+    const m = manifest;
+    return REPAIRABLE_PATH_FIELDS.filter((f) => fieldHasBareEntries(m[f]));
+}
+/**
+ * Auto-repair a plugin's SOURCE plugin.json in place: delete any `skills`/
+ * `commands` field that holds bare names (Claude Code silently rejects the
+ * ENTIRE plugin otherwise). Claude auto-discovers both from their directories,
+ * so deletion is the canonical, lossless fix — exactly what the validator's
+ * warning already recommends. Returns the fields it dropped (empty = no change).
+ *
+ * Writes to the source manifest (not the regenerated marketplace copy) so the
+ * fix survives the next sync. Pass `{ dryRun }` to preview without writing.
+ */
+export function repairPluginManifestFile(manifestPath, opts = {}) {
+    if (!fs.existsSync(manifestPath))
+        return [];
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    }
+    catch {
+        return []; // unparseable manifest is a different failure; don't touch it.
+    }
+    const dropped = repairableManifestFields(manifest);
+    if (dropped.length === 0 || opts.dryRun)
+        return dropped;
+    for (const f of dropped)
+        delete manifest[f];
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    return dropped;
+}
 // ─── Catalog synthesis ──────────────────────────────────────────────────────
 /**
  * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the plugins

package/dist/lib/plugins.d.ts

@@ -65,7 +65,12 @@ export declare function loadPluginManifest(pluginRoot: string): PluginManifest |
 export declare function validatePluginName(name: string): boolean;
 export declare function assertPluginTargetContained(targetRoot: string, pluginsDir: string): void;
 /**
- * Get a specific plugin by name.
+ * Get a specific plugin by name. On a cross-marketplace name collision the
+ * highest-precedence scope wins (project > extra > user > system) — the same
+ * resolution the sync writer's Map(last-wins) dedupe and collectPluginScopes()
+ * use. discoverPlugins() yields low→high precedence order, so the LAST match is
+ * the winner; returning the first match would resolve to the lowest scope (e.g.
+ * a system plugin over the user's same-named one), which is exactly backwards.
  */
 export declare function getPlugin(name: string): DiscoveredPlugin | null;
 /**
@@ -118,6 +123,16 @@ export declare function saveUserConfig(pluginName: string, config: Record<string
  * Returns names of missing dependencies (warning only — not a hard error).
  */
 export declare function checkPluginDependencies(manifest: PluginManifest): string[];
+/**
+ * Reconstruct a MarketplaceSpec from a marketplace name. The inverse of
+ * marketplaceNameFor(): "agents-cli" → user, "agents-project" → project,
+ * "agents-system" → system, "agents-<alias>" → extra. The per-version
+ * marketplace operations only key off the name (never spec.root), but we
+ * resolve the real source root anyway so the spec is honest for any caller that
+ * inspects it (e.g. descriptionFor, which would otherwise label the system
+ * marketplace as an extra repo named "system").
+ */
+export declare function marketplaceSpecForName(name: string | undefined, cwd?: string): MarketplaceSpec;
 /**
  * Sync a plugin to a specific agent version's home directory.
  *
@@ -212,6 +227,23 @@ export declare function installPlugin(spec: string): Promise<{
     isNew: boolean;
     capabilities: PluginCapabilities;
 }>;
+/** Parsed `.source` provenance written by install/update. `version` is the
+ *  upstream manifest version captured at the last pull (absent on pre-existing
+ *  installs from before baseline tracking). */
+export interface PluginSourceInfo {
+    source: string;
+    isGit: boolean;
+    version?: string;
+}
+/** Read a plugin's `.source` provenance, or null when absent/unreadable. */
+export declare function readPluginSourceInfo(root: string): PluginSourceInfo | null;
+/**
+ * Resolve the CURRENT upstream manifest version for a local-sourced plugin
+ * (the `.system`/local-path case). Returns null for git sources — reading their
+ * upstream version would need a network fetch, so git plugins are refreshed only
+ * via the explicit `agents plugins update`.
+ */
+export declare function getUpstreamManifestVersion(info: PluginSourceInfo): string | null;
 /**
  * Update an installed plugin by re-pulling from its original source.
  * Returns true if the update succeeded.