@phnx-labs/agents-cli 1.22.58 → 1.22.59

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)
@@ -230,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] } });
     }
@@ -274,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) {
@@ -283,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)
@@ -296,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)
@@ -458,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
@@ -477,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 ────────────────────────────────────────────────────────────────────
@@ -485,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')
@@ -522,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;
@@ -555,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).
@@ -628,17 +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,
@@ -649,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,
@@ -663,24 +798,48 @@ export function registerMonitorsCommands(program) {
                     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 ──────────────────────────────────────────────────────────────────
@@ -820,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/routines.test-fixture.js

@@ -149,6 +149,11 @@ export function createDaemonHarness(fileSlug) {
                 // and kills real tmux-wrapped processes every five-minute tick (RUSH-2545).
                 AGENTS_HISTORY_DIR: path.join(home, '.agents', '.history'),
                 AGENTS_SKIP_MIGRATION: '1',
+                // PHNX-2545 test-home tripwire: name the isolated home this daemon must
+                // resolve its state dir under. If the HOME override above ever failed to
+                // reach the child, runDaemon()'s assertTestDaemonHome() refuses to boot
+                // instead of ticking its scheduler against the operator's real host.
+                AGENTS_DAEMON_TEST_HOME: home,
             },
             detached: true,
             stdio: 'ignore',

package/dist/commands/send.d.ts

@@ -11,7 +11,8 @@
  * Compat: positional text still works (`agents send "hi" --channel … --to …`).
  *
  * `agents notify` is the same delivery path with owner defaults
- * (`send --to owner`). Not a second stack. Not agent control — use
+ * (`send --to owner`) and is deprecated — new callers should use
+ * `agents feed post`. Not a second stack. Not agent control — use
  * `agents message` / `agents sessions inject` for running agents.
  *
  * Feed / activity are a different plane (record + read); feed.broadcast may

package/dist/commands/send.js

@@ -47,7 +47,7 @@ async function runSend(positionalText, opts, ownerMode) {
 }
 const SHARED_NOTES = `
   Planes (do not mix them up):
-    send / notify     - DELIVER a message to a recipient (this command)
+    send              - DELIVER a message to a recipient (this command)
     feed post         - RECORD progress / milestones (optional broadcast may call send)
     activity          - READ the activity stream (not a send path)
     message / inject  - CONTROL a running agent (mailbox answer or terminal keystroke)
@@ -97,7 +97,7 @@ export function registerSendCommand(program) {
     });
     const notifyCmd = program
         .command('notify [text]')
-        .description('Deliver to the owner (alias of send --to owner). Channel + target default from notify.owner in agents.yaml.')
+        .description('[DEPRECATED] Deliver to the owner (alias of send --to owner). Use "agents feed post" for new code.')
         .option('--text <text>', 'message body (preferred over positional text)')
         .option('--channel <name>', 'override owner channel')
         .option('--to <target>', 'override owner target (or pass a non-owner dest with --channel)')
@@ -110,7 +110,7 @@ export function registerSendCommand(program) {
         .option('--dry-run', 'resolve + build but do not send');
     setHelpSections(notifyCmd, {
         examples: `
-      # Same as: agents send --to owner --text "…"
+      # Deprecated: prefer "agents feed post --title \"…\" \"…\" --level important"
       agents notify --text "Build finished — PR #1346 is green"
       agents notify "legacy positional still works"
 
@@ -120,13 +120,15 @@ export function registerSendCommand(program) {
       agents notify --text "probe" --dry-run --json
     `,
         notes: `
-      notify ≡ send --to owner. One delivery stack (lib/channels). Set
-      notify.owner.{channel,to} in agents.yaml once per machine/fleet.
+      DEPRECATED. notify ≡ send --to owner and still works, but new callers
+      should use "agents feed post" (record + optional broadcast) instead.
+      Set notify.owner.{channel,to} in agents.yaml once per machine/fleet.
 
       ${SHARED_NOTES}
     `,
     });
     notifyCmd.action(async (text, opts) => {
+        console.error(chalk.yellow('Warning: "agents notify" is deprecated. Use "agents feed post" for progress posts that can also reach the owner.'));
         await runSend(text, opts, true);
     });
 }

package/dist/commands/sessions-stats.js

@@ -6,6 +6,19 @@ import { discoverPlugins } from '../lib/plugins/plugins.js';
 import { setHelpSections } from '../lib/help.js';
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth } from '../lib/session/width.js';
 const DEFAULT_TOP = 20;
+/**
+ * The recorded-set the zero-counts must be read against (PHNX-2301). A resource
+ * only records an EXPLICIT invocation from a harness that emits the event:
+ * `Skill` tool calls come from Claude + Kimi, slash-commands from Claude only
+ * (`SKILL_TOOL_NAME_BY_AGENT` in `lib/session/highlights.ts`, slash-command
+ * parsing in `lib/session/parse.ts`). A session under any other harness — or an
+ * auto-triggered skill, which emits no event on any harness — contributes
+ * nothing, so its resources read as 0 whether or not they were used. Keep these
+ * in lockstep with the writer: widening them here without a verified transcript
+ * tool-name would make the caveat lie about coverage it does not have.
+ */
+const RECORDING_SKILL_HARNESSES = ['claude', 'kimi'];
+const RECORDING_COMMAND_HARNESSES = ['claude'];
 /**
  * The both-ends "dead weight" set: installed resources whose identity
  * (kind + name — name already embeds `plugin:short`, so it matches the stored
@@ -128,7 +141,7 @@ async function statsAction(cmd) {
     const totalInvocations = allInvoked.reduce((s, r) => s + r.invocations, 0);
     if (opts.json) {
         process.stdout.write(JSON.stringify({
-            schemaVersion: 1,
+            schemaVersion: 2,
             kind: 'sessions-stats',
             generatedAt: new Date().toISOString(),
             filters: {
@@ -142,9 +155,21 @@ async function statsAction(cmd) {
             signal: {
                 explicitOnly: true,
                 note: 'Explicit invocations only (slash commands + Skill tool calls). Auto-triggered skills emit no event and read as 0. Skill invocations are recorded for Claude and Kimi; slash-commands for Claude only.',
+                // Structured recorded-set so a machine consumer can tell a zero from a
+                // non-recording harness apart from a genuine non-use (PHNX-2301): a
+                // zeroInvoked resource may simply have been auto-triggered, or only
+                // used under a harness not in these sets.
+                recording: {
+                    skills: RECORDING_SKILL_HARNESSES,
+                    commands: RECORDING_COMMAND_HARNESSES,
+                },
             },
             coverage: {
+                // sessionsWithUsage/sessionsIndexed kept for the SES-IF-4b envelope
+                // contract; sessionsScanned is the honest backfill-coverage numerator
+                // (ledger rows), distinct from the absolute sessionsWithUsage count.
                 sessionsWithUsage: coverage.covered,
+                sessionsScanned: coverage.scanned,
                 sessionsIndexed: coverage.total,
             },
             totals: {
@@ -210,8 +235,12 @@ function renderHuman(args) {
     out.push(chalk.bold('Resource usage') +
         chalk.gray(`  ·  ${allInvokedCount} invoked · ${totalInvocations} invocation${totalInvocations !== 1 ? 's' : ''}` +
             (scopeBits.length ? `  ·  ${scopeBits.join(' · ')}` : '')));
-    out.push(chalk.gray(`  coverage: ${coverage.covered}/${coverage.total} sessions carry the signal`) +
-        (coverage.total > 0 && coverage.covered / coverage.total < 0.5
+    // Scan coverage (ledger) is the honest "has the backfill folded in history?"
+    // signal and drives the hint; sessionsWithUsage is an ABSOLUTE count of sessions
+    // carrying ≥1 explicit invocation, which stays small at full scan coverage
+    // because most sessions invoke nothing (PHNX-2301).
+    out.push(chalk.gray(`  coverage: ${coverage.scanned}/${coverage.total} sessions scanned · ${coverage.covered} carry an explicit invocation`) +
+        (coverage.total > 0 && coverage.scanned / coverage.total < 0.5
             ? chalk.yellow('  — run `agents sessions backfill resources` to fold in history')
             : ''));
     out.push(chalk.gray('  signal: explicit invocations only (slash commands + Skill tool); auto-triggered skills read as 0; skills from Claude+Kimi, slash-commands Claude-only'));
@@ -228,8 +257,11 @@ function renderHuman(args) {
         }
         out.push('');
     }
-    // Zero-invoked section (the dead weight).
-    out.push(chalk.bold('Installed but never invoked') + chalk.gray(`  (${zeroInvoked.length})`));
+    // Zero-invoked section (the dead weight). "Never invoked" is scoped to the
+    // recorded set: never EXPLICITLY invoked under a recording harness (skills
+    // Claude+Kimi, commands Claude-only) — it may still have been auto-triggered or
+    // used under another harness, which is why this is dead-weight EVIDENCE, not proof.
+    out.push(chalk.bold('Installed but never explicitly invoked') + chalk.gray(`  (${zeroInvoked.length})`));
     if (zeroInvoked.length === 0) {
         out.push(chalk.gray('  (every installed resource has at least one explicit invocation in this window)'));
     }

package/dist/commands/sessions.js

@@ -2316,9 +2316,16 @@ limitSource) {
         return;
     }
     // --device / --devices values are merged into options.host for internal routing. A bare `all` / `fleet` sentinel means
-    // "search every peer" — which is already the default — so it resolves to no
-    // explicit host set rather than erroring on a device literally named "all".
-    const deviceTargets = [...(options.device ?? []), ...(options.devices ?? [])]
+    // "search every peer" — which is already the default for `--active` and the
+    // interactive listing — so it resolves to no explicit host set rather than
+    // erroring on a device literally named "all".
+    const rawDeviceTargets = [...(options.device ?? []), ...(options.devices ?? [])];
+    // But the HISTORICAL `--json` listing does NOT fan out by default (it stays a
+    // deterministic local slice for scripts), so the sentinel would otherwise be
+    // silently dropped and the fleet never reached (PHNX-2673). Remember it so that
+    // path can sweep every peer, exactly as the interactive listing already does.
+    const fleetWide = rawDeviceTargets.some(t => t.toLowerCase() === 'all' || t.toLowerCase() === 'fleet');
+    const deviceTargets = rawDeviceTargets
         .filter(t => t.toLowerCase() !== 'all' && t.toLowerCase() !== 'fleet');
     if (deviceTargets.length > 0) {
         options.host = [...(options.host ?? []), ...deviceTargets];
@@ -2775,16 +2782,43 @@ limitSource) {
             // each peer) would fall to FTS content search and return every transcript
             // that merely MENTIONS the id, defeating exact remote resolution. A genuine
             // search phrase keeps the ranked metadata+content path.
-            const filtered = searchQuery
+            let filtered = searchQuery
                 ? resolveSessionQuery(sessions, searchQuery, {
                     scope: { agent: options.agent, project: options.project, routine: options.routine },
                 }).matches
                 : sessions;
+            // `--device all`/`--fleet` on a historical `--json` query fans out to every
+            // peer and merges their rows in — the SAME SSH sweep the interactive listing
+            // below uses, and the whole-fleet twin of the explicit `--device <host>
+            // --json` path (`runRemoteSessionsJson`). Without this the documented
+            // "search the whole fleet" flag returned local rows only (PHNX-2673). Guarded
+            // to the sentinel so a bare `--json` stays a deterministic local slice for
+            // scripts, and skipped under `--local`/the peer recursion guard. Dead peers
+            // are skipped by the fan-out, never fatal — enrichment, not a dependency.
+            const forceLocalJson = options.local === true || process.env[NO_FANOUT_ENV] === '1';
+            if (fleetWide && !forceLocalJson) {
+                const forwarded = ensureWholeIndex(buildForwardedArgs(process.argv, new Set(options.host ?? [])));
+                if (!forwarded.includes('--json'))
+                    forwarded.push('--json');
+                const fanSpinner = isInteractiveTerminal() ? ora('Reaching other machines...').start() : null;
+                try {
+                    const { sessions: remoteSessions } = await gatherRemoteList(forwarded, undefined);
+                    if (remoteSessions.length > 0) {
+                        filtered = mergeLocalFirst([...filtered, ...remoteSessions], machineId());
+                    }
+                }
+                catch {
+                    // fan-out is an enrichment, never a hard dependency
+                }
+                finally {
+                    fanSpinner?.stop();
+                }
+            }
             // JSON is the canonical picker contract: enrich the durable rows once
             // from the shared live cache so every consumer gets lifecycle/recovery
             // metadata without performing its own join or transcript scan.
             const live = await gatherActiveSessions({
-                local: options.local === true || process.env[NO_FANOUT_ENV] === '1',
+                local: forceLocalJson,
                 hosts: options.host,
             });
             process.stdout.write(serializeSessionsJson(serializeSessionPickerRows(filtered, live.sessions)));

package/dist/commands/ssh.js

@@ -130,7 +130,11 @@ function pctCell(v, width) {
  * header — which defeats the scannability this column exists for. */
 const SPEC_WIDTH_MIN = 12;
 /** The static hardware as one compact cell — `12c 64G 1T`: cores, total RAM,
- * total root disk via fmtBytes. `—` only when no probe has ever seen the box.
+ * total root disk via fmtBytes. `—` covers two cases: no probe has ever seen
+ * the box, or the probe answered but yielded no usable core count (`parseNcpu`
+ * finding none, or the Windows `ncpu` group failing the finite-and-positive
+ * check) — the cell is keyed on `ncpu` because a spec string without it would
+ * read as a machine with zero cores.
  *
  * Deliberately NOT gated on `reachable`: hardware does not change while a
  * machine is down, so an offline device keeps rendering the spec from its last
@@ -2298,6 +2302,13 @@ box; \`agents doctor\` names it.
 
 A box whose probe cannot answer (no POSIX shell, e.g. Windows) is reported
 \`unverified\` rather than counted as a success.
+
+The upgrade OWNS its global bin links: after installing, it verifies that
+\`<prefix>/bin/{agents,ag,browser,computer}\` resolve to the freshly-installed
+copy and RESTORES any the package manager dropped — the state that once left a
+box upgraded in place but with every \`agents\` invocation "command not found"
+(PHNX-2768). A link it cannot make resolve fails the upgrade loud, so that box
+is reported \`failed\` (exit non-zero), never a stranded \`ok\`.
 `)
         .action(async (version) => {
         let cmd;

package/dist/commands/versions.js

@@ -11,7 +11,7 @@ import { installVersion, removeVersion, listInstalledVersions, isVersionInstalle
 import { carryForwardSettings } from '../lib/settings-manifest.js';
 import { createShim, createVersionedAlias, supportsIsolatedInstall, isIsolationProtected, CONFIG_ENV_ISOLATED_AGENTS, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/installations/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
-import { tryAutoPull } from '../lib/git.js';
+import { tryAutoPullSystemRepo } from '../lib/git.js';
 import { getAgentsDir, getTrashVersionsDir } from '../lib/state.js';
 import { setHelpSections } from '../lib/help.js';
 import { updateSessionFilePaths } from '../lib/session/db.js';
@@ -630,10 +630,18 @@ export function registerVersionsCommands(program) {
     useCmd.action(async (agentArg, versionArg, options) => {
         try {
             const skipPrompts = options.yes || !isInteractiveTerminal();
-            // Auto-pull ~/.agents/.system if it's a git repo with remote (silent on success)
+            // Auto-pull ~/.agents/.system if it's a git repo tracking the EXPECTED
+            // system remote (silent on success). The system repo ships hooks that run
+            // as shell on tool events, so pulling from a repointed origin would be
+            // remote code execution — tryAutoPullSystemRepo refuses that (PHNX-2957).
             const agentsDir = getAgentsDir();
-            const pullResult = await tryAutoPull(agentsDir);
-            if (pullResult.pulled) {
+            const pullResult = await tryAutoPullSystemRepo(agentsDir);
+            if (pullResult.refused) {
+                console.error(chalk.red(`Refusing to auto-sync ~/.agents/.system: its origin (${pullResult.actualRemote}) is not the expected system repo.`));
+                console.error(chalk.gray('The system repo ships hooks that run on tool events; a fast-forward from an unexpected origin is not applied. ' +
+                    'Re-point it (git -C ~/.agents/.system remote set-url origin <expected>) or set AGENTS_SYSTEM_REPO, then re-run `agents setup --force`.'));
+            }
+            else if (pullResult.pulled) {
                 console.log(chalk.gray('Synced ~/.agents/.system from remote'));
             }
             // Support both "claude 2.0.65" and "claude@2.0.65" formats