@phnx-labs/agents-cli 1.22.119 → 1.22.121

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

@@ -1,57 +1,25 @@
-/**
- * Monitor evaluate/fire loop.
- *
- * Modeled on the routines daemon: a single MonitorEngine lives inside runDaemon()
- * beside the cron JobScheduler. On each tick it evaluates every enabled monitor
- * that is DUE and owned by this device, applies the condition through the native
- * state-diff store, and on a fire dispatches the action, writes a fire record, and
- * updates state. A per-monitor rate limit auto-pauses a firehose.
- *
- * v1 covers the poll model (command, poll, poll-http, file, device). Push sources
- * (ws, webhook) return null from `evaluate` — they deliver through `subscribe` /
- * the webhook receiver, wired in a follow-up; the engine treats them as inert.
- */
 import { type MonitorConfig, type MonitorEvent } from './config.js';
 import { type Observation } from './sources/index.js';
-/** How often the engine wakes to check which monitors are due. */
 export declare const MONITOR_ENGINE_TICK_MS = 5000;
-/** Poll-model source types the engine actually evaluates on a cadence; ws/webhook are push-only and inert here. */
 export declare const POLL_SOURCE_TYPES: Set<string>;
-/**
- * Whether a monitor's liveness has crossed into a drought worth notifying the
- * owner about: enough consecutive failed checks, and not already notified for
- * this drought. Pure so the branch is unit-testable without a real notify.
- */
 export declare function shouldEscalateDrought(liveness: MonitorLivenessLike): boolean;
-/** The liveness fields the drought predicate reads. */
 interface MonitorLivenessLike {
     consecutiveErrors: number;
     droughtNotifiedAt?: string;
 }
-/** The fire/no-fire decision for one observation, plus what to persist. */
 interface FireDecision {
     fire: boolean;
-    /** The value whose de-dupe signature is stored on persist. */
     value: string;
-    /** The de-dupe key (regex) applied to the value, if any. */
     dedupeKey?: string;
-    /** Persist `value` as the new baseline even when not firing (on-change baseline). */
     persist: boolean;
-    /** The event to dispatch, present iff `fire`. */
     event: MonitorEvent | null;
 }
-/**
- * Apply a monitor's condition to an observation. Pure (reads state, never
- * writes), so both the tick loop and the `test` dry-run share it.
- */
 export declare function decideFire(monitor: MonitorConfig, observation: Observation): FireDecision;
-/** One evaluation of a monitor's source + condition, without side effects. Used by `test`. */
 export declare function evaluateMonitorOnce(monitor: MonitorConfig): Promise<{
     observation: Observation | null;
     decision: FireDecision | null;
 }>;
 type LogFn = (level: string, message: string) => void;
-/** The durable monitor engine. One instance per daemon. */
 export declare class MonitorEngine {
     private logFn;
     private timer;
@@ -60,37 +28,17 @@ export declare class MonitorEngine {
     private ticking;
     private running;
     constructor(logFn?: LogFn);
-    /** Load owned+enabled monitors and start the tick loop. */
     start(options?: {
         externalScheduler?: boolean;
     }): void;
-    /** Reload monitor configs (SIGHUP). */
     reload(): void;
-    /** Stop the tick loop. No monitor dispatches after this until `start()`. */
     stop(): void;
     private loadAll;
     private intervalMs;
     private isDue;
-    /** Evaluate every due monitor once. Overlap-guarded so a slow cycle never stacks. */
-    tick(): Promise<void>;
-    /**
-     * Evaluate one monitor once and record the outcome. Public so the daemon tick
-     * and tests drive the exact same path. A "failed check" is an evaluation that
-     * produced no observation, threw, OR fired an action that failed — all three
-     * are "the monitor ran and accomplished nothing", the drought signal. A poll
-     * that observes and either fires cleanly or matches nothing is a success and
-     * resets the streak.
-     */
+    tick(launchWindowMs?: number): Promise<void>;
     runMonitor(monitor: MonitorConfig): Promise<void>;
-    /**
-     * Record the poll heartbeat and, on a sustained failure streak, escalate a
-     * drought to the owner exactly once. The heartbeat is what makes a
-     * polling-but-not-matching monitor visibly distinct from one the engine never
-     * touched (RUSH-2485); the streak is what turns "every poll fails and the owner
-     * never hears about it" into one notification.
-     */
     private afterCheck;
-    /** Notify the owner that an enabled monitor has failed N checks in a row and done nothing. */
     private escalateDrought;
     private fire;
 }

package/dist/lib/monitors/engine.js

@@ -1,40 +1,14 @@
-/**
- * Monitor evaluate/fire loop.
- *
- * Modeled on the routines daemon: a single MonitorEngine lives inside runDaemon()
- * beside the cron JobScheduler. On each tick it evaluates every enabled monitor
- * that is DUE and owned by this device, applies the condition through the native
- * state-diff store, and on a fire dispatches the action, writes a fire record, and
- * updates state. A per-monitor rate limit auto-pauses a firehose.
- *
- * v1 covers the poll model (command, poll, poll-http, file, device). Push sources
- * (ws, webhook) return null from `evaluate` — they deliver through `subscribe` /
- * the webhook receiver, wired in a follow-up; the engine treats them as inert.
- */
 import { listMonitors, monitorRunsOnThisDevice, parseInterval, setMonitorEnabled, } from './config.js';
 import { evaluateSource } from './sources/index.js';
 import { hasChanged, readState, writeState, recordFireTime, writeFireRecord, recordCheck, markDroughtNotified, } from './state.js';
 import { dispatchAction, injectEvent } from './dispatch.js';
 import { sendToOwner } from '../notify.js';
 import { readRunMeta } from '../scheduling/routines.js';
-/** How often the engine wakes to check which monitors are due. */
 export const MONITOR_ENGINE_TICK_MS = 5_000;
-/** Default evaluation cadence for sources that carry no explicit interval. */
 const DEFAULT_INTERVAL_MS = 60_000;
-/**
- * Consecutive failed polls before the engine escalates a drought to the owner.
- * A monitor that looks healthy (enabled, daemon up) but whose source errors
- * every poll does no real work — the "every signal reads healthy while zero work
- * happened" failure RUSH-2485 is about. One notification per drought.
- */
+const MAX_CONCURRENT_POLLS = 4;
 const DROUGHT_THRESHOLD = 5;
-/** Poll-model source types the engine actually evaluates on a cadence; ws/webhook are push-only and inert here. */
 export const POLL_SOURCE_TYPES = new Set(['command', 'poll', 'poll-http', 'file', 'device']);
-/**
- * Whether a monitor's liveness has crossed into a drought worth notifying the
- * owner about: enough consecutive failed checks, and not already notified for
- * this drought. Pure so the branch is unit-testable without a real notify.
- */
 export function shouldEscalateDrought(liveness) {
     return liveness.consecutiveErrors >= DROUGHT_THRESHOLD && !liveness.droughtNotifiedAt;
 }
@@ -45,30 +19,16 @@ function truncateSummary(text) {
 function buildEvent(monitor, summary, payload) {
     return { monitorName: monitor.name, firedAt: new Date().toISOString(), summary, payload };
 }
-/**
- * Apply a monitor's condition to an observation. Pure (reads state, never
- * writes), so both the tick loop and the `test` dry-run share it.
- */
+// Failed observations never move state; every-mode ignores blank output, while the first valid on-change value, even empty, becomes a silent baseline.
 export function decideFire(monitor, observation) {
     const cond = monitor.condition;
     const raw = observation.raw;
     const payload = observation.meta ?? {};
     const dedupeKey = cond.dedupeKey;
-    // A snapshot the source flagged as an OBSERVATION FAILURE (a poll that exited
-    // non-zero or emitted a transport/auth/rate-limit error) is never a value
-    // change: don't fire, don't move the baseline — so an empty→error→empty flap
-    // can't read as two value changes (PHNX-3510). The engine records it as a
-    // failed check separately, feeding the drought health streak.
     if (observation.failed) {
         return { fire: false, value: raw, dedupeKey, persist: false, event: null };
     }
     if (cond.mode === 'every') {
-        // Fire on every tick that carries a real observation. An empty (or
-        // whitespace-only) observation means "nothing to report": firing an action
-        // with an empty {event} is never useful, and skipping it lets a poll whose
-        // command yields no rows (e.g. no mergeable PR) stay silent while still
-        // re-firing every tick the set is non-empty — the retry semantics a
-        // silently-failed action dispatch needs (RUSH-2488).
         if (raw.trim() === '') {
             return { fire: false, value: raw, dedupeKey, persist: false, event: null };
         }
@@ -101,8 +61,6 @@ export function decideFire(monitor, observation) {
             event: changed ? buildEvent(monitor, truncateSummary(matchedValue), payload) : null,
         };
     }
-    // on-change (default): the first observation establishes a silent baseline;
-    // thereafter fire when the de-dupe signature differs from last-seen.
     const prior = readState(monitor.name);
     if (!prior) {
         return { fire: false, value: raw, dedupeKey, persist: true, event: null };
@@ -116,14 +74,12 @@ export function decideFire(monitor, observation) {
         event: changed ? buildEvent(monitor, truncateSummary(raw), payload) : null,
     };
 }
-/** One evaluation of a monitor's source + condition, without side effects. Used by `test`. */
 export async function evaluateMonitorOnce(monitor) {
     const observation = await evaluateSource(monitor.source);
     if (!observation)
         return { observation: null, decision: null };
     return { observation, decision: decideFire(monitor, observation) };
 }
-/** The durable monitor engine. One instance per daemon. */
 export class MonitorEngine {
     logFn;
     timer = null;
@@ -134,7 +90,6 @@ export class MonitorEngine {
     constructor(logFn = () => { }) {
         this.logFn = logFn;
     }
-    /** Load owned+enabled monitors and start the tick loop. */
     start(options = {}) {
         this.running = true;
         this.loadAll();
@@ -143,12 +98,10 @@ export class MonitorEngine {
             this.timer = setInterval(() => void this.tick(), MONITOR_ENGINE_TICK_MS);
         }
     }
-    /** Reload monitor configs (SIGHUP). */
     reload() {
         this.loadAll();
         this.logFn('INFO', `Monitor engine reloaded (${this.monitors.length} monitor(s) on this device)`);
     }
-    /** Stop the tick loop. No monitor dispatches after this until `start()`. */
     stop() {
         this.running = false;
         if (this.timer) {
@@ -168,39 +121,29 @@ export class MonitorEngine {
         const last = this.lastEval.get(monitor.name) ?? 0;
         return now - last >= this.intervalMs(monitor);
     }
-    /** Evaluate every due monitor once. Overlap-guarded so a slow cycle never stacks. */
-    async tick() {
-        // A stopped engine dispatches nothing (PHNX-3608): under the external
-        // scheduler the supervisor owns the timer, so a `stop()` (monitors service
-        // disabled) must be honoured HERE — otherwise the next supervised tick would
-        // still fire the last-loaded monitors even though the engine is stopped.
+    async tick(launchWindowMs = Infinity) {
         if (!this.running || this.ticking)
             return;
         this.ticking = true;
         try {
-            const now = Date.now();
-            for (const monitor of this.monitors) {
-                if (!this.isDue(monitor, now))
-                    continue;
-                this.lastEval.set(monitor.name, now);
-                await this.runMonitor(monitor);
-            }
+            const startedAt = Date.now();
+            const due = this.monitors
+                .filter((monitor) => this.isDue(monitor, startedAt))
+                .sort((a, b) => (this.lastEval.get(a.name) ?? 0) - (this.lastEval.get(b.name) ?? 0));
+            const worker = async () => {
+                while (this.running && due.length > 0 && Date.now() - startedAt < launchWindowMs) {
+                    const monitor = due.shift();
+                    this.lastEval.set(monitor.name, Date.now());
+                    await this.runMonitor(monitor);
+                }
+            };
+            await Promise.all(Array.from({ length: MAX_CONCURRENT_POLLS }, worker));
         }
         finally {
             this.ticking = false;
         }
     }
-    /**
-     * Evaluate one monitor once and record the outcome. Public so the daemon tick
-     * and tests drive the exact same path. A "failed check" is an evaluation that
-     * produced no observation, threw, OR fired an action that failed — all three
-     * are "the monitor ran and accomplished nothing", the drought signal. A poll
-     * that observes and either fires cleanly or matches nothing is a success and
-     * resets the streak.
-     */
     async runMonitor(monitor) {
-        // Push-only sources (ws/webhook) deliver through subscribe, not this loop —
-        // they return null from evaluate by design, so they have no poll to record.
         const isPollSource = POLL_SOURCE_TYPES.has(monitor.source.type);
         if (!isPollSource)
             return;
@@ -212,12 +155,6 @@ export class MonitorEngine {
                 checkError = 'source produced no observation';
             }
             else if (observation.failed) {
-                // The poll ran but did not OBSERVE (non-zero exit, or a transport/auth/
-                // rate-limit error in its output). Skip it entirely: no decideFire, no
-                // fire, watched-state untouched — so no empty→error→empty flap dispatches
-                // an agent on a dead premise. Record it as a failed check so a sustained
-                // streak escalates as a drought, the same health surface `--postcondition`
-                // uses on the action side (PHNX-3510).
                 checkError = `poll failed: ${observation.failureReason ?? 'observation failure'}`;
                 this.logFn('WARN', `monitor '${monitor.name}' poll failed (${observation.failureReason ?? 'observation failure'}) — not treated as a value change`);
             }
@@ -229,7 +166,6 @@ export class MonitorEngine {
                         checkError = `action ${result.kind} failed: ${result.error ?? 'unknown'}`;
                 }
                 else if (decision.persist) {
-                    // Silent baseline / no-change: record the value so we don't re-fire.
                     writeState(monitor.name, decision.value, decision.dedupeKey);
                 }
             }
@@ -240,24 +176,15 @@ export class MonitorEngine {
         }
         this.afterCheck(monitor, checkedAt, checkError);
     }
-    /**
-     * Record the poll heartbeat and, on a sustained failure streak, escalate a
-     * drought to the owner exactly once. The heartbeat is what makes a
-     * polling-but-not-matching monitor visibly distinct from one the engine never
-     * touched (RUSH-2485); the streak is what turns "every poll fails and the owner
-     * never hears about it" into one notification.
-     */
+    // Liveness is independent of change state: every poll updates it and recovery resets the drought.
     afterCheck(monitor, checkedAt, error) {
         const liveness = recordCheck(monitor.name, checkedAt, error);
         if (error && shouldEscalateDrought(liveness)) {
             void this.escalateDrought(monitor, liveness.consecutiveErrors, error);
         }
     }
-    /** Notify the owner that an enabled monitor has failed N checks in a row and done nothing. */
     async escalateDrought(monitor, consecutiveErrors, error) {
         const at = new Date().toISOString();
-        // Stamp the marker BEFORE the send so a slow/failing notify can't re-fire the
-        // drought on the next tick; recordCheck clears it on the first good check.
         markDroughtNotified(monitor.name, at);
         const text = `Monitor '${monitor.name}' has failed ${consecutiveErrors} checks in a row and accomplished nothing. ` +
             `Last error: ${error}`;
@@ -273,24 +200,18 @@ export class MonitorEngine {
     async fire(monitor, decision, event) {
         const now = Date.now();
         let fireTimes;
-        // Firehose guard: auto-pause a monitor that exceeds its rate limit.
         if (monitor.rateLimit) {
             const windowMs = parseInterval(monitor.rateLimit.per) ?? 60_000;
             fireTimes = recordFireTime(monitor.name, now, windowMs);
             if (fireTimes.length > monitor.rateLimit.max) {
-                // Record the tripped event in fire history too, so `agents monitors runs`
-                // reflects what `view`'s `lastFiredAt` shows — the firehose event the guard
-                // exists to surface must not be invisible in the fire log.
                 writeFireRecord(event, { action: monitor.action.type, ok: false, error: 'rate limited — auto-paused' });
                 writeState(monitor.name, decision.value, decision.dedupeKey, { lastFiredAt: event.firedAt, fireTimes });
                 try {
                     setMonitorEnabled(monitor.name, false);
                 }
-                catch { /* best-effort pause */ }
+                catch { }
                 this.logFn('WARN', `monitor '${monitor.name}' exceeded rate limit (${monitor.rateLimit.max}/${monitor.rateLimit.per}) — auto-paused`);
                 this.loadAll();
-                // An auto-pause is a deliberate stop, not a failed action — don't let it
-                // feed the drought streak (the monitor is now disabled anyway).
                 return { kind: monitor.action.type, ok: true };
             }
         }
@@ -301,17 +222,7 @@ export class MonitorEngine {
         catch (err) {
             result = { kind: monitor.action.type, ok: false, error: err.message };
         }
-        // Best-effort snapshot of the run's status AT THIS INSTANT — the same
-        // synchronous view `dispatchAction` just returned from. For the async-race
-        // case (RUSH-2690) this reads 'running': the dispatched process is still
-        // in flight, `ok` was frozen on that transient state, and the real outcome
-        // is not known yet. Recorded so a future reconciliation pass can find
-        // exactly the fires whose `ok` needs revisiting; `resolveFireOutcome`
-        // (state.ts) never trusts this field — it re-reads the run fresh instead.
         const runStatusAtFire = result.runId ? readRunMeta(monitor.name, result.runId)?.status : undefined;
-        // Snapshot the postcondition with `{event}` already interpolated so a later
-        // `resolveFireOutcome` can assert the stated effect without re-reading YAML
-        // (PHNX-2842). Notify/webhook-out have no run to settle, so they skip this.
         const postcondition = (result.kind === 'run' || result.kind === 'routine') && monitor.action.postcondition
             ? injectEvent(monitor.action.postcondition, event)
             : undefined;

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

@@ -1,46 +1,3 @@
-/**
- * Semantic identity of a monitor — "are these two definitions the same watcher?"
- *
- * A monitor's NAME is not its identity. Two monitors can poll the same command
- * on the same interval and fire the same action under two different names, and
- * nothing today notices: `writeMonitor` overwrites by name and never compares
- * arguments. Observed on one box: `open-pr-watch`, `pr-ci-fail`, three stale
- * `pr2222-*` watchers, and an agent-added lander, all polling
- * `gh pr list ... phnx-labs/agents-cli` — four overlapping triggers on one PR
- * queue, added without a single warning.
- *
- * That is the double-trigger bug class. The fingerprint is what lets `add`
- * refuse it.
- *
- * WHAT IS HASHED: only fields that change what the monitor DOES — the source it
- * watches, how often, the condition that fires, and the action it takes. Name,
- * description, and `enabled` are deliberately excluded, because a duplicate
- * under a new name is exactly the case being caught, and a paused duplicate is
- * still a duplicate the moment someone resumes it.
- *
- * WHAT IS NOT HASHED: `device`/`devices`/`runOn`. Placement is who executes, not
- * what runs — and two boxes deliberately owning the same watcher is a different
- * decision (see `monitorRunsOnThisDevice`). Including placement would let the
- * same watcher be added N times by varying only the owner, which is the very
- * duplication this guards.
- */
 import type { MonitorConfig } from './config.js';
-/**
- * The behavioral identity of a monitor, as a short hex digest. Two monitors with
- * the same fingerprint watch the same thing and do the same thing on fire —
- * whatever they are called and wherever they are pinned.
- *
- * Pure: no I/O, so the duplicate check is unit-tested without a monitors dir.
- */
 export declare function monitorFingerprint(config: Pick<MonitorConfig, 'source' | 'condition' | 'action'>): string;
-/**
- * The already-existing monitor that this config would duplicate, or null.
- *
- * `existing` is the full monitor set (user + system layers), so a user monitor
- * duplicating a shipped built-in is caught too. A monitor never collides with
- * itself: a same-NAME entry is a rewrite of that monitor, which `add` reports
- * separately and more precisely than "duplicate".
- *
- * Pure — the caller supplies the list.
- */
 export declare function findDuplicateMonitor(config: Pick<MonitorConfig, 'name' | 'source' | 'condition' | 'action'>, existing: Array<Pick<MonitorConfig, 'name' | 'source' | 'condition' | 'action'>>): string | null;

package/dist/lib/monitors/fingerprint.js

@@ -1,44 +1,4 @@
-/**
- * Semantic identity of a monitor — "are these two definitions the same watcher?"
- *
- * A monitor's NAME is not its identity. Two monitors can poll the same command
- * on the same interval and fire the same action under two different names, and
- * nothing today notices: `writeMonitor` overwrites by name and never compares
- * arguments. Observed on one box: `open-pr-watch`, `pr-ci-fail`, three stale
- * `pr2222-*` watchers, and an agent-added lander, all polling
- * `gh pr list ... phnx-labs/agents-cli` — four overlapping triggers on one PR
- * queue, added without a single warning.
- *
- * That is the double-trigger bug class. The fingerprint is what lets `add`
- * refuse it.
- *
- * WHAT IS HASHED: only fields that change what the monitor DOES — the source it
- * watches, how often, the condition that fires, and the action it takes. Name,
- * description, and `enabled` are deliberately excluded, because a duplicate
- * under a new name is exactly the case being caught, and a paused duplicate is
- * still a duplicate the moment someone resumes it.
- *
- * WHAT IS NOT HASHED: `device`/`devices`/`runOn`. Placement is who executes, not
- * what runs — and two boxes deliberately owning the same watcher is a different
- * decision (see `monitorRunsOnThisDevice`). Including placement would let the
- * same watcher be added N times by varying only the owner, which is the very
- * duplication this guards.
- */
 import { createHash } from 'crypto';
-/**
- * Stable JSON: object keys sorted, so key order in the YAML cannot change the hash.
- *
- * Cycle-safe by construction. A monitor can arrive from arbitrary YAML
- * (`agents monitors add ./watcher.yml`), and a recursive anchor produces a
- * genuinely cyclic object that `validateMonitor` accepts — it checks named
- * fields, while this walks the whole graph. Without the seen-set the recursion
- * blew the stack before `JSON.stringify` could raise its own circular-structure
- * error, turning a bad input into a stack trace instead of a clear refusal.
- *
- * A `Date` is serialized to its ISO string rather than falling into the object
- * branch, where every Date collapsed to `{}` and two different timestamps
- * fingerprinted identically.
- */
 function stable(value, seen = new WeakSet()) {
     if (value instanceof Date)
         return value.toISOString();
@@ -63,13 +23,6 @@ function stable(value, seen = new WeakSet()) {
     }
     return value;
 }
-/**
- * The behavioral identity of a monitor, as a short hex digest. Two monitors with
- * the same fingerprint watch the same thing and do the same thing on fire —
- * whatever they are called and wherever they are pinned.
- *
- * Pure: no I/O, so the duplicate check is unit-tested without a monitors dir.
- */
 export function monitorFingerprint(config) {
     const identity = stable({
         source: config.source,
@@ -78,16 +31,6 @@ export function monitorFingerprint(config) {
     });
     return createHash('sha256').update(JSON.stringify(identity)).digest('hex').slice(0, 16);
 }
-/**
- * The already-existing monitor that this config would duplicate, or null.
- *
- * `existing` is the full monitor set (user + system layers), so a user monitor
- * duplicating a shipped built-in is caught too. A monitor never collides with
- * itself: a same-NAME entry is a rewrite of that monitor, which `add` reports
- * separately and more precisely than "duplicate".
- *
- * Pure — the caller supplies the list.
- */
 export function findDuplicateMonitor(config, existing) {
     const fp = monitorFingerprint(config);
     for (const other of existing) {

package/dist/lib/monitors/pid-watch.d.ts

@@ -1,35 +1,4 @@
-/**
- * `--watch-pid` support — turns a backgrounded OS process into a durable,
- * daemon-polled watcher instead of relying on a harness's own exit hook
- * (PHNX-3023: a "will re-invoke me" background shell never fires when the
- * harness only notifies on process exit and the watch loop itself never
- * exits — `gh pr checks --watch`, a long sleep, a tick poll).
- *
- * The command built here reuses the same existence-check predicate
- * `isPidAlive`'s existence branch uses (`process.kill(pid, 0)`), but it runs
- * inside the monitor engine's own poll loop (`sources/command.ts`) rather than
- * the caller's process — so the check survives past the CLI invocation that
- * armed it.
- */
-/** The token a --watch-pid source's condition matches on process exit. */
 export declare const PID_WATCH_EXITED_TOKEN = "exited";
-/** Emitted while the pid is alive. */
 export declare const PID_WATCH_RUNNING_TOKEN = "running";
-/**
- * Emitted when the pid is not alive AND has never been observed alive — the
- * `--force` not-yet-spawned case. Deliberately distinct from
- * {@link PID_WATCH_EXITED_TOKEN} so it can never match the exit condition.
- */
 export declare const PID_WATCH_NOT_YET_SPAWNED_TOKEN = "notyetspawned";
-/**
- * The shell command a --watch-pid source polls. A poll only reports "exited"
- * once it has FIRST observed the pid running — tracked with a marker file the
- * command touches on every "running" poll — otherwise a `--force`-armed watch
- * on a not-yet-spawned pid would report "exited" on its very first poll (the
- * pid doesn't exist *yet*, not *anymore*), which the engine's match-mode
- * fires immediately (no prior state to diff against) and then persists as the
- * baseline — silencing the real exit forever once the process actually spawns
- * and later dies. Portable across the shells `sources/command.ts` invokes
- * (`/bin/sh -c` posix, `cmd /c` Windows).
- */
 export declare function pidLivenessCommand(pid: number, seenRunningMarkerPath: string): string;

package/dist/lib/monitors/pid-watch.js

@@ -1,38 +1,7 @@
-/**
- * `--watch-pid` support — turns a backgrounded OS process into a durable,
- * daemon-polled watcher instead of relying on a harness's own exit hook
- * (PHNX-3023: a "will re-invoke me" background shell never fires when the
- * harness only notifies on process exit and the watch loop itself never
- * exits — `gh pr checks --watch`, a long sleep, a tick poll).
- *
- * The command built here reuses the same existence-check predicate
- * `isPidAlive`'s existence branch uses (`process.kill(pid, 0)`), but it runs
- * inside the monitor engine's own poll loop (`sources/command.ts`) rather than
- * the caller's process — so the check survives past the CLI invocation that
- * armed it.
- */
 import { IS_WINDOWS } from '../platform/index.js';
-/** The token a --watch-pid source's condition matches on process exit. */
 export const PID_WATCH_EXITED_TOKEN = 'exited';
-/** Emitted while the pid is alive. */
 export const PID_WATCH_RUNNING_TOKEN = 'running';
-/**
- * Emitted when the pid is not alive AND has never been observed alive — the
- * `--force` not-yet-spawned case. Deliberately distinct from
- * {@link PID_WATCH_EXITED_TOKEN} so it can never match the exit condition.
- */
 export const PID_WATCH_NOT_YET_SPAWNED_TOKEN = 'notyetspawned';
-/**
- * The shell command a --watch-pid source polls. A poll only reports "exited"
- * once it has FIRST observed the pid running — tracked with a marker file the
- * command touches on every "running" poll — otherwise a `--force`-armed watch
- * on a not-yet-spawned pid would report "exited" on its very first poll (the
- * pid doesn't exist *yet*, not *anymore*), which the engine's match-mode
- * fires immediately (no prior state to diff against) and then persists as the
- * baseline — silencing the real exit forever once the process actually spawns
- * and later dies. Portable across the shells `sources/command.ts` invokes
- * (`/bin/sh -c` posix, `cmd /c` Windows).
- */
 export function pidLivenessCommand(pid, seenRunningMarkerPath) {
     if (IS_WINDOWS) {
         return (`tasklist /FI "PID eq ${pid}" 2>NUL | findstr /I "${pid}" >NUL ` +

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

@@ -1,31 +1,6 @@
-/**
- * Fleet-wide monitor lookup — "is any box already watching this?"
- *
- * A monitor's identity is its ARGUMENTS, not its name or its device. Agents
- * create monitors per work item, so the same shape runs many times over with
- * different arguments (PR #2517 vs #2600) and those must all coexist. The case
- * that must NOT happen is two agents, on two different machines, creating a
- * watcher with the SAME arguments — one work item, two triggers.
- *
- * A local-only check cannot see that: each box reads its own `monitors/` dir and
- * neither sees the other. So the duplicate guard asks the fleet, reusing the
- * same cross-machine fan-out `sessions --active` and `fleet status` already run
- * (`lib/remote-agents-json.ts`).
- *
- * Deliberately NOT solved by syncing `monitors/*.yml` through the DotAgents repo:
- * an agent's per-PR watcher is running state, not config, and syncing would push
- * every one of them onto every box — the accumulation this guard exists to stop.
- */
 import { type GatherRemoteAgentsJsonDeps } from '../remote-agents-json.js';
 import type { MonitorConfig } from './config.js';
-/** Recursion guard: a peer answering the fan-out must not fan out again. */
 export declare const NO_MONITOR_FANOUT_ENV = "AGENTS_MONITORS_LOCAL";
-/**
- * The owning box's view of a remote monitor, beyond its behavioral identity —
- * enough for `monitors list` to render it (enabled/placement/scope) and show a
- * one-line liveness note without a second round-trip. All optional: a peer on an
- * older CLI may omit them, and the duplicate guard never reads them.
- */
 export interface RemoteMonitorDisplay {
     enabled?: boolean;
     owner?: string;
@@ -36,48 +11,21 @@ export interface RemoteMonitorDisplay {
     lastFiredAt?: string | null;
     lastActionFailed?: boolean;
 }
-/** One monitor as seen on a peer, tagged with the box it lives on. */
 export interface RemoteMonitor {
     machine: string;
     monitor: Pick<MonitorConfig, 'name' | 'source' | 'condition' | 'action'>;
-    /** The owning box's enabled/placement/scope/liveness view, for `list` display. */
     display?: RemoteMonitorDisplay;
 }
-/**
- * Parse a peer's `monitors list --json`. Defensive against version skew: a peer
- * on an older CLI may emit a different shape or no JSON at all, and one bad peer
- * must never blank the guard for the rest of the fleet.
- */
 export declare function parseRemoteMonitors(stdout: string, machine: string): RemoteMonitor[];
 interface FleetMonitorsResult {
     monitors: RemoteMonitor[];
-    /** Target discovery failed before any peer was dialed — the fleet was not
-     *  consulted at all, which must not read as "no duplicate anywhere". */
     discoveryFailed: boolean;
-    /** Peers dialed but unreachable / erroring — the guard reports these rather than
-     *  silently treating "we could not ask" as "there is no duplicate". */
     skipped: string[];
 }
 interface GatherFleetMonitorsOptions {
-    /** When supplied, the fan-out aborts as soon as any peer returns a monitor with
-     *  this behavioral fingerprint. The miss path still waits for every peer so the
-     *  guard can prove absence fleet-wide. */
     againstFingerprint?: string;
-    /** Optional test seam for the SSH boundary; production uses the real capture. */
     deps?: GatherRemoteAgentsJsonDeps;
-    /** Optional explicit host list; production omits it and asks the device registry. */
     hosts?: string[];
 }
-/**
- * Every monitor on every other registered device. Never throws: an unreachable
- * fleet degrades to an empty list plus the names we could not consult, and the
- * caller decides what to say about them.
- *
- * When {@link GatherFleetMonitorsOptions.againstFingerprint} is provided, a peer
- * returning that fingerprint is a definitive clash: the remaining peers are
- * SIGTERM'd immediately rather than burning the rest of the timeout budget.
- * Absence of a clash still waits for the full fleet, because uniqueness is only
- * knowable once every peer has answered.
- */
 export declare function gatherFleetMonitors(options?: GatherFleetMonitorsOptions): Promise<FleetMonitorsResult>;
 export {};