@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/commands/lease.d.ts

@@ -1,7 +1,7 @@
 /**
- * `agents lease` — manage the disposable cloud boxes used by `agents run --lease`.
+ * `agents devices lease` — manage the disposable cloud boxes used by `agents run --lease`.
  *
- * Today: `agents lease gc`, which stops expired + idle "orphan" boxes that are
+ * Today: `agents devices lease gc`, which stops expired + idle "orphan" boxes that are
  * holding a provider's server quota (the cause of the `server_limit` 403 a new
  * lease hits). Reaping is conservative: only boxes whose lease has expired AND
  * that have been untouched for a safety window are eligible (see `isReapSafe`),
@@ -25,7 +25,7 @@ export declare function boxStatus(box: CrabboxBox): string;
  * freshest box (an untouched `lastTouchedAt` sorts last).
  */
 export declare function reusableBoxes(boxes: CrabboxBox[], nowSecs: number): CrabboxBox[];
-/** One aligned row for the reuse picker / `agents lease list`. */
+/** One aligned row for the reuse picker / `agents devices lease list`. */
 export declare function formatBoxRow(box: CrabboxBox, nowSecs: number): string;
 /** Validate a Hetzner token against the live API. Exported for unit tests (fetch injectable). */
 export declare function validateHetznerToken(token: string, fetchImpl?: typeof fetch): Promise<'valid' | 'invalid' | 'unreachable'>;
@@ -39,4 +39,4 @@ export declare function validateHetznerToken(token: string, fetchImpl?: typeof f
 export declare function runLeaseSetup(opts?: {
     provider?: string;
 }): Promise<boolean>;
-export declare function registerLeaseCommand(program: Command): void;
+export declare function registerLeaseCommand(devicesCommand: Command): void;

package/dist/commands/lease.js

@@ -1,7 +1,7 @@
 /**
- * `agents lease` — manage the disposable cloud boxes used by `agents run --lease`.
+ * `agents devices lease` — manage the disposable cloud boxes used by `agents run --lease`.
  *
- * Today: `agents lease gc`, which stops expired + idle "orphan" boxes that are
+ * Today: `agents devices lease gc`, which stops expired + idle "orphan" boxes that are
  * holding a provider's server quota (the cause of the `server_limit` 403 a new
  * lease hits). Reaping is conservative: only boxes whose lease has expired AND
  * that have been untouched for a safety window are eligible (see `isReapSafe`),
@@ -64,7 +64,7 @@ export function reusableBoxes(boxes, nowSecs) {
         .filter((b) => b.ready && (b.expiresAt === null || b.expiresAt > nowSecs))
         .sort((a, b) => (b.lastTouchedAt ?? 0) - (a.lastTouchedAt ?? 0));
 }
-/** One aligned row for the reuse picker / `agents lease list`. */
+/** One aligned row for the reuse picker / `agents devices lease list`. */
 export function formatBoxRow(box, nowSecs) {
     const slug = box.slug.padEnd(16);
     const cls = (box.class ?? '?').padEnd(10);
@@ -201,8 +201,8 @@ export async function runLeaseSetup(opts = {}) {
         throw e;
     }
 }
-export function registerLeaseCommand(program) {
-    const lease = program
+export function registerLeaseCommand(devicesCommand) {
+    const lease = devicesCommand
         .command('lease')
         .description('Manage the disposable cloud boxes used by `agents run --lease`.');
     lease
@@ -241,7 +241,7 @@ export function registerLeaseCommand(program) {
         console.log(chalk.bold(`Warm boxes (${boxes.length})`));
         for (const b of boxes)
             console.log('  ' + formatBoxRow(b, nowSecs));
-        console.log(chalk.gray('  Reuse: agents run <agent> "…" --box <slug>   ·   Stop: agents lease stop <slug>'));
+        console.log(chalk.gray('  Reuse: agents run <agent> "…" --box <slug>   ·   Stop: agents devices lease stop <slug>'));
     });
     lease
         .command('stop <slug>')

package/dist/commands/login.js

@@ -107,17 +107,4 @@ export function registerLoginCommands(program) {
         clearVaultKey();
         console.log(chalk.green('Logged out. Synced secrets are locked.'));
     });
-    program
-        .command('whoami')
-        .description('Show synced-secrets login status')
-        .action(() => {
-        const session = getVaultSession();
-        if (!session.loggedIn) {
-            console.log(chalk.yellow('Not logged in.'));
-            console.log(chalk.gray(`File: ${vaultPath()}${vaultExists() ? '' : ' (not created)'}`));
-            return;
-        }
-        console.log(chalk.green(`Logged in (${formatRemaining(session.expiresAt)} remaining).`));
-        console.log(chalk.gray(`File: ${vaultPath()}`));
-    });
 }

package/dist/commands/logs.d.ts

@@ -17,8 +17,8 @@
  * id, `--host`/`--agent`/`--version` filter a merged candidate list; one match is
  * shown, several open the fuzzy picker (or, non-TTY, print the list).
  *
- * Additive: `agents hosts logs` and `agents sessions tail` are unchanged and share
- * the same underlying helpers (showHostTaskLog / streamSessionTail).
+ * Additive: `agents devices ps`/`stop` and `agents sessions tail` are unchanged and
+ * share the same underlying helpers (showHostTaskLog / streamSessionTail).
  */
 import type { Command } from 'commander';
 /** Register the top-level `agents logs` command. */

package/dist/commands/logs.js

@@ -17,8 +17,8 @@
  * id, `--host`/`--agent`/`--version` filter a merged candidate list; one match is
  * shown, several open the fuzzy picker (or, non-TTY, print the list).
  *
- * Additive: `agents hosts logs` and `agents sessions tail` are unchanged and share
- * the same underlying helpers (showHostTaskLog / streamSessionTail).
+ * Additive: `agents devices ps`/`stop` and `agents sessions tail` are unchanged and
+ * share the same underlying helpers (showHostTaskLog / streamSessionTail).
  */
 import chalk from 'chalk';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';

package/dist/commands/mcp.js

@@ -564,9 +564,11 @@ Examples:
         }
         console.log();
     });
+    // Deprecated: superseded by `agents sync --mcp`. Kept as a warned, functional
+    // alias so old muscle-memory and scripts don't break.
     mcpCmd
-        .command('register [name]')
-        .description('Apply MCP servers from manifest to agent config files')
+        .command('register [name]', { hidden: true })
+        .description('Deprecated — use `agents sync --mcp` instead.')
         .option('-a, --agents <list>', 'Override manifest targets: claude, codex@0.116.0')
         .option('-y, --yes', 'Auto-install any missing agent versions without prompting')
         .addHelpText('after', `
@@ -581,6 +583,9 @@ Examples:
   agents mcp register --agents codex@0.116.0
 `)
         .action(async (name, options) => {
+        console.warn(chalk.yellow('`agents mcp register` is deprecated — use `agents sync --mcp` instead:'));
+        console.warn(chalk.gray('  all servers:     agents sync --mcp'));
+        console.warn(chalk.gray('  specific server: agents sync --mcp <name>'));
         const localPath = getUserAgentsDir();
         const manifest = readManifest(localPath);
         if (!manifest?.mcp) {

package/dist/commands/memory.js

@@ -111,11 +111,16 @@ export function registerMemoryCommands(program) {
         console.log(chalk.dim(`# ${fact.name}  [${fact.layer}]  ${fact.path}`));
         console.log(fs.readFileSync(fact.path, 'utf-8'));
     });
+    // Deprecated: superseded by `agents sync --memory`. Kept as a warned, functional
+    // alias so old muscle-memory and scripts don't break.
     memoryCmd
-        .command('sync [agent]')
-        .description('Copy canonical memory into capable agent version homes')
+        .command('sync [agent]', { hidden: true })
+        .description('Deprecated — use `agents sync --memory` instead.')
         .option('-a, --agent <agent>', 'Limit to one agent (or agent@version)')
         .action(async (agentArg, options) => {
+        console.warn(chalk.yellow('`agents memory sync` is deprecated — use `agents sync --memory` instead:'));
+        console.warn(chalk.gray('  all agents:  agents sync --memory'));
+        console.warn(chalk.gray('  one agent:   agents sync --memory <agent>'));
         ensureUserMemoryDir();
         const input = agentArg || options.agent;
         if (input) {

package/dist/commands/message.d.ts

@@ -12,7 +12,7 @@
  * written on the host that actually owns the agent. A caller who doesn't already
  * know the host (a detached `agents run --device <h> --no-follow` dispatch) is
  * still resolved automatically: a `target` matching no local/cloud session falls
- * through to the `~/.agents/.cache/hosts/` records `agents hosts ps` reads
+ * through to the `~/.agents/.cache/hosts/` records `agents devices ps` reads
  * (RUSH-2366 follow-up — see decideHostTaskRoute in lib/mailbox-target.ts), and
  * the message is rerouted there.
  *

package/dist/commands/message.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { spawn } from 'child_process';
 import { die } from '../lib/format.js';
 import { parseDuration } from '../lib/hooks/cache.js';
-import { getActiveSessions } from '../lib/session/active.js';
+import { getActiveSessions, isSessionIdLiveOnProcessTable } from '../lib/session/active.js';
 import { getTaskById, updateTaskStatus } from '../lib/cloud/store.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { mailboxDir, enqueue } from '../lib/mailbox.js';
@@ -119,7 +119,7 @@ async function deliverViaResume(route, mailboxId) {
  * dispatch (RUSH-2366 follow-up). `getActiveSessions()` never sees these: the
  * live process is on the dispatch's host, not this machine, so the local
  * session resolver in `resolveMessageTarget` reports "no running agent" even
- * while `agents hosts ps` shows the same dispatch running with a live remote
+ * while `agents devices ps` shows the same dispatch running with a live remote
  * pid — the only recovery was kill-and-redispatch, losing all context.
  *
  * Re-spawns `agents message <remoteRef> <text> --host <host>` through
@@ -251,11 +251,42 @@ export function registerMessageCommand(program) {
                 return;
             }
             case 'none': {
+                // RUSH-2384: a live local process can still advertise `--session-id
+                // <target>` in its argv when getActiveSessions lost the row (empty
+                // by-pid registry, teams status flap, fold into a parent). Mailbox
+                // delivery only needs the id — prove liveness from the process table
+                // before giving up, so a mid-run agent is never unreachable while
+                // its pid is alive.
+                if (await isSessionIdLiveOnProcessTable(target)) {
+                    try {
+                        const block = findOpenBlockForMailbox(target);
+                        const route = resolveAnswerRoute({
+                            mailboxId: target,
+                            answer: text,
+                            block,
+                            session: null,
+                        });
+                        if (route.kind === 'refuse')
+                            die(route.reason);
+                        claimBlockAnswer(block, opts);
+                        if (route.kind === 'mailbox') {
+                            await deliverViaMailbox(target, text, block, { from: opts.from, ttlSeconds });
+                            return;
+                        }
+                        die(`Live process carries --session-id ${target} but needs a ${route.kind} rail ` +
+                            `that is unavailable without an active-session row. Retry after the session ` +
+                            `reappears in \`agents sessions --active\`, or inject into its terminal directly.`);
+                    }
+                    catch (err) {
+                        die(err.message);
+                    }
+                    return;
+                }
                 // Not a local/cloud session — check whether it's a detached
                 // `--device ... --no-follow` dispatch, which `getActiveSessions()`
                 // never sees (its live process is on another host). Same records
-                // `agents hosts ps` reads, so the two commands never disagree.
-                // Heal first, exactly as `hosts stop`/`hosts ps` do: a detached
+                // `agents devices ps` reads, so the two commands never disagree.
+                // Heal first, exactly as `agents devices stop`/`agents devices ps` do: a detached
                 // dispatch record never self-updates, so a finished run is still
                 // stamped `status:'running'` on disk. Without this we'd route a dead
                 // task through an SSH reroute that can only fail, instead of
@@ -269,9 +300,9 @@ export function registerMessageCommand(program) {
                 if (hostRoute.kind === 'finished') {
                     die(`Task '${target}' on host '${hostRoute.host}' already ${hostRoute.status}` +
                         (hostRoute.exitCode !== undefined ? ` (exit ${hostRoute.exitCode})` : '') +
-                        `. Nothing to message. View its output: \`agents hosts logs ${target}\`.`);
+                        `. Nothing to message. View its output: \`agents logs ${target}\`.`);
                 }
-                die(`No running agent or cloud task matches "${target}". List targets with \`agents sessions --active\` or \`agents hosts ps\`.`);
+                die(`No running agent or cloud task matches "${target}". List targets with \`agents sessions --active\` or \`agents devices ps\`.`);
             }
         }
     });

package/dist/commands/models.js

@@ -77,6 +77,7 @@ export function registerModelsCommand(program) {
     });
     // Override subcommands. These WRITE agents.yaml so the user never hand-edits it;
     // resolution is exact `<agent>@<version>` over `<agent>` over the auto guess.
+    const tierDeprecation = chalk.yellow('Deprecation: `agents models tier` is replaced by `agents config set run.<agent@version>.tier.<tier>`.');
     const tier = models
         .command('tier')
         .description('Override which model a cost tier resolves to (per harness, or per agent@version).');
@@ -85,6 +86,7 @@ export function registerModelsCommand(program) {
         .description('Pin a tier to a model. selector: <agent> or <agent>@<version> (e.g. kimi, kimi@0.19.2).')
         .action((selector, tierName, model) => {
         try {
+            console.warn(tierDeprecation);
             const entry = setTierOverride(selector, tierName, model);
             console.log(chalk.green(`✓ ${entry.selector}  ${chalk.cyan(tierName.toLowerCase())} → ${chalk.bold(model)}`));
         }
@@ -98,6 +100,7 @@ export function registerModelsCommand(program) {
         .description('Clear one tier (or all tiers) back to the auto guess.')
         .action((selector, tierName) => {
         try {
+            console.warn(tierDeprecation);
             const changed = clearTierOverride(selector, tierName);
             console.log(changed ? chalk.green(`✓ cleared ${selector}${tierName ? ` ${tierName}` : ''}`) : chalk.gray('nothing to clear'));
         }
@@ -110,6 +113,7 @@ export function registerModelsCommand(program) {
         .command('list')
         .description('List all configured tier overrides.')
         .action(() => {
+        console.warn(tierDeprecation);
         const entries = listTierOverrides();
         if (entries.length === 0) {
             console.log(chalk.gray('No tier overrides — every tier uses the auto guess. Set one with `agents models tier set`.'));

package/dist/commands/monitors.d.ts

@@ -8,5 +8,4 @@
  * source instead of a clock.
  */
 import type { Command } from 'commander';
-/** Register the `agents monitors` command tree. */
 export declare function registerMonitorsCommands(program: Command): void;

package/dist/commands/monitors.js

@@ -12,9 +12,12 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, } from '../lib/daemon.js';
-import { listMonitors, readMonitor, writeMonitor, deleteMonitor, setMonitorEnabled, getMonitorPath, validateMonitor, monitorRunsOnThisDevice, } from '../lib/monitors/config.js';
-import { evaluateMonitorOnce } from '../lib/monitors/engine.js';
-import { listFires, readState } from '../lib/monitors/state.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 { formatRelativeTime } from '../lib/session/relative-time.js';
+import { evaluateMonitorOnce, POLL_SOURCE_TYPES } from '../lib/monitors/engine.js';
+import { listFires, readState, readLiveness } from '../lib/monitors/state.js';
 import { listRuns, getLatestRun, getRunDir } from '../lib/routines.js';
 import { getMonitorsDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
@@ -72,6 +75,54 @@ function ownerLabel(monitor) {
         return monitor.devices.join(',');
     return 'all';
 }
+/** A monitor's evaluation cadence in ms (falls back to the engine default). */
+function monitorIntervalMs(monitor) {
+    if (monitor.source.interval)
+        return parseInterval(monitor.source.interval) ?? 60_000;
+    return 60_000;
+}
+/**
+ * True when an enabled, locally-owned monitor's last poll is far enough past its
+ * interval that the engine has plainly stopped checking it (dead engine, swallowed
+ * start failure, never picked up). Tolerates a few missed ticks before flagging.
+ */
+function isStalled(monitor, liveness) {
+    if (!monitor.enabled || !monitorRunsOnThisDevice(monitor))
+        return false;
+    if (!liveness)
+        return false; // "never polled" is its own state, handled separately
+    const staleAfter = Math.max(monitorIntervalMs(monitor) * 3, 90_000);
+    return Date.now() - new Date(liveness.lastCheckedAt).getTime() > staleAfter;
+}
+/**
+ * The human liveness line for a monitor. This is the RUSH-2485 fix: it makes
+ * "the engine has never touched this" (`never polled`) visibly distinct from
+ * "polling steadily, condition just isn't matching" (`checked Nx`), from a real
+ * fire, and from a stalled engine.
+ */
+function livenessLabel(monitor, state, liveness) {
+    const here = monitorRunsOnThisDevice(monitor);
+    if (!monitor.enabled)
+        return chalk.gray('paused');
+    if (!here) {
+        // Not owned by this box — this daemon never checks it, so there's no local
+        // liveness to report; fall back to fire history if the owner synced it.
+        return state?.lastFiredAt ? chalk.gray(`fired ${formatRelativeTime(state.lastFiredAt)}`) : chalk.gray('owned elsewhere');
+    }
+    if (!liveness)
+        return chalk.yellow('never polled');
+    if (isStalled(monitor, liveness)) {
+        return chalk.red(`STALLED — last poll ${formatRelativeTime(liveness.lastCheckedAt)}`);
+    }
+    const checkedAgo = formatRelativeTime(liveness.lastCheckedAt);
+    if (liveness.lastError) {
+        return chalk.red(`checked ${liveness.checkCount}x · error: ${liveness.lastError.replace(/\s+/g, ' ').slice(0, 60)}`);
+    }
+    if (state?.lastFiredAt) {
+        return chalk.green(`fired ${formatRelativeTime(state.lastFiredAt)}`) + chalk.gray(` · checked ${liveness.checkCount}x`);
+    }
+    return chalk.gray(`checked ${liveness.checkCount}x · last ${checkedAgo} · no match yet`);
+}
 /** Start or reload the background daemon so a newly-added monitor is watched. */
 function ensureDaemonRunning() {
     if (isDaemonRunning()) {
@@ -88,6 +139,37 @@ function ensureDaemonRunning() {
         stderrLine(chalk.yellow('Could not start the daemon. Start it manually with: agents routines start'));
     }
 }
+/**
+ * Assert the postcondition of `add`: the engine actually picked the monitor up.
+ * Config acceptance is not enough — RUSH-2485 was a monitor that added cleanly,
+ * listed as `on`, and never polled. A poll-model monitor owned by and enabled on
+ * this box should show a liveness heartbeat within a couple of engine ticks; wait
+ * for it and report the real outcome instead of reporting success on write. A
+ * miss is a warning, not a hard failure — a freshly-started daemon may still be
+ * booting — but it is surfaced so a dead engine can never masquerade as healthy.
+ */
+async function assertEnginePickup(monitor) {
+    const pollSource = POLL_SOURCE_TYPES.has(monitor.source.type);
+    if (!monitor.enabled || !monitorRunsOnThisDevice(monitor) || !pollSource)
+        return; // nothing to assert here
+    const before = readLiveness(monitor.name);
+    const baseline = before?.checkCount ?? 0;
+    const deadline = Date.now() + 12_000; // a couple of 5s ticks, plus daemon-boot slack
+    stderrLine(chalk.gray('  waiting for the engine to poll it…'));
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 500));
+        const now = readLiveness(monitor.name);
+        if (now && now.checkCount > baseline) {
+            console.log(chalk.green(`  engine picked it up — first poll ${formatRelativeTime(now.lastCheckedAt)}`));
+            if (now.lastError) {
+                stderrLine(chalk.yellow(`  note: that poll errored — ${now.lastError.replace(/\s+/g, ' ').slice(0, 80)}`));
+            }
+            return;
+        }
+    }
+    stderrLine(chalk.yellow(`  the engine has not polled '${monitor.name}' yet.`));
+    stderrLine(chalk.yellow(`  confirm the daemon is running (agents routines status) and re-check with: agents monitors view ${monitor.name}`));
+}
 /** Validate a single device name against the registered fleet; exit on miss. */
 async function validateDevice(name) {
     const normalized = normalizeHost(name.trim());
@@ -242,6 +324,58 @@ async function pickMonitor(message, alternatives = []) {
     }
 }
 /** Register the `agents monitors` command tree. */
+/**
+ * Refuse a monitor that duplicates one already in play — same NAME (which
+ * `writeMonitor` would silently overwrite) or same BEHAVIOR under any name, on
+ * this box or any other. Exits the process on a refusal.
+ *
+ * Shared by BOTH `add` paths. The file path (`add ./watcher.yml`) returns early
+ * and used to skip the guard entirely, so a duplicate could be walked straight
+ * in through a YAML file — the one input an agent is most likely to generate.
+ */
+async function guardAgainstDuplicateMonitor(config, force) {
+    if (force)
+        return;
+    const existing = listMonitors();
+    const sameName = existing.find((m) => m.name === config.name);
+    if (sameName) {
+        stderrLine(chalk.red(`Monitor '${config.name}' already exists — adding would overwrite it.`));
+        stderrLine(chalk.gray(`  Inspect it:   agents monitors view ${config.name}`));
+        stderrLine(chalk.gray(`  Replace it:   agents monitors add ${config.name} ... --force`));
+        process.exit(1);
+    }
+    const duplicate = findDuplicateMonitor(config, existing);
+    if (duplicate) {
+        stderrLine(chalk.red(`Monitor '${duplicate}' already watches this exact source and fires the same action.`));
+        stderrLine(chalk.gray('  Adding it again would fire the same trigger twice.'));
+        stderrLine(chalk.gray(`  Inspect it:   agents monitors view ${duplicate}`));
+        stderrLine(chalk.gray(`  Add anyway:   agents monitors add ${config.name} ... --force`));
+        process.exit(1);
+    }
+    // The case a local check cannot see: another agent, on another box, already
+    // watching this same work item with these same arguments. One work item, two
+    // triggers. Identity is the arguments, so the claim has to be fleet-wide —
+    // different arguments (another PR) are not a clash and still pass.
+    if (process.env[NO_MONITOR_FANOUT_ENV])
+        return;
+    const fleet = await gatherFleetMonitors();
+    const mine = monitorFingerprint(config);
+    const clash = fleet.monitors.find((r) => monitorFingerprint(r.monitor) === mine);
+    if (clash) {
+        stderrLine(chalk.red(`Monitor '${clash.monitor.name}' on ${chalk.bold(clash.machine)} already watches this exact source and fires the same action.`));
+        stderrLine(chalk.gray('  Two boxes watching one work item is a double trigger.'));
+        stderrLine(chalk.gray(`  Inspect it:   agents ssh ${clash.machine} 'agents monitors view ${clash.monitor.name}'`));
+        stderrLine(chalk.gray(`  Add anyway:   agents monitors add ${config.name} ... --force`));
+        process.exit(1);
+    }
+    // Never treat "could not ask" as "no duplicate".
+    if (fleet.discoveryFailed) {
+        stderrLine(chalk.yellow('  Note: could not reach the device registry — the fleet was not checked for duplicates.'));
+    }
+    else if (fleet.skipped.length > 0) {
+        stderrLine(chalk.yellow(`  Note: could not check ${fleet.skipped.join(', ')} — a duplicate there would not have been caught.`));
+    }
+}
 export function registerMonitorsCommands(program) {
     const monitorsCmd = program
         .command('monitors')
@@ -315,11 +449,12 @@ export function registerMonitorsCommands(program) {
         .option('--notify [channel]', 'Notify the owner (notify.owner); [channel] overrides the owner channel')
         .option('--webhook-out <url>', 'POST the event to this URL')
         // PLACEMENT / hygiene
-        .option('--device <name>', 'OWNER (not body placement) — the single machine that evaluates + fires (exactly-once). See docs/00-concepts.md#placement.')
+        .option('--device <name>', 'OWNER (not body placement) — the single machine that evaluates + fires (exactly-once). See docs/concepts.md#placement.')
         .option('--devices <list>', 'Allowlist (comma-separated): each device fires independently')
         .option('--run-on <host>', 'BODY placement — execute the ACTION on this machine over SSH (same idea as run --where device:<host>)')
         .option('--rate-limit <spec>', 'Auto-pause if it fires more than N/<interval> (e.g. 5/1m)')
         .option('--disabled', 'Create the monitor paused (enable later with resume)')
+        .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);
@@ -342,9 +477,11 @@ export function registerMonitorsCommands(program) {
                     stderrLine(chalk.red(`  - ${err}`));
                 process.exit(1);
             }
+            await guardAgainstDuplicateMonitor(config, options.force === true);
             writeMonitor(config);
             console.log(chalk.green(`Monitor '${name}' added`));
             ensureDaemonRunning();
+            await assertEnginePickup(config);
             return;
         }
         if (!nameOrPath) {
@@ -413,10 +550,12 @@ export function registerMonitorsCommands(program) {
         if (condition.mode === 'match' && condition.match && /^(issued|success|ok|pass(ed)?|done|ready)$/i.test(condition.match)) {
             stderrLine(chalk.yellow(`  Note: --match '${condition.match}' only fires on success — it stays silent if the source breaks or never matches.`));
         }
+        await guardAgainstDuplicateMonitor(config, options.force === true);
         writeMonitor(config);
         console.log(chalk.green(`Monitor '${nameOrPath}' added`));
         console.log(chalk.gray(`  ${sourceLabel(source)} → [${condition.mode}] → ${actionLabel(action)} · owner: ${ownerLabel(config)}`));
         ensureDaemonRunning();
+        await assertEnginePickup(config);
     });
     // ─── list ────────────────────────────────────────────────────────────────────
     monitorsCmd
@@ -428,16 +567,28 @@ export function registerMonitorsCommands(program) {
         if (options.json) {
             const payload = monitors.map((m) => {
                 const state = readState(m.name);
+                const liveness = readLiveness(m.name);
                 return {
                     name: m.name,
                     enabled: m.enabled,
                     source: m.source,
                     condition: m.condition,
-                    action: { type: m.action.type },
+                    // Full action, not just `type`: the cross-machine duplicate guard
+                    // fingerprints source+condition+action, so a type-only action made
+                    // every `--run` monitor unmatchable and the fleet check inert for
+                    // exactly the case it exists for. `source` already ships whole.
+                    action: m.action,
                     owner: ownerLabel(m),
                     runsHere: monitorRunsOnThisDevice(m),
                     lastSeenAt: state?.lastSeenAt ?? null,
                     lastFiredAt: state?.lastFiredAt ?? null,
+                    // Liveness heartbeat (RUSH-2485): distinguishes never-polled from
+                    // polling-not-matching from a stalled engine.
+                    lastCheckedAt: liveness?.lastCheckedAt ?? null,
+                    checkCount: liveness?.checkCount ?? 0,
+                    lastError: liveness?.lastError ?? null,
+                    consecutiveErrors: liveness?.consecutiveErrors ?? 0,
+                    stalled: isStalled(m, liveness),
                 };
             });
             stdoutJson(payload);
@@ -451,12 +602,12 @@ export function registerMonitorsCommands(program) {
         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));
-            const lastFired = state?.lastFiredAt ? `fired ${state.lastFiredAt}` : chalk.gray('never fired');
             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}`)}  ${chalk.gray(lastFired)}`);
+            console.log(`  ${' '.repeat(22)}     ${chalk.gray(`[${m.condition.mode}]`)} → ${actionLabel(m.action)}  ${chalk.gray(`owner: ${owner}`)}  ${livenessLabel(m, state, liveness)}`);
         }
         console.log();
     });
@@ -477,6 +628,7 @@ export function registerMonitorsCommands(program) {
             process.exit(1);
         }
         const state = readState(name);
+        const liveness = readLiveness(name);
         const recentFires = listFires(name).slice(-5);
         if (options.json) {
             stdoutJson({
@@ -485,14 +637,30 @@ export function registerMonitorsCommands(program) {
                 owner: ownerLabel(monitor),
                 runsHere: monitorRunsOnThisDevice(monitor),
                 state,
+                liveness,
+                stalled: isStalled(monitor, liveness),
                 recentFires,
             });
             return;
         }
         console.log(chalk.bold(`Monitor: ${name}\n`));
         console.log(yaml.stringify(monitor));
+        // Liveness first (RUSH-2485): the heartbeat is the answer to "is this thing
+        // actually running?" — it renders even when the monitor has never fired.
+        console.log(chalk.bold('Liveness'));
+        console.log(`  ${livenessLabel(monitor, state, liveness)}`);
+        if (liveness) {
+            console.log(chalk.gray(`  last checked: ${liveness.lastCheckedAt} (${formatRelativeTime(liveness.lastCheckedAt)})`));
+            console.log(chalk.gray(`  checks:       ${liveness.checkCount}`));
+            if (liveness.lastError) {
+                console.log(chalk.red(`  last error:   ${liveness.lastError.replace(/\s+/g, ' ').slice(0, 200)} (${liveness.consecutiveErrors} in a row)`));
+            }
+        }
+        else if (monitor.enabled && monitorRunsOnThisDevice(monitor)) {
+            console.log(chalk.yellow('  The engine has not polled this monitor yet. If this persists, the daemon may not have picked it up — check: agents routines status'));
+        }
         if (state) {
-            console.log(chalk.bold('Watched state'));
+            console.log(chalk.bold('\nWatched state'));
             console.log(chalk.gray(`  last seen:  ${state.lastSeenAt}`));
             if (state.lastFiredAt)
                 console.log(chalk.gray(`  last fired: ${state.lastFiredAt}`));
@@ -566,19 +734,29 @@ export function registerMonitorsCommands(program) {
             if (!name)
                 return;
         }
+        // getMonitorPath is user-layer only: edits always land in the user dir,
+        // never the pull-only system mirror. Editing a system built-in (no user
+        // copy yet) materializes one, prefilled with the built-in's own config.
         let monitorPath = getMonitorPath(name);
         if (!monitorPath) {
             const dir = getMonitorsDir();
             fs.mkdirSync(dir, { recursive: true });
             monitorPath = safeJoin(dir, `${name}.yml`);
-            const template = yaml.stringify({
-                name,
-                source: { type: 'poll', command: 'echo hello', interval: '1m' },
-                condition: { mode: 'on-change' },
-                action: { type: 'notify' },
-            });
-            fs.writeFileSync(monitorPath, template, 'utf-8');
-            console.log(chalk.gray(`Created new monitor file: ${monitorPath}`));
+            const builtIn = readMonitor(name);
+            if (builtIn) {
+                fs.writeFileSync(monitorPath, yaml.stringify(builtIn), 'utf-8');
+                console.log(chalk.gray(`Editing a copy of built-in monitor '${name}' in your user dir: ${monitorPath}`));
+            }
+            else {
+                const template = yaml.stringify({
+                    name,
+                    source: { type: 'poll', command: 'echo hello', interval: '1m' },
+                    condition: { mode: 'on-change' },
+                    action: { type: 'notify' },
+                });
+                fs.writeFileSync(monitorPath, template, 'utf-8');
+                console.log(chalk.gray(`Created new monitor file: ${monitorPath}`));
+            }
         }
         const editor = process.env.EDITOR || process.env.VISUAL || (IS_WINDOWS ? 'notepad' : 'vi');
         const parts = editor.split(/\s+/).filter(Boolean);
@@ -772,6 +950,11 @@ export function registerMonitorsCommands(program) {
                 stderrLine(chalk.gray('Daemon reloaded'));
             }
         }
+        else if (readMonitor(name)) {
+            // Resolvable but not in the user dir: a pull-only system built-in.
+            stderrLine(chalk.red(`Monitor '${name}' is a built-in and can't be removed; pause it with: agents monitors pause ${name}`));
+            process.exit(1);
+        }
         else {
             stderrLine(chalk.red(`Monitor '${name}' not found`));
             process.exit(1);

package/dist/commands/open.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `agents open` — resolve an `agents://` deep link, and manage the OS handler
+ * that routes such links here.
+ *
+ *   agents open agents://session/<id>     resume that session in a terminal
+ *   agents open register                  register the agents:// scheme with the OS
+ *   agents open unregister                remove the handler
+ *   agents open status                    report whether the handler is registered
+ *
+ * A rendered artifact (plan/report) embeds `agents://session/<id>` in its
+ * provenance line; clicking it hands the URL to the OS, which invokes
+ * `agents open <url>`. This command parses it (lib/deeplink/url.ts) and hands the
+ * session id to the existing resume dispatcher, which resolves the owning host
+ * and opens the terminal with the cursor in the input bar. The id is passed as
+ * argv, never interpolated into a shell.
+ */
+import type { Command } from 'commander';
+export declare function registerOpenCommand(program: Command): void;