@phnx-labs/agents-cli 1.20.26 → 1.20.27

package/dist/lib/doctor-diff.js

@@ -80,13 +80,13 @@ function buildLayerBases(cwd, kind, opts = {}) {
     return out;
 }
 // ─── commands ─────────────────────────────────────────────────────────────────
-function diffCommands(agent, version, cwd) {
+function diffCommands(agent, version, cwd, excludeProject = false) {
     const agentConfig = AGENTS[agent];
     const isToml = agentConfig.format === 'toml';
     const ext = isToml ? '.toml' : '.md';
     const homeDir = getVersionCommandsDir(agent, version);
     const installed = new Set(listCommandsInVersionHome(agent, version));
-    const layerBases = buildLayerBases(cwd, 'commands');
+    const layerBases = buildLayerBases(cwd, 'commands', { excludeProject });
     const sourceByName = new Map();
     for (const base of layerBases) {
         if (!fs.existsSync(base.path))
@@ -190,10 +190,10 @@ function dirsContentMatch(src, dst) {
     }
     return true;
 }
-function diffSkills(agent, version, cwd) {
+function diffSkills(agent, version, cwd, excludeProject = false) {
     const homeDir = getVersionSkillsDir(agent, version);
     const installed = new Set(listSkillsInVersionHome(agent, version));
-    const layerBases = buildLayerBases(cwd, 'skills');
+    const layerBases = buildLayerBases(cwd, 'skills', { excludeProject });
     const sourceByName = new Map();
     for (const base of layerBases) {
         if (!fs.existsSync(base.path))
@@ -298,8 +298,8 @@ function diffHooks(agent, version, cwd) {
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
 // ─── rules / memory ───────────────────────────────────────────────────────────
-function listRulesNames(cwd) {
-    const projectDir = getProjectAgentsDir(cwd);
+function listRulesNames(cwd, excludeProject = false) {
+    const projectDir = excludeProject ? null : getProjectAgentsDir(cwd);
     const userRules = getUserRulesDir();
     const systemRules = getResolvedRulesDir();
     const extras = getEnabledExtraRepos();
@@ -349,11 +349,11 @@ function expectedRuleContent(agent, name, sourcePath) {
     }
     return readSafe(sourcePath);
 }
-function diffRules(agent, version, cwd) {
+function diffRules(agent, version, cwd, excludeProject = false) {
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
     const configDir = path.join(versionHome, agentConfigDirName(agent));
-    const sourcesByName = listRulesNames(cwd);
+    const sourcesByName = listRulesNames(cwd, excludeProject);
     // Files actually present in the version home.
     const homeFiles = new Set();
     if (fs.existsSync(configDir)) {
@@ -432,9 +432,14 @@ function diffPromptcuts() {
     return [{ kind: 'promptcuts', name: 'promptcuts.yaml', status: 'ok', sourcePath }];
 }
 export function diffVersionResources(agent, version, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
+    const rawCwd = options.cwd ?? process.cwd();
+    const excludeProject = options.excludeProject ?? false;
     const home = getVersionHomePath(agent, version);
     const requested = new Set(options.kinds ?? ALL_KINDS);
+    // When excluding the project layer, resolve every per-cwd lookup against a
+    // neutral cwd so no `<cwd>/.agents/` is ever discovered.
+    const cwd = rawCwd;
+    const projectDir = excludeProject ? null : getProjectAgentsDir(cwd);
     const available = getAvailableResources(cwd);
     const synced = getActuallySyncedResources(agent, version, { cwd });
     const empty = {
@@ -449,13 +454,13 @@ export function diffVersionResources(agent, version, options = {}) {
         promptcuts: [],
     };
     if (requested.has('commands'))
-        empty.commands = diffCommands(agent, version, cwd);
+        empty.commands = diffCommands(agent, version, cwd, excludeProject);
     if (requested.has('skills'))
-        empty.skills = diffSkills(agent, version, cwd);
+        empty.skills = diffSkills(agent, version, cwd, excludeProject);
     if (requested.has('hooks'))
         empty.hooks = diffHooks(agent, version, cwd);
     if (requested.has('rules'))
-        empty.rules = diffRules(agent, version, cwd);
+        empty.rules = diffRules(agent, version, cwd, excludeProject);
     if (requested.has('mcp'))
         empty.mcp = diffPresenceOnly('mcp', available.mcp, synced.mcp);
     if (requested.has('permissions'))
@@ -485,7 +490,7 @@ export function diffVersionResources(agent, version, options = {}) {
         home,
         cwd,
         layers: {
-            project: getProjectAgentsDir(cwd),
+            project: projectDir,
             user: getUserAgentsDir(),
             system: getSystemAgentsDir(),
             extras: getEnabledExtraRepos().map((e) => ({ alias: e.alias, dir: e.dir })),

package/dist/lib/heal.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Resource heal engine — close the gap between what DotAgents repos DEFINE and
+ * what is actually present/valid in each installed agent home.
+ *
+ * Powers two callers:
+ *   - `agents doctor --fix`  — explicit, operator-driven. Mode 'full': fills
+ *     missing, overwrites drifted content, and refreshes stale plugins even when
+ *     the baseline is unknown (the operator asked for it).
+ *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
+ *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
+ *     provably-unmodified stale plugins). Drift and risky refreshes are reported,
+ *     never clobbered.
+ *
+ * Built on the LIVE-home diff (`diffVersionResources`) — NOT the staleness
+ * manifest. `isStale()` only compares the last-synced manifest against the
+ * sources, so home-side rot (a deleted, corrupted, or Claude-rejected file in a
+ * version home whose source never changed) is invisible to it and to the sync
+ * fast-guard. The diff reads the actual home, so heal catches exactly that class
+ * of drift — the kind that silently broke the `code` plugin on a non-default
+ * Claude version.
+ *
+ * Heal FILLS and FIXES; it never deletes. Orphan/extra removal stays the job of
+ * `agents prune cleanup`, so a heal pass can never lose work.
+ */
+import type { AgentId } from './types.js';
+import { type DoctorKind, type DiffStatus } from './doctor-diff.js';
+export interface HealedResource {
+    kind: DoctorKind;
+    name: string;
+    /** Why it was healed: 'missing' (filled) or 'diff' (overwritten / re-pushed). */
+    was: DiffStatus;
+}
+export interface SkippedResource {
+    kind: DoctorKind;
+    name: string;
+    /** 'drift': hand-edited content left untouched in 'safe' mode.
+     *  'unreconcilable': heal wrote it but the diff still flags it — a source/home
+     *  asymmetry the writer can't satisfy (e.g. a hook sidecar the installer omits),
+     *  surfaced honestly instead of "fixed" on every pass. */
+    reason: 'drift' | 'unreconcilable';
+}
+export interface VersionHealResult {
+    agent: AgentId;
+    version: string;
+    healed: HealedResource[];
+    skipped: SkippedResource[];
+}
+export interface ManifestRepairResult {
+    plugin: string;
+    /** Bare-name fields stripped from the source plugin.json (e.g. ["skills"]). */
+    droppedFields: string[];
+}
+export interface PluginRefreshResult {
+    plugin: string;
+    from: string;
+    to: string;
+}
+export interface PluginRefreshSkip {
+    plugin: string;
+    from: string;
+    upstream: string;
+    /** 'modified': central diverged from baseline. 'no-baseline': pre-tracking install. */
+    reason: 'modified' | 'no-baseline';
+}
+export interface HealResult {
+    versions: VersionHealResult[];
+    repairedManifests: ManifestRepairResult[];
+    refreshedPlugins: PluginRefreshResult[];
+    skippedPlugins: PluginRefreshSkip[];
+}
+export interface HealOptions {
+    /** 'full' (doctor --fix): fix drift + refresh unknown-baseline plugins.
+     *  'safe' (daemon): missing + invalid-manifest + unmodified refresh only. */
+    mode: 'full' | 'safe';
+    /** Resolution cwd. Defaults to the home dir so no project layer is ever
+     *  resolved — heal targets the GLOBAL install, never a project. Tests override. */
+    cwd?: string;
+    /** Scope to one agent; omit to heal every installed agent. */
+    agent?: AgentId;
+    /** Scope to specific versions of `agent`; omit for all installed versions. */
+    versions?: string[];
+    /** Compute the plan without writing anything. */
+    dryRun?: boolean;
+}
+/** True when a heal pass made (or would make) any change at all. */
+export declare function healChangedAnything(r: HealResult): boolean;
+/** One-line summary of a heal pass for daemon logs. */
+export declare function summarizeHeal(r: HealResult): string;
+/**
+ * Fire a native desktop notification when a background heal did something
+ * noteworthy. Best-effort — missing `osascript`/`notify-send` or no display is
+ * swallowed. Silent when the pass auto-fixed everything and nothing needs the
+ * operator (no point pinging them for routine self-healing).
+ */
+export declare function notifyHeal(r: HealResult): void;
+/**
+ * Strip Claude-invalid bare-name `skills`/`commands` fields from every central
+ * plugin's SOURCE plugin.json. Unambiguously safe (Claude auto-discovers both
+ * from their directories) and the precondition for those plugins loading at all.
+ */
+export declare function repairCentralPluginManifests(dryRun?: boolean): ManifestRepairResult[];
+/**
+ * Run a heal pass. Repairs the central plugin layer once (manifest + stale
+ * refresh), then reconciles every targeted (agent, version) home against its
+ * live diff. Returns a full account of what changed (or would, under dryRun).
+ */
+export declare function heal(opts: HealOptions): Promise<HealResult>;

package/dist/lib/heal.js

@@ -0,0 +1,279 @@
+/**
+ * Resource heal engine — close the gap between what DotAgents repos DEFINE and
+ * what is actually present/valid in each installed agent home.
+ *
+ * Powers two callers:
+ *   - `agents doctor --fix`  — explicit, operator-driven. Mode 'full': fills
+ *     missing, overwrites drifted content, and refreshes stale plugins even when
+ *     the baseline is unknown (the operator asked for it).
+ *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
+ *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
+ *     provably-unmodified stale plugins). Drift and risky refreshes are reported,
+ *     never clobbered.
+ *
+ * Built on the LIVE-home diff (`diffVersionResources`) — NOT the staleness
+ * manifest. `isStale()` only compares the last-synced manifest against the
+ * sources, so home-side rot (a deleted, corrupted, or Claude-rejected file in a
+ * version home whose source never changed) is invisible to it and to the sync
+ * fast-guard. The diff reads the actual home, so heal catches exactly that class
+ * of drift — the kind that silently broke the `code` plugin on a non-default
+ * Claude version.
+ *
+ * Heal FILLS and FIXES; it never deletes. Orphan/extra removal stays the job of
+ * `agents prune cleanup`, so a heal pass can never lose work.
+ */
+import { ALL_AGENT_IDS } from './agents.js';
+import { syncResourcesToVersion, listInstalledVersions, getVersionHomePath, getActuallySyncedResources, compareVersions, } from './versions.js';
+import { diffVersionResources, } from './doctor-diff.js';
+import { discoverPlugins, updatePlugin, readPluginSourceInfo, getUpstreamManifestVersion, } from './plugins.js';
+import { repairPluginManifestFile } from './plugin-marketplace.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { spawn } from 'child_process';
+// ─── diff → selection mapping ────────────────────────────────────────────────
+// Which ResourceSelection key each healable diff kind writes through. `rules`
+// re-syncs via the whole-memory channel (not name-scoped); `promptcuts` is not
+// version-synced at all, so it is never healed here.
+const KIND_TO_SELECTION = {
+    commands: 'commands',
+    skills: 'skills',
+    hooks: 'hooks',
+    mcp: 'mcp',
+    permissions: 'permissions',
+    subagents: 'subagents',
+    plugins: 'plugins',
+};
+function totalHealed(r) {
+    return r.versions.reduce((n, v) => n + v.healed.length, 0);
+}
+/** True when a heal pass made (or would make) any change at all. */
+export function healChangedAnything(r) {
+    return (totalHealed(r) > 0 ||
+        r.repairedManifests.length > 0 ||
+        r.refreshedPlugins.length > 0);
+}
+/** One-line summary of a heal pass for daemon logs. */
+export function summarizeHeal(r) {
+    const parts = [];
+    const healed = totalHealed(r);
+    if (healed > 0)
+        parts.push(`${healed} resource(s) healed`);
+    if (r.repairedManifests.length > 0)
+        parts.push(`${r.repairedManifests.length} manifest(s) repaired`);
+    if (r.refreshedPlugins.length > 0)
+        parts.push(`${r.refreshedPlugins.length} plugin(s) refreshed`);
+    if (r.skippedPlugins.length > 0)
+        parts.push(`${r.skippedPlugins.length} plugin(s) need attention`);
+    return parts.length > 0 ? parts.join(', ') : 'nothing to heal';
+}
+/**
+ * Fire a native desktop notification when a background heal did something
+ * noteworthy. Best-effort — missing `osascript`/`notify-send` or no display is
+ * swallowed. Silent when the pass auto-fixed everything and nothing needs the
+ * operator (no point pinging them for routine self-healing).
+ */
+export function notifyHeal(r) {
+    const needsAttention = r.skippedPlugins.length;
+    const healed = totalHealed(r) + r.repairedManifests.length + r.refreshedPlugins.length;
+    if (needsAttention === 0 && healed === 0)
+        return;
+    const title = needsAttention > 0
+        ? `agents: ${needsAttention} plugin${needsAttention === 1 ? '' : 's'} need attention`
+        : 'agents: auto-healed config gaps';
+    const body = needsAttention > 0
+        ? `${summarizeHeal(r)}. Run: agents doctor --fix`
+        : summarizeHeal(r);
+    const platform = os.platform();
+    try {
+        if (platform === 'darwin') {
+            const safeTitle = title.replace(/"/g, '\\"');
+            const safeBody = body.replace(/"/g, '\\"');
+            const child = spawn('osascript', ['-e', `display notification "${safeBody}" with title "${safeTitle}"`], { detached: true, stdio: 'ignore' });
+            child.unref();
+        }
+        else if (platform === 'linux') {
+            const child = spawn('notify-send', [title, body], { detached: true, stdio: 'ignore' });
+            child.unref();
+        }
+    }
+    catch {
+        // Notification is best-effort; nothing to do.
+    }
+}
+// ─── central plugin layer (version-independent, runs once per heal) ──────────
+/**
+ * Strip Claude-invalid bare-name `skills`/`commands` fields from every central
+ * plugin's SOURCE plugin.json. Unambiguously safe (Claude auto-discovers both
+ * from their directories) and the precondition for those plugins loading at all.
+ */
+export function repairCentralPluginManifests(dryRun = false) {
+    const out = [];
+    for (const p of discoverPlugins()) {
+        const manifestPath = path.join(p.root, '.claude-plugin', 'plugin.json');
+        const dropped = repairPluginManifestFile(manifestPath, { dryRun });
+        if (dropped.length > 0)
+            out.push({ plugin: p.name, droppedFields: dropped });
+    }
+    return out;
+}
+/**
+ * Fast-forward central plugins whose local `.source` upstream now ships a newer
+ * version. `allowModified` (full mode) re-pulls regardless of baseline; safe
+ * mode refreshes only when the central copy is provably an untouched mirror of
+ * its last pull (baseline version === current version) and reports the rest.
+ */
+async function refreshStaleCentralPlugins(opts) {
+    const refreshed = [];
+    const skipped = [];
+    for (const p of discoverPlugins()) {
+        const info = readPluginSourceInfo(p.root);
+        if (!info)
+            continue;
+        const upstream = getUpstreamManifestVersion(info); // null for git sources
+        if (!upstream)
+            continue;
+        const central = p.manifest.version;
+        if (compareVersions(upstream, central) <= 0)
+            continue; // central already current
+        const baselineKnown = info.version !== undefined;
+        const modified = baselineKnown && info.version !== central;
+        if (!opts.allowModified) {
+            // Safe mode never overwrites a copy it can't prove is pristine.
+            if (modified) {
+                skipped.push({ plugin: p.name, from: central, upstream, reason: 'modified' });
+                continue;
+            }
+            if (!baselineKnown) {
+                skipped.push({ plugin: p.name, from: central, upstream, reason: 'no-baseline' });
+                continue;
+            }
+        }
+        if (opts.dryRun) {
+            refreshed.push({ plugin: p.name, from: central, to: upstream });
+            continue;
+        }
+        const r = await updatePlugin(p.name);
+        if (r.success)
+            refreshed.push({ plugin: p.name, from: central, to: upstream });
+    }
+    return { refreshed, skipped };
+}
+// ─── per-version heal ────────────────────────────────────────────────────────
+function healVersion(agent, version, opts) {
+    const result = { agent, version, healed: [], skipped: [] };
+    const home = getVersionHomePath(agent, version);
+    if (!fs.existsSync(home))
+        return result;
+    // Always resolve against non-project layers: the global version home is never
+    // reconciled against per-cwd project resources (they layer in at launch).
+    const diffOpts = { cwd: opts.cwd, excludeProject: true };
+    const report = diffVersionResources(agent, version, diffOpts);
+    const selection = {};
+    // Resources we attempt to write, tracked so the post-write re-diff can tell
+    // "actually fixed" from "writer couldn't satisfy the diff" (no false claims).
+    const attempted = [];
+    for (const rows of Object.values(report.kinds)) {
+        for (const row of rows) {
+            const isMissing = row.status === 'missing';
+            const isDrift = row.status === 'diff';
+            if (!isMissing && !isDrift)
+                continue;
+            if (isDrift && !opts.includeDrift) {
+                // Ambiguous content drift — could be a deliberate hand-edit. Report it
+                // (the daemon notifies); never silently overwrite in safe mode.
+                result.skipped.push({ kind: row.kind, name: row.name, reason: 'drift' });
+                continue;
+            }
+            if (row.kind === 'promptcuts')
+                continue; // not version-synced
+            if (row.kind === 'rules') {
+                selection.memory = 'all';
+                attempted.push({ kind: row.kind, name: row.name, was: row.status });
+                continue;
+            }
+            const key = KIND_TO_SELECTION[row.kind];
+            if (!key)
+                continue;
+            (selection[key] ??= []).push(row.name);
+            attempted.push({ kind: row.kind, name: row.name, was: row.status });
+        }
+    }
+    // Plugins are presence-only in the diff, so a stale/invalid-but-present plugin
+    // mirror never shows as 'diff' — yet its central source just changed (repaired
+    // or refreshed). Re-push those into this version's marketplace mirror, but only
+    // where the plugin is already installed (don't force-install into a version
+    // that opted out). These are verified by the central change, not the re-diff.
+    const pluginHealed = [];
+    if (opts.changedPlugins.size > 0) {
+        const synced = new Set(getActuallySyncedResources(agent, version, diffOpts).plugins);
+        const already = new Set(selection.plugins ?? []);
+        for (const name of opts.changedPlugins) {
+            if (!synced.has(name) || already.has(name))
+                continue;
+            (selection.plugins ??= []).push(name);
+            pluginHealed.push({ kind: 'plugins', name, was: 'diff' });
+        }
+    }
+    const hasWork = Object.keys(selection).length > 0;
+    if (!hasWork)
+        return result;
+    if (opts.dryRun) {
+        // No write — report the intended fixes as-is.
+        result.healed.push(...attempted, ...pluginHealed);
+        return result;
+    }
+    // Explicit selection => bypasses the manifest fast-guard and writes exactly
+    // these names (additive; no orphan-sweep), so nothing outside the gap moves.
+    syncResourcesToVersion(agent, version, selection, { cwd: opts.cwd });
+    result.healed.push(...pluginHealed);
+    // Verify: re-diff and only claim resources that actually flipped to ok. Ones
+    // still flagged are reported as 'unreconcilable' so repeated runs converge in
+    // messaging instead of "fixing" the same item forever.
+    const post = diffVersionResources(agent, version, diffOpts);
+    const stillBad = new Set();
+    for (const rows of Object.values(post.kinds)) {
+        for (const row of rows) {
+            if (row.status === 'missing' || row.status === 'diff')
+                stillBad.add(`${row.kind}:${row.name}`);
+        }
+    }
+    for (const a of attempted) {
+        if (stillBad.has(`${a.kind}:${a.name}`)) {
+            result.skipped.push({ kind: a.kind, name: a.name, reason: 'unreconcilable' });
+        }
+        else {
+            result.healed.push(a);
+        }
+    }
+    return result;
+}
+// ─── public entrypoint ────────────────────────────────────────────────────────
+/**
+ * Run a heal pass. Repairs the central plugin layer once (manifest + stale
+ * refresh), then reconciles every targeted (agent, version) home against its
+ * live diff. Returns a full account of what changed (or would, under dryRun).
+ */
+export async function heal(opts) {
+    const cwd = opts.cwd ?? os.homedir();
+    const full = opts.mode === 'full';
+    const repairedManifests = repairCentralPluginManifests(opts.dryRun);
+    const { refreshed, skipped: skippedPlugins } = await refreshStaleCentralPlugins({
+        dryRun: opts.dryRun,
+        allowModified: full,
+    });
+    const changedPlugins = new Set([
+        ...repairedManifests.map((r) => r.plugin),
+        ...refreshed.map((r) => r.plugin),
+    ]);
+    const targets = opts.agent
+        ? [{ agent: opts.agent, versions: opts.versions ?? listInstalledVersions(opts.agent) }]
+        : ALL_AGENT_IDS.map((a) => ({ agent: a, versions: listInstalledVersions(a) }));
+    const versions = [];
+    for (const t of targets) {
+        for (const v of t.versions) {
+            versions.push(healVersion(t.agent, v, { cwd, includeDrift: full, changedPlugins, dryRun: opts.dryRun }));
+        }
+    }
+    return { versions, repairedManifests, refreshedPlugins: refreshed, skippedPlugins };
+}

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;
 /**
@@ -212,6 +217,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.