@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/monitors/config.d.ts

@@ -1,18 +1,5 @@
-/**
- * Monitor (event-triggered watcher) configuration, validation, and CRUD.
- *
- * A monitor is a routine whose trigger is a *watched source* instead of a
- * *clock*. It watches a SOURCE, detects a CONDITION change, and fires an ACTION —
- * reusing the routines daemon, dispatch engine, device model, and notify path.
- *
- * Monitors are YAML files in ~/.agents/monitors/. This module owns the on-disk
- * shape (mirroring lib/routines.ts read/write helpers), hand-rolled validation
- * (mirroring validateJob — no zod), and the device-owner eligibility gate.
- */
 import type { AgentId } from '../types.js';
-/** Source types a monitor can watch. */
 export type MonitorSourceType = 'command' | 'poll' | 'poll-http' | 'webhook' | 'ws' | 'file' | 'device';
-/** Webhook source filters — reuse the github/linear matcher shape from triggers/webhook.ts. */
 export interface MonitorWebhookSource {
     source: 'github' | 'linear';
     event: string;
@@ -22,243 +9,69 @@ export interface MonitorWebhookSource {
     teamKey?: string;
     label?: string;
 }
-/**
- * What a monitor watches. Exactly one source-payload field is populated, keyed by
- * `type`: `command`/`interval` for command/poll, `url`/`interval` for poll-http,
- * `wsUrl` for ws, `path` for file, `device` for device, `webhook` for webhook.
- */
 export interface MonitorSource {
     type: MonitorSourceType;
-    /** Shell command whose stdout is the observation (command, poll). */
     command?: string;
-    /** Re-evaluation interval (poll, poll-http; optional for command/file/device). e.g. `30s`, `15m`, `8h`. */
     interval?: string;
-    /** URL to GET (poll-http). */
     url?: string;
-    /** WebSocket URL; each frame is an observation (ws). */
     wsUrl?: string;
-    /** File or directory to watch (file). */
     path?: string;
-    /** A registered fleet device whose health/reachability is the observation (device). */
     device?: string;
-    /** Webhook trigger filters (webhook). */
     webhook?: MonitorWebhookSource;
 }
-/** How an observation becomes a fire. */
 export type MonitorConditionMode = 'on-change' | 'match' | 'every';
 export interface MonitorCondition {
     mode: MonitorConditionMode;
-    /** Regex (required for `match` mode) — fire when the observation matches. */
     match?: string;
-    /**
-     * What counts as "the same event" for de-duplication. When set, the dedupe
-     * signature is the first regex match of this expression against the
-     * observation (so re-observing the same token is silent); when omitted, the
-     * full observation is the signature.
-     */
     dedupeKey?: string;
 }
-/** Action types a monitor can fire. */
 export type MonitorActionType = 'run' | 'routine' | 'notify' | 'webhook-out';
-/**
- * What a monitor does on a fire. Shares the run-shaped fields (agent, prompt,
- * mode, effort, timeout) conceptually with JobConfig (lib/routines.ts) so
- * dispatch reuses the routines path (executeJobDetached). The fired event is
- * injected into the prompt as `{event}`.
- */
 export interface ActionConfig {
     type: MonitorActionType;
-    /** run: which agent to spawn — a native harness id or a custom harness name (agents harness list). */
     agent?: AgentId | (string & {});
-    /** run: the prompt; `{event}` is replaced with the fired event summary. */
     prompt?: string;
-    /** run: execution mode (shared with routines). */
     mode?: 'plan' | 'edit' | 'auto' | 'skip' | 'full';
-    /** run: reasoning effort (shared with routines). */
     effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
-    /** run: kill the action if it runs longer than this (e.g. `10m`). */
     timeout?: string;
-    /** routine: name of an existing routine to fire. */
     routine?: string;
-    /** notify: override the owner channel (defaults to `notify.owner.channel`). */
     notifyChannel?: string;
-    /** webhook-out: URL to POST the event to. */
     url?: string;
-    /**
-     * Shell command that must exit 0 after a `run`/`routine` action settles.
-     * Asserts the stated effect actually happened (PHNX-2842) — e.g.
-     * `gh pr view 1682 --json state --jq .state | grep -qx MERGED`. `{event}` is
-     * replaced with the fired event summary, same as the prompt. Evaluated once
-     * the dispatched run is no longer `running`; a failed check makes the fire
-     * `ok: false` with effect `none` (`postcondition not met`), not a healthy
-     * `completed`. Notify/webhook-out already have a synchronous ok and refuse
-     * this field.
-     */
     postcondition?: string;
 }
-/** Full monitor configuration (persisted as YAML in ~/.agents/monitors/). */
 export interface MonitorConfig {
     name: string;
     enabled: boolean;
     source: MonitorSource;
     condition: MonitorCondition;
     action: ActionConfig;
-    /**
-     * Pin-to-one OWNER device — the single machine whose daemon evaluates the
-     * source and fires. Exactly-once for v1 (no distributed lock). When set, only
-     * that machine is eligible; everywhere else the monitor is inert.
-     */
     device?: string;
-    /**
-     * Fleet allowlist (advanced) — each listed device evaluates and fires
-     * independently, like routines' `devices`. Mutually exclusive with `device`.
-     */
     devices?: string[];
-    /**
-     * Does this monitor's SOURCE poll a fleet-shared queue (a PR list, a ticket
-     * tracker, the feed, a sync bucket) rather than the firing box's own state
-     * (its repos, sessions, caches)?
-     *
-     * This is the SING-9 placement switch for an UNPINNED monitor (no `device` /
-     * `devices`). A shared-input source has no per-box input, so every daemon
-     * firing it independently is a multi-executor race on shared state — the exact
-     * double-fire bug class. So an unpinned shared-input monitor fires only on the
-     * single owner (`interactive.host`, else the sole box on a one-device fleet),
-     * never on every daemon.
-     *
-     * Defaults differ by layer so the SAFE side is the default for each:
-     * - a **system built-in** (`scope: 'system'`) is treated as shared-input
-     *   unless it sets `sharedInput: false`, so a built-in shipped with no pin
-     *   can never fan out across the fleet — a device-local built-in opts back
-     *   into fleet-wide firing with `sharedInput: false`;
-     * - a **user monitor** keeps its historical fleet-wide default and only
-     *   becomes owner-restricted when it explicitly sets `sharedInput: true`.
-     *
-     * An explicit `device` / `devices` pin always wins and makes this moot — the
-     * author has already chosen the executor(s).
-     */
     sharedInput?: boolean;
-    /** Execute the ACTION on this machine over SSH (placement), distinct from the owner that fires it. */
     runOn?: string;
-    /**
-     * Working directory for a `run` action, in the routines-portable form
-     * (`~/…`, or relative to the execution target's home). Optional: a monitor
-     * watches a source rather than owning a project, so `dispatchAction` defaults
-     * it to the target's home (`~`) when unset.
-     *
-     * Without this, every `run` action was blocked at readiness with
-     * `execution_context_missing` — `resolveJobExecutionContext` refuses an
-     * agent job carrying neither `project` nor `cwd` (`lib/routine-context.ts`),
-     * and a monitor had no field with which to supply one (RUSH-2681).
-     */
     cwd?: string;
-    /** Firehose guard: auto-pause the monitor if it fires more than `max` times per `per`. */
     rateLimit?: {
         max: number;
         per: string;
     };
-    /** User-defined prompt variables (expanded like routines' variables). */
     variables?: Record<string, string>;
-    /** Pin the agent version for `run` actions (omit to use the run strategy). */
     version?: string;
-    /**
-     * Which layer this monitor was read from — `user` (~/.agents/monitors/) or
-     * `system` (the npm-shipped built-in mirror ~/.agents/.system/monitors/).
-     * A DERIVED, runtime-only annotation stamped by `readMonitorFile`, never a
-     * persisted YAML field: it tags a built-in in `list`/`view` (mirroring
-     * routines' `(built-in)` label) and `writeMonitor` strips it before writing,
-     * so materializing a user copy of a built-in always lands as `user`.
-     */
     scope?: 'user' | 'system';
 }
-/**
- * A fired event. `summary` is injected into the action prompt as `{event}`;
- * `payload` carries the structured observation for `webhook-out` and inspection.
- */
 export interface MonitorEvent {
     monitorName: string;
     firedAt: string;
     summary: string;
     payload: Record<string, unknown>;
 }
-/**
- * Parse a human interval string (e.g. `30s`, `15m`, `8h`, `1d`, `1h30m`) into
- * milliseconds. Unlike routines' parseTimeout, seconds are supported (polls tick
- * in seconds). Returns null on empty/unparseable/zero input.
- */
 export declare function parseInterval(interval: string): number | null;
-/**
- * True when an UNPINNED monitor must be placed on a single owner rather than
- * fired by every daemon — the SING-9 guard against a shared-queue double-fire.
- *
- * A `device` / `devices` pin is an explicit executor choice, so it is never
- * owner-overridden (returns false here). For an unpinned monitor the default is
- * layer-specific, SAFE side first: a **system built-in** is treated as
- * shared-input unless it opts out with `sharedInput: false`; a **user monitor**
- * keeps its fleet-wide default and only opts IN with `sharedInput: true`.
- */
 export declare function requiresSingleOwner(config: Pick<MonitorConfig, 'device' | 'devices' | 'scope' | 'sharedInput'>): boolean;
-/**
- * The single fleet box that owns unpinned shared-input monitors — PURE, so the
- * placement rule is unit-testable without a live tailnet. Priority:
- *
- * 1. the configured `interactive.host` (the box the operator sits at);
- * 2. else, on a fleet with no OTHER registered device, this box — a single-box
- *    install has no peer to race, so the built-in still fires here;
- * 3. else `undefined` — a multi-box fleet with no interactive host has no safe
- *    single owner, so an unpinned shared-input monitor fires NOWHERE (fail safe:
- *    a silent no-op beats a fleet-wide double-fire) until one is pinned.
- *
- * `deviceNames` is the registered fleet (registry keys); `self` is `machineId()`.
- */
 export declare function resolveSharedInputOwner(interactiveHost: string | undefined, deviceNames: string[], self: string): string | undefined;
-/** Resolve {@link resolveSharedInputOwner} from live config + the device registry. */
 export declare function monitorSharedInputOwner(): string | undefined;
-/**
- * True when the monitor may evaluate + fire on this machine. Owner semantics:
- * `device` (single owner, exactly-once) → only that machine; else `devices`
- * (allowlist) → any listed machine; else placement depends on shared-input: an
- * unpinned SHARED-INPUT monitor (a system built-in by default, or a user monitor
- * that set `sharedInput: true`) fires only on the resolved owner
- * ({@link monitorSharedInputOwner}), so a built-in that polls a fleet-shared
- * queue can never fan out across every daemon (SING-9); anything else is
- * unrestricted. Both sides normalize so `Yosemite-S0` and
- * `yosemite-s0.tailnet.ts.net` agree with `yosemite-s0`.
- *
- * `ownerHost` overrides the resolved owner for tests/callers that already know
- * it; omit it in production to resolve from config + the device registry.
- */
 export declare function monitorRunsOnThisDevice(config: Pick<MonitorConfig, 'device' | 'devices' | 'scope' | 'sharedInput'>, ownerHost?: string): boolean;
-/**
- * Validate a partial monitor config, returning a list of human-readable errors.
- * Hand-rolled like validateJob (lib/routines.ts) — no zod. Rejects: no source,
- * two sources, no action, two actions, match-mode without `match`, plus the
- * per-type field/shape checks.
- */
 export declare function validateMonitor(config: Partial<MonitorConfig>): string[];
-/**
- * List all monitor configs, unioning the user dir (~/.agents/monitors/) over the
- * built-in system dir (~/.agents/.system/monitors/). Higher layer wins by name
- * (first-seen), so a user monitor shadows a system built-in of the same name.
- */
 export declare function listMonitors(): MonitorConfig[];
-/**
- * Read a single monitor config by name, checking the user dir then the system
- * dir (a user monitor shadows a system built-in). Returns null if not found or
- * corrupt.
- */
 export declare function readMonitor(name: string): MonitorConfig | null;
-/**
- * Get the filesystem path of a monitor's YAML config in the USER dir, or null.
- * User-layer only by design — like routines' getJobPath (lib/routines.ts), its
- * caller (`agents monitors edit`) writes to the returned path, and the system
- * mirror is pull-only. To edit a system built-in, `edit` materializes a user
- * copy (prefilled via readMonitor()) rather than opening the mirror.
- */
 export declare function getMonitorPath(name: string): string | null;
-/** Write a monitor config to disk atomically, omitting fields that match defaults. */
 export declare function writeMonitor(config: MonitorConfig): void;
-/** Delete a monitor config file by name. Returns true if the file existed. */
 export declare function deleteMonitor(name: string): boolean;
-/** Enable or disable a monitor by name. */
 export declare function setMonitorEnabled(name: string, enabled: boolean): void;

package/dist/lib/monitors/config.js

@@ -1,14 +1,3 @@
-/**
- * Monitor (event-triggered watcher) configuration, validation, and CRUD.
- *
- * A monitor is a routine whose trigger is a *watched source* instead of a
- * *clock*. It watches a SOURCE, detects a CONDITION change, and fires an ACTION —
- * reusing the routines daemon, dispatch engine, device model, and notify path.
- *
- * Monitors are YAML files in ~/.agents/monitors/. This module owns the on-disk
- * shape (mirroring lib/routines.ts read/write helpers), hand-rolled validation
- * (mirroring validateJob — no zod), and the device-owner eligibility gate.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -19,7 +8,6 @@ import { machineId, normalizeHost } from '../machine-id.js';
 import { loadDevicesSync } from '../devices/registry.js';
 import { ALL_AGENT_IDS } from '../agents.js';
 import { isCustomHarnessName } from '../profiles.js';
-/** Default values applied to every monitor config when fields are omitted. */
 const MONITOR_DEFAULTS = {
     enabled: true,
 };
@@ -34,11 +22,6 @@ const SOURCE_TYPES = [
 ];
 const CONDITION_MODES = ['on-change', 'match', 'every'];
 const ACTION_TYPES = ['run', 'routine', 'notify', 'webhook-out'];
-/**
- * Parse a human interval string (e.g. `30s`, `15m`, `8h`, `1d`, `1h30m`) into
- * milliseconds. Unlike routines' parseTimeout, seconds are supported (polls tick
- * in seconds). Returns null on empty/unparseable/zero input.
- */
 export function parseInterval(interval) {
     const match = interval.trim().match(/^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/);
     if (!match)
@@ -51,16 +34,7 @@ export function parseInterval(interval) {
     const ms = ((((weeks * 7 + days) * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
     return ms > 0 ? ms : null;
 }
-/**
- * True when an UNPINNED monitor must be placed on a single owner rather than
- * fired by every daemon — the SING-9 guard against a shared-queue double-fire.
- *
- * A `device` / `devices` pin is an explicit executor choice, so it is never
- * owner-overridden (returns false here). For an unpinned monitor the default is
- * layer-specific, SAFE side first: a **system built-in** is treated as
- * shared-input unless it opts out with `sharedInput: false`; a **user monitor**
- * keeps its fleet-wide default and only opts IN with `sharedInput: true`.
- */
+// Unpinned system/shared-input monitors require one resolved owner; no owner means fire nowhere.
 export function requiresSingleOwner(config) {
     if (config.device || (config.devices && config.devices.length > 0))
         return false;
@@ -68,29 +42,15 @@ export function requiresSingleOwner(config) {
         return config.sharedInput !== false;
     return config.sharedInput === true;
 }
-/**
- * The single fleet box that owns unpinned shared-input monitors — PURE, so the
- * placement rule is unit-testable without a live tailnet. Priority:
- *
- * 1. the configured `interactive.host` (the box the operator sits at);
- * 2. else, on a fleet with no OTHER registered device, this box — a single-box
- *    install has no peer to race, so the built-in still fires here;
- * 3. else `undefined` — a multi-box fleet with no interactive host has no safe
- *    single owner, so an unpinned shared-input monitor fires NOWHERE (fail safe:
- *    a silent no-op beats a fleet-wide double-fire) until one is pinned.
- *
- * `deviceNames` is the registered fleet (registry keys); `self` is `machineId()`.
- */
 export function resolveSharedInputOwner(interactiveHost, deviceNames, self) {
     if (typeof interactiveHost === 'string' && interactiveHost.trim()) {
         return normalizeHost(interactiveHost);
     }
     const others = deviceNames.map((d) => normalizeHost(d)).filter((d) => d && d !== self);
     if (others.length === 0)
-        return self; // single-box fleet: no peer, no race
-    return undefined; // multi-box, no interactive host pinned → no safe owner
+        return self;
+    return undefined;
 }
-/** Resolve {@link resolveSharedInputOwner} from live config + the device registry. */
 export function monitorSharedInputOwner() {
     const self = machineId();
     const interactiveHost = readMeta().config?.interactiveHost;
@@ -103,20 +63,7 @@ export function monitorSharedInputOwner() {
     }
     return resolveSharedInputOwner(typeof interactiveHost === 'string' ? interactiveHost : undefined, deviceNames, self);
 }
-/**
- * True when the monitor may evaluate + fire on this machine. Owner semantics:
- * `device` (single owner, exactly-once) → only that machine; else `devices`
- * (allowlist) → any listed machine; else placement depends on shared-input: an
- * unpinned SHARED-INPUT monitor (a system built-in by default, or a user monitor
- * that set `sharedInput: true`) fires only on the resolved owner
- * ({@link monitorSharedInputOwner}), so a built-in that polls a fleet-shared
- * queue can never fan out across every daemon (SING-9); anything else is
- * unrestricted. Both sides normalize so `Yosemite-S0` and
- * `yosemite-s0.tailnet.ts.net` agree with `yosemite-s0`.
- *
- * `ownerHost` overrides the resolved owner for tests/callers that already know
- * it; omit it in production to resolve from config + the device registry.
- */
+// Explicit device/device lists remain the executor choice and bypass shared-input owner inference.
 export function monitorRunsOnThisDevice(config, ownerHost) {
     const self = machineId();
     if (config.device)
@@ -131,7 +78,6 @@ export function monitorRunsOnThisDevice(config, ownerHost) {
     }
     return true;
 }
-/** Count the populated source-payload fields to detect "two sources". */
 function populatedSourceFields(source) {
     const fields = [
         ['command', source.command],
@@ -143,7 +89,6 @@ function populatedSourceFields(source) {
     ];
     return fields.filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k]) => k);
 }
-/** Which source-payload field each source type requires. */
 const SOURCE_TYPE_FIELD = {
     command: 'command',
     poll: 'command',
@@ -153,7 +98,6 @@ const SOURCE_TYPE_FIELD = {
     file: 'path',
     device: 'device',
 };
-/** Count the populated action-payload fields to detect "two actions". */
 function populatedActionFields(action) {
     const fields = [
         ['agent', action.agent],
@@ -162,12 +106,6 @@ function populatedActionFields(action) {
     ];
     return fields.filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k]) => k);
 }
-/**
- * Validate a partial monitor config, returning a list of human-readable errors.
- * Hand-rolled like validateJob (lib/routines.ts) — no zod. Rejects: no source,
- * two sources, no action, two actions, match-mode without `match`, plus the
- * per-type field/shape checks.
- */
 export function validateMonitor(config) {
     const errors = [];
     if (!config.name || typeof config.name !== 'string') {
@@ -177,7 +115,6 @@ export function validateMonitor(config) {
         errors.push(`invalid name ${JSON.stringify(config.name)}: must be a single path segment ` +
             `(no '/', '\\\\', or null bytes, and not '.' or '..')`);
     }
-    // ─── SOURCE ───────────────────────────────────────────────────────────────
     const source = config.source;
     if (!source || typeof source !== 'object') {
         errors.push('a source is required (source: { type, ... })');
@@ -189,7 +126,6 @@ export function validateMonitor(config) {
         const populated = populatedSourceFields(source);
         if (source.type && SOURCE_TYPES.includes(source.type)) {
             const required = SOURCE_TYPE_FIELD[source.type];
-            // Two sources: any populated field that doesn't belong to this type.
             const stray = populated.filter((f) => f !== required);
             if (stray.length > 0) {
                 errors.push(`source has conflicting fields (${[required, ...stray].join(', ')}); specify exactly one source`);
@@ -201,7 +137,6 @@ export function validateMonitor(config) {
         else if (populated.length > 1) {
             errors.push(`source has conflicting fields (${populated.join(', ')}); specify exactly one source`);
         }
-        // Interval-bearing sources must carry a parseable interval.
         if ((source.type === 'poll' || source.type === 'poll-http') && source.interval === undefined) {
             errors.push(`source.type '${source.type}' requires source.interval (e.g. 30s, 15m, 8h)`);
         }
@@ -221,7 +156,6 @@ export function validateMonitor(config) {
             }
         }
     }
-    // ─── CONDITION ──────────────────────────────────────────────────────────────
     const condition = config.condition;
     if (!condition || typeof condition !== 'object') {
         errors.push('a condition is required (condition: { mode, ... })');
@@ -252,7 +186,6 @@ export function validateMonitor(config) {
             }
         }
     }
-    // ─── ACTION ─────────────────────────────────────────────────────────────────
     const action = config.action;
     if (!action || typeof action !== 'object') {
         errors.push('an action is required (action: { type, ... })');
@@ -269,7 +202,6 @@ export function validateMonitor(config) {
         };
         if (action.type && ACTION_TYPES.includes(action.type)) {
             const required = requiredByType[action.type];
-            // Two actions: a populated field that belongs to a different action type.
             const stray = populatedAct.filter((f) => f !== required);
             if (stray.length > 0) {
                 errors.push(`action has conflicting fields (${[...(required ? [required] : []), ...stray].join(', ')}); specify exactly one action`);
@@ -313,7 +245,6 @@ export function validateMonitor(config) {
             }
         }
     }
-    // ─── PLACEMENT ───────────────────────────────────────────────────────────────
     if (config.device !== undefined && config.devices !== undefined) {
         errors.push("device (single owner) and devices (allowlist) are mutually exclusive — pick one");
     }
@@ -342,7 +273,6 @@ export function validateMonitor(config) {
     if (config.cwd !== undefined && (typeof config.cwd !== 'string' || config.cwd.trim() === '')) {
         errors.push('cwd must be a non-empty path (home-relative or ~/…)');
     }
-    // ─── HYGIENE ─────────────────────────────────────────────────────────────────
     if (config.rateLimit !== undefined) {
         const rl = config.rateLimit;
         if (!rl || typeof rl !== 'object' || typeof rl.max !== 'number' || rl.max <= 0) {
@@ -385,10 +315,6 @@ function readMonitorFile(filePath, scope = 'user') {
             ...MONITOR_DEFAULTS,
             ...parsed,
             name: parsed.name || path.basename(filePath).replace(/\.ya?ml$/, ''),
-            // Enabled unless the user explicitly disables it — same default for user
-            // and system layers, so a built-in is visible and on like any other
-            // system resource. `scope` is stamped below for the (built-in) tag, not
-            // used to gate enablement.
             enabled: hasEnabled ? parsed.enabled !== false : (MONITOR_DEFAULTS.enabled ?? true),
             scope,
         };
@@ -397,18 +323,12 @@ function readMonitorFile(filePath, scope = 'user') {
         return null;
     }
 }
-/** The layered monitor dirs, user before system so user shadows system by name. */
 function monitorLayers() {
     return [
         { scope: 'user', path: getMonitorsDir() },
         { scope: 'system', path: getSystemMonitorsDir() },
     ];
 }
-/**
- * List all monitor configs, unioning the user dir (~/.agents/monitors/) over the
- * built-in system dir (~/.agents/.system/monitors/). Higher layer wins by name
- * (first-seen), so a user monitor shadows a system built-in of the same name.
- */
 export function listMonitors() {
     ensureAgentsDir();
     const monitors = [];
@@ -426,11 +346,6 @@ export function listMonitors() {
     }
     return monitors;
 }
-/**
- * Read a single monitor config by name, checking the user dir then the system
- * dir (a user monitor shadows a system built-in). Returns null if not found or
- * corrupt.
- */
 export function readMonitor(name) {
     ensureAgentsDir();
     for (const { scope, path: dir } of monitorLayers()) {
@@ -442,13 +357,6 @@ export function readMonitor(name) {
     }
     return null;
 }
-/**
- * Get the filesystem path of a monitor's YAML config in the USER dir, or null.
- * User-layer only by design — like routines' getJobPath (lib/routines.ts), its
- * caller (`agents monitors edit`) writes to the returned path, and the system
- * mirror is pull-only. To edit a system built-in, `edit` materializes a user
- * copy (prefilled via readMonitor()) rather than opening the mirror.
- */
 export function getMonitorPath(name) {
     const dir = getMonitorsDir();
     for (const ext of ['.yml', '.yaml']) {
@@ -458,7 +366,6 @@ export function getMonitorPath(name) {
     }
     return null;
 }
-/** Write a monitor config to disk atomically, omitting fields that match defaults. */
 export function writeMonitor(config) {
     ensureAgentsDir();
     const dir = getMonitorsDir();
@@ -472,15 +379,12 @@ export function writeMonitor(config) {
     const output = { ...config };
     if (output.enabled === true)
         delete output.enabled;
-    // `scope` is a derived read-time annotation, never part of the on-disk schema —
-    // strip it so a materialized user copy of a built-in doesn't persist `scope: system`.
     delete output.scope;
     const devArr = output.devices;
     if (!devArr || devArr.length === 0)
         delete output.devices;
     atomicWriteFileSync(filePath, yaml.stringify(output));
 }
-/** Delete a monitor config file by name. Returns true if the file existed. */
 export function deleteMonitor(name) {
     const dir = getMonitorsDir();
     for (const ext of ['.yml', '.yaml']) {
@@ -492,7 +396,6 @@ export function deleteMonitor(name) {
     }
     return false;
 }
-/** Enable or disable a monitor by name. */
 export function setMonitorEnabled(name, enabled) {
     const monitor = readMonitor(name);
     if (!monitor)

package/dist/lib/monitors/dispatch.d.ts

@@ -1,32 +1,10 @@
-/**
- * Monitor action dispatch.
- *
- * On a fire, the monitor feeds the event to an action. Every `run`/`routine`
- * action goes through the *same* detached spawn cron and webhook fires use
- * (executeJobDetached, lib/daemon/runner.ts) — a monitor never duplicates spawn logic,
- * it synthesizes a JobConfig and hands it to the one dispatch seam. `notify`
- * routes the owner through the one channel seam (sendToOwner → lookupTransport,
- * lib/notify.ts) — recipient from notify.owner, no hardcoded chat id, and an
- * unresolvable channel comes back as `ok: false` instead of exiting the daemon;
- * `webhook-out` POSTs the event.
- */
 import type { Meta } from '../types.js';
 import type { ActionConfig, MonitorConfig, MonitorEvent } from './config.js';
-/** Outcome of a dispatched action. */
 export interface DispatchResult {
     kind: ActionConfig['type'];
     ok: boolean;
-    /** Run id for `run`/`routine` actions dispatched through executeJobDetached. */
     runId?: string;
     error?: string;
 }
-/** Replace `{event}` in a prompt with the fired event summary. */
 export declare function injectEvent(prompt: string, event: MonitorEvent): string;
-/**
- * Dispatch a monitor's action for a fired event. `run` synthesizes a JobConfig
- * (event injected into the prompt, action fields mapped onto the routines shape,
- * runOn → host placement) and calls executeJobDetached — the exact path routines
- * use. `routine` fires an existing routine with the event injected. `notify` and
- * `webhook-out` are terminal side-effects.
- */
 export declare function dispatchAction(monitor: MonitorConfig, event: MonitorEvent, meta?: Meta): Promise<DispatchResult>;

package/dist/lib/monitors/dispatch.js

@@ -1,41 +1,14 @@
-/**
- * Monitor action dispatch.
- *
- * On a fire, the monitor feeds the event to an action. Every `run`/`routine`
- * action goes through the *same* detached spawn cron and webhook fires use
- * (executeJobDetached, lib/daemon/runner.ts) — a monitor never duplicates spawn logic,
- * it synthesizes a JobConfig and hands it to the one dispatch seam. `notify`
- * routes the owner through the one channel seam (sendToOwner → lookupTransport,
- * lib/notify.ts) — recipient from notify.owner, no hardcoded chat id, and an
- * unresolvable channel comes back as `ok: false` instead of exiting the daemon;
- * `webhook-out` POSTs the event.
- */
 import { executeJobDetached } from '../daemon/runner.js';
 import { readJob } from '../scheduling/routines.js';
 import { sendToOwner } from '../notify.js';
-/** Replace `{event}` in a prompt with the fired event summary. */
 export function injectEvent(prompt, event) {
     return prompt.replace(/\{event\}/g, event.summary);
 }
-/**
- * Dispatch a monitor's action for a fired event. `run` synthesizes a JobConfig
- * (event injected into the prompt, action fields mapped onto the routines shape,
- * runOn → host placement) and calls executeJobDetached — the exact path routines
- * use. `routine` fires an existing routine with the event injected. `notify` and
- * `webhook-out` are terminal side-effects.
- */
 export async function dispatchAction(monitor, event, meta) {
     const action = monitor.action;
     if (action.type === 'run') {
         const job = {
             name: monitor.name,
-            // This job is not a routine — no definition, no yaml, never listed by
-            // `agents routines` — so it can never be a member of this device's routine
-            // activation manifest and MUST NOT be gated on it. Before this marker the
-            // gate refused every monitor `run` action with `wrong_owner` and an empty
-            // allowlist ("Job '<name>' can only run on: "), so no monitor action ever
-            // executed (RUSH-2681). The monitor's own `device:` pin already resolved
-            // exactly-once ownership before this dispatch.
             dispatchedBy: 'monitor',
             agent: action.agent,
             mode: action.mode ?? 'auto',
@@ -43,12 +16,6 @@ export async function dispatchAction(monitor, event, meta) {
             timeout: action.timeout ?? '10m',
             enabled: true,
             prompt: injectEvent(action.prompt ?? '', event),
-            // A monitor watches a source; it owns no project, and until `cwd` existed
-            // it had no field able to supply one — so `resolveJobExecutionContext`
-            // blocked every `run` action with `execution_context_missing`
-            // (lib/routine-context.ts) once the eligibility gate above stopped
-            // swallowing them first. `~` is the execution TARGET's home, so it stays
-            // portable across a `runOn:` SSH hop.
             cwd: monitor.cwd ?? '~',
             ...(monitor.variables ? { variables: monitor.variables } : {}),
             ...(monitor.version ? { version: monitor.version } : {}),
@@ -70,7 +37,6 @@ export async function dispatchAction(monitor, event, meta) {
         if (!routine) {
             return { kind: 'routine', ok: false, error: `routine '${action.routine}' not found` };
         }
-        // Inject the event into the routine's prompt so the fired routine sees it.
         const fired = { ...routine, prompt: injectEvent(routine.prompt ?? '', event) };
         try {
             const runMeta = await executeJobDetached(fired);
@@ -90,7 +56,6 @@ export async function dispatchAction(monitor, event, meta) {
         });
         return { kind: 'notify', ok: result.ok, ...(result.ok ? {} : { error: result.error }) };
     }
-    // webhook-out
     if (!action.url)
         return { kind: 'webhook-out', ok: false, error: 'action.url is required' };
     try {