@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,183 +1,51 @@
-/**
- * Native per-monitor state-diff store.
- *
- * This is the one genuinely new primitive monitors add over routines: a
- * last-observed-*value* store. Routines persist per-*run* metadata but have no
- * last-seen value, so hand-built watchers (the RUSH-1107 SSL watcher) re-invented
- * state-diffing through a markdown memory file every time. This store kills that.
- *
- * Layout (sibling of the runs layout, atomic writes like writeRunMeta):
- *   ~/.agents/.history/monitors/<name>/state.json      # last-seen hash/value + fire bookkeeping
- *   ~/.agents/.history/monitors/<name>/fires/<id>/…    # fire history
- */
 import { type RunMeta } from '../scheduling/routines.js';
 import type { MonitorEvent } from './config.js';
-/** Persisted last-seen state for one monitor. */
 interface MonitorState {
     monitorName: string;
-    /** Hash of the last-seen de-dupe signature (see hasChanged). */
     lastHash: string;
-    /** The last-seen raw observation (truncated for storage). */
     lastValue: string;
-    /** RFC3339 timestamp of the last observation. */
     lastSeenAt: string;
-    /** RFC3339 timestamp of the last fire, when the monitor has ever fired. */
     lastFiredAt?: string;
-    /** 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;
-/** Read a monitor's last-seen state, or null if it has never been observed. */
 export declare function readState(name: string): MonitorState | null;
-/**
- * Record a new observation as the monitor's last-seen state, preserving fire
- * bookkeeping. Truncates the stored raw value so a firehose can't bloat disk.
- */
 export declare function writeState(name: string, value: string, dedupeKey?: string, extra?: Partial<Pick<MonitorState, 'lastFiredAt' | 'fireTimes'>>): MonitorState;
-/**
- * The de-dupe signature for an observation. When `dedupeKey` is set, the
- * signature is the first regex match of dedupeKey against the observation (so
- * "the same event" is same matched token); otherwise it is the full observation.
- * An unmatched dedupeKey falls back to the full observation.
- */
 export declare function dedupeSignature(observation: string, dedupeKey?: string): string;
-/**
- * True when `observation`'s de-dupe signature differs from the monitor's
- * last-seen signature (or the monitor has never been observed). Pure read — the
- * 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.
- */
 export declare function recordFireTime(name: string, now: number, windowMs: number): number[];
-/** Write a fire record to fires/<id>/event.json and return the fire id. */
 export declare function writeFireRecord(event: MonitorEvent, meta?: Record<string, unknown>): string;
-/** A single fire history entry (as read back from disk). */
 interface FireRecord extends MonitorEvent {
     runId?: string;
     action?: string;
     ok?: boolean;
     error?: string;
-    /**
-     * The dispatched run's status AT FIRE TIME, best-effort (RUSH-2690).
-     * `dispatchAction` (lib/monitors/dispatch.ts) only sees a synchronous
-     * snapshot: `executeJobDetached` writes `status: 'running'` before spawning
-     * and returns immediately — the real outcome (`completed`/`failed`/`timeout`)
-     * lands later, asynchronously, in `executeJobDetachedClaimed`'s own
-     * `settle()` on child exit/error (lib/daemon/runner.ts). So a fire recorded
-     * `runStatusAtFire: 'running'` had its `ok` frozen before the run actually
-     * finished — that is the signal a future reconciliation pass (a daemon tick
-     * that revisits `running`-at-fire records and patches `ok` for real) would
-     * scan for. Never used to gate `ok` itself; `resolveFireOutcome` re-reads the
-     * run fresh on every call instead of trusting this snapshot.
-     */
     runStatusAtFire?: RunMeta['status'];
-    /**
-     * The action's postcondition command, snapshotted at fire time with `{event}`
-     * already interpolated (PHNX-2842). `resolveFireOutcome` runs this once the
-     * dispatched run has settled `completed`.
-     */
     postcondition?: string;
-    /** Result of the postcondition check, persisted after the first evaluation. */
     postconditionOk?: boolean;
-    /** stderr/stdout snippet when `postconditionOk` is false. */
     postconditionError?: string;
 }
-/** List a monitor's fire history, chronologically ascending. */
 export declare function listFires(name: string): FireRecord[];
-/** The reconciled outcome of one fire, resolved against the run's live status. */
 interface ReconciledFireOutcome {
-    /** True fire outcome, correcting the frozen `ok` against the run's CURRENT status. */
     ok: boolean;
-    /** The run's live terminal status, when a runId is present and resolvable. */
     runStatus?: RunMeta['status'];
-    /**
-     * Present when a `completed` run had a postcondition to assert (PHNX-2842).
-     * `met` = the command exited 0; `none` = ran but the intended effect did not
-     * happen (the fire must not read as `ok`).
-     */
     effect?: 'met' | 'none';
-    /** Why the fire is not ok, when the postcondition failed. */
     error?: string;
 }
-/**
- * Run a fire's postcondition command. Exit 0 means the intended effect happened;
- * anything else (nonzero, timeout, spawn error, empty command) is "no effect".
- * Real `/bin/sh -c` (or `cmd /c`) — the same seam command sources use.
- */
 export declare function evaluatePostcondition(command: string): {
     ok: boolean;
     error?: string;
 };
-/**
- * Reconcile a fire's frozen `ok` against its dispatched run's REAL, current
- * status — the render-time fix for RUSH-2690 — and, when the run has settled
- * `completed`, against a declared postcondition (PHNX-2842).
- *
- * `writeFireRecord` (this module) persists `ok` once, at fire time, from
- * `dispatchAction`'s synchronous return. For a `run`/`routine` action that
- * return is a snapshot: `executeJobDetached` writes `status: 'running'` before
- * spawning and hands that back immediately, so `dispatchAction`'s negative
- * check (`skipped`/`blocked`/`failed`) never sees the async outcome that lands
- * later via `settle()` — a run that goes on to fail, time out, or otherwise
- * never produce output still reads `ok: true` in `agents monitors runs`
- * forever, while `agents monitors logs` (which reads the run record fresh)
- * shows the real status. Re-reading the run here, at DISPLAY time, closes that
- * gap without touching the write path or the frozen historical record on disk.
- *
- * A fire with no `runId` (a `notify`/`webhook-out` action, or a `run`/`routine`
- * dispatch that never got a runId at all) has nothing to reconcile against —
- * its frozen `ok` is the only signal and is returned as-is.
- *
- * `completed` is not success by itself. An agent that exits 0 without doing
- * the job (merge-on-green that never merged) used to record `ok` because
- * `OK_RUN_STATUSES` treated `completed` as healthy. When the fire carries a
- * `postcondition` command, this function runs it once the run has settled and
- * returns `ok: false, effect: 'none'` when it fails — distinguishing "ran but
- * no effect" from a working fire. The result is persisted on the fire record
- * so later listings do not re-exec the command.
- */
 export declare function resolveFireOutcome(jobName: string, fire: FireRecord): ReconciledFireOutcome;
 export {};

package/dist/lib/monitors/state.js

@@ -1,15 +1,3 @@
-/**
- * Native per-monitor state-diff store.
- *
- * This is the one genuinely new primitive monitors add over routines: a
- * last-observed-*value* store. Routines persist per-*run* metadata but have no
- * last-seen value, so hand-built watchers (the RUSH-1107 SSL watcher) re-invented
- * state-diffing through a markdown memory file every time. This store kills that.
- *
- * Layout (sibling of the runs layout, atomic writes like writeRunMeta):
- *   ~/.agents/.history/monitors/<name>/state.json      # last-seen hash/value + fire bookkeeping
- *   ~/.agents/.history/monitors/<name>/fires/<id>/…    # fire history
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'crypto';
@@ -18,7 +6,6 @@ import { getMonitorsHistoryDir, ensureAgentsDir } from '../state.js';
 import { safeJoin } from '../paths.js';
 import { readRunMeta } from '../scheduling/routines.js';
 const MAX_STORED_VALUE = 4096;
-/** Per-monitor history root, with the (untrusted) name contained to one segment. */
 export function getMonitorHistoryDir(name) {
     return safeJoin(getMonitorsHistoryDir(), name);
 }
@@ -28,11 +15,9 @@ function getStatePath(name) {
 function getLivenessPath(name) {
     return path.join(getMonitorHistoryDir(name), 'liveness.json');
 }
-/** Directory holding a monitor's fire history. */
 function getMonitorFiresDir(name) {
     return path.join(getMonitorHistoryDir(name), 'fires');
 }
-/** Read a monitor's last-seen state, or null if it has never been observed. */
 export function readState(name) {
     const statePath = getStatePath(name);
     if (!fs.existsSync(statePath))
@@ -44,7 +29,6 @@ export function readState(name) {
         return null;
     }
 }
-/** Persist a monitor's state atomically (temp file + rename, like writeRunMeta). */
 function writeStateRaw(state) {
     ensureAgentsDir();
     const dir = getMonitorHistoryDir(state.monitorName);
@@ -54,10 +38,6 @@ function writeStateRaw(state) {
     fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf-8');
     fs.renameSync(tmp, statePath);
 }
-/**
- * Record a new observation as the monitor's last-seen state, preserving fire
- * bookkeeping. Truncates the stored raw value so a firehose can't bloat disk.
- */
 export function writeState(name, value, dedupeKey, extra = {}) {
     const prev = readState(name);
     const state = {
@@ -72,12 +52,6 @@ export function writeState(name, value, dedupeKey, extra = {}) {
     writeStateRaw(state);
     return state;
 }
-/**
- * The de-dupe signature for an observation. When `dedupeKey` is set, the
- * signature is the first regex match of dedupeKey against the observation (so
- * "the same event" is same matched token); otherwise it is the full observation.
- * An unmatched dedupeKey falls back to the full observation.
- */
 export function dedupeSignature(observation, dedupeKey) {
     if (!dedupeKey)
         return observation;
@@ -87,25 +61,18 @@ export function dedupeSignature(observation, dedupeKey) {
             return m[1] ?? m[0];
     }
     catch {
-        /* invalid regex — fall back to full observation */
     }
     return observation;
 }
 function hashSignature(observation, dedupeKey) {
     return createHash('sha256').update(dedupeSignature(observation, dedupeKey)).digest('hex');
 }
-/**
- * True when `observation`'s de-dupe signature differs from the monitor's
- * last-seen signature (or the monitor has never been observed). Pure read — the
- * caller persists the new value via writeState only on a real fire.
- */
 export function hasChanged(name, observation, dedupeKey) {
     const prev = readState(name);
     if (!prev)
         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))
@@ -117,15 +84,6 @@ export function readLiveness(name) {
         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;
@@ -135,7 +93,6 @@ export function recordCheck(name, checkedAt, error) {
         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();
@@ -147,7 +104,7 @@ export function recordCheck(name, checkedAt, error) {
     fs.renameSync(tmp, livenessPath);
     return liveness;
 }
-/** Stamp the drought-notified marker so the engine notifies at most once per drought. */
+// Notify once per drought; a subsequent successful recordCheck clears this marker.
 export function markDroughtNotified(name, at) {
     const prev = readLiveness(name);
     if (!prev)
@@ -158,16 +115,11 @@ export function markDroughtNotified(name, at) {
     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.
- */
 export function recordFireTime(name, now, windowMs) {
     const prev = readState(name);
     const times = [...(prev?.fireTimes ?? []), now].filter((t) => now - t <= windowMs);
     return times;
 }
-/** Write a fire record to fires/<id>/event.json and return the fire id. */
 export function writeFireRecord(event, meta = {}) {
     ensureAgentsDir();
     const fireId = event.firedAt.replace(/[:.]/g, '-');
@@ -176,7 +128,6 @@ export function writeFireRecord(event, meta = {}) {
     fs.writeFileSync(path.join(fireDir, 'event.json'), JSON.stringify({ ...event, ...meta }, null, 2), 'utf-8');
     return fireId;
 }
-/** List a monitor's fire history, chronologically ascending. */
 export function listFires(name) {
     const dir = getMonitorFiresDir(name);
     if (!fs.existsSync(dir))
@@ -195,18 +146,11 @@ export function listFires(name) {
             fires.push(JSON.parse(fs.readFileSync(eventPath, 'utf-8')));
         }
         catch {
-            /* skip corrupt record */
         }
     }
     return fires;
 }
-/** Cap a display-time postcondition so `monitors runs` cannot hang on a stuck command. */
 const POSTCONDITION_TIMEOUT_MS = 15_000;
-/**
- * Run a fire's postcondition command. Exit 0 means the intended effect happened;
- * anything else (nonzero, timeout, spawn error, empty command) is "no effect".
- * Real `/bin/sh -c` (or `cmd /c`) — the same seam command sources use.
- */
 export function evaluatePostcondition(command) {
     const trimmed = command.trim();
     if (!trimmed)
@@ -233,41 +177,13 @@ export function evaluatePostcondition(command) {
     const exit = result.status ?? 'unknown';
     return { ok: false, error: `postcondition not met${detail ? `: ${detail}` : ` (exit ${exit})`}` };
 }
-/** Persist the postcondition result onto the existing fire record. Frozen `ok` is left as the fire-time snapshot. */
 function persistPostcondition(fire, result) {
     writeFireRecord(fire, {
         postconditionOk: result.ok,
         ...(result.error ? { postconditionError: result.error } : {}),
     });
 }
-/**
- * Reconcile a fire's frozen `ok` against its dispatched run's REAL, current
- * status — the render-time fix for RUSH-2690 — and, when the run has settled
- * `completed`, against a declared postcondition (PHNX-2842).
- *
- * `writeFireRecord` (this module) persists `ok` once, at fire time, from
- * `dispatchAction`'s synchronous return. For a `run`/`routine` action that
- * return is a snapshot: `executeJobDetached` writes `status: 'running'` before
- * spawning and hands that back immediately, so `dispatchAction`'s negative
- * check (`skipped`/`blocked`/`failed`) never sees the async outcome that lands
- * later via `settle()` — a run that goes on to fail, time out, or otherwise
- * never produce output still reads `ok: true` in `agents monitors runs`
- * forever, while `agents monitors logs` (which reads the run record fresh)
- * shows the real status. Re-reading the run here, at DISPLAY time, closes that
- * gap without touching the write path or the frozen historical record on disk.
- *
- * A fire with no `runId` (a `notify`/`webhook-out` action, or a `run`/`routine`
- * dispatch that never got a runId at all) has nothing to reconcile against —
- * its frozen `ok` is the only signal and is returned as-is.
- *
- * `completed` is not success by itself. An agent that exits 0 without doing
- * the job (merge-on-green that never merged) used to record `ok` because
- * `OK_RUN_STATUSES` treated `completed` as healthy. When the fire carries a
- * `postcondition` command, this function runs it once the run has settled and
- * returns `ok: false, effect: 'none'` when it fails — distinguishing "ran but
- * no effect" from a working fire. The result is persisted on the fire record
- * so later listings do not re-exec the command.
- */
+// Fire-time success is provisional: re-read the run, require any postcondition, and persist that result once.
 export function resolveFireOutcome(jobName, fire) {
     if (!fire.runId)
         return { ok: fire.ok !== false };

package/dist/lib/native-accounts.d.ts

@@ -1,35 +1,3 @@
-/**
- * Native-account lookup leaf (PHNX-3940).
- *
- * A PURE, types-only module: it answers "which registered account is this
- * email / what does its identity key decode to" from a `Meta` snapshot passed
- * in by the caller — it never reads state, the keychain, or the network, and it
- * imports nothing from `account-registry` (which imports the agent-spec engine).
- * That import-graph constraint is load-bearing: `agent-spec/agents.ts`
- * completes an email-only worker home from the registry row here, and importing
- * `account-registry` there would be a cycle. `account-registry` re-exports both
- * functions so existing callers keep one import site.
- *
- * The merge of central (`accounts.native`, `scope:'version'`) and device-scoped
- * (`deviceAccounts.native`) rows mirrors `listNativeAccounts`, inlined so this
- * module stays a leaf.
- */
 import type { AgentId, Meta, NativeAccountRecord } from './types.js';
-/**
- * The one native row for `agent` whose `identityLabel` (email) matches, or null.
- *
- * Returns null when zero OR several rows match — never guesses. Several rows can
- * share one email (a Team seat AND a personal Max under the same address are two
- * accounts, two orgs), and picking one would attribute a worker home to the
- * wrong org. The read-side caller falls closed to email-only identity in that
- * case, which is correct: an ambiguous identity is better left unresolved than
- * resolved wrong.
- */
 export declare function registeredNativeAccountForEmail(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, agent: AgentId, email: string): NativeAccountRecord | null;
-/**
- * Decode an `<agent>:<label>=<value>[:<label>=<value>…]` identity key into its
- * parts, or null when it does not belong to `agent` or is malformed. The key
- * shape is what `buildIdentityKey` in `agent-spec/agents.ts` writes — e.g.
- * `claude:account=<uuid>:org=<uuid>` → `{ account, org }`.
- */
 export declare function parseNativeIdentityKey(agent: AgentId, identityKey: string): Record<string, string> | null;

package/dist/lib/native-accounts.js

@@ -1,18 +1,7 @@
-/** Central + device-scoped native rows, device winning on a shared id. */
 function mergedNativeAccounts(meta) {
     const merged = { ...meta.accounts?.native, ...meta.deviceAccounts?.native };
     return Object.values(merged);
 }
-/**
- * The one native row for `agent` whose `identityLabel` (email) matches, or null.
- *
- * Returns null when zero OR several rows match — never guesses. Several rows can
- * share one email (a Team seat AND a personal Max under the same address are two
- * accounts, two orgs), and picking one would attribute a worker home to the
- * wrong org. The read-side caller falls closed to email-only identity in that
- * case, which is correct: an ambiguous identity is better left unresolved than
- * resolved wrong.
- */
 export function registeredNativeAccountForEmail(meta, agent, email) {
     const needle = email.trim().toLowerCase();
     if (!needle)
@@ -20,12 +9,6 @@ export function registeredNativeAccountForEmail(meta, agent, email) {
     const matches = mergedNativeAccounts(meta).filter((account) => account.agent === agent && account.identityLabel?.trim().toLowerCase() === needle);
     return matches.length === 1 ? matches[0] : null;
 }
-/**
- * Decode an `<agent>:<label>=<value>[:<label>=<value>…]` identity key into its
- * parts, or null when it does not belong to `agent` or is malformed. The key
- * shape is what `buildIdentityKey` in `agent-spec/agents.ts` writes — e.g.
- * `claude:account=<uuid>:org=<uuid>` → `{ account, org }`.
- */
 export function parseNativeIdentityKey(agent, identityKey) {
     const prefix = `${agent}:`;
     if (!identityKey.startsWith(prefix))

package/dist/lib/net-close.d.ts

@@ -1,11 +1,2 @@
-/**
- * Bounded-close helper for a local `net.Server`. Generic — no secrets/engine
- * dependency — so consumers that only needed it for that reason (the webhook
- * receiver, the daemon's webhook service) no longer import `lib/secrets/*`.
- */
 import type * as net from 'node:net';
-/**
- * Close `server`, resolving once closed or after `timeoutMs`, whichever comes
- * first — a shutdown must never hang on a client that never disconnects.
- */
 export declare function closeServerBounded(server: net.Server, timeoutMs?: number): Promise<void>;

package/dist/lib/net-close.js

@@ -1,8 +1,4 @@
 const SERVER_CLOSE_TIMEOUT_MS = 5000;
-/**
- * Close `server`, resolving once closed or after `timeoutMs`, whichever comes
- * first — a shutdown must never hang on a client that never disconnects.
- */
 export function closeServerBounded(server, timeoutMs = SERVER_CLOSE_TIMEOUT_MS) {
     return new Promise((resolve) => {
         let settled = false;
@@ -18,7 +14,6 @@ export function closeServerBounded(server, timeoutMs = SERVER_CLOSE_TIMEOUT_MS)
             server.close(() => finish());
         }
         catch {
-            // Already closed / not listening — treat as released.
             finish();
         }
     });

package/dist/lib/notify.d.ts

@@ -1,43 +1,15 @@
-/**
- * Owner notifier — the one seam for "ping the human" messages.
- *
- * Every human-facing owner notification (feed urgent-block dispatch, monitor
- * `notify` action, `agents send --to owner`) funnels through the single channel seam:
- * `lookupTransport(channel, meta).provider.send(text, opts)`. The recipient comes
- * from `humans.yaml` — never a hardcoded chat id — so changing the
- * owner is honoured by every path at once. `notify.transports` picks the actual
- * provider per host (rush telegram on zion, openclaw-telegram on mac-mini).
- * Best-effort: a delivery failure is returned to the caller, never thrown, so a
- * notification hiccup never blocks the agent. That is why this module resolves
- * with `lookupTransport` and not the `die()`-capable `resolveTransport` — the
- * monitor daemon and the feed-dispatch loop call in here, and `process.exit()`
- * would take them down on a typo'd channel name, bypassing their try/catch.
- */
 import type { OpenBlock } from './feed/feed.js';
 import type { Meta } from './types.js';
 import type { SendResult } from './channels/registry.js';
 import { type SinkMessageFormat } from './sink-format.js';
 export interface OwnerNotifyOptions {
-    /** Config source (defaults to `readMeta()`); lets callers/tests inject it. */
     meta?: Meta;
-    /** Override the owner channel resolved from humans.yaml. */
     channel?: string;
-    /** Override the owner target resolved from humans.yaml. */
     target?: string;
-    /** Resolve + build the delivery but do not actually send. */
     dryRun?: boolean;
     thread?: string;
     attachments?: string[];
     from?: string;
-    /**
-     * Per-destination body composer (PHNX-3698). The owner policy fans one alert
-     * out to several channels (imessage + slack, …), and only Slack can render a
-     * labeled link — so when set, each destination gets the body shaped for its
-     * OWN resolved provider (Slack → `mrkdwn` `<url|label>` links, everything else
-     * → `plain` the human sentence, no URLs) instead of the single `text` going to
-     * every channel. Absent for callers whose body is already final (urgent
-     * blocks, monitor summaries): `text` is delivered verbatim to every channel.
-     */
     composeForFormat?: (format: SinkMessageFormat) => string;
 }
 export interface NotifyResult {
@@ -46,29 +18,10 @@ export interface NotifyResult {
     error?: string;
 }
 export declare function formatUrgentBlockMessage(block: OpenBlock): string;
-/**
- * Build openclaw argv for a Telegram send (used by the openclaw-telegram
- * provider and its tests). `target` is required — the recipient is always
- * resolved by the caller, never defaulted to a hardcoded number here.
- */
 export declare function buildOpenClawNotifyArgs(text: string, opts: {
     target: string;
     channel?: string;
     account?: string;
 }): string[];
-/**
- * Deliver a message to the configured owner through the one channel seam.
- * `channel`/`target` default to the normal owner channel in humans.yaml; `notify.transports`
- * selects the provider per host. A missing owner config or a delivery failure
- * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
- * ENOENT — so callers surface a consistent, best-effort failure.
- *
- * When local delivery fails because THIS box structurally cannot reach the owner
- * — the rush-backed owner channel is macOS-only, so a headless Linux worker can
- * never ring the phone (PHNX-3303) — the notify is forwarded over SSH to a
- * capable fleet peer that DOES have the provider, mirroring the reroute
- * `agents message` already uses. A successful forward is returned as the result;
- * if no capable peer is reachable, the original clean local error stands.
- */
 export declare function sendToOwner(text: string, options?: OwnerNotifyOptions): Promise<SendResult>;
 export declare function notifyUrgentBlock(block: OpenBlock, options?: OwnerNotifyOptions): Promise<NotifyResult>;

package/dist/lib/notify.js

@@ -13,11 +13,6 @@ export function formatUrgentBlockMessage(block) {
     const cost = block.costOfDelay ?? 'low';
     return `URGENT ${cls.toUpperCase()}${host}: ${header}${text} (cost: ${cost}, id: ${block.blockId})`;
 }
-/**
- * Build openclaw argv for a Telegram send (used by the openclaw-telegram
- * provider and its tests). `target` is required — the recipient is always
- * resolved by the caller, never defaulted to a hardcoded number here.
- */
 export function buildOpenClawNotifyArgs(text, opts) {
     const channel = opts.channel ?? 'telegram';
     const account = opts.account ?? 'default';
@@ -34,20 +29,6 @@ export function buildOpenClawNotifyArgs(text, opts) {
         text,
     ];
 }
-/**
- * Deliver a message to the configured owner through the one channel seam.
- * `channel`/`target` default to the normal owner channel in humans.yaml; `notify.transports`
- * selects the provider per host. A missing owner config or a delivery failure
- * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
- * ENOENT — so callers surface a consistent, best-effort failure.
- *
- * When local delivery fails because THIS box structurally cannot reach the owner
- * — the rush-backed owner channel is macOS-only, so a headless Linux worker can
- * never ring the phone (PHNX-3303) — the notify is forwarded over SSH to a
- * capable fleet peer that DOES have the provider, mirroring the reroute
- * `agents message` already uses. A successful forward is returned as the result;
- * if no capable peer is reachable, the original clean local error stands.
- */
 export async function sendToOwner(text, options = {}) {
     const meta = options.meta ?? readMeta();
     const canonical = getOwnerNotifyDestinationsFromHumans();
@@ -74,12 +55,6 @@ export async function sendToOwner(text, options = {}) {
     const deliveries = [];
     for (const { channel, to: target } of addressable) {
         const { provider, providerName, error } = lookupTransport(channel, meta);
-        // Each destination gets the body shaped for the provider it ACTUALLY
-        // delivers through (the same `notify.transports` remap `lookupTransport`
-        // applied), so a Slack destination turns its ticket keys + session crumb
-        // into `<url|label>` links while a sibling iMessage copy stays plain
-        // (PHNX-3698). Without a composer the caller's already-final `text` is used
-        // for every channel.
         const body = options.composeForFormat
             ? options.composeForFormat(sinkMessageFormat(providerName))
             : text;
@@ -99,8 +74,6 @@ export async function sendToOwner(text, options = {}) {
         catch (err) {
             result = { ok: false, channel, id: target, error: err.message };
         }
-        // A dry-run never delivers, and an override target is an explicit recipient
-        // (not the fleet-wide owner) — neither should hop to a peer.
         if (!result.ok && !options.dryRun && options.target === undefined) {
             if (options.attachments?.length) {
                 result = {
@@ -114,9 +87,6 @@ export async function sendToOwner(text, options = {}) {
                 }) ?? result;
             }
         }
-        // Echo the exact per-destination body delivered, so a caller (and
-        // `agents send --to owner --dry-run --json`) can see Slack got the labeled-link
-        // variant and iMessage the plain one — the observable proof of PHNX-3698.
         deliveries.push({ ...result, body });
     }
     if (deliveries.length === 1)

package/dist/lib/onepassword.d.ts

@@ -1,6 +1,3 @@
-/**
- * 1Password CLI (op) integration for importing secrets from vaults.
- */
 interface OpItemSummary {
     id: string;
     title: string;
@@ -25,11 +22,6 @@ 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;
 }
 interface SkippedField {
@@ -40,12 +32,6 @@ interface SkippedField {
 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;
 } | {