@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/commands/fork.js

@@ -1,79 +1,132 @@
+/**
+ * `agents sessions fork <session>` — branch an existing conversation into a new,
+ * independent same-harness sibling, seeded with a recap so it picks up where the
+ * original left off. The original is untouched. Also exposed as the hidden
+ * top-level alias `agents fork` (back-compat).
+ *
+ * The source is resolved CROSS-FLEET (the same path `agents sessions preview`
+ * uses), so a session that lives on another device forks fine — the sibling is
+ * handed a plain-text recap as its opening input and never has to reach the
+ * source transcript. Because the seed is text, any REPL harness can be forked,
+ * not just Claude.
+ *
+ * Thin command layer; the pure recap text lives in `lib/session/fork.ts`.
+ */
+import { spawnSync } from 'child_process';
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
-import { findSessionsById } from '../lib/session/db.js';
-import { discoverSessions } from '../lib/session/discover.js';
-import { forkSession, isForkableAgent, FORKABLE_AGENTS } from '../lib/session/fork.js';
+import { getCliLaunch } from '../lib/cli-entry.js';
+import { buildForkRecap, forkLabelFor } from '../lib/session/fork.js';
+function defaultDeps() {
+    return {
+        runPreview: (sub) => {
+            const p = getCliLaunch(['sessions', 'preview', ...sub]);
+            // stderr inherited so preview's own resolution errors reach the user verbatim.
+            const r = spawnSync(p.command, p.args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'inherit'] });
+            return { status: r.status, stdout: r.stdout ?? '' };
+        },
+        launch: (sub) => {
+            const l = getCliLaunch(sub);
+            // In-place stdio so the sibling takes over this terminal.
+            const r = spawnSync(l.command, l.args, { stdio: 'inherit' });
+            return { status: r.status };
+        },
+    };
+}
 const FORK_HELP = {
     examples: `
-    # Fork a session by (partial) id, then continue the fork
+    # Fork a session by (partial) id — launches a same-harness sibling seeded with a recap
     agents sessions fork 4f3a9c21
-    agents sessions resume <new-id>
 
-    # Give the fork a name
+    # Name the fork's session label
     agents sessions fork 4f3a9c21 --name "try redis instead"
+
+    # Place the sibling on a fleet worker instead of here
+    agents sessions fork 4f3a9c21 --device auto
+
+    # Open the sibling in a fresh terminal tab where you work
+    agents sessions fork 4f3a9c21 --terminal
   `,
     notes: `
-    - 'resume' continues the SAME conversation; 'fork' copies it under a new id so the two diverge.
-    - The fork is a full copy of the conversation so far; continuing it never touches the original.
-    - Resolve the session the same way as resume: an exact or prefix id fragment.
-    - Native copy currently supports: ${FORKABLE_AGENTS.join(', ')}. For other harnesses, branch by
-      starting a fresh agent and seeding it with '/continue <id>' — the source stays put.
+    - 'resume' continues the SAME conversation; 'fork' launches a NEW same-harness
+      session seeded with a recap of the source, so the two diverge.
+    - Works cross-device and cross-harness: the source is resolved across the fleet
+      and the sibling gets a plain-text recap, so it never reaches the source transcript.
+    - The recap carries the source id — the sibling can run '/continue <id>' for the
+      full history if it needs more than the recap.
+    - Resolve the source the same way as resume: an exact or prefix id fragment.
   `,
 };
 /**
- * Resolve the source session, copy it under a fresh id, and print how to
- * continue the fork. Shared by `agents sessions fork` and the `agents fork` alias.
+ * Resolve the source cross-fleet, build a recap from its preview digest, and
+ * launch a same-harness sibling seeded with that recap. Shared by
+ * `agents sessions fork` and the `agents fork` alias.
  */
-export async function runFork(sessionArg, options) {
-    // Resolve the source. Try the index first; only pay for a rescan if the id
-    // isn't found yet (mirrors the resume path's freshen-then-lookup).
-    let matches = findSessionsById(sessionArg, {});
-    if (matches.length === 0) {
-        await discoverSessions({});
-        matches = findSessionsById(sessionArg, {});
-    }
-    if (matches.length === 0) {
-        // Errors go to stderr and set a non-zero exit code so a script chaining on
-        // `agents sessions fork <id> && agents sessions resume <new>` doesn't proceed
-        // on a failed fork.
-        console.error(chalk.red(`No session matching "${sessionArg}".`));
-        console.error(chalk.gray('List candidates with: agents sessions'));
+export async function runFork(sessionArg, options, deps = defaultDeps()) {
+    // Resolve + digest in one cross-fleet hop by shelling the existing preview
+    // verb: it resolves the id across the fleet (SSH fan-out + peer hop), computes
+    // the digest on the OWNING device, and prints it as JSON — so a remote source
+    // resolves fine and we never re-implement resolution or digesting here.
+    // --terminal opens a tab on THIS machine; --device dispatches over SSH. `agents
+    // run` refuses the combination, so reject it here with a fork-specific message
+    // before resolving anything, rather than after an overpromising progress line.
+    if (options.device && options.terminal !== undefined) {
+        console.error(chalk.red('Pick one placement: --terminal opens a tab here; --device places the sibling on another box. They cannot combine.'));
         process.exitCode = 1;
         return;
     }
-    if (matches.length > 1) {
-        console.error(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
-        for (const m of matches.slice(0, 8)) {
-            console.error(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
-        }
-        process.exitCode = 1;
+    const res = deps.runPreview([sessionArg, '--json']);
+    if (res.status !== 0) {
+        // preview already explained why on stderr; propagate its exit code.
+        process.exitCode = res.status ?? 1;
         return;
     }
-    const source = matches[0];
-    if (!isForkableAgent(source.agent)) {
-        // A native copy needs the agent's transcript to be resumable by id; harnesses
-        // without that can still be branched by hand. Fail loud with the manual path
-        // rather than a silent no-op or a fake copy.
-        console.error(chalk.yellow(`A native fork copy isn't supported for ${source.agent} sessions yet (supported: ${FORKABLE_AGENTS.join(', ')}).`));
-        console.error(chalk.gray(`  Branch it by hand — start a fresh ${source.agent} and seed it with the source's context:`));
-        console.error(chalk.gray(`    agents run ${source.agent} --terminal   # then, in the new session:`));
-        console.error(chalk.gray(`    /continue ${source.shortId}`));
+    let data;
+    try {
+        data = JSON.parse(res.stdout);
+    }
+    catch {
+        console.error(chalk.red(`Could not read the source session for "${sessionArg}".`));
         process.exitCode = 1;
         return;
     }
-    let result;
-    try {
-        result = forkSession(source, { name: options.name });
-    }
-    catch (err) {
-        console.error(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
+    const source = data?.session;
+    if (!source?.id || !source?.agent) {
+        console.error(chalk.red(`Could not resolve a forkable source for "${sessionArg}".`));
         process.exitCode = 1;
         return;
     }
-    console.log(chalk.green(`Forked ${source.shortId} -> ${result.shortId}`));
-    console.log(chalk.gray(`  Label:    ${result.label}`));
-    console.log(chalk.gray(`  Continue: agents sessions resume ${result.shortId}`));
-    console.log(chalk.gray(`  Original ${source.shortId} is untouched.`));
+    const digest = data?.preview ?? undefined;
+    // Most sessions have no explicit --name label; fall back to the auto-derived
+    // topic the rest of the CLI shows, not the raw short id (forkLabelFor is the
+    // shared 3-tier resolver, and preview's --json now carries `topic`).
+    const label = forkLabelFor({ label: source.label, topic: source.topic, shortId: source.shortId });
+    const recap = buildForkRecap({
+        agent: source.agent,
+        label,
+        cwd: source.cwd,
+        ticketId: source.ticketId,
+        machine: source.machine,
+        shortId: source.shortId,
+        id: source.id,
+        lastAssistant: digest?.lastAssistant,
+        changes: digest?.changes,
+    });
+    // Launch a NEW same-harness session, load-balanced across accounts (balanced),
+    // seeded with the recap as its opening input. Runs here by default; --device
+    // places it on the fleet; --terminal opens it in a fresh tab where the user works.
+    const runArgs = ['run', source.agent, recap, '-i', '--strategy', 'balanced', '--name', options.name || `fork of ${label}`];
+    if (options.device)
+        runArgs.push('--device', options.device);
+    if (options.terminal !== undefined) {
+        runArgs.push('--terminal');
+        if (typeof options.terminal === 'string')
+            runArgs.push(options.terminal);
+    }
+    const where = options.device ? ` on ${options.device}` : options.terminal !== undefined ? ' in a new terminal' : '';
+    console.error(chalk.gray(`Forking ${source.shortId} → new ${source.agent} session${where}, seeded with a recap…`));
+    const child = deps.launch(runArgs);
+    process.exitCode = child.status ?? 0;
 }
 /**
  * Register `agents sessions fork <session>` — the canonical surface (fork is a
@@ -82,10 +135,12 @@ export async function runFork(sessionArg, options) {
 export function registerSessionsForkCommand(sessionsCmd) {
     const cmd = sessionsCmd
         .command('fork <session>')
-        .description('Branch a session into a new, independent copy you can continue separately. The original is untouched.')
-        .option('--name <label>', 'Label for the fork (default: "fork of <original>")');
+        .description('Branch a session into a new same-harness sibling, seeded with a recap so it continues the work. The original is untouched.')
+        .option('--name <label>', 'Session label for the fork (default: "fork of <original>")')
+        .option('--device <host>', 'Place the sibling on a fleet device (name or "auto"); defaults to here')
+        .option('--terminal [backend]', 'Open the sibling in a real terminal tab (iterm | ghostty | terminal | tmux | vscodium-agent) instead of in-place');
     setHelpSections(cmd, FORK_HELP);
-    cmd.action(runFork);
+    cmd.action((session, options) => runFork(session, options));
 }
 /**
  * Register the hidden top-level `agents fork` alias. Kept working for back-compat
@@ -94,7 +149,9 @@ export function registerSessionsForkCommand(sessionsCmd) {
 export function registerForkCommand(program) {
     const cmd = program
         .command('fork <session>', { hidden: true })
-        .description('Alias for `agents sessions fork` — branch a session into a new, independent copy.')
-        .option('--name <label>', 'Label for the fork (default: "fork of <original>")');
-    cmd.action(runFork);
+        .description('Alias for `agents sessions fork` — branch a session into a new same-harness sibling.')
+        .option('--name <label>', 'Session label for the fork (default: "fork of <original>")')
+        .option('--device <host>', 'Place the sibling on a fleet device (name or "auto"); defaults to here')
+        .option('--terminal [backend]', 'Open the sibling in a real terminal tab (iterm | ghostty | terminal | tmux | vscodium-agent) instead of in-place');
+    cmd.action((session, options) => runFork(session, options));
 }

package/dist/commands/monitors.js

@@ -14,10 +14,10 @@ import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, } from '../lib/daemon/daemon.js';
 import { findDuplicateMonitor, monitorFingerprint } from '../lib/monitors/fingerprint.js';
 import { gatherFleetMonitors, NO_MONITOR_FANOUT_ENV } from '../lib/monitors/remote.js';
-import { listMonitors, readMonitor, writeMonitor, deleteMonitor, setMonitorEnabled, getMonitorPath, validateMonitor, monitorRunsOnThisDevice, parseInterval, } from '../lib/monitors/config.js';
+import { listMonitors, readMonitor, writeMonitor, deleteMonitor, setMonitorEnabled, getMonitorPath, validateMonitor, monitorRunsOnThisDevice, requiresSingleOwner, monitorSharedInputOwner, parseInterval, } from '../lib/monitors/config.js';
 import { formatRelativeTime } from '../lib/session/relative-time.js';
 import { evaluateMonitorOnce, POLL_SOURCE_TYPES } from '../lib/monitors/engine.js';
-import { listFires, readState, readLiveness, resolveFireOutcome } from '../lib/monitors/state.js';
+import { listFires, readState, readLiveness, resolveFireOutcome, getMonitorHistoryDir } from '../lib/monitors/state.js';
 import { listRuns, getLatestRun, getRunDir } from '../lib/scheduling/routines.js';
 import { getMonitorsDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
@@ -26,6 +26,8 @@ import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { loadDevices } from '../lib/devices/registry.js';
 import { assertDaemonEnabled } from '../lib/device-config.js';
 import { setHelpSections } from '../lib/help.js';
+import { isPidAlive } from '../lib/session/active.js';
+import { PID_WATCH_EXITED_TOKEN, pidLivenessCommand } from '../lib/monitors/pid-watch.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 function stdoutJson(payload) {
     process.stdout.write(JSON.stringify(payload) + '\n');
@@ -94,8 +96,79 @@ function ownerLabel(monitor) {
         return monitor.device;
     if (monitor.devices && monitor.devices.length > 0)
         return monitor.devices.join(',');
+    // An unpinned shared-input monitor (a system built-in by default) is NOT
+    // fleet-wide — it fires only on the single resolved owner (SING-9). Show that
+    // owner, not a misleading "all"; surface the unresolved case loudly.
+    if (requiresSingleOwner(monitor)) {
+        const owner = monitorSharedInputOwner();
+        return owner ? `${owner} (owner)` : 'unowned — set interactive.host';
+    }
     return 'all';
 }
+/** The `(built-in)` tag for a system-layer monitor, mirroring routines' list. */
+function builtinTag(monitor) {
+    return monitor.scope === 'system' ? chalk.gray(' (built-in)') : '';
+}
+/**
+ * A one-line liveness note for a monitor living on a PEER, reconstructed from the
+ * `--json` fields that box reported (it computes the colorized local label, which
+ * doesn't cross the wire). Deliberately terse — the owning box's `monitors view`
+ * has the full detail.
+ */
+function remoteLivenessNote(d) {
+    if (!d)
+        return chalk.gray('—');
+    if (d.enabled === false)
+        return chalk.gray('paused');
+    if (d.stalled)
+        return chalk.red('STALLED');
+    if (d.lastActionFailed)
+        return chalk.red('ACTION FAILED');
+    if (d.lastFiredAt)
+        return chalk.green(`fired ${formatRelativeTime(d.lastFiredAt)}`);
+    if (typeof d.checkCount === 'number' && d.checkCount > 0)
+        return chalk.gray(`checked ${d.checkCount}x`);
+    if (d.lastCheckedAt)
+        return chalk.gray(`checked ${formatRelativeTime(d.lastCheckedAt)}`);
+    return chalk.yellow('never polled');
+}
+/**
+ * Print a stderr note when the fleet fan-out couldn't consult every box, so a
+ * partial listing never silently reads as "these are all the monitors there are".
+ */
+function fleetReachNote(fleet) {
+    if (fleet.discoveryFailed) {
+        stderrLine(chalk.yellow('  Note: could not reach the device registry — the fleet was not checked, only this device is shown.'));
+    }
+    else if (fleet.skipped.length > 0) {
+        stderrLine(chalk.yellow(`  Note: could not reach ${fleet.skipped.length} device(s): ${fleet.skipped.join(', ')} — their monitors are not shown.`));
+    }
+}
+/** A remote monitor rendered into the same `--json` row shape as a local one. */
+function remoteMonitorJsonRow(r) {
+    const d = r.display;
+    return {
+        machine: r.machine,
+        name: r.monitor.name,
+        enabled: d?.enabled ?? null,
+        source: r.monitor.source,
+        condition: r.monitor.condition,
+        action: r.monitor.action,
+        owner: d?.owner ?? null,
+        scope: d?.scope ?? null,
+        builtin: d?.scope === 'system',
+        runsHere: false,
+        lastSeenAt: null,
+        lastFiredAt: d?.lastFiredAt ?? null,
+        lastCheckedAt: d?.lastCheckedAt ?? null,
+        checkCount: d?.checkCount ?? 0,
+        lastError: null,
+        consecutiveErrors: 0,
+        stalled: d?.stalled ?? false,
+        lastActionStatus: null,
+        lastActionFailed: d?.lastActionFailed ?? false,
+    };
+}
 /** A monitor's evaluation cadence in ms (falls back to the engine default). */
 function monitorIntervalMs(monitor) {
     if (monitor.source.interval)
@@ -139,6 +212,13 @@ function livenessLabel(monitor, state, liveness) {
     if (liveness.lastError) {
         return chalk.red(`checked ${liveness.checkCount}x · error: ${liveness.lastError.replace(/\s+/g, ' ').slice(0, 60)}`);
     }
+    const latestFire = listFires(monitor.name).at(-1);
+    if (latestFire) {
+        const outcome = resolveFireOutcome(monitor.name, latestFire);
+        if (!outcome.ok) {
+            return chalk.red(`ACTION FAILED ${formatRelativeTime(latestFire.firedAt)}`) + chalk.gray(` · checked ${liveness.checkCount}x`);
+        }
+    }
     if (state?.lastFiredAt) {
         return chalk.green(`fired ${formatRelativeTime(state.lastFiredAt)}`) + chalk.gray(` · checked ${liveness.checkCount}x`);
     }
@@ -223,11 +303,28 @@ async function validateDevice(name) {
     }
     return normalized;
 }
-/** Parse the source flags into a MonitorSource, exiting on missing/ambiguous input. */
-function buildSource(options) {
+/** Parse the source flags into a MonitorSource, exiting on missing/ambiguous input. `name` seeds the --watch-pid running-seen marker. */
+function buildSource(options, name) {
     const chosen = [];
     if (options.watch)
         chosen.push({ type: 'command', source: { type: 'command', command: options.watch } });
+    if (options.watchPid) {
+        const pid = Number(options.watchPid);
+        if (!Number.isInteger(pid) || pid < 1) {
+            stderrLine(chalk.red(`--watch-pid must be a positive integer pid, got '${options.watchPid}'`));
+            process.exit(1);
+        }
+        // Fail loud rather than silently arming a watcher on a corpse (PHNX-3023):
+        // a pid that is already gone at arm time can never transition to "exited",
+        // so the monitor would sit enabled and never fire.
+        if (!isPidAlive(pid) && !options.force) {
+            stderrLine(chalk.red(`Process ${pid} is not running — there is nothing to watch.`));
+            stderrLine(chalk.gray('Pass --force to arm it anyway (e.g. the pid is about to be spawned by a concurrent step).'));
+            process.exit(1);
+        }
+        const seenRunningMarkerPath = path.join(getMonitorHistoryDir(name), 'pid-watch-seen-running');
+        chosen.push({ type: 'command', source: { type: 'command', command: pidLivenessCommand(pid, seenRunningMarkerPath) } });
+    }
     if (options.poll) {
         chosen.push({ type: 'poll', source: { type: 'poll', command: options.poll[0], interval: options.poll[1] } });
     }
@@ -267,7 +364,7 @@ function buildSource(options) {
         chosen.push({ type: 'webhook', source: { type: 'webhook', webhook } });
     }
     if (chosen.length === 0) {
-        stderrLine(chalk.red('A source is required: --watch, --poll, --poll-http, --ws, --watch-file, --watch-device, or --on'));
+        stderrLine(chalk.red('A source is required: --watch, --watch-pid, --poll, --poll-http, --ws, --watch-file, --watch-device, or --on'));
         process.exit(1);
     }
     if (chosen.length > 1) {
@@ -276,7 +373,12 @@ function buildSource(options) {
     }
     return chosen[0].source;
 }
-/** Parse the condition flags into a MonitorCondition (default on-change). */
+/**
+ * Parse the condition flags into a MonitorCondition (default on-change).
+ * `--watch-pid` with no explicit mode defaults to firing on exit rather than
+ * on-change, since "running"/"exited" is a two-value observation where
+ * on-change would fire the instant the daemon takes its first poll.
+ */
 function buildCondition(options) {
     const modes = [];
     if (options.onChange)
@@ -289,6 +391,9 @@ function buildCondition(options) {
         stderrLine(chalk.red('--on-change, --match, and --every are mutually exclusive'));
         process.exit(1);
     }
+    if (options.watchPid && modes.length === 0) {
+        return { mode: 'match', match: PID_WATCH_EXITED_TOKEN };
+    }
     const mode = modes[0] ?? (options.match ? 'match' : 'on-change');
     const condition = { mode };
     if (options.match)
@@ -451,11 +556,17 @@ export function registerMonitorsCommands(program) {
       # A fleet box going loaded → spin up an agent
       agents monitors add box-loaded --watch-device yosemite-s0 --match loaded \\
         --run claude --prompt 'yosemite-s0 is loaded: {event}. Investigate.'
+
+      # A backgrounded shell that will never exit on its own (a watch loop, gh pr
+      # checks --watch, a long sleep) — arm a REAL watcher instead of trusting the
+      # harness's own exit hook (which only fires when the process dies):
+      agents monitors add pr-checks-1234 --watch-pid 48213 \\
+        --run claude --prompt 'PID 48213 exited: {event}. Resume and check the result.'
     `,
         notes: `
       A monitor is a routine whose trigger is a watched SOURCE instead of a clock.
       It has three parts:
-        - SOURCE    (--watch, --poll, --poll-http, --ws, --watch-file, --watch-device, --on)
+        - SOURCE    (--watch, --watch-pid, --poll, --poll-http, --ws, --watch-file, --watch-device, --on)
         - CONDITION (--on-change [default], --match <re>, --every; --dedupe-key)
         - ACTION    (--run <agent> --prompt, --routine, --notify, --webhook-out)
                     --postcondition <cmd> on --run/--routine asserts the effect
@@ -470,6 +581,11 @@ export function registerMonitorsCommands(program) {
       v1 evaluates poll sources (command, poll, poll-http, file, device). Push
       sources (ws, webhook) are accepted but delivered through a receiver wired in
       a follow-up.
+
+      --watch-pid <pid> refuses to arm (fails loud) when the pid is already dead —
+      a "will re-invoke me" watcher pointed at a corpse never fires. It defaults
+      the condition to fire on exit, unlike a raw --watch which defaults to
+      on-change.
     `,
     });
     // ─── add ────────────────────────────────────────────────────────────────────
@@ -478,6 +594,7 @@ export function registerMonitorsCommands(program) {
         .description('Create a monitor from inline flags or a YAML file. Auto-starts the daemon unless daemon.enabled is false.')
         // SOURCE
         .option('--watch <cmd>', 'Run a shell command; its stdout is the observation')
+        .option('--watch-pid <pid>', 'Watch a backgrounded process for exit — a reliable, daemon-polled alternative to a harness exit hook. Fails loud if the pid is already gone. Defaults to firing on exit')
         .option('--poll <cmd...>', 'Re-run a command every interval: --poll "<cmd>" <interval> (e.g. 30s)')
         .option('--poll-http <url...>', 'GET a URL every interval: --poll-http <url> <interval> (e.g. 15m)')
         .option('--on <source:event>', 'Webhook trigger source: github:pull_request or linear:Issue')
@@ -515,7 +632,7 @@ export function registerMonitorsCommands(program) {
         .option('--force', 'Overwrite a same-named monitor, or add one that duplicates an existing watcher')
         .action(async (nameOrPath, options) => {
         // File mode: a single arg pointing at an existing .yml with no source flags.
-        const hasSourceFlag = Boolean(options.watch || options.poll || options.pollHttp || options.on || options.ws || options.watchFile || options.watchDevice);
+        const hasSourceFlag = Boolean(options.watch || options.watchPid || options.poll || options.pollHttp || options.on || options.ws || options.watchFile || options.watchDevice);
         if (!hasSourceFlag && nameOrPath && /\.ya?ml$/.test(nameOrPath) && fs.existsSync(path.resolve(nameOrPath))) {
             const resolved = path.resolve(nameOrPath);
             let parsed;
@@ -548,7 +665,7 @@ export function registerMonitorsCommands(program) {
             stderrLine(chalk.gray('Usage: agents monitors add <name> --poll "<cmd>" 30s --match fail --run claude --prompt "..."'));
             process.exit(1);
         }
-        const source = buildSource(options);
+        const source = buildSource(options, nameOrPath);
         // A --watch-device source name must resolve to a registered fleet member —
         // validate it (fail fast with the registered list) so a typo/removed device
         // can't silently watch the local machine (same gate as --device/--devices).
@@ -621,15 +738,37 @@ export function registerMonitorsCommands(program) {
     // ─── list ────────────────────────────────────────────────────────────────────
     monitorsCmd
         .command('list')
-        .description('See all monitors: source, condition, action, owner, and last fire.')
+        .description('See all monitors across the fleet: source, condition, action, owner, last fire, and the box each lives on.')
         .option('--json', 'Emit machine-readable JSON')
-        .action((options) => {
+        .option('--local', 'This device only — skip the fleet fan-out')
+        .action(async (options) => {
+        const self = machineId();
         const monitors = listMonitors();
+        // A peer answering the fan-out (NO_MONITOR_FANOUT_ENV set) reports its own
+        // box only, so the parent's gather is a flat union and never recurses. The
+        // duplicate guard reads exactly this bare local array, so its shape must not
+        // change when the env is set. `--local` is the same opt-out for a human.
+        const peerMode = !!process.env[NO_MONITOR_FANOUT_ENV];
+        const localOnly = peerMode || options.local === true;
+        let fleet = null;
+        if (!localOnly) {
+            // Same cross-machine fan-out `sessions --active` and the add-time guard
+            // use — visibility, not git-sync (PHNX-2506 item 3). Never throws; an
+            // unreachable fleet degrades to an empty remote set plus skipped names.
+            fleet = await gatherFleetMonitors();
+        }
+        // Peers may echo this box's own monitors back (a synced mirror, or the box
+        // resolving its own name); drop anything on `self` so local rows aren't
+        // double-listed.
+        const remote = (fleet?.monitors ?? []).filter((r) => normalizeHost(r.machine) !== self);
         if (options.json) {
-            const payload = monitors.map((m) => {
+            const localRows = monitors.map((m) => {
                 const state = readState(m.name);
                 const liveness = readLiveness(m.name);
+                const latestFire = listFires(m.name).at(-1);
+                const latestOutcome = latestFire ? resolveFireOutcome(m.name, latestFire) : null;
                 return {
+                    machine: self,
                     name: m.name,
                     enabled: m.enabled,
                     source: m.source,
@@ -640,6 +779,11 @@ export function registerMonitorsCommands(program) {
                     // exactly the case it exists for. `source` already ships whole.
                     action: m.action,
                     owner: ownerLabel(m),
+                    // `scope`/`builtin` (PHNX-2506 item 2): where the monitor came from,
+                    // so "is this a shipped built-in?" is answerable without knowing the
+                    // system mirror exists. Peers read `scope` off this field.
+                    scope: m.scope ?? 'user',
+                    builtin: m.scope === 'system',
                     runsHere: monitorRunsOnThisDevice(m),
                     lastSeenAt: state?.lastSeenAt ?? null,
                     lastFiredAt: state?.lastFiredAt ?? null,
@@ -650,26 +794,52 @@ export function registerMonitorsCommands(program) {
                     lastError: liveness?.lastError ?? null,
                     consecutiveErrors: liveness?.consecutiveErrors ?? 0,
                     stalled: isStalled(m, liveness),
+                    lastActionStatus: latestOutcome?.runStatus ?? null,
+                    lastActionFailed: latestOutcome ? !latestOutcome.ok : false,
                 };
             });
-            stdoutJson(payload);
+            stdoutJson([...localRows, ...remote.map(remoteMonitorJsonRow)]);
             return;
         }
-        if (monitors.length === 0) {
+        if (monitors.length === 0 && remote.length === 0) {
             console.log(chalk.gray('No monitors configured'));
             console.log(chalk.gray('  Add one: agents monitors add <name> --poll "<cmd>" 30s --match fail --run claude --prompt "..."'));
+            if (fleet && (fleet.discoveryFailed || fleet.skipped.length > 0))
+                fleetReachNote(fleet);
             return;
         }
         console.log(chalk.bold('Monitors\n'));
-        for (const m of monitors) {
-            const state = readState(m.name);
-            const liveness = readLiveness(m.name);
-            const enabled = m.enabled ? chalk.green('on') : chalk.gray('off');
-            const here = monitorRunsOnThisDevice(m);
-            const owner = here ? ownerLabel(m) : chalk.gray(ownerLabel(m));
-            console.log(`  ${chalk.cyan(m.name.padEnd(22))} ${enabled.padEnd(3)} ${sourceLabel(m.source)}`);
-            console.log(`  ${' '.repeat(22)}     ${chalk.gray(`[${m.condition.mode}]`)} → ${actionLabel(m.action)}  ${chalk.gray(`owner: ${owner}`)}  ${livenessLabel(m, state, liveness)}`);
+        // This box first — it has full liveness detail.
+        if (monitors.length > 0) {
+            if (remote.length > 0)
+                console.log(chalk.gray(`  ${self} (this device)`));
+            for (const m of monitors) {
+                const state = readState(m.name);
+                const liveness = readLiveness(m.name);
+                const enabled = m.enabled ? chalk.green('on') : chalk.gray('off');
+                const here = monitorRunsOnThisDevice(m);
+                const owner = here ? ownerLabel(m) : chalk.gray(ownerLabel(m));
+                console.log(`  ${chalk.cyan(m.name.padEnd(22))} ${enabled.padEnd(3)} ${sourceLabel(m.source)}${builtinTag(m)}`);
+                console.log(`  ${' '.repeat(22)}     ${chalk.gray(`[${m.condition.mode}]`)} → ${actionLabel(m.action)}  ${chalk.gray(`owner: ${owner}`)}  ${livenessLabel(m, state, liveness)}`);
+            }
+        }
+        // Then each peer's monitors, grouped by the box they live on.
+        const byMachine = new Map();
+        for (const r of remote) {
+            const key = r.machine;
+            (byMachine.get(key) ?? byMachine.set(key, []).get(key)).push(r);
+        }
+        for (const machine of [...byMachine.keys()].sort()) {
+            console.log(chalk.gray(`\n  ${machine}`));
+            for (const r of byMachine.get(machine)) {
+                const m = r.monitor;
+                const enabled = r.display?.enabled === false ? chalk.gray('off') : chalk.green('on');
+                console.log(`  ${chalk.cyan(m.name.padEnd(22))} ${enabled.padEnd(3)} ${sourceLabel(m.source)}${builtinTag({ scope: r.display?.scope })}`);
+                console.log(`  ${' '.repeat(22)}     ${chalk.gray(`[${m.condition.mode}]`)} → ${actionLabel(m.action)}  ${chalk.gray(`owner: ${r.display?.owner ?? machine}`)}  ${remoteLivenessNote(r.display)}`);
+            }
         }
+        if (fleet && (fleet.discoveryFailed || fleet.skipped.length > 0))
+            fleetReachNote(fleet);
         console.log();
     });
     // ─── view ──────────────────────────────────────────────────────────────────
@@ -809,7 +979,12 @@ export function registerMonitorsCommands(program) {
             monitorPath = safeJoin(dir, `${name}.yml`);
             const builtIn = readMonitor(name);
             if (builtIn) {
-                fs.writeFileSync(monitorPath, yaml.stringify(builtIn), 'utf-8');
+                // Route through writeMonitor, NOT a raw yaml.stringify: readMonitor
+                // stamps the derived `scope` (and a built-in's `enabled: true`), and
+                // only writeMonitor strips those from the on-disk schema. A raw dump
+                // would persist `scope: system` into the user copy — dead, contradictory
+                // state that violates the "scope never persists" contract.
+                writeMonitor(builtIn);
                 console.log(chalk.gray(`Editing a copy of built-in monitor '${name}' in your user dir: ${monitorPath}`));
             }
             else {

package/dist/commands/prune.js

@@ -66,9 +66,11 @@ function collectOrphans(types, all) {
     }
     if (types.includes('hooks')) {
         for (const { agent, version } of scopePairs(iterHooksCapableVersions(), all)) {
-            // Orphan hooks = scripts present in the version home that no
-            // agents.yaml/hooks.yaml entry registers, so they never fire. Same
-            // definition the doctor overview reports.
+            // Orphan hooks = scripts present in the version home but absent from
+            // every configured source (user + system + extras) — genuinely dead
+            // files, not merely unregistered ones (sync copies helper/test scripts
+            // that no manifest entry declares). Same definition the doctor overview
+            // reports (PHNX-2693).
             const orphans = listUnmanagedHooksInVersionHome(agent, version);
             if (orphans.length > 0) {
                 groups.push({ type: 'hooks', agent, version, orphans });

package/dist/commands/routines.d.ts

@@ -46,5 +46,13 @@ export declare function groupRoutineJobsByDevice(jobs: JobConfig[], registry: De
  */
 export declare function groupRoutineJobsByProject(jobs: JobConfig[], knownProjectNames: Set<string>): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];
+/**
+ * The short, human reason a run did not simply complete — for inline display in
+ * the list/detail so "why did it fail" needs no dig into the run dir. Prefers the
+ * concrete `errorMessage` (which carries `auth_failed: …`, OAuth-revoked, timeouts),
+ * then the readiness block for a `blocked` run, then the mapped skip reason. Returns
+ * null for a healthy (`completed`/`running`) run, which needs no annotation.
+ */
+export declare function runFailureReason(run: RunMeta): string | null;
 /** Register the `agents routines` command tree. */
 export declare function registerRoutinesCommands(program: Command): void;