@phnx-labs/agents-cli 1.20.25 → 1.20.27

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/hooks.js

@@ -15,7 +15,8 @@ import * as TOML from 'smol-toml';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { supports, explainSkip, capableAgents } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
-import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos } from './state.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir } from './state.js';
+import { collectSubruleHooksFromState } from './rules/compose.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
 /**
  * Resolve a hook script's absolute path. Checks user dir first, then enabled
@@ -52,6 +53,12 @@ function getManagedHookPrefixes() {
         path.join(getUserAgentsDir(), 'hooks') + path.sep,
         ...extraDirs.map(d => path.join(d, 'hooks') + path.sep),
         path.join(getSystemAgentsDir(), 'hooks') + path.sep,
+        // Subrule-dir hook scripts register by their absolute source path under a
+        // rules `subrules/` tree. Cover those trees so a removed subrule/hook's
+        // stale settings entry gets garbage-collected like any other managed hook.
+        path.join(getUserRulesDir(), 'subrules') + path.sep,
+        ...extraDirs.map(d => path.join(d, 'rules', 'subrules') + path.sep),
+        path.join(getResolvedRulesDir(), 'subrules') + path.sep,
     ];
 }
 /**
@@ -159,6 +166,19 @@ const SCRIPT_EXTENSIONS = new Set([
 function isExecutable(mode) {
     return (mode & 0o111) !== 0;
 }
+/**
+ * Ensure a script file carries an exec bit. Subrule-dir hook scripts are
+ * registered by their source path (not copied), so they must be executable in
+ * place. Best-effort: a chmod failure (read-only fs, foreign owner) is ignored.
+ */
+function ensureExecutable(scriptPath) {
+    try {
+        const mode = fs.statSync(scriptPath).mode;
+        if (!isExecutable(mode))
+            fs.chmodSync(scriptPath, mode | 0o755);
+    }
+    catch { /* best effort */ }
+}
 function getHooksDir(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -666,6 +686,15 @@ export function parseHookManifest(opts = {}) {
     const warn = opts.warn !== false;
     const merged = {};
     const systemHooks = {};
+    // Lowest-precedence layer: hooks declared inside active subrule directories.
+    // Seeded first so any same-key entry from system/user agents.yaml wins.
+    // Gated so a malformed hooks.yaml never breaks rule sync.
+    try {
+        const subruleHooks = collectSubruleHooksFromState();
+        for (const [name, def] of Object.entries(subruleHooks))
+            merged[name] = def;
+    }
+    catch { /* subrule hook collection is best-effort */ }
     // System layer: hooks: section of agents.yaml (npm-shipped, separate repo).
     const systemPath = path.join(getSystemAgentsDir(), 'agents.yaml');
     if (fs.existsSync(systemPath)) {
@@ -780,6 +809,12 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         ? path.join(versionHome, agentConfigDirName(agentId), AGENTS[agentId].hooksDir)
         : null;
     const resolveScript = (script) => {
+        // Subrule-dir hooks declare an already-absolute script path. Use it
+        // directly (made executable) — these are not copied into the version home.
+        if (path.isAbsolute(script) && fs.existsSync(script)) {
+            ensureExecutable(script);
+            return script;
+        }
         if (overrideRoots) {
             return resolveContainedHookPath(path.join(overrideRoots[0], 'hooks'), script);
         }

package/dist/lib/menubar/install-menubar.d.ts

@@ -35,21 +35,45 @@ export declare function ensureMenubarAppInstalled(opts?: {
 export declare function enableMenubarService(opts?: {
     clearOptOut?: boolean;
 }): boolean;
+/**
+ * Pure staleness decision (no I/O) so the truth table is unit-testable. The
+ * installed service is stale when the helper binary is gone, or when it was
+ * installed by a different CLI version than the one now running — a version
+ * change is the signal that the plist's baked interpreter/entry/bundle paths
+ * and the helper binary itself may have drifted. A null installedVersion
+ * (pre-stamp install) counts as stale so old installs get re-stamped once.
+ */
+export declare function isMenubarStale(opts: {
+    installedVersion: string | null;
+    currentVersion: string;
+    execExists: boolean;
+}): boolean;
 /**
  * Stop + remove the menu-bar service and write the sticky opt-out so the
  * upgrade migration won't re-enable it.
  */
 export declare function disableMenubarService(): void;
 /**
- * Upgrade-time auto-enable. Runs from runMigration() once per sentinel bump.
- * No-ops if: not darwin, the user opted out, no helper bundle ships, or the
- * service is already installed. Best-effort — never throws into migration.
+ * Startup self-heal, run on every darwin CLI invocation (see src/index.ts).
+ * No-ops cheaply (a couple of existsSync + a tiny file read) unless work is
+ * needed:
+ *   - fresh install (no service yet)      -> enable
+ *   - upgrade (version stamp changed) or  -> re-enable: recopy the new helper
+ *     the App Support helper went missing     binary + rewrite the plist + kick
+ *
+ * Without the staleness re-enable, `npm update` refreshed the CLI but left the
+ * menu bar running the previous release's helper binary on a possibly-stale
+ * plist. No-ops if: not darwin, the user opted out, or no helper bundle ships.
+ * Best-effort — never throws into startup.
  */
 export declare function installMenubarLaunchAgentOnUpgrade(): void;
 export interface MenubarStatus {
     platform: string;
     source: string | null;
     installedApp: string | null;
+    installedVersion: string | null;
+    currentVersion: string;
+    stale: boolean;
     serviceInstalled: boolean;
     running: boolean;
     disabledByUser: boolean;

package/dist/lib/menubar/install-menubar.js

@@ -20,15 +20,38 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { getRuntimeStateDir, getHelpersDir } from '../state.js';
+import { getCliVersion } from '../version.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
 function onDarwin() {
     return process.platform === 'darwin';
 }
+/** ~/Library/Application Support/agents-cli */
+function installDir() {
+    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME);
+}
 /** ~/Library/Application Support/agents-cli/MenubarHelper.app */
 function installedAppPath() {
-    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+    return path.join(installDir(), APP_BUNDLE_NAME);
+}
+/**
+ * Version stamp written next to the installed bundle. The upgrade self-heal
+ * compares this against the running CLI's version to decide whether the App
+ * Support copy + plist need to be rebuilt — without it, a `npm update` refreshes
+ * dist/index.js but leaves the menu bar running the OLD helper binary and a
+ * plist whose baked paths may have drifted.
+ */
+function installedVersionMarkerPath() {
+    return path.join(installDir(), '.menubar-version');
+}
+function readInstalledMenubarVersion() {
+    try {
+        return fs.readFileSync(installedVersionMarkerPath(), 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
 }
 /** Executable inside the installed bundle. */
 function installedExecutablePath() {
@@ -222,8 +245,34 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
         execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
     }
     catch { /* best effort */ }
+    // Stamp the version we just installed so the upgrade self-heal can tell when
+    // a later release ships a newer helper that needs reinstalling.
+    try {
+        fs.writeFileSync(installedVersionMarkerPath(), getCliVersion());
+    }
+    catch { /* best effort */ }
     return true;
 }
+/**
+ * Pure staleness decision (no I/O) so the truth table is unit-testable. The
+ * installed service is stale when the helper binary is gone, or when it was
+ * installed by a different CLI version than the one now running — a version
+ * change is the signal that the plist's baked interpreter/entry/bundle paths
+ * and the helper binary itself may have drifted. A null installedVersion
+ * (pre-stamp install) counts as stale so old installs get re-stamped once.
+ */
+export function isMenubarStale(opts) {
+    if (!opts.execExists)
+        return true;
+    return opts.installedVersion !== opts.currentVersion;
+}
+function menubarSetupStale() {
+    return isMenubarStale({
+        installedVersion: readInstalledMenubarVersion(),
+        currentVersion: getCliVersion(),
+        execExists: fs.existsSync(installedExecutablePath()),
+    });
+}
 /**
  * Stop + remove the menu-bar service and write the sticky opt-out so the
  * upgrade migration won't re-enable it.
@@ -253,9 +302,17 @@ export function disableMenubarService() {
     catch { /* best effort */ }
 }
 /**
- * Upgrade-time auto-enable. Runs from runMigration() once per sentinel bump.
- * No-ops if: not darwin, the user opted out, no helper bundle ships, or the
- * service is already installed. Best-effort — never throws into migration.
+ * Startup self-heal, run on every darwin CLI invocation (see src/index.ts).
+ * No-ops cheaply (a couple of existsSync + a tiny file read) unless work is
+ * needed:
+ *   - fresh install (no service yet)      -> enable
+ *   - upgrade (version stamp changed) or  -> re-enable: recopy the new helper
+ *     the App Support helper went missing     binary + rewrite the plist + kick
+ *
+ * Without the staleness re-enable, `npm update` refreshed the CLI but left the
+ * menu bar running the previous release's helper binary on a possibly-stale
+ * plist. No-ops if: not darwin, the user opted out, or no helper bundle ships.
+ * Best-effort — never throws into startup.
  */
 export function installMenubarLaunchAgentOnUpgrade() {
     try {
@@ -263,14 +320,18 @@ export function installMenubarLaunchAgentOnUpgrade() {
             return;
         if (menubarDisabledByUser())
             return;
-        if (menubarServiceInstalled())
-            return;
         if (!sourceAppPath())
             return;
-        enableMenubarService({ clearOptOut: false });
+        if (!menubarServiceInstalled()) {
+            enableMenubarService({ clearOptOut: false });
+            return;
+        }
+        if (menubarSetupStale()) {
+            enableMenubarService({ clearOptOut: false });
+        }
     }
     catch {
-        /* never block migration on the menu bar */
+        /* never block startup on the menu bar */
     }
 }
 export function getMenubarStatus() {
@@ -280,11 +341,15 @@ export function getMenubarStatus() {
         const r = spawnSync('pgrep', ['-f', 'MenubarHelper'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
         running = r.status === 0 && (r.stdout || '').trim().length > 0;
     }
+    const serviceInstalled = menubarServiceInstalled();
     return {
         platform: process.platform,
         source: sourceAppPath(),
         installedApp: fs.existsSync(dest) ? dest : null,
-        serviceInstalled: menubarServiceInstalled(),
+        installedVersion: readInstalledMenubarVersion(),
+        currentVersion: getCliVersion(),
+        stale: onDarwin() && serviceInstalled && menubarSetupStale(),
+        serviceInstalled,
         running,
         disabledByUser: menubarDisabledByUser(),
     };

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