@phnx-labs/agents-cli 1.22.58 → 1.22.60

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

@@ -132,6 +132,16 @@ function renderLabelTable(title, rows, warnMs, limit) {
         formatMs(r.maxMs),
         formatRateColumn(r),
     ]), sliced.map((r) => r.p99Ms > warnMs));
+    // Sub-phase break-out (agent.run's `startup` = spawn overhead before the child
+    // runs, PHNX-3468). Indented under the row so a slow boot is visible next to
+    // the total without adding columns that are empty for phaseless labels.
+    for (const r of sliced) {
+        if (!r.phases)
+            continue;
+        for (const [name, ph] of Object.entries(r.phases)) {
+            console.log(chalk.gray(`  └ ${name}: p50 ${formatMs(ph.p50Ms)}  p90 ${formatMs(ph.p90Ms)}  (n=${ph.n})`));
+        }
+    }
 }
 /**
  * Prefer SQLite samples; fall back to the legacy daily JSONL so existing

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-picker.d.ts

@@ -3,6 +3,19 @@ import { fetchPeerPreviewDigest } from '../lib/session/remote-list.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import type { FileChange } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractSkills } from '../lib/session/highlights.js';
+/** A session whose transcript FILE is on another machine: its `filePath` is on
+ * that peer's disk, so the preview can't parse it locally — it fetches the
+ * peer's digest over SSH and shows metadata + a "resume there" note until that
+ * lands. `_remote` is an explicit signal; a peer `machine` plus no readable
+ * local file covers host-dispatch index rows and live-registry rows that were
+ * synthesized outside the fan-out. A locally-readable synced mirror stays
+ * local even when its recorded owner is another machine.
+ *
+ * This is the READ rule and only the read rule. Whether a session may be
+ * RESUMED here is a different question with a different answer — a mirror is
+ * readable but not resumable — and `sessionOwnerDevice`
+ * (lib/session/resume-owner.ts) is the single place that answers it (RUSH-2022). */
+export declare function transcriptOnPeerOf(session: SessionMeta): string | undefined;
 /**
  * Compact checklist tally for list rows and previews (RUSH-2045).
  * Example: `✓6/8 · A5 wiring runner`. Empty string when there is no list.

package/dist/commands/sessions-picker.js

@@ -25,19 +25,28 @@ import { createMemoryCache } from '../lib/memory-cache.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills, harnessTracksBackgroundShells, isBackgroundShellStart, isSubAgentTool, } from '../lib/session/highlights.js';
 import { getSessionPlugins, readSessionPreviewCache, writeSessionPreviewCache, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
-/** A session whose transcript FILE is on another machine (folded in over the
- * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
- * preview can't parse it locally — it fetches the peer's digest over SSH and
- * shows metadata + a "resume there" note until that lands. Keys off `_remote`,
- * not the machine tag, so locally-readable synced mirrors still parse their
- * file normally.
+import { machineId } from '../lib/session/sync/config.js';
+/** A session whose transcript FILE is on another machine: its `filePath` is on
+ * that peer's disk, so the preview can't parse it locally — it fetches the
+ * peer's digest over SSH and shows metadata + a "resume there" note until that
+ * lands. `_remote` is an explicit signal; a peer `machine` plus no readable
+ * local file covers host-dispatch index rows and live-registry rows that were
+ * synthesized outside the fan-out. A locally-readable synced mirror stays
+ * local even when its recorded owner is another machine.
  *
  * This is the READ rule and only the read rule. Whether a session may be
  * RESUMED here is a different question with a different answer — a mirror is
  * readable but not resumable — and `sessionOwnerDevice`
  * (lib/session/resume-owner.ts) is the single place that answers it (RUSH-2022). */
-function transcriptOnPeerOf(session) {
-    return session._remote ? session.machine : undefined;
+export function transcriptOnPeerOf(session) {
+    if (session._remote)
+        return session.machine;
+    if (session.machine
+        && session.machine !== machineId()
+        && (!session.filePath || !fs.existsSync(session.filePath))) {
+        return session.machine;
+    }
+    return undefined;
 }
 /**
  * Compact checklist tally for list rows and previews (RUSH-2045).

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)'));
     }