@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/daemon-ticks.d.ts

@@ -1,19 +1,3 @@
-/**
- * Daemon account-state tick bodies.
- *
- * These two bodies are the `refreshUsage` / `refreshAuth` implementations the
- * supervised `AccountStateDaemonService` (daemon/account-state-daemon-service.ts)
- * runs on its tick, in-process (usage every tick, auth on the slower ~3 min
- * cadence). They are NOT routines and are never fired through the scheduler — the
- * daemon owns usage and authentication health as first-party device state
- * (RUSH-2451); the supervisor bounds each tick with a deadline + AbortSignal so a
- * hung refresh is abandoned and restarted instead of latching (PHNX-3608).
- *
- * `refreshLocalFleetAuthState` is also called by `agents fleet`/`ssh` surfaces
- * that need a fresh local auth snapshot on demand; provider-level work is guarded
- * by the cross-process refresh lease so an explicit CLI refresh and the daemon
- * timer converge on the same published result.
- */
 import type { FleetStatusRow } from './fleet-status.js';
 import { type AuthProbeRow } from './auth-health.js';
 export { AUTH_PROBE_MAX_AGE_MS } from './auth-health.js';
@@ -21,61 +5,9 @@ export declare function isFreshFleetAuthSnapshot(value: {
     row: FleetStatusRow;
     authRows: AuthProbeRow[];
 }, minimumCapturedAt: number): boolean;
-/**
- * How stale a cached auth verdict may get before the periodic tick re-probes.
- *
- * The auth verdict rides the same rate-limited `/api/oauth/usage` endpoint as
- * the usage probe. Firing it every 3-minute tick on every fleet device drove one
- * per-account request quota to a permanent 429, and the shared backoff then
- * parked usage fleet-wide and froze the usage cache (RUSH-2998). Re-probing at
- * most every 20 minutes cuts that endpoint traffic ~5x while still catching a
- * revocation within one window — and every device keeps a REAL verdict (not a
- * degraded "unverified"), so `agents devices ping --strict` and the run
- * auth-preflight keep working on every host, unlike a publisher/subscriber split
- * that would blind every non-primary box to revocation. Fleet status still
- * publishes every tick — it does not ride that endpoint.
- */
-/**
- * The cached rows still backed by a home on this device, by `authTargetKey`.
- *
- * A row for an uninstalled version is an ORPHAN: the probe enumerates installed
- * homes + account slots, so nothing re-probes it and its `checkedAt` is frozen
- * at whatever the last probe left. Pure — unit-tested.
- */
 export declare function installedAuthRows(authRows: readonly AuthProbeRow[], installedTargets: ReadonlySet<string>): AuthProbeRow[];
-/**
- * True when every cached auth row FOR AN INSTALLED HOME was probed within
- * {@link AUTH_PROBE_MAX_AGE_MS} — i.e. reusing them would not let a verdict get
- * staler than one probe window. No installed row is never fresh (nothing to
- * reuse). Pure — unit-tested.
- *
- * Orphan rows are excluded rather than counted stale (PHNX-4051). Counting them
- * made this permanently false on any box that had ever uninstalled a version:
- * the orphan can never be re-probed, so the tick live-probed the rate-limited
- * `/api/oauth/usage` for every account every 3 minutes, re-arming the per-account
- * 429 backoff and parking the usage refresher — the RUSH-2998 failure the reuse
- * window exists to prevent. Observed on yosemite-m0 (rows dated Sep 2 / Sep 6 for
- * uninstalled Claude versions).
- */
 export declare function isCachedFleetAuthProbeFresh(authRows: readonly AuthProbeRow[], now: number, installedTargets: ReadonlySet<string>, maxAgeMs?: number): boolean;
-/**
- * Whether the tick may reuse the cached auth verdict instead of re-probing the
- * rate-limited endpoint. `force` (an on-demand `agents devices ping`) ALWAYS
- * re-probes — the whole point of the command is a genuinely live verdict, and
- * missing this `!force` is exactly how a `--strict` check silently passed a
- * revoked account (the second `runFleetPing` call site, RUSH-2998). Pure —
- * unit-tested so that inversion cannot regress unnoticed.
- */
 export declare function shouldReuseCachedAuthProbe(force: boolean, cached: readonly AuthProbeRow[], now: number, installedTargets: ReadonlySet<string>, maxAgeMs?: number): boolean;
-/**
- * Fleet cache warm: publish THIS host's row for the caches `agents fleet
- * status` / `agents devices list` read (PUBLISH-OWN / READ-UNION, RUSH-2061).
- *
- * `force` is set by on-demand callers (`agents devices ping`) that must return a
- * genuinely live verdict; the periodic daemon tick leaves it unset so it reuses a
- * recent verdict per {@link AUTH_PROBE_MAX_AGE_MS} instead of hammering the
- * rate-limited endpoint every 3 minutes (RUSH-2998).
- */
 export declare function refreshLocalFleetAuthState(opts?: {
     force?: boolean;
     signal?: AbortSignal;
@@ -84,75 +16,17 @@ export declare function refreshLocalFleetAuthState(opts?: {
     authRows: import('./auth-health.js').AuthProbeRow[];
 }>;
 export declare function runFleetCacheWarmTick(signal?: AbortSignal): Promise<void>;
-/**
- * Usage refresh: keep the usage cache the `agents run` router reads
- * (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
- * Every host is its own provider-facing writer — it refreshes only the
- * accounts it holds credentials for, straight from the provider APIs
- * (RUSH-3193 #15; no cross-host broadcast).
- */
 export declare function runUsageRefreshTick(signal?: AbortSignal): Promise<void>;
-/**
- * Active-sessions warm (RUSH-2062 / RUSH-2484): publish THIS host's live session
- * rows so `agents sessions watch` (and the extension that tails it) receive
- * journal deltas. Publish-own only — no cross-host SSH.
- *
- * Cadence matches {@link DEFAULT_ACTIVE_CACHE_MAX_AGE_MS} so one-shot readers and
- * long-lived watchers share one writer. Without this tick the journal has no
- * continuous producer and Factory freezes after the initial cache snapshot.
- *
- * Gated on reader presence (RUSH-3193): when no `sessions watch` / `feed watch`
- * consumer has checked in within {@link ACTIVE_SESSIONS_READER_IDLE_WINDOW_MS} the
- * expensive `ps`+`lsof` gather is skipped entirely on this scheduled tick. A
- * watcher connecting to a cold/idle daemon is NOT served by this tick alone —
- * {@link noteActiveSessionsJournalReader} only writes a presence timestamp, with
- * no path back to this timer — so the daemon separately runs
- * {@link watchActiveSessionsReaderPresence} to detect that idle→recent edge and
- * fire an out-of-band call into this same function immediately (RUSH-2484).
- */
 export declare function runActiveSessionsWarmTick(opts?: {
     gather?: () => Promise<import('./session/active.js').ActiveSession[]>;
     nowMs?: number;
 }): Promise<{
     sessions: number;
 }>;
-/**
- * Session-index warm (RUSH-2682): incrementally scan THIS host's transcript dirs
- * into the local SQLite index on a timer, so a session started HERE reaches this
- * box's index within seconds instead of on the next unrelated `agents sessions*`
- * call. Indexing was otherwise lazy — only `discoverSessions` writes the index,
- * and nothing scheduled it — which inverted freshness: a peer's session arrived
- * via sync in ~0s while a locally-started one sat unindexed for minutes.
- *
- * The scan is incremental (only files whose mtime/size changed) and single-flight
- * across processes via the DB scan claim, so a foreground `agents sessions*` and
- * this tick never double-scan. The daemon is the single scheduled executor,
- * consistent with the one-scheduler rule.
- *
- * Calls `scanSessionsIncremental`, NOT `discoverSessions` (RUSH-2691). A bare
- * `discoverSessions()` ends in a listing query that defaults its cwd filter to
- * `process.cwd()` — the daemon's, i.e. `$HOME` — and caps at 50, so its row count
- * described "sessions whose cwd is exactly $HOME", which is 0 on a normal box no
- * matter how much the scan indexed. The tick reported that 0 every 20s while
- * still paying for the query's existence check and Linear fetch. Scanning
- * directly reports what was actually parsed and skips the query entirely.
- */
 export declare function runSessionIndexWarmTick(): Promise<{
     indexed: number;
     claimed: boolean;
 }>;
-/**
- * Deferred tool-index pass for large-transcript harnesses (PHNX-3411).
- *
- * Kimi (wire.jsonl) and Grok (chat_history.jsonl) scanners produce only
- * metadata — no events. Calling parseSession for those on the warm tick wedges
- * the Node event loop when the transcript is large and active (observed: several
- * seconds per tick on zion, causing browser IPC ECONNREFUSED). This pass fills
- * the gap: it queries recently-active kimi/grok sessions and calls
- * ensureToolIndex, which uses tool_scan_ledger stamps to skip already-current
- * sessions and applies byte/file budget caps so no large transcript monopolises
- * the tick.
- */
 export declare function runDeferredToolIndex(): Promise<{
     indexed: number;
 }>;

package/dist/lib/daemon-ticks.js

@@ -1,19 +1,3 @@
-/**
- * Daemon account-state tick bodies.
- *
- * These two bodies are the `refreshUsage` / `refreshAuth` implementations the
- * supervised `AccountStateDaemonService` (daemon/account-state-daemon-service.ts)
- * runs on its tick, in-process (usage every tick, auth on the slower ~3 min
- * cadence). They are NOT routines and are never fired through the scheduler — the
- * daemon owns usage and authentication health as first-party device state
- * (RUSH-2451); the supervisor bounds each tick with a deadline + AbortSignal so a
- * hung refresh is abandoned and restarted instead of latching (PHNX-3608).
- *
- * `refreshLocalFleetAuthState` is also called by `agents fleet`/`ssh` surfaces
- * that need a fresh local auth snapshot on demand; provider-level work is guarded
- * by the cross-process refresh lease so an explicit CLI refresh and the daemon
- * timer converge on the same published result.
- */
 import { AUTH_PROBE_MAX_AGE_MS, authTargetKey } from './auth-health.js';
 export { AUTH_PROBE_MAX_AGE_MS } from './auth-health.js';
 export function isFreshFleetAuthSnapshot(value, minimumCapturedAt) {
@@ -21,68 +5,16 @@ export function isFreshFleetAuthSnapshot(value, minimumCapturedAt) {
         && value.authRows.length > 0
         && value.authRows.every(authRow => authRow.health.checkedAt >= minimumCapturedAt);
 }
-/**
- * How stale a cached auth verdict may get before the periodic tick re-probes.
- *
- * The auth verdict rides the same rate-limited `/api/oauth/usage` endpoint as
- * the usage probe. Firing it every 3-minute tick on every fleet device drove one
- * per-account request quota to a permanent 429, and the shared backoff then
- * parked usage fleet-wide and froze the usage cache (RUSH-2998). Re-probing at
- * most every 20 minutes cuts that endpoint traffic ~5x while still catching a
- * revocation within one window — and every device keeps a REAL verdict (not a
- * degraded "unverified"), so `agents devices ping --strict` and the run
- * auth-preflight keep working on every host, unlike a publisher/subscriber split
- * that would blind every non-primary box to revocation. Fleet status still
- * publishes every tick — it does not ride that endpoint.
- */
-/**
- * The cached rows still backed by a home on this device, by `authTargetKey`.
- *
- * A row for an uninstalled version is an ORPHAN: the probe enumerates installed
- * homes + account slots, so nothing re-probes it and its `checkedAt` is frozen
- * at whatever the last probe left. Pure — unit-tested.
- */
 export function installedAuthRows(authRows, installedTargets) {
     return authRows.filter((r) => installedTargets.has(authTargetKey(r.agent, r.version)));
 }
-/**
- * True when every cached auth row FOR AN INSTALLED HOME was probed within
- * {@link AUTH_PROBE_MAX_AGE_MS} — i.e. reusing them would not let a verdict get
- * staler than one probe window. No installed row is never fresh (nothing to
- * reuse). Pure — unit-tested.
- *
- * Orphan rows are excluded rather than counted stale (PHNX-4051). Counting them
- * made this permanently false on any box that had ever uninstalled a version:
- * the orphan can never be re-probed, so the tick live-probed the rate-limited
- * `/api/oauth/usage` for every account every 3 minutes, re-arming the per-account
- * 429 backoff and parking the usage refresher — the RUSH-2998 failure the reuse
- * window exists to prevent. Observed on yosemite-m0 (rows dated Sep 2 / Sep 6 for
- * uninstalled Claude versions).
- */
 export function isCachedFleetAuthProbeFresh(authRows, now, installedTargets, maxAgeMs = AUTH_PROBE_MAX_AGE_MS) {
     const installed = installedAuthRows(authRows, installedTargets);
     return installed.length > 0 && installed.every((r) => now - r.health.checkedAt < maxAgeMs);
 }
-/**
- * Whether the tick may reuse the cached auth verdict instead of re-probing the
- * rate-limited endpoint. `force` (an on-demand `agents devices ping`) ALWAYS
- * re-probes — the whole point of the command is a genuinely live verdict, and
- * missing this `!force` is exactly how a `--strict` check silently passed a
- * revoked account (the second `runFleetPing` call site, RUSH-2998). Pure —
- * unit-tested so that inversion cannot regress unnoticed.
- */
 export function shouldReuseCachedAuthProbe(force, cached, now, installedTargets, maxAgeMs = AUTH_PROBE_MAX_AGE_MS) {
     return !force && isCachedFleetAuthProbeFresh(cached, now, installedTargets, maxAgeMs);
 }
-/**
- * Fleet cache warm: publish THIS host's row for the caches `agents fleet
- * status` / `agents devices list` read (PUBLISH-OWN / READ-UNION, RUSH-2061).
- *
- * `force` is set by on-demand callers (`agents devices ping`) that must return a
- * genuinely live verdict; the periodic daemon tick leaves it unset so it reuses a
- * recent verdict per {@link AUTH_PROBE_MAX_AGE_MS} instead of hammering the
- * rate-limited endpoint every 3 minutes (RUSH-2998).
- */
 export async function refreshLocalFleetAuthState(opts) {
     const force = opts?.force === true;
     const signal = opts?.signal;
@@ -103,22 +35,13 @@ export async function refreshLocalFleetAuthState(opts) {
                 return null;
             return { row, authRows: readFleetAuthRows(self) };
         },
-        // A recent daemon publication is the completed result, not a reason to probe
-        // every provider a second time. An on-demand caller (force) never accepts a
-        // cached snapshot — it must return a genuinely live verdict.
         isCompleted: (value) => !force && isFreshFleetAuthSnapshot(value, minimumCapturedAt),
         refresh: async () => {
-            // Re-probe the rate-limited /oauth/usage endpoint at most every
-            // AUTH_PROBE_MAX_AGE_MS; reuse the last real verdict in between (RUSH-2998).
-            // Fleet status publishes every tick regardless — it does not ride that endpoint.
             const installed = localAuthTargetKeys();
             const cached = readFleetAuthRows(self);
             const live = installedAuthRows(cached, installed);
             const reuse = shouldReuseCachedAuthProbe(force, cached, requestedAt, installed);
             const authRows = reuse ? live : await probeLocalFleetAuth({ cliVersion: getCliVersion(), forceLive: force, signal });
-            // Write when we probed, and ALSO when the cache holds orphan rows for homes
-            // that are gone: a reusing tick is the common case, so leaving the prune on
-            // the probe branch would keep them in `agents view` indefinitely (PHNX-4051).
             if (!reuse || live.length !== cached.length)
                 writeFleetAuthRows(self, authRows, installed);
             const row = await publishLocalFleetStatus(self);
@@ -128,19 +51,10 @@ export async function refreshLocalFleetAuthState(opts) {
 }
 export async function runFleetCacheWarmTick(signal) {
     const result = await refreshLocalFleetAuthState({ signal });
-    // A waiter receives the already-published fleet row. The auth-row count is
-    // available only to the process that performed the provider probes.
     const row = result.row;
     const authCount = result.authRows.length;
     console.log(`fleet cache warm: ${authCount} auth row(s) refreshed, ${row.agents.running} running agent(s) on ${row.host}`);
 }
-/**
- * Usage refresh: keep the usage cache the `agents run` router reads
- * (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
- * Every host is its own provider-facing writer — it refreshes only the
- * accounts it holds credentials for, straight from the provider APIs
- * (RUSH-3193 #15; no cross-host broadcast).
- */
 export async function runUsageRefreshTick(signal) {
     const { runUsageRefresh, buildLocalUsageAccounts } = await import('./usage-refresh.js');
     const { writeClaudeUsageCache, readClaudeUsageCache } = await import('./accounting/usage.js');
@@ -150,16 +64,9 @@ export async function runUsageRefreshTick(signal) {
         listAccounts: buildLocalUsageAccounts,
         writeUsageCache: writeClaudeUsageCache,
         backoffUntil: (agentId, usageKey) => usageRateLimitedUntil(agentId, Date.now(), usageKey),
-        // The free statusline ingest of a live `agents run` writes this same cache,
-        // so a recent capture means the account is already fresh at zero API cost —
-        // the refresher re-derives headroom from it and skips the API fetch.
         readCachedSnapshot: (usageKey) => readClaudeUsageCache(usageKey),
-        // Thread the supervisor deadline into each provider fetch so the tick's I/O
-        // is bounded by deadlineMs, not just each fetch's own 5s timeout (PHNX-3608).
         signal,
         pollerDevice: machineId(),
-        // A changed poll refreshes this box's own state file so the next usage-sync
-        // fan-out (or a placement probe before it) sends the new reading.
         onSnapshotsChanged: async () => {
             const { publishUsageSnapshotToSharedStore } = await import('./accounting/usage-sync.js');
             await publishUsageSnapshotToSharedStore();
@@ -170,24 +77,6 @@ export async function runUsageRefreshTick(signal) {
     const byok = await refreshDueByokUsage(listProfiles());
     console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped, ${r.skippedBudget} over-budget, ${r.skippedFresh} statusline-fresh; BYOK ${byok.refreshed} refreshed, ${byok.skipped} not-due`);
 }
-/**
- * Active-sessions warm (RUSH-2062 / RUSH-2484): publish THIS host's live session
- * rows so `agents sessions watch` (and the extension that tails it) receive
- * journal deltas. Publish-own only — no cross-host SSH.
- *
- * Cadence matches {@link DEFAULT_ACTIVE_CACHE_MAX_AGE_MS} so one-shot readers and
- * long-lived watchers share one writer. Without this tick the journal has no
- * continuous producer and Factory freezes after the initial cache snapshot.
- *
- * Gated on reader presence (RUSH-3193): when no `sessions watch` / `feed watch`
- * consumer has checked in within {@link ACTIVE_SESSIONS_READER_IDLE_WINDOW_MS} the
- * expensive `ps`+`lsof` gather is skipped entirely on this scheduled tick. A
- * watcher connecting to a cold/idle daemon is NOT served by this tick alone —
- * {@link noteActiveSessionsJournalReader} only writes a presence timestamp, with
- * no path back to this timer — so the daemon separately runs
- * {@link watchActiveSessionsReaderPresence} to detect that idle→recent edge and
- * fire an out-of-band call into this same function immediately (RUSH-2484).
- */
 export async function runActiveSessionsWarmTick(opts = {}) {
     const { publishLocalActiveSessions, isActiveSessionsJournalReaderRecent } = await import('./session/session-cache.js');
     const nowMs = opts.nowMs ?? Date.now();
@@ -195,18 +84,11 @@ export async function runActiveSessionsWarmTick(opts = {}) {
         console.log('active-sessions warm: idle (no recent reader), skipping gather');
         return { sessions: 0 };
     }
-    // ONE gather per tick, then fold, then publish. The order is load-bearing:
-    // the publish's per-row merge reads the timeline cache, so folding first is
-    // what puts a CURRENT timeline on the row this tick writes to the journal
-    // rather than the previous tick's (PHNX-3939).
     const gather = opts.gather ?? (async () => {
         const { getActiveSessions } = await import('./session/active.js');
         return getActiveSessions({ localOnly: true });
     });
     const gathered = await gather();
-    // Bounded so it can never own the tick: at most 8 sessions, and for the
-    // resumable harnesses only the bytes each transcript grew by. A failure here
-    // must not cost the publish.
     const { runTimelinePassSync } = await import('./session/timeline-pass.js');
     let timeline = { computed: 0, reused: 0, skipped: 0 };
     try {
@@ -220,59 +102,22 @@ export async function runActiveSessionsWarmTick(opts = {}) {
         + `timeline ${timeline.computed} folded, ${timeline.reused} current, ${timeline.skipped} skipped`);
     return { sessions: r.sessions.length };
 }
-/**
- * Session-index warm (RUSH-2682): incrementally scan THIS host's transcript dirs
- * into the local SQLite index on a timer, so a session started HERE reaches this
- * box's index within seconds instead of on the next unrelated `agents sessions*`
- * call. Indexing was otherwise lazy — only `discoverSessions` writes the index,
- * and nothing scheduled it — which inverted freshness: a peer's session arrived
- * via sync in ~0s while a locally-started one sat unindexed for minutes.
- *
- * The scan is incremental (only files whose mtime/size changed) and single-flight
- * across processes via the DB scan claim, so a foreground `agents sessions*` and
- * this tick never double-scan. The daemon is the single scheduled executor,
- * consistent with the one-scheduler rule.
- *
- * Calls `scanSessionsIncremental`, NOT `discoverSessions` (RUSH-2691). A bare
- * `discoverSessions()` ends in a listing query that defaults its cwd filter to
- * `process.cwd()` — the daemon's, i.e. `$HOME` — and caps at 50, so its row count
- * described "sessions whose cwd is exactly $HOME", which is 0 on a normal box no
- * matter how much the scan indexed. The tick reported that 0 every 20s while
- * still paying for the query's existence check and Linear fetch. Scanning
- * directly reports what was actually parsed and skips the query entirely.
- */
 export async function runSessionIndexWarmTick() {
     const { scanSessionsIncremental } = await import('./session/discover.js');
     const { claimed, scanned } = await scanSessionsIncremental();
-    // A skipped claim is not a failure — a foreground `agents sessions*` is
-    // scanning right now and this tick would be a duplicate.
     if (!claimed)
         return { indexed: 0, claimed: false };
     return { indexed: scanned, claimed: true };
 }
-/**
- * Deferred tool-index pass for large-transcript harnesses (PHNX-3411).
- *
- * Kimi (wire.jsonl) and Grok (chat_history.jsonl) scanners produce only
- * metadata — no events. Calling parseSession for those on the warm tick wedges
- * the Node event loop when the transcript is large and active (observed: several
- * seconds per tick on zion, causing browser IPC ECONNREFUSED). This pass fills
- * the gap: it queries recently-active kimi/grok sessions and calls
- * ensureToolIndex, which uses tool_scan_ledger stamps to skip already-current
- * sessions and applies byte/file budget caps so no large transcript monopolises
- * the tick.
- */
 export async function runDeferredToolIndex() {
     const { querySessionsForDeferredToolIndex } = await import('./session/db.js');
     const { ensureToolIndex } = await import('./session/tool-index.js');
-    // Feed the 200 most-recently-active kimi/grok sessions; ensureToolIndex skips
-    // any whose tool_scan_ledger stamp is current.
     const sessions = querySessionsForDeferredToolIndex(200);
     if (sessions.length === 0)
         return { indexed: 0 };
     const coverage = await ensureToolIndex(sessions, {
         maxFiles: 20,
-        maxBytes: 20 * 1024 * 1024, // 20 MB — bounds one tick even on large transcripts
+        maxBytes: 20 * 1024 * 1024,
     });
     return { indexed: coverage.indexedFiles };
 }

package/dist/lib/daemon-webhooks.d.ts

@@ -1,79 +1,28 @@
-/**
- * Per-box hosted webhook receivers: config + daemon host (RUSH-2548).
- *
- * `~/.agents/daemon/webhooks.yaml` declares which signed webhook receivers THIS
- * box hosts — bundle, local port, rate limit, and an optional public Tailscale
- * Funnel port. The daemon's `webhook-receiver` service reads it and binds one
- * receiver per entry, drawing each receiver's signing secret through the
- * standalone `secrets` CLI (an agentOnly read via secrets-client.ts — no
- * `AGENTS_SECRETS_PASSPHRASE`, no `nohup`). An absent or empty file hosts
- * nothing, so an unconfigured box binds nothing.
- *
- * This is per-box operational state (a public receiver runs on exactly one box),
- * so it is deliberately NOT part of the fleet-synced device config — it mirrors
- * `services.yaml` / daemon-services.ts, not `agents config`.
- */
 import { type WebhookSecrets } from './triggers/webhook.js';
 import { type FunnelPort } from './funnel.js';
 export declare const DEFAULT_WEBHOOK_PORT = 8787;
 export declare const DEFAULT_WEBHOOK_RATE_LIMIT = 60;
-/** Optional public exposure for a hosted receiver via Tailscale Funnel. */
 export interface HostedReceiverFunnel {
-    /** Public HTTPS port (Funnel allows 443 / 8443 / 10000). */
     publicPort: FunnelPort;
 }
-/** One receiver this box hosts. */
 export interface HostedReceiverConfig {
-    /** Secrets bundle holding GITHUB_WEBHOOK_SECRET, LINEAR_WEBHOOK_SECRET, and/or
-     *  SLACK_SIGNING_SECRET (a Slack receiver also carries SLACK_BOT_TOKEN when the
-     *  agent replies with the Slack Web API rather than `agents send`). */
     bundle: string;
-    /** Local bind port (default 8787). */
     port?: number;
-    /** Accepted deliveries per source per minute (default 60). */
     rateLimit?: number;
-    /** Public Funnel exposure; omit to bind localhost only. */
     funnel?: HostedReceiverFunnel;
 }
 interface DaemonWebhooksConfig {
     receivers: HostedReceiverConfig[];
 }
-/** Path to `~/.agents/daemon/webhooks.yaml`. */
 export declare function getDaemonWebhooksConfigPath(): string;
-/**
- * Read the hosted-receivers config. A missing or malformed file yields an empty
- * receiver list — never throws — so a box with no config hosts nothing.
- */
 export declare function readDaemonWebhooksConfig(): DaemonWebhooksConfig;
-/** Write the hosted-receivers config, creating the daemon config dir if needed. */
 export declare function writeDaemonWebhooksConfig(cfg: DaemonWebhooksConfig): void;
-/** The port a receiver binds — its identity, since one port hosts one receiver. */
 export declare function hostedReceiverPort(receiver: HostedReceiverConfig): number;
-/**
- * Declare a receiver on this box, replacing any existing entry on the same port.
- * Port is the identity because two receivers cannot bind one port — a second
- * `add` on a port is an edit, never a silently ignored duplicate.
- */
 export declare function addHostedReceiver(receiver: HostedReceiverConfig): DaemonWebhooksConfig;
-/**
- * Drop the receiver bound to `port`. Returns the removed entry, or null when
- * nothing was declared there. The caller is responsible for taking down any
- * public Funnel the removed entry declared — leaving it up would keep a public
- * `https://<host>.ts.net` route pointed at a port nothing serves.
- */
 export declare function removeHostedReceiver(port: number): HostedReceiverConfig | null;
-/**
- * Resolve a receiver's signing secrets from its bundle. Reads `agentOnly` (no
- * Touch ID — the daemon is a background service, SEC-13): a broker-held or
- * file-store bundle resolves silently; a locked bundle THROWS the actionable
- * unlock message, which fails the receiver LOUD rather than binding with no
- * verifiable signature. Throws when neither webhook secret is present.
- */
 export declare function resolveReceiverSecrets(bundle: string): WebhookSecrets;
 export interface HostedWebhookReceivers {
-    /** Number of receivers actually bound. */
     count: number;
-    /** Stop every hosted receiver. Idempotent. */
     close(): Promise<void>;
 }
 type Logger = (level: string, message: string) => void;
@@ -94,12 +43,6 @@ type Logger = (level: string, message: string) => void;
  */
 export declare function startHostedWebhookReceivers(opts: {
     log: Logger;
-    /**
-     * How a receiver's signing secrets are resolved. Defaults to
-     * `resolveReceiverSecrets` (the real secrets-client read). Injectable for the same
-     * reason `FireWebhookOptions.dispatch` is — so a test can exercise the bind
-     * path against real sockets without a machine-local secrets bundle.
-     */
     resolveSecrets?: (bundle: string) => WebhookSecrets;
 }): Promise<HostedWebhookReceivers>;
 export {};

package/dist/lib/daemon-webhooks.js

@@ -1,18 +1,3 @@
-/**
- * Per-box hosted webhook receivers: config + daemon host (RUSH-2548).
- *
- * `~/.agents/daemon/webhooks.yaml` declares which signed webhook receivers THIS
- * box hosts — bundle, local port, rate limit, and an optional public Tailscale
- * Funnel port. The daemon's `webhook-receiver` service reads it and binds one
- * receiver per entry, drawing each receiver's signing secret through the
- * standalone `secrets` CLI (an agentOnly read via secrets-client.ts — no
- * `AGENTS_SECRETS_PASSPHRASE`, no `nohup`). An absent or empty file hosts
- * nothing, so an unconfigured box binds nothing.
- *
- * This is per-box operational state (a public receiver runs on exactly one box),
- * so it is deliberately NOT part of the fleet-synced device config — it mirrors
- * `services.yaml` / daemon-services.ts, not `agents config`.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -25,7 +10,6 @@ import { startWebhookServer, createFileDeliveryStore, waitForListening } from '.
 import { buildFunnelUpCommand, FUNNEL_PORTS } from './funnel.js';
 export const DEFAULT_WEBHOOK_PORT = 8787;
 export const DEFAULT_WEBHOOK_RATE_LIMIT = 60;
-/** Path to `~/.agents/daemon/webhooks.yaml`. */
 export function getDaemonWebhooksConfigPath() {
     return path.join(getDaemonConfigDir(), 'webhooks.yaml');
 }
@@ -41,17 +25,11 @@ function coerceReceiver(item) {
     if (typeof obj.rateLimit === 'number' && Number.isInteger(obj.rateLimit) && obj.rateLimit > 0)
         rc.rateLimit = obj.rateLimit;
     const funnel = obj.funnel;
-    // A publicPort Funnel cannot serve is dropped rather than carried forward — the
-    // receiver still binds localhost, and `daemon webhooks add` rejects it up front.
     if (funnel && typeof funnel === 'object' && FUNNEL_PORTS.includes(funnel.publicPort)) {
         rc.funnel = { publicPort: funnel.publicPort };
     }
     return rc;
 }
-/**
- * Read the hosted-receivers config. A missing or malformed file yields an empty
- * receiver list — never throws — so a box with no config hosts nothing.
- */
 export function readDaemonWebhooksConfig() {
     try {
         const raw = fs.readFileSync(getDaemonWebhooksConfigPath(), 'utf-8');
@@ -64,21 +42,14 @@ export function readDaemonWebhooksConfig() {
         return { receivers: [] };
     }
 }
-/** Write the hosted-receivers config, creating the daemon config dir if needed. */
 export function writeDaemonWebhooksConfig(cfg) {
     fs.mkdirSync(getDaemonConfigDir(), { recursive: true });
     const out = yaml.stringify({ receivers: cfg.receivers }, { sortMapEntries: false });
     atomicWriteFileSync(getDaemonWebhooksConfigPath(), out, 'utf-8');
 }
-/** The port a receiver binds — its identity, since one port hosts one receiver. */
 export function hostedReceiverPort(receiver) {
     return receiver.port ?? DEFAULT_WEBHOOK_PORT;
 }
-/**
- * Declare a receiver on this box, replacing any existing entry on the same port.
- * Port is the identity because two receivers cannot bind one port — a second
- * `add` on a port is an edit, never a silently ignored duplicate.
- */
 export function addHostedReceiver(receiver) {
     const port = hostedReceiverPort(receiver);
     const existing = readDaemonWebhooksConfig().receivers.filter((r) => hostedReceiverPort(r) !== port);
@@ -86,12 +57,6 @@ export function addHostedReceiver(receiver) {
     writeDaemonWebhooksConfig(next);
     return next;
 }
-/**
- * Drop the receiver bound to `port`. Returns the removed entry, or null when
- * nothing was declared there. The caller is responsible for taking down any
- * public Funnel the removed entry declared — leaving it up would keep a public
- * `https://<host>.ts.net` route pointed at a port nothing serves.
- */
 export function removeHostedReceiver(port) {
     const { receivers } = readDaemonWebhooksConfig();
     const removed = receivers.find((r) => hostedReceiverPort(r) === port);
@@ -100,14 +65,8 @@ export function removeHostedReceiver(port) {
     writeDaemonWebhooksConfig({ receivers: receivers.filter((r) => hostedReceiverPort(r) !== port) });
     return removed;
 }
-/**
- * Resolve a receiver's signing secrets from its bundle. Reads `agentOnly` (no
- * Touch ID — the daemon is a background service, SEC-13): a broker-held or
- * file-store bundle resolves silently; a locked bundle THROWS the actionable
- * unlock message, which fails the receiver LOUD rather than binding with no
- * verifiable signature. Throws when neither webhook secret is present.
- */
 export function resolveReceiverSecrets(bundle) {
+    // Daemon reads are broker-only; missing signing secrets fail before any public bind.
     const { env } = readAndResolveBundleEnvSync(bundle, { caller: 'daemon webhook-receiver', agentOnly: true });
     const secrets = {};
     if (env.GITHUB_WEBHOOK_SECRET)
@@ -121,7 +80,6 @@ export function resolveReceiverSecrets(bundle) {
     }
     return secrets;
 }
-/** Best-effort funnel reconcile: bring the declared public port up, log on failure. */
 function reconcileFunnel(publicPort, localPort, log) {
     let command;
     try {
@@ -156,6 +114,7 @@ function reconcileFunnel(publicPort, localPort, log) {
  * skipped receiver.
  */
 export async function startHostedWebhookReceivers(opts) {
+    // Receiver config is per-box; one failed bind closes its partial server without taking siblings down.
     const { log } = opts;
     const resolveSecrets = opts.resolveSecrets ?? resolveReceiverSecrets;
     const { receivers } = readDaemonWebhooksConfig();
@@ -177,12 +136,7 @@ export async function startHostedWebhookReceivers(opts) {
                 port,
                 secrets,
                 rateLimitPerMinute: receiver.rateLimit ?? DEFAULT_WEBHOOK_RATE_LIMIT,
-                // Per-port durable delivery dedup so replays survive a daemon restart and
-                // two receivers on distinct ports never share a dedup ledger.
                 deliveryStore: createFileDeliveryStore(path.join(getRuntimeStateDir(), 'webhook', `deliveries-${port}.json`)),
-                // Logged at MATCH time, before dispatch — a `run.command` handler can
-                // block on a shelled-out agent run for minutes, and that must never
-                // delay the log that says a delivery fired (RUSH-2722).
                 onMatch: (webhook, matchedJobNames, matchedHandlerNames) => {
                     const parts = [];
                     if (matchedJobNames.length)
@@ -191,8 +145,6 @@ export async function startHostedWebhookReceivers(opts) {
                         parts.push(`handlers ${matchedHandlerNames.join(', ')}`);
                     log('INFO', `webhook ${webhook.source}:${webhook.event} ${parts.length ? `fired ${parts.join('; ')}` : 'no match'}`);
                 },
-                // The 202 ack means no HTTP status carries a settle failure — the daemon
-                // log is where it surfaces, so it is never swallowed.
                 onDeliveryError: (webhook, err) => {
                     log('WARN', `webhook ${webhook.source}:${webhook.event} dispatch failed after ack: ${err.message}`);
                 },
@@ -209,8 +161,6 @@ export async function startHostedWebhookReceivers(opts) {
                 reconcileFunnel(receiver.funnel.publicPort, port, log);
         }
         catch (err) {
-            // Close the half-started server so a failed bind leaks no handle, and keep
-            // going: one unusable receiver must not cost the others their ingress.
             server?.close(() => { });
             log('WARN', `webhook receiver on :${port} failed to bind: ${err.message}`);
         }
@@ -218,8 +168,6 @@ export async function startHostedWebhookReceivers(opts) {
     return {
         count: servers.length,
         close: () => Promise.all(servers.map(async ({ server, sockets }) => {
-            // Stop accepting first, then force every persistent HTTP connection
-            // closed so keep-alive cannot hold daemon shutdown open indefinitely.
             const closing = closeServerBounded(server);
             for (const socket of sockets)
                 socket.destroy();