@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/lib/monitors/config.d.ts

@@ -114,6 +114,30 @@ export interface MonitorConfig {
      * independently, like routines' `devices`. Mutually exclusive with `device`.
      */
     devices?: string[];
+    /**
+     * Does this monitor's SOURCE poll a fleet-shared queue (a PR list, a ticket
+     * tracker, the feed, a sync bucket) rather than the firing box's own state
+     * (its repos, sessions, caches)?
+     *
+     * This is the SING-9 placement switch for an UNPINNED monitor (no `device` /
+     * `devices`). A shared-input source has no per-box input, so every daemon
+     * firing it independently is a multi-executor race on shared state — the exact
+     * double-fire bug class. So an unpinned shared-input monitor fires only on the
+     * single owner (`interactive.host`, else the sole box on a one-device fleet),
+     * never on every daemon.
+     *
+     * Defaults differ by layer so the SAFE side is the default for each:
+     * - a **system built-in** (`scope: 'system'`) is treated as shared-input
+     *   unless it sets `sharedInput: false`, so a built-in shipped with no pin
+     *   can never fan out across the fleet — a device-local built-in opts back
+     *   into fleet-wide firing with `sharedInput: false`;
+     * - a **user monitor** keeps its historical fleet-wide default and only
+     *   becomes owner-restricted when it explicitly sets `sharedInput: true`.
+     *
+     * An explicit `device` / `devices` pin always wins and makes this moot — the
+     * author has already chosen the executor(s).
+     */
+    sharedInput?: boolean;
     /** Execute the ACTION on this machine over SSH (placement), distinct from the owner that fires it. */
     runOn?: string;
     /**
@@ -137,6 +161,15 @@ export interface MonitorConfig {
     variables?: Record<string, string>;
     /** Pin the agent version for `run` actions (omit to use the run strategy). */
     version?: string;
+    /**
+     * Which layer this monitor was read from — `user` (~/.agents/monitors/) or
+     * `system` (the npm-shipped built-in mirror ~/.agents/.system/monitors/).
+     * A DERIVED, runtime-only annotation stamped by `readMonitorFile`, never a
+     * persisted YAML field: it tags a built-in in `list`/`view` (mirroring
+     * routines' `(built-in)` label) and `writeMonitor` strips it before writing,
+     * so materializing a user copy of a built-in always lands as `user`.
+     */
+    scope?: 'user' | 'system';
 }
 /**
  * A fired event. `summary` is injected into the action prompt as `{event}`;
@@ -154,13 +187,48 @@ export interface MonitorEvent {
  * in seconds). Returns null on empty/unparseable/zero input.
  */
 export declare function parseInterval(interval: string): number | null;
+/**
+ * True when an UNPINNED monitor must be placed on a single owner rather than
+ * fired by every daemon — the SING-9 guard against a shared-queue double-fire.
+ *
+ * A `device` / `devices` pin is an explicit executor choice, so it is never
+ * owner-overridden (returns false here). For an unpinned monitor the default is
+ * layer-specific, SAFE side first: a **system built-in** is treated as
+ * shared-input unless it opts out with `sharedInput: false`; a **user monitor**
+ * keeps its fleet-wide default and only opts IN with `sharedInput: true`.
+ */
+export declare function requiresSingleOwner(config: Pick<MonitorConfig, 'device' | 'devices' | 'scope' | 'sharedInput'>): boolean;
+/**
+ * The single fleet box that owns unpinned shared-input monitors — PURE, so the
+ * placement rule is unit-testable without a live tailnet. Priority:
+ *
+ * 1. the configured `interactive.host` (the box the operator sits at);
+ * 2. else, on a fleet with no OTHER registered device, this box — a single-box
+ *    install has no peer to race, so the built-in still fires here;
+ * 3. else `undefined` — a multi-box fleet with no interactive host has no safe
+ *    single owner, so an unpinned shared-input monitor fires NOWHERE (fail safe:
+ *    a silent no-op beats a fleet-wide double-fire) until one is pinned.
+ *
+ * `deviceNames` is the registered fleet (registry keys); `self` is `machineId()`.
+ */
+export declare function resolveSharedInputOwner(interactiveHost: string | undefined, deviceNames: string[], self: string): string | undefined;
+/** Resolve {@link resolveSharedInputOwner} from live config + the device registry. */
+export declare function monitorSharedInputOwner(): string | undefined;
 /**
  * True when the monitor may evaluate + fire on this machine. Owner semantics:
  * `device` (single owner, exactly-once) → only that machine; else `devices`
- * (allowlist) → any listed machine; else unrestricted. Both sides normalize so
- * `Yosemite-S0` and `yosemite-s0.tailnet.ts.net` agree with `yosemite-s0`.
+ * (allowlist) → any listed machine; else placement depends on shared-input: an
+ * unpinned SHARED-INPUT monitor (a system built-in by default, or a user monitor
+ * that set `sharedInput: true`) fires only on the resolved owner
+ * ({@link monitorSharedInputOwner}), so a built-in that polls a fleet-shared
+ * queue can never fan out across every daemon (SING-9); anything else is
+ * unrestricted. Both sides normalize so `Yosemite-S0` and
+ * `yosemite-s0.tailnet.ts.net` agree with `yosemite-s0`.
+ *
+ * `ownerHost` overrides the resolved owner for tests/callers that already know
+ * it; omit it in production to resolve from config + the device registry.
  */
-export declare function monitorRunsOnThisDevice(config: Pick<MonitorConfig, 'device' | 'devices'>): boolean;
+export declare function monitorRunsOnThisDevice(config: Pick<MonitorConfig, 'device' | 'devices' | 'scope' | 'sharedInput'>, ownerHost?: string): boolean;
 /**
  * Validate a partial monitor config, returning a list of human-readable errors.
  * Hand-rolled like validateJob (lib/routines.ts) — no zod. Rejects: no source,

package/dist/lib/monitors/config.js

@@ -12,10 +12,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getMonitorsDir, getSystemMonitorsDir, ensureAgentsDir } from '../state.js';
+import { getMonitorsDir, getSystemMonitorsDir, ensureAgentsDir, readMeta } from '../state.js';
 import { safeJoin, isSafeSegmentName } from '../paths.js';
 import { atomicWriteFileSync } from '../fs-atomic.js';
 import { machineId, normalizeHost } from '../machine-id.js';
+import { loadDevicesSync } from '../devices/registry.js';
 import { ALL_AGENT_IDS } from '../agents.js';
 import { isCustomHarnessName } from '../profiles.js';
 /** Default values applied to every monitor config when fields are omitted. */
@@ -50,19 +51,84 @@ export function parseInterval(interval) {
     const ms = ((((weeks * 7 + days) * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
     return ms > 0 ? ms : null;
 }
+/**
+ * True when an UNPINNED monitor must be placed on a single owner rather than
+ * fired by every daemon — the SING-9 guard against a shared-queue double-fire.
+ *
+ * A `device` / `devices` pin is an explicit executor choice, so it is never
+ * owner-overridden (returns false here). For an unpinned monitor the default is
+ * layer-specific, SAFE side first: a **system built-in** is treated as
+ * shared-input unless it opts out with `sharedInput: false`; a **user monitor**
+ * keeps its fleet-wide default and only opts IN with `sharedInput: true`.
+ */
+export function requiresSingleOwner(config) {
+    if (config.device || (config.devices && config.devices.length > 0))
+        return false;
+    if (config.scope === 'system')
+        return config.sharedInput !== false;
+    return config.sharedInput === true;
+}
+/**
+ * The single fleet box that owns unpinned shared-input monitors — PURE, so the
+ * placement rule is unit-testable without a live tailnet. Priority:
+ *
+ * 1. the configured `interactive.host` (the box the operator sits at);
+ * 2. else, on a fleet with no OTHER registered device, this box — a single-box
+ *    install has no peer to race, so the built-in still fires here;
+ * 3. else `undefined` — a multi-box fleet with no interactive host has no safe
+ *    single owner, so an unpinned shared-input monitor fires NOWHERE (fail safe:
+ *    a silent no-op beats a fleet-wide double-fire) until one is pinned.
+ *
+ * `deviceNames` is the registered fleet (registry keys); `self` is `machineId()`.
+ */
+export function resolveSharedInputOwner(interactiveHost, deviceNames, self) {
+    if (typeof interactiveHost === 'string' && interactiveHost.trim()) {
+        return normalizeHost(interactiveHost);
+    }
+    const others = deviceNames.map((d) => normalizeHost(d)).filter((d) => d && d !== self);
+    if (others.length === 0)
+        return self; // single-box fleet: no peer, no race
+    return undefined; // multi-box, no interactive host pinned → no safe owner
+}
+/** Resolve {@link resolveSharedInputOwner} from live config + the device registry. */
+export function monitorSharedInputOwner() {
+    const self = machineId();
+    const interactiveHost = readMeta().config?.interactiveHost;
+    let deviceNames = [];
+    try {
+        deviceNames = Object.keys(loadDevicesSync());
+    }
+    catch {
+        deviceNames = [];
+    }
+    return resolveSharedInputOwner(typeof interactiveHost === 'string' ? interactiveHost : undefined, deviceNames, self);
+}
 /**
  * True when the monitor may evaluate + fire on this machine. Owner semantics:
  * `device` (single owner, exactly-once) → only that machine; else `devices`
- * (allowlist) → any listed machine; else unrestricted. Both sides normalize so
- * `Yosemite-S0` and `yosemite-s0.tailnet.ts.net` agree with `yosemite-s0`.
+ * (allowlist) → any listed machine; else placement depends on shared-input: an
+ * unpinned SHARED-INPUT monitor (a system built-in by default, or a user monitor
+ * that set `sharedInput: true`) fires only on the resolved owner
+ * ({@link monitorSharedInputOwner}), so a built-in that polls a fleet-shared
+ * queue can never fan out across every daemon (SING-9); anything else is
+ * unrestricted. Both sides normalize so `Yosemite-S0` and
+ * `yosemite-s0.tailnet.ts.net` agree with `yosemite-s0`.
+ *
+ * `ownerHost` overrides the resolved owner for tests/callers that already know
+ * it; omit it in production to resolve from config + the device registry.
  */
-export function monitorRunsOnThisDevice(config) {
+export function monitorRunsOnThisDevice(config, ownerHost) {
     const self = machineId();
     if (config.device)
         return normalizeHost(config.device) === self;
     if (config.devices && config.devices.length > 0) {
         return config.devices.some((d) => normalizeHost(d) === self);
     }
+    if (requiresSingleOwner(config)) {
+        const resolved = ownerHost !== undefined ? ownerHost : monitorSharedInputOwner();
+        const owner = resolved && resolved.trim() ? normalizeHost(resolved) : undefined;
+        return owner !== undefined && owner === self;
+    }
     return true;
 }
 /** Count the populated source-payload fields to detect "two sources". */
@@ -267,6 +333,9 @@ export function validateMonitor(config) {
             }
         }
     }
+    if (config.sharedInput !== undefined && typeof config.sharedInput !== 'boolean') {
+        errors.push('sharedInput must be a boolean (true = source polls a fleet-shared queue)');
+    }
     if (config.runOn !== undefined && (typeof config.runOn !== 'string' || config.runOn.trim() === '')) {
         errors.push('runOn must be a non-empty machine name (a registered host, device, capability tag, or user@host)');
     }
@@ -286,11 +355,24 @@ export function validateMonitor(config) {
     return errors;
 }
 /**
- * Read and normalize a monitor file. `scope` decides the enabled default when
- * the YAML has no explicit `enabled:` field: a `user` monitor defaults to
- * enabled (MONITOR_DEFAULTS), while a `system` built-in stays opt-in (disabled)
- * until the user enables it — mirroring how routines treat a fresh built-in
- * (lib/routines.ts readJobFile).
+ * Read and normalize a monitor file. A built-in defaults to enabled exactly like
+ * every other system-layer resource (rules, hooks, commands, skills): a monitor
+ * shipped in the system mirror is on for every install unless the user shadows it
+ * with an explicit `enabled: false` (via `agents monitors pause`, which writes a
+ * user copy — the system mirror is pull-only). There is deliberately no
+ * system-scope special-case: monitors used to be the lone outlier that shipped
+ * disabled+invisible (PHNX-2506). `scope` no longer changes the enabled default;
+ * it is retained on the config so `list`/`view` can tag a built-in.
+ *
+ * Enabled-by-default is NOT, on its own, permission to fire on every daemon. A
+ * shared-input built-in (one whose source polls a fleet-shared queue such as `gh
+ * pr list --author @me`) is placed on a single owner by `monitorRunsOnThisDevice`
+ * / `requiresSingleOwner` even when the shipped YAML carries no `device:` pin: a
+ * system built-in is treated as shared-input unless it sets `sharedInput: false`,
+ * so it can never fan out across the fleet and double-fire on a shared queue
+ * (SING-9). A device-local built-in opts back into fleet-wide firing with
+ * `sharedInput: false`; a genuinely-shared one should still ship a `device:` pin
+ * (or `sharedInput: true`) to document the intent.
  */
 function readMonitorFile(filePath, scope = 'user') {
     try {
@@ -303,9 +385,12 @@ function readMonitorFile(filePath, scope = 'user') {
             ...MONITOR_DEFAULTS,
             ...parsed,
             name: parsed.name || path.basename(filePath).replace(/\.ya?ml$/, ''),
-            // A system built-in with no explicit `enabled:` is opt-in until enabled;
-            // a user monitor keeps the enabled-by-default behavior.
-            enabled: hasEnabled ? parsed.enabled !== false : scope === 'system' ? false : (MONITOR_DEFAULTS.enabled ?? true),
+            // Enabled unless the user explicitly disables it — same default for user
+            // and system layers, so a built-in is visible and on like any other
+            // system resource. `scope` is stamped below for the (built-in) tag, not
+            // used to gate enablement.
+            enabled: hasEnabled ? parsed.enabled !== false : (MONITOR_DEFAULTS.enabled ?? true),
+            scope,
         };
     }
     catch {
@@ -387,6 +472,9 @@ export function writeMonitor(config) {
     const output = { ...config };
     if (output.enabled === true)
         delete output.enabled;
+    // `scope` is a derived read-time annotation, never part of the on-disk schema —
+    // strip it so a materialized user copy of a built-in doesn't persist `scope: system`.
+    delete output.scope;
     const devArr = output.devices;
     if (!devArr || devArr.length === 0)
         delete output.devices;

package/dist/lib/monitors/pid-watch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `--watch-pid` support — turns a backgrounded OS process into a durable,
+ * daemon-polled watcher instead of relying on a harness's own exit hook
+ * (PHNX-3023: a "will re-invoke me" background shell never fires when the
+ * harness only notifies on process exit and the watch loop itself never
+ * exits — `gh pr checks --watch`, a long sleep, a tick poll).
+ *
+ * The command built here reuses the same existence-check predicate
+ * `isPidAlive`'s existence branch uses (`process.kill(pid, 0)`), but it runs
+ * inside the monitor engine's own poll loop (`sources/command.ts`) rather than
+ * the caller's process — so the check survives past the CLI invocation that
+ * armed it.
+ */
+/** The token a --watch-pid source's condition matches on process exit. */
+export declare const PID_WATCH_EXITED_TOKEN = "exited";
+/** Emitted while the pid is alive. */
+export declare const PID_WATCH_RUNNING_TOKEN = "running";
+/**
+ * Emitted when the pid is not alive AND has never been observed alive — the
+ * `--force` not-yet-spawned case. Deliberately distinct from
+ * {@link PID_WATCH_EXITED_TOKEN} so it can never match the exit condition.
+ */
+export declare const PID_WATCH_NOT_YET_SPAWNED_TOKEN = "notyetspawned";
+/**
+ * The shell command a --watch-pid source polls. A poll only reports "exited"
+ * once it has FIRST observed the pid running — tracked with a marker file the
+ * command touches on every "running" poll — otherwise a `--force`-armed watch
+ * on a not-yet-spawned pid would report "exited" on its very first poll (the
+ * pid doesn't exist *yet*, not *anymore*), which the engine's match-mode
+ * fires immediately (no prior state to diff against) and then persists as the
+ * baseline — silencing the real exit forever once the process actually spawns
+ * and later dies. Portable across the shells `sources/command.ts` invokes
+ * (`/bin/sh -c` posix, `cmd /c` Windows).
+ */
+export declare function pidLivenessCommand(pid: number, seenRunningMarkerPath: string): string;

package/dist/lib/monitors/pid-watch.js

@@ -0,0 +1,45 @@
+/**
+ * `--watch-pid` support — turns a backgrounded OS process into a durable,
+ * daemon-polled watcher instead of relying on a harness's own exit hook
+ * (PHNX-3023: a "will re-invoke me" background shell never fires when the
+ * harness only notifies on process exit and the watch loop itself never
+ * exits — `gh pr checks --watch`, a long sleep, a tick poll).
+ *
+ * The command built here reuses the same existence-check predicate
+ * `isPidAlive`'s existence branch uses (`process.kill(pid, 0)`), but it runs
+ * inside the monitor engine's own poll loop (`sources/command.ts`) rather than
+ * the caller's process — so the check survives past the CLI invocation that
+ * armed it.
+ */
+import { IS_WINDOWS } from '../platform/index.js';
+/** The token a --watch-pid source's condition matches on process exit. */
+export const PID_WATCH_EXITED_TOKEN = 'exited';
+/** Emitted while the pid is alive. */
+export const PID_WATCH_RUNNING_TOKEN = 'running';
+/**
+ * Emitted when the pid is not alive AND has never been observed alive — the
+ * `--force` not-yet-spawned case. Deliberately distinct from
+ * {@link PID_WATCH_EXITED_TOKEN} so it can never match the exit condition.
+ */
+export const PID_WATCH_NOT_YET_SPAWNED_TOKEN = 'notyetspawned';
+/**
+ * The shell command a --watch-pid source polls. A poll only reports "exited"
+ * once it has FIRST observed the pid running — tracked with a marker file the
+ * command touches on every "running" poll — otherwise a `--force`-armed watch
+ * on a not-yet-spawned pid would report "exited" on its very first poll (the
+ * pid doesn't exist *yet*, not *anymore*), which the engine's match-mode
+ * fires immediately (no prior state to diff against) and then persists as the
+ * baseline — silencing the real exit forever once the process actually spawns
+ * and later dies. Portable across the shells `sources/command.ts` invokes
+ * (`/bin/sh -c` posix, `cmd /c` Windows).
+ */
+export function pidLivenessCommand(pid, seenRunningMarkerPath) {
+    if (IS_WINDOWS) {
+        return (`tasklist /FI "PID eq ${pid}" 2>NUL | findstr /I "${pid}" >NUL ` +
+            `&& (type nul > "${seenRunningMarkerPath}" & echo ${PID_WATCH_RUNNING_TOKEN}) ` +
+            `|| (if exist "${seenRunningMarkerPath}" (echo ${PID_WATCH_EXITED_TOKEN}) else (echo ${PID_WATCH_NOT_YET_SPAWNED_TOKEN}))`);
+    }
+    return (`kill -0 ${pid} 2>/dev/null ` +
+        `&& { mkdir -p "$(dirname "${seenRunningMarkerPath}")" 2>/dev/null; : > "${seenRunningMarkerPath}"; echo ${PID_WATCH_RUNNING_TOKEN}; } ` +
+        `|| { [ -e "${seenRunningMarkerPath}" ] && echo ${PID_WATCH_EXITED_TOKEN} || echo ${PID_WATCH_NOT_YET_SPAWNED_TOKEN}; }`);
+}

package/dist/lib/monitors/remote.d.ts

@@ -20,10 +20,28 @@ import { type GatherRemoteAgentsJsonDeps } from '../remote-agents-json.js';
 import type { MonitorConfig } from './config.js';
 /** Recursion guard: a peer answering the fan-out must not fan out again. */
 export declare const NO_MONITOR_FANOUT_ENV = "AGENTS_MONITORS_LOCAL";
+/**
+ * The owning box's view of a remote monitor, beyond its behavioral identity —
+ * enough for `monitors list` to render it (enabled/placement/scope) and show a
+ * one-line liveness note without a second round-trip. All optional: a peer on an
+ * older CLI may omit them, and the duplicate guard never reads them.
+ */
+export interface RemoteMonitorDisplay {
+    enabled?: boolean;
+    owner?: string;
+    scope?: 'user' | 'system';
+    stalled?: boolean;
+    checkCount?: number;
+    lastCheckedAt?: string | null;
+    lastFiredAt?: string | null;
+    lastActionFailed?: boolean;
+}
 /** One monitor as seen on a peer, tagged with the box it lives on. */
 export interface RemoteMonitor {
     machine: string;
     monitor: Pick<MonitorConfig, 'name' | 'source' | 'condition' | 'action'>;
+    /** The owning box's enabled/placement/scope/liveness view, for `list` display. */
+    display?: RemoteMonitorDisplay;
 }
 /**
  * Parse a peer's `monitors list --json`. Defensive against version skew: a peer

package/dist/lib/monitors/remote.js

@@ -48,9 +48,20 @@ export function parseRemoteMonitors(stdout, machine) {
         // row cannot participate in the duplicate check either way.
         if (!m.name || !m.source || !m.condition || !m.action)
             continue;
+        const display = {
+            enabled: typeof m.enabled === 'boolean' ? m.enabled : undefined,
+            owner: typeof m.owner === 'string' ? m.owner : undefined,
+            scope: m.scope === 'system' || m.scope === 'user' ? m.scope : undefined,
+            stalled: typeof m.stalled === 'boolean' ? m.stalled : undefined,
+            checkCount: typeof m.checkCount === 'number' ? m.checkCount : undefined,
+            lastCheckedAt: typeof m.lastCheckedAt === 'string' ? m.lastCheckedAt : undefined,
+            lastFiredAt: typeof m.lastFiredAt === 'string' ? m.lastFiredAt : undefined,
+            lastActionFailed: typeof m.lastActionFailed === 'boolean' ? m.lastActionFailed : undefined,
+        };
         out.push({
             machine,
             monitor: { name: m.name, source: m.source, condition: m.condition, action: m.action },
+            display,
         });
     }
     return out;

package/dist/lib/permissions.js

@@ -323,8 +323,13 @@ export function buildPermissionsFromGroups(groupNames) {
             const content = fs.readFileSync(filePath, 'utf-8');
             // Extract rules using line-by-line regex (more robust than YAML parsing)
             // Matches lines like: - "Bash(git *)" or   - "WebFetch(domain:example.com)"
-            // Handles nested quotes that break YAML parsers
-            const lines = content.split('\n');
+            // Handles nested quotes that break YAML parsers.
+            // Split on CRLF or LF: git checks group yaml out with CRLF on Windows
+            // (core.autocrlf), and a plain split('\n') leaves a trailing '\r' so the
+            // closing-quote anchor `"$` never matches — extracting ZERO rules, which
+            // wrote an empty permission set and left `agents doctor --fix` unable to
+            // reconcile permissions on Windows forever (PHNX-3187).
+            const lines = content.split(/\r?\n/);
             let section = null;
             for (const line of lines) {
                 const sectionMatch = line.match(/^\s*(allow|deny)\s*:\s*(?:#.*)?$/);

package/dist/lib/plugins/plugins.d.ts

@@ -254,12 +254,26 @@ export declare function removePluginFromVersion(pluginName: string, pluginRoot:
     mcp: number;
 };
 /**
- * Remove orphaned plugin entries from a version home. An entry is "orphan" if
- * its plugin name is not in the active plugin set. Soft-deletes the affected
+ * The active plugin set, either as bare names (legacy callers / the dual-dash
+ * sweep, which has no marketplace to key on) or as the discovered plugins
+ * themselves (which carry marketplace provenance, enabling per-marketplace
+ * orphan detection — the PHNX-2618 shadow case below).
+ */
+export type ActivePluginsInput = Set<string> | Array<{
+    name: string;
+    marketplace?: string;
+}>;
+/**
+ * Remove orphaned plugin entries from a version home. A marketplace-plugin
+ * install is "orphan" when no active source plugin matches its (marketplace,
+ * name) pair (see isOrphanMarketplacePlugin). Soft-deletes the affected
  * marketplace plugin dir to ~/.agents/.trash/plugins/. Also cleans up any
  * legacy dual-dash skills/ directories from older agents-cli versions.
+ *
+ * Pass the discovered plugins (`discoverPlugins()`) for marketplace-aware
+ * detection; a bare `Set<string>` of names keeps the original name-only behavior.
  */
-export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>, version?: string): string[];
+export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePlugins: ActivePluginsInput, version?: string): string[];
 export interface VersionPluginDiff {
     agent: AgentId;
     version: string;

package/dist/lib/plugins/plugins.js

@@ -1430,14 +1430,88 @@ function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, resul
         catch { /* ignore */ }
     }
 }
-// ─── Orphan cleanup ───────────────────────────────────────────────────────────
+function pairKey(marketplace, name) {
+    return `${marketplace}${name}`;
+}
+function indexActivePlugins(input) {
+    if (input instanceof Set)
+        return { names: input, pairs: null };
+    const names = new Set();
+    const pairs = new Set();
+    for (const p of input) {
+        names.add(p.name);
+        // A discovered plugin always carries provenance; the type allows undefined,
+        // so mirror discovery's own default (a marketplace-less plugin is the user
+        // "agents-cli" marketplace — see discoverPlugins / buildDiscoveredPlugin).
+        pairs.add(pairKey(p.marketplace ?? MARKETPLACE_NAME, p.name));
+    }
+    return { names, pairs };
+}
+/**
+ * Does the SOURCE repo backing a synthesized marketplace exist on disk? A
+ * marketplace's version-home install is only authoritative-cleanable when its
+ * source repo is present: a present repo missing a plugin means that plugin was
+ * genuinely removed, while an absent repo (a project we're not in, a removed
+ * extra repo) is merely unreachable and must not be mistaken for deletion.
+ *
+ * We check the REPO root, not the plugins/ subdir: the user repo (~/.agents/)
+ * always exists but its plugins/ dir may not, and "user repo present, no `code`
+ * plugin in it" is exactly what makes an `agents-cli` `code` shadow a real
+ * orphan (PHNX-2618).
+ */
+function marketplaceSourceRepoExists(marketplaceName, cwd) {
+    const spec = marketplaceSpecForName(marketplaceName, cwd);
+    switch (spec.kind) {
+        case 'user': return fs.existsSync(path.dirname(getPluginsDir()));
+        case 'system': return fs.existsSync(path.dirname(getSystemPluginsDir()));
+        case 'extra': return fs.existsSync(path.dirname(getExtraPluginsDir(spec.alias)));
+        case 'project': {
+            const root = getProjectPluginsDir(cwd);
+            return root != null && fs.existsSync(path.dirname(root));
+        }
+    }
+}
+/**
+ * Is a version-home marketplace-plugin install an orphan (safe to trash)?
+ *
+ * A version-home plugin is keyed by (marketplace, name), not name alone — the
+ * bug PHNX-2618 exposed. When the same plugin name lives in two marketplaces
+ * (e.g. a legacy `code` under `agents-cli` and the current `code` under
+ * `agents-system`), a name-only test keeps BOTH alive because the name is active
+ * somewhere, so the stale copy never gets cleaned and serves deleted skills.
+ *
+ *   - Pair still active → keep.
+ *   - Pair gone, but the marketplace's source repo is present (authoritative) →
+ *     orphan. Trash it even though another marketplace still ships that name.
+ *   - Pair gone AND the source repo is absent (unreachable) → fall back to the
+ *     original name-only test so an unrelated sync can't trash a plugin whose
+ *     source simply isn't on this box / in this cwd right now.
+ *
+ * When `pairs` is null (a legacy bare-name caller), this reduces to the original
+ * name-only behavior unchanged.
+ */
+function isOrphanMarketplacePlugin(marketplaceName, pluginName, active, cwd) {
+    if (active.pairs === null)
+        return !active.names.has(pluginName);
+    if (active.pairs.has(pairKey(marketplaceName, pluginName)))
+        return false;
+    if (marketplaceSourceRepoExists(marketplaceName, cwd))
+        return true;
+    return !active.names.has(pluginName);
+}
 /**
- * Remove orphaned plugin entries from a version home. An entry is "orphan" if
- * its plugin name is not in the active plugin set. Soft-deletes the affected
+ * Remove orphaned plugin entries from a version home. A marketplace-plugin
+ * install is "orphan" when no active source plugin matches its (marketplace,
+ * name) pair (see isOrphanMarketplacePlugin). Soft-deletes the affected
  * marketplace plugin dir to ~/.agents/.trash/plugins/. Also cleans up any
  * legacy dual-dash skills/ directories from older agents-cli versions.
+ *
+ * Pass the discovered plugins (`discoverPlugins()`) for marketplace-aware
+ * detection; a bare `Set<string>` of names keeps the original name-only behavior.
  */
-export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames, version) {
+export function cleanOrphanedPluginSkills(agent, versionHome, activePlugins, version) {
+    const active = indexActivePlugins(activePlugins);
+    const cwd = process.cwd();
     const removed = [];
     // 1. Walk every marketplace's install dir and trash entries no longer active.
     for (const name of listVersionMarketplaceNames(agent, versionHome)) {
@@ -1449,7 +1523,7 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
         for (const entry of fs.readdirSync(mktPluginsDir, { withFileTypes: true })) {
             if (!entry.isDirectory() || entry.name.startsWith('.'))
                 continue;
-            if (activePluginNames.has(entry.name))
+            if (!isOrphanMarketplacePlugin(name, entry.name, active, cwd))
                 continue;
             try {
                 const stamp = new Date().toISOString().replace(/[:.]/g, '-');
@@ -1488,7 +1562,7 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
             if (dashIdx === -1)
                 continue;
             const pluginName = entry.name.slice(0, dashIdx);
-            if (activePluginNames.has(pluginName))
+            if (active.names.has(pluginName))
                 continue;
             try {
                 const stamp = new Date().toISOString().replace(/[:.]/g, '-');
@@ -1505,7 +1579,8 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
 }
 export function diffVersionPlugins(agent, version) {
     const versionHome = getVersionHomePath(agent, version);
-    const activePlugins = new Set(discoverPlugins().map(p => p.name));
+    const active = indexActivePlugins(discoverPlugins());
+    const cwd = process.cwd();
     const orphans = [];
     for (const name of listVersionMarketplaceNames(agent, versionHome)) {
         const mktPluginsDir = path.join(marketplaceRoot(name, agent, versionHome), 'plugins');
@@ -1514,7 +1589,7 @@ export function diffVersionPlugins(agent, version) {
         for (const entry of fs.readdirSync(mktPluginsDir, { withFileTypes: true })) {
             if (!entry.isDirectory() || entry.name.startsWith('.'))
                 continue;
-            if (!activePlugins.has(entry.name)) {
+            if (isOrphanMarketplacePlugin(name, entry.name, active, cwd)) {
                 orphans.push(entry.name);
             }
         }
@@ -1529,7 +1604,7 @@ export function diffVersionPlugins(agent, version) {
             if (dashIdx === -1)
                 continue;
             const pluginName = entry.name.slice(0, dashIdx);
-            if (!activePlugins.has(pluginName)) {
+            if (!active.names.has(pluginName)) {
                 orphans.push(entry.name);
             }
         }

package/dist/lib/plugins/skills.d.ts

@@ -79,7 +79,14 @@ export declare function skillContentMatches(agentId: AgentId, skillName: string,
 export declare function listCentralSkills(): string[];
 /**
  * Resolve a skill name to its source directory. Searches user dir first,
- * then system dir, then extra repos. Returns null if no source has a SKILL.md.
+ * then system dir, then extra repos, then plugin-bundled skills
+ * (`plugins/<plugin>/skills/<name>` under any trusted base). Returns null if no
+ * source has a SKILL.md.
+ *
+ * Crediting plugins here is load-bearing (PHNX-3185): a skill materialized from
+ * `plugins/design/skills/design` has a real source, so it must resolve — else
+ * `versionSkillMatches` finds no source and the skill reads as drifted, and
+ * {@link diffVersionSkills} classes it an orphan `prune cleanup` would delete.
  */
 export declare function resolveSkillSourcePath(skillName: string): string | null;
 /**