@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/monitors/engine.js

@@ -13,12 +13,30 @@
  */
 import { listMonitors, monitorRunsOnThisDevice, parseInterval, setMonitorEnabled, } from './config.js';
 import { evaluateSource } from './sources/index.js';
-import { hasChanged, readState, writeState, recordFireTime, writeFireRecord, } from './state.js';
+import { hasChanged, readState, writeState, recordFireTime, writeFireRecord, recordCheck, markDroughtNotified, } from './state.js';
 import { dispatchAction } from './dispatch.js';
+import { sendToOwner } from '../notify.js';
 /** How often the engine wakes to check which monitors are due. */
 const 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 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;
+}
 function truncateSummary(text) {
     const oneLine = text.replace(/\s+/g, ' ').trim();
     return oneLine.length > 240 ? oneLine.slice(0, 240) + '…' : oneLine;
@@ -36,6 +54,15 @@ export function decideFire(monitor, observation) {
     const payload = observation.meta ?? {};
     const dedupeKey = cond.dedupeKey;
     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 };
+        }
         return {
             fire: true,
             value: raw,
@@ -145,21 +172,74 @@ export class MonitorEngine {
             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;
+        const checkedAt = new Date().toISOString();
+        let checkError;
         try {
-            const { observation, decision } = await evaluateMonitorOnce(monitor);
-            if (!observation || !decision)
-                return;
-            if (decision.fire && decision.event) {
-                await this.fire(monitor, decision, decision.event);
+            const observation = await evaluateSource(monitor.source);
+            if (!observation) {
+                checkError = 'source produced no observation';
             }
-            else if (decision.persist) {
-                // Silent baseline / no-change: record the value so we don't re-fire.
-                writeState(monitor.name, decision.value, decision.dedupeKey);
+            else {
+                const decision = decideFire(monitor, observation);
+                if (decision.fire && decision.event) {
+                    const result = await this.fire(monitor, decision, decision.event);
+                    if (!result.ok)
+                        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);
+                }
             }
         }
         catch (err) {
-            this.logFn('ERROR', `monitor '${monitor.name}' evaluation failed: ${err.message}`);
+            checkError = err.message;
+            this.logFn('ERROR', `monitor '${monitor.name}' evaluation failed: ${checkError}`);
+        }
+        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.
+     */
+    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}`;
+        try {
+            const result = await sendToOwner(text);
+            this.logFn(result.ok ? 'WARN' : 'ERROR', `monitor '${monitor.name}' drought (${consecutiveErrors} failed checks) → notify owner` +
+                (result.ok ? '' : ` FAILED: ${result.error}`));
+        }
+        catch (err) {
+            this.logFn('ERROR', `monitor '${monitor.name}' drought notify threw: ${err.message}`);
         }
     }
     async fire(monitor, decision, event) {
@@ -181,7 +261,9 @@ export class MonitorEngine {
                 catch { /* best-effort pause */ }
                 this.logFn('WARN', `monitor '${monitor.name}' exceeded rate limit (${monitor.rateLimit.max}/${monitor.rateLimit.per}) — auto-paused`);
                 this.loadAll();
-                return;
+                // 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 };
             }
         }
         let result;
@@ -201,5 +283,6 @@ export class MonitorEngine {
         this.logFn(result.ok ? 'INFO' : 'ERROR', `monitor '${monitor.name}' fired → ${result.kind}` +
             (result.runId ? ` (run: ${result.runId})` : '') +
             (result.ok ? '' : ` FAILED: ${result.error}`));
+        return result;
     }
 }

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

@@ -0,0 +1,46 @@
+/**
+ * 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

@@ -0,0 +1,100 @@
+/**
+ * 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();
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return '[circular]';
+        seen.add(value);
+        return value.map((v) => stable(v, seen));
+    }
+    if (value && typeof value === 'object') {
+        if (seen.has(value))
+            return '[circular]';
+        seen.add(value);
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const v = value[key];
+            if (v === undefined)
+                continue;
+            out[key] = stable(v, seen);
+        }
+        return out;
+    }
+    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,
+        condition: config.condition,
+        action: config.action,
+    });
+    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) {
+        if (other.name === config.name)
+            continue;
+        if (monitorFingerprint(other) === fp)
+            return other.name;
+    }
+    return null;
+}

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

@@ -0,0 +1,47 @@
+/**
+ * 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 { 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";
+/** 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'>;
+}
+/**
+ * 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[];
+export 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[];
+}
+/**
+ * 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.
+ */
+export declare function gatherFleetMonitors(): Promise<FleetMonitorsResult>;

package/dist/lib/monitors/remote.js

@@ -0,0 +1,81 @@
+/**
+ * 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 { gatherRemoteAgentsJson } from '../remote-agents-json.js';
+/** Recursion guard: a peer answering the fan-out must not fan out again. */
+export const NO_MONITOR_FANOUT_ENV = 'AGENTS_MONITORS_LOCAL';
+/**
+ * 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 function parseRemoteMonitors(stdout, machine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    // `monitors list --json` writes a BARE array (stdoutJson -> JSON.stringify of
+    // monitors.map(...)); it has never wrapped. Guarding an envelope shape that has
+    // never existed would be a fallback for an imaginary bug.
+    if (!Array.isArray(parsed))
+        return [];
+    const rows = parsed;
+    const out = [];
+    for (const row of rows) {
+        if (!row || typeof row !== 'object' || Array.isArray(row))
+            continue;
+        const m = row;
+        // Without source+condition+action there is no identity to compare, so the
+        // row cannot participate in the duplicate check either way.
+        if (!m.name || !m.source || !m.condition || !m.action)
+            continue;
+        out.push({
+            machine,
+            monitor: { name: m.name, source: m.source, condition: m.condition, action: m.action },
+        });
+    }
+    return out;
+}
+/**
+ * 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.
+ */
+export async function gatherFleetMonitors() {
+    try {
+        const result = await gatherRemoteAgentsJson({
+            args: ['monitors', 'list', '--json'],
+            noFanoutEnv: NO_MONITOR_FANOUT_ENV,
+            parse: parseRemoteMonitors,
+            quiet: true,
+        });
+        return {
+            monitors: result.items,
+            skipped: [...result.skipped, ...result.parseFailed],
+            discoveryFailed: result.discoveryFailed,
+        };
+    }
+    catch {
+        // Could not consult the fleet at all. Reported as such by the caller, never
+        // as an absence of duplicates.
+        return { monitors: [], skipped: [], discoveryFailed: true };
+    }
+}

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

@@ -25,6 +25,31 @@ export interface MonitorState {
     /** Epoch-ms timestamps of recent fires, for the rate-limit / firehose guard. */
     fireTimes?: number[];
 }
+/**
+ * Per-monitor liveness heartbeat, recorded on EVERY poll — fire or not, match or
+ * not. This is deliberately a separate record from MonitorState: change-detection
+ * state (lastHash/lastValue) is written only when a monitor fires or establishes
+ * a baseline, so a monitor that polls steadily but never matches leaves no
+ * change-detection trace. Without a heartbeat, `view` on such a monitor showed
+ * `state: null` — indistinguishable from a monitor the engine never touched, the
+ * exact confusion RUSH-2485 reports. The heartbeat makes "never checked" (no
+ * record) visibly distinct from "checked N times, not matching" (recent record,
+ * zero fires). Kept in its own file so it can never perturb the baseline logic in
+ * decideFire/hasChanged.
+ */
+export interface MonitorLiveness {
+    monitorName: string;
+    /** RFC3339 timestamp of the last poll attempt. */
+    lastCheckedAt: string;
+    /** Total polls the engine has run against this monitor's source. */
+    checkCount: number;
+    /** The last poll's error (source produced nothing / threw), cleared on the next good poll. */
+    lastError?: string;
+    /** Consecutive failed polls; reset to 0 on any successful observation. Drives drought escalation. */
+    consecutiveErrors: number;
+    /** RFC3339 timestamp of the last drought notification, so the engine notifies once per drought. */
+    droughtNotifiedAt?: string;
+}
 /** Per-monitor history root, with the (untrusted) name contained to one segment. */
 export declare function getMonitorHistoryDir(name: string): string;
 /** Directory holding a monitor's fire history. */
@@ -51,6 +76,20 @@ export declare function dedupeSignature(observation: string, dedupeKey?: string)
  * caller persists the new value via writeState only on a real fire.
  */
 export declare function hasChanged(name: string, observation: string, dedupeKey?: string): boolean;
+/** Read a monitor's liveness heartbeat, or null if the engine has never polled it. */
+export declare function readLiveness(name: string): MonitorLiveness | null;
+/**
+ * Record one poll attempt as the monitor's liveness heartbeat — the single call
+ * the engine makes on every evaluation, regardless of fire/match. A successful
+ * observation clears `lastError`/`consecutiveErrors` and any drought flag; a
+ * failed one (source threw or produced nothing) records the error and increments
+ * the consecutive-failure counter the drought escalation reads. Written
+ * atomically (temp + rename) like writeStateRaw, and never touches state.json, so
+ * change-detection is untouched.
+ */
+export declare function recordCheck(name: string, checkedAt: string, error?: string): MonitorLiveness;
+/** Stamp the drought-notified marker so the engine notifies at most once per drought. */
+export declare function markDroughtNotified(name: string, at: string): void;
 /**
  * Append a fire timestamp and return the pruned window (fires within `windowMs`).
  * The engine uses the returned length to decide whether the rate limit tripped.

package/dist/lib/monitors/state.js

@@ -23,6 +23,9 @@ export function getMonitorHistoryDir(name) {
 function getStatePath(name) {
     return path.join(getMonitorHistoryDir(name), 'state.json');
 }
+function getLivenessPath(name) {
+    return path.join(getMonitorHistoryDir(name), 'liveness.json');
+}
 /** Directory holding a monitor's fire history. */
 export function getMonitorFiresDir(name) {
     return path.join(getMonitorHistoryDir(name), 'fires');
@@ -100,6 +103,59 @@ export function hasChanged(name, observation, dedupeKey) {
         return true;
     return prev.lastHash !== hashSignature(observation, dedupeKey);
 }
+/** Read a monitor's liveness heartbeat, or null if the engine has never polled it. */
+export function readLiveness(name) {
+    const livenessPath = getLivenessPath(name);
+    if (!fs.existsSync(livenessPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(livenessPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record one poll attempt as the monitor's liveness heartbeat — the single call
+ * the engine makes on every evaluation, regardless of fire/match. A successful
+ * observation clears `lastError`/`consecutiveErrors` and any drought flag; a
+ * failed one (source threw or produced nothing) records the error and increments
+ * the consecutive-failure counter the drought escalation reads. Written
+ * atomically (temp + rename) like writeStateRaw, and never touches state.json, so
+ * change-detection is untouched.
+ */
+export function recordCheck(name, checkedAt, error) {
+    const prev = readLiveness(name);
+    const consecutiveErrors = error ? (prev?.consecutiveErrors ?? 0) + 1 : 0;
+    const liveness = {
+        monitorName: name,
+        lastCheckedAt: checkedAt,
+        checkCount: (prev?.checkCount ?? 0) + 1,
+        consecutiveErrors,
+        ...(error ? { lastError: error } : {}),
+        // A drought flag only survives while the drought does — cleared on recovery.
+        ...(error && prev?.droughtNotifiedAt ? { droughtNotifiedAt: prev.droughtNotifiedAt } : {}),
+    };
+    ensureAgentsDir();
+    const dir = getMonitorHistoryDir(name);
+    fs.mkdirSync(dir, { recursive: true });
+    const livenessPath = path.join(dir, 'liveness.json');
+    const tmp = `${livenessPath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(liveness, null, 2), 'utf-8');
+    fs.renameSync(tmp, livenessPath);
+    return liveness;
+}
+/** Stamp the drought-notified marker so the engine notifies at most once per drought. */
+export function markDroughtNotified(name, at) {
+    const prev = readLiveness(name);
+    if (!prev)
+        return;
+    const livenessPath = getLivenessPath(name);
+    const next = { ...prev, droughtNotifiedAt: at };
+    const tmp = `${livenessPath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2), 'utf-8');
+    fs.renameSync(tmp, livenessPath);
+}
 /**
  * Append a fire timestamp and return the pruned window (fires within `windowMs`).
  * The engine uses the returned length to decide whether the rate limit tripped.

package/dist/lib/onepassword.d.ts

@@ -29,6 +29,12 @@ export interface ImportableSecret {
     itemTitle: string;
     fieldLabel: string;
     value: string;
+    /**
+     * The item's free-form notes (1Password's `notesPlain` / any NOTES-purpose
+     * field), carried as descriptive metadata for the imported secret. Never the
+     * secret value — omitted when the item has no notes.
+     */
+    description?: string;
 }
 export interface SkippedField {
     itemTitle: string;
@@ -41,6 +47,17 @@ export declare function listItems(vaultName: string): OpItemSummary[];
 export declare function getItem(itemId: string, vaultName: string): OpItem;
 export declare function toEnvKey(title: string): string;
 export declare function slugify(name: string): string;
+/**
+ * Pure transform from a fetched 1Password item to an importable secret (or the
+ * reason it was skipped). Split out of extractSecrets so the field-selection
+ * and notes-extraction logic is exercised directly by tests without shelling
+ * out to `op`.
+ */
+export declare function itemToSecret(item: OpItem): {
+    secret: ImportableSecret;
+} | {
+    skipped: SkippedField;
+};
 export declare function extractSecrets(items: OpItemSummary[], vaultName: string): {
     secrets: ImportableSecret[];
     skipped: SkippedField[];