@phnx-labs/agents-cli 1.22.58 → 1.22.60

package/dist/lib/git.d.ts

@@ -161,6 +161,21 @@ export declare function canonicalGitRemote(url: string): string;
  * checkout; {@link isSystemRepoOrigin} reads a dir's origin and delegates here.
  */
 export declare function isSystemRepoRemote(remote: string | null | undefined): boolean;
+/**
+ * True when `remote` is the origin the system repo is EXPECTED to track on this
+ * machine, honouring an operator's `AGENTS_SYSTEM_REPO` override.
+ *
+ * The system repo ships hooks that register as shell `command` strings run on
+ * every tool event, and its checkout auto-fast-forwards from origin — so a
+ * fast-forward from an origin the operator never chose is remote code execution
+ * on the next command that loads a system resource (PHNX-2957). This is the
+ * pinning predicate every auto-pull of the system repo gates on: pull only when
+ * origin is the canonical {@link isSystemRepoRemote} repo, or the exact
+ * `AGENTS_SYSTEM_REPO` the operator pointed at instead. Anything else — a
+ * repointed origin, a fork, an unset-then-swapped remote — is refused, not
+ * pulled. Pure string check; no git spawn.
+ */
+export declare function isExpectedSystemRepoRemote(remote: string | null | undefined): boolean;
 /** True when two git remote URLs point at the same repo across transport forms. */
 export declare function sameGitRemote(a: string | null | undefined, b: string | null | undefined): boolean;
 /**
@@ -500,6 +515,29 @@ export declare function tryAutoPull(dir: string): Promise<{
     pulled: boolean;
     error?: string;
 }>;
+/** Result of {@link tryAutoPullSystemRepo}. `refused` is set only when the pull
+ *  was blocked because origin is not the expected system remote. */
+export interface SystemRepoPullResult {
+    pulled: boolean;
+    error?: string;
+    /** True when origin is present but is NOT the expected system remote; no
+     *  fast-forward was attempted. `actualRemote` names what was found. */
+    refused?: boolean;
+    /** The origin fetch URL that was examined (present when a remote exists). */
+    actualRemote?: string;
+}
+/**
+ * Auto-pull the system repo ONLY after verifying its origin is the expected
+ * system remote (PHNX-2957). The system repo ships hooks that run as shell on
+ * tool events, so fast-forwarding it from an unexpected/repointed origin is
+ * remote code execution. An origin that fails {@link isExpectedSystemRepoRemote}
+ * is REFUSED loud (`refused: true`), never pulled — the canonical system repo
+ * (or an operator's `AGENTS_SYSTEM_REPO`) still fast-forwards exactly as before.
+ *
+ * A system dir with no origin at all is a plain no-op (`pulled: false`), not a
+ * refusal — there is nothing to pull from and nothing to distrust.
+ */
+export declare function tryAutoPullSystemRepo(dir: string): Promise<SystemRepoPullResult>;
 /**
  * How many commits `dir`'s checked-out branch is behind its upstream, read from
  * the LAST-FETCHED remote-tracking ref — no network call. Returns null when the

package/dist/lib/git.js

@@ -537,6 +537,33 @@ export function isSystemRepoRemote(remote) {
     const c = canonicalGitRemote(remote);
     return c === canonicalGitRemote(`https://github.com/${systemRepoSlug(DEFAULT_SYSTEM_REPO)}`);
 }
+/**
+ * True when `remote` is the origin the system repo is EXPECTED to track on this
+ * machine, honouring an operator's `AGENTS_SYSTEM_REPO` override.
+ *
+ * The system repo ships hooks that register as shell `command` strings run on
+ * every tool event, and its checkout auto-fast-forwards from origin — so a
+ * fast-forward from an origin the operator never chose is remote code execution
+ * on the next command that loads a system resource (PHNX-2957). This is the
+ * pinning predicate every auto-pull of the system repo gates on: pull only when
+ * origin is the canonical {@link isSystemRepoRemote} repo, or the exact
+ * `AGENTS_SYSTEM_REPO` the operator pointed at instead. Anything else — a
+ * repointed origin, a fork, an unset-then-swapped remote — is refused, not
+ * pulled. Pure string check; no git spawn.
+ */
+export function isExpectedSystemRepoRemote(remote) {
+    if (!remote)
+        return false;
+    const override = process.env.AGENTS_SYSTEM_REPO?.trim();
+    if (override) {
+        // The override is a source spec (`gh:owner/repo`) or a full clone URL. Match
+        // the GitHub-slug form the setup path clones, and the raw spec itself, so a
+        // non-GitHub override URL still verifies.
+        return (sameGitRemote(remote, `https://github.com/${systemRepoSlug(override)}`) ||
+            sameGitRemote(remote, override.replace(/^gh:/, '')));
+    }
+    return isSystemRepoRemote(remote);
+}
 /** True when two git remote URLs point at the same repo across transport forms. */
 export function sameGitRemote(a, b) {
     if (!a || !b)
@@ -1665,6 +1692,37 @@ export async function tryAutoPull(dir) {
         return { pulled: false, error: err.message };
     }
 }
+/**
+ * Auto-pull the system repo ONLY after verifying its origin is the expected
+ * system remote (PHNX-2957). The system repo ships hooks that run as shell on
+ * tool events, so fast-forwarding it from an unexpected/repointed origin is
+ * remote code execution. An origin that fails {@link isExpectedSystemRepoRemote}
+ * is REFUSED loud (`refused: true`), never pulled — the canonical system repo
+ * (or an operator's `AGENTS_SYSTEM_REPO`) still fast-forwards exactly as before.
+ *
+ * A system dir with no origin at all is a plain no-op (`pulled: false`), not a
+ * refusal — there is nothing to pull from and nothing to distrust.
+ */
+export async function tryAutoPullSystemRepo(dir) {
+    if (!isGitRepo(dir))
+        return { pulled: false };
+    let remote;
+    try {
+        const git = simpleGit(dir);
+        const remotes = await git.getRemotes(true);
+        remote = remotes.find(r => r.name === 'origin')?.refs?.fetch;
+    }
+    catch {
+        return { pulled: false };
+    }
+    if (!remote)
+        return { pulled: false };
+    if (!isExpectedSystemRepoRemote(remote)) {
+        return { pulled: false, refused: true, actualRemote: remote };
+    }
+    const res = await tryAutoPull(dir);
+    return { ...res, actualRemote: remote };
+}
 /**
  * How many commits `dir`'s checked-out branch is behind its upstream, read from
  * the LAST-FETCHED remote-tracking ref — no network call. Returns null when the

package/dist/lib/hosts/ready.d.ts

@@ -100,6 +100,14 @@ export interface ViewAgentAccountEligibility {
  * --json`. A picker may route to a signed-out version because launching it is
  * the login flow, but it must not route to a device whose every signed-in
  * account is throttled.
+ *
+ * The sign-in gate reads the per-version `launchable` field — the strict
+ * per-version launch truth (`isLaunchableSignedIn`) — so a remote box is judged
+ * by the SAME launchability the local candidate uses (`collectRunCandidates` →
+ * `isLaunchableSignedIn`), not the display `signedIn` that inherits the
+ * active/global HOME login and passes a box that dies at spawn (PHNX-3466). An
+ * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
+ * pre-fix behavior, so a rolling fleet does not regress.
  */
 export declare function viewAgentAccountEligibility(view: string, agent: string): ViewAgentAccountEligibility;
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;

package/dist/lib/hosts/ready.js

@@ -213,6 +213,14 @@ export function missingPinnedVersionMessage(hostName, agent, version, installed)
  * --json`. A picker may route to a signed-out version because launching it is
  * the login flow, but it must not route to a device whose every signed-in
  * account is throttled.
+ *
+ * The sign-in gate reads the per-version `launchable` field — the strict
+ * per-version launch truth (`isLaunchableSignedIn`) — so a remote box is judged
+ * by the SAME launchability the local candidate uses (`collectRunCandidates` →
+ * `isLaunchableSignedIn`), not the display `signedIn` that inherits the
+ * active/global HOME login and passes a box that dies at spawn (PHNX-3466). An
+ * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
+ * pre-fix behavior, so a rolling fleet does not regress.
  */
 export function viewAgentAccountEligibility(view, agent) {
     try {
@@ -223,12 +231,15 @@ export function viewAgentAccountEligibility(view, agent) {
         const verdicts = (row.versions ?? []).flatMap((version) => {
             if (typeof version.signedIn !== 'boolean')
                 return [];
+            // Prefer the strict per-version launch signal; fall back to the display
+            // `signedIn` for an older remote CLI that does not emit `launchable`.
+            const launchable = typeof version.launchable === 'boolean' ? version.launchable : version.signedIn;
             const throttled = version.usageStatus === 'rate_limited' || version.usageStatus === 'out_of_credits';
             const authBlocked = version.authVerdict !== null
                 && version.authVerdict !== undefined
                 && isDeadVerdict(version.authVerdict);
-            const ready = version.signedIn && !authBlocked && !throttled;
-            return [{ ready, pickerEligible: ready || !version.signedIn || authBlocked }];
+            const ready = launchable && !authBlocked && !throttled;
+            return [{ ready, pickerEligible: ready || !launchable || authBlocked }];
         });
         if (verdicts.length === 0)
             return { signedIn: undefined, pickerEligible: undefined };

package/dist/lib/installations/versions.d.ts

@@ -427,6 +427,23 @@ export declare function mergeRepoScopedSelections(repos: string[], cwd?: string)
  *
  * For Gemini: commands are converted from markdown to TOML.
  */
+/**
+ * Resolve a caller's hook selection against the available hook set, matching a
+ * selection entry by exact name OR by its extensionless basename, and returning
+ * the AVAILABLE (extensioned) name in every case.
+ *
+ * `available.hooks` carries the source filename WITH its extension
+ * (`git-guard.sh`) — the shape the hooks writer's source resolver requires — but
+ * the doctor/heal resource diff identifies a hook by its extensionless basename
+ * (`git-guard`). A heal pass feeds those diff names straight back as the
+ * selection, so a plain exact-set filter matched NOTHING and `agents doctor
+ * --fix` could never reconcile a flagged hook (PHNX-3187). Basename tolerance
+ * closes that gap without changing the extensioned names the writer needs.
+ *
+ * Order-stable and de-duplicated; a selection entry that matches nothing is
+ * dropped (mirrors resolveSelection).
+ */
+export declare function resolveHookSelection(sel: string[] | 'all' | undefined, available: string[]): string[];
 export declare function syncResourcesToVersion(agent: AgentId, version: string, selection?: ResourceSelection, options?: {
     projectDir?: string;
     cwd?: string;

package/dist/lib/installations/versions.js

@@ -2198,6 +2198,46 @@ export function mergeRepoScopedSelections(repos, cwd = process.cwd()) {
  *
  * For Gemini: commands are converted from markdown to TOML.
  */
+/**
+ * Resolve a caller's hook selection against the available hook set, matching a
+ * selection entry by exact name OR by its extensionless basename, and returning
+ * the AVAILABLE (extensioned) name in every case.
+ *
+ * `available.hooks` carries the source filename WITH its extension
+ * (`git-guard.sh`) — the shape the hooks writer's source resolver requires — but
+ * the doctor/heal resource diff identifies a hook by its extensionless basename
+ * (`git-guard`). A heal pass feeds those diff names straight back as the
+ * selection, so a plain exact-set filter matched NOTHING and `agents doctor
+ * --fix` could never reconcile a flagged hook (PHNX-3187). Basename tolerance
+ * closes that gap without changing the extensioned names the writer needs.
+ *
+ * Order-stable and de-duplicated; a selection entry that matches nothing is
+ * dropped (mirrors resolveSelection).
+ */
+export function resolveHookSelection(sel, available) {
+    if (sel === 'all')
+        return available;
+    if (!Array.isArray(sel))
+        return [];
+    const stripExt = (n) => n.replace(/\.[^./\\]+$/, '');
+    const exact = new Set(available);
+    const byBase = new Map();
+    for (const a of available) {
+        const base = stripExt(a);
+        if (!byBase.has(base))
+            byBase.set(base, a); // first available wins the basename
+    }
+    const out = [];
+    const seen = new Set();
+    for (const name of sel) {
+        const resolved = exact.has(name) ? name : byBase.get(stripExt(name));
+        if (resolved && !seen.has(resolved)) {
+            seen.add(resolved);
+            out.push(resolved);
+        }
+    }
+    return out;
+}
 export function syncResourcesToVersion(agent, version, selection, options = {}) {
     if (isAgentHardDeprecated(agent)) {
         return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [], projectSkipped: [], pruned: { commands: [], skills: [] }, declined: [] };
@@ -2494,8 +2534,14 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             console.warn(explainSkip(agent, 'hooks', hooksGate, version) + ' -- skipped');
         }
         else {
+            // Resolve requested hooks against the available set BY BASENAME as well as
+            // exact name. `available.hooks` carries the source filename WITH its
+            // extension (`git-guard.sh`), but the doctor/heal diff identifies a hook
+            // by its extensionless basename (`git-guard`) — so a heal pass that feeds
+            // the diff's names straight back through the plain resolveSelection
+            // matched NOTHING and could never reconcile a flagged hook (PHNX-3187).
             const hooksToSync = selection
-                ? resolveSelection(selection.hooks, available.hooks)
+                ? resolveHookSelection(selection.hooks, available.hooks)
                 : available.hooks;
             let hookManifest = {};
             if (hooksToSync.length > 0) {
@@ -2647,6 +2693,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         if (r.paths)
             writtenTargets.push(...r.paths);
         result.subagents.push(...r.synced);
+        if (r.errors?.length)
+            result.declined.push(...r.errors.map((e) => `subagents: ${e}`));
         // Orphan-sweep for Claude only — see comment on commands/skills sweep
         // for the no-selection guard. OpenClaw stores subagents as siblings of
         // other resources so a readdir sweep would over-reach.
@@ -2673,7 +2721,10 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (pluginsToSync.length > 0 && pluginsWriter) {
         if (options.allowExecSurfaces) {
             const allPlugins = discoverPlugins();
-            cleanOrphanedPluginSkills(agent, versionHome, new Set(allPlugins.map(p => p.name)));
+            // Pass the discovered plugins (with marketplace provenance) so a stale
+            // install under one marketplace is trashed even when another marketplace
+            // still ships that name — the PHNX-2618 shadow `code` plugin.
+            cleanOrphanedPluginSkills(agent, versionHome, allPlugins);
             const pluginMap = new Map(allPlugins.map(p => [p.name, p]));
             for (const name of pluginsToSync) {
                 const plugin = pluginMap.get(name);

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}; }`);
+}