@phnx-labs/agents-cli 1.21.1 → 1.21.2

package/dist/lib/analytics/usage-db.js

@@ -0,0 +1,301 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from '../sqlite.js';
+import { getUsageDbPath, getSecretsDbPath, getAnalyticsDir } from '../state.js';
+import { localMachineId } from '../session/origin-machine.js';
+export const USAGE_KINDS = [
+    'secret',
+    'agent',
+    'skill',
+    'plugin',
+    'browser',
+    'computer',
+];
+const EVENT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS usage_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  name TEXT NOT NULL,
+  event TEXT NOT NULL,
+  agent TEXT,
+  session_id TEXT,
+  machine TEXT,
+  actor TEXT,
+  source TEXT,
+  status TEXT,
+  meta_json TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_ts ON usage_events(ts DESC);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_kind_ts ON usage_events(kind, ts DESC);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_kind_name ON usage_events(kind, name);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_kind_event ON usage_events(kind, event);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_machine_ts ON usage_events(machine, ts DESC);
+CREATE INDEX IF NOT EXISTS idx_analytics_usage_session ON usage_events(session_id);
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+let cached = null;
+function isDisabled() {
+    const v = process.env.AGENTS_NO_USAGE_TRACK;
+    return v === '1' || v === 'true';
+}
+function open() {
+    if (isDisabled())
+        return null;
+    const dbPath = getUsageDbPath();
+    if (cached && cached.path === dbPath)
+        return cached.db;
+    if (cached) {
+        try {
+            cached.db.close();
+        }
+        catch { /* ignore */ }
+        cached = null;
+    }
+    try {
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true, mode: 0o700 });
+        const db = new Database(dbPath);
+        db.pragma('journal_mode = WAL');
+        db.pragma('busy_timeout = 2000');
+        db.exec(SCHEMA);
+        try {
+            db.prepare(`DELETE FROM usage_events WHERE ts < ?`).run(new Date(Date.now() - EVENT_RETENTION_MS).toISOString());
+        }
+        catch { /* prune best-effort */ }
+        migrateSecretsUsageOnce(db);
+        cached = { path: dbPath, db };
+        return db;
+    }
+    catch {
+        return null;
+    }
+}
+function migrateSecretsUsageOnce(db) {
+    try {
+        const done = db.prepare(`SELECT value FROM meta WHERE key = 'migrate_secrets_v1'`).get();
+        if (done?.value === '1')
+            return;
+        const secretsPath = getSecretsDbPath();
+        if (fs.existsSync(secretsPath)) {
+            const legacy = new Database(secretsPath);
+            try {
+                const rows = legacy.prepare(`SELECT ts, bundle, event, agent, host, source, status, key_count FROM usage_events`).all();
+                const insert = db.prepare(`INSERT INTO usage_events (ts, kind, name, event, agent, session_id, machine, actor, source, status, meta_json)
+           VALUES (?, 'secret', ?, ?, ?, NULL, ?, NULL, ?, ?, ?)`);
+                const machine = localMachineId();
+                const txn = db.transaction((items) => {
+                    for (const r of items) {
+                        if (!r.bundle)
+                            continue;
+                        const meta = r.key_count != null ? JSON.stringify({ keyCount: r.key_count, host: r.host }) : (r.host ? JSON.stringify({ host: r.host }) : null);
+                        insert.run(r.ts, r.bundle, r.event, r.agent, machine, r.source, r.status, meta);
+                    }
+                });
+                txn(rows);
+            }
+            finally {
+                try {
+                    legacy.close();
+                }
+                catch { /* ignore */ }
+            }
+        }
+        db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES ('migrate_secrets_v1', '1')`).run();
+    }
+    catch {
+        /* migrate is best-effort */
+    }
+}
+export function recordUsage(p) {
+    if (isDisabled())
+        return;
+    if (!p.kind || !p.name || !p.event)
+        return;
+    const db = open();
+    if (!db)
+        return;
+    try {
+        db.prepare(`INSERT INTO usage_events (ts, kind, name, event, agent, session_id, machine, actor, source, status, meta_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(p.ts ?? new Date().toISOString(), p.kind, p.name, p.event, p.agent ?? null, p.sessionId ?? null, p.machine ?? localMachineId(), p.actor ?? null, p.source ?? null, p.status ?? 'success', p.meta != null ? JSON.stringify(p.meta) : null);
+    }
+    catch {
+        /* telemetry must never break callers */
+    }
+}
+export function usageDbPath() {
+    return getUsageDbPath();
+}
+export function analyticsDir() {
+    return getAnalyticsDir();
+}
+export function listUsageKindsWithData(sinceIso) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        const rows = db.prepare(`SELECT DISTINCT kind FROM usage_events WHERE ts >= ?`).all(sinceIso);
+        return rows.map((r) => r.kind).filter((k) => USAGE_KINDS.includes(k));
+    }
+    catch {
+        return [];
+    }
+}
+export function countUsage(opts) {
+    const db = open();
+    if (!db)
+        return 0;
+    try {
+        const clauses = ['ts >= ?'];
+        const args = [opts.sinceIso];
+        if (opts.kind) {
+            clauses.push('kind = ?');
+            args.push(opts.kind);
+        }
+        if (opts.name) {
+            clauses.push('name = ?');
+            args.push(opts.name);
+        }
+        if (opts.event) {
+            clauses.push('event = ?');
+            args.push(opts.event);
+        }
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM usage_events WHERE ${clauses.join(' AND ')}`).get(...args);
+        return row?.n ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function queryUsage(opts) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        const clauses = ['ts >= ?'];
+        const args = [opts.sinceIso];
+        if (opts.kind) {
+            clauses.push('kind = ?');
+            args.push(opts.kind);
+        }
+        if (opts.name) {
+            clauses.push('name = ?');
+            args.push(opts.name);
+        }
+        if (opts.event) {
+            clauses.push('event = ?');
+            args.push(opts.event);
+        }
+        const limit = opts.limit && opts.limit > 0 ? opts.limit : 100;
+        args.push(limit);
+        const rows = db.prepare(`SELECT ts, kind, name, event, agent, session_id AS sessionId, machine, actor, source, status, meta_json AS metaJson
+         FROM usage_events WHERE ${clauses.join(' AND ')}
+         ORDER BY ts DESC, id DESC LIMIT ?`).all(...args);
+        return rows;
+    }
+    catch {
+        return [];
+    }
+}
+export function topNamesByKind(kind, sinceIso, limit = 20) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT name, COUNT(*) AS n, MAX(ts) AS last
+         FROM usage_events WHERE kind = ? AND ts >= ?
+         GROUP BY name ORDER BY n DESC LIMIT ?`).all(kind, sinceIso, limit);
+    }
+    catch {
+        return [];
+    }
+}
+export function kindMix(sinceIso) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT kind, COUNT(*) AS n FROM usage_events WHERE ts >= ? GROUP BY kind ORDER BY n DESC`).all(sinceIso);
+    }
+    catch {
+        return [];
+    }
+}
+export function getSecretBundleRollup(bundle) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT event, COUNT(*) AS n, MAX(ts) AS last, MIN(ts) AS first
+         FROM usage_events WHERE kind = 'secret' AND name = ? GROUP BY event`).all(bundle);
+    }
+    catch {
+        return [];
+    }
+}
+export function getSecretBundleAgents(bundle) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT agent, COUNT(*) AS n FROM usage_events
+         WHERE kind = 'secret' AND name = ? AND agent IS NOT NULL
+         GROUP BY agent ORDER BY n DESC`).all(bundle);
+    }
+    catch {
+        return [];
+    }
+}
+export function getAllSecretBundleRollups() {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        return db.prepare(`SELECT name, event, COUNT(*) AS n, MAX(ts) AS last, MIN(ts) AS first
+         FROM usage_events WHERE kind = 'secret' GROUP BY name, event`).all();
+    }
+    catch {
+        return [];
+    }
+}
+export function getSecretHistory(bundle, limit = 20) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        const sql = bundle
+            ? `SELECT ts, name AS bundle, event, agent, source, status, meta_json
+           FROM usage_events WHERE kind = 'secret' AND name = ? ORDER BY ts DESC, id DESC LIMIT ?`
+            : `SELECT ts, name AS bundle, event, agent, source, status, meta_json
+           FROM usage_events WHERE kind = 'secret' ORDER BY ts DESC, id DESC LIMIT ?`;
+        const rows = (bundle ? db.prepare(sql).all(bundle, limit) : db.prepare(sql).all(limit));
+        return rows.map((r) => {
+            let host = null;
+            let keyCount = null;
+            if (r.meta_json) {
+                try {
+                    const m = JSON.parse(r.meta_json);
+                    host = m.host ?? null;
+                    keyCount = typeof m.keyCount === 'number' ? m.keyCount : null;
+                }
+                catch { /* ignore */ }
+            }
+            return { ts: r.ts, bundle: r.bundle, event: r.event, agent: r.agent, host, source: r.source, status: r.status, keyCount };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function closeUsageDb() {
+    if (cached) {
+        try {
+            cached.db.close();
+        }
+        catch { /* ignore */ }
+        cached = null;
+    }
+}

package/dist/lib/browser/service.js

@@ -346,6 +346,15 @@ export class BrowserService {
         conn.tasks.set(taskName, task);
         await this.saveTaskState(effectiveProfileName, conn.tasks);
         emit('browser.launch', { profile: effectiveProfileName, task: taskName, pid: conn.pid });
+        void import('../analytics/usage-db.js').then(({ recordUsage }) => {
+            recordUsage({
+                kind: 'browser',
+                name: effectiveProfileName,
+                event: 'launch',
+                source: 'browser',
+                meta: { task: taskName },
+            });
+        }).catch(() => { });
         // If URL provided, create tab directly (no about:blank)
         let tabId;
         if (opts.url && !conn.electron) {
@@ -412,6 +421,15 @@ export class BrowserService {
                 conn.tasks.delete(taskName);
                 await this.saveTaskState(profileName, conn.tasks);
                 emit('browser.close', { profile: profileName, task: taskName });
+                void import('../analytics/usage-db.js').then(({ recordUsage }) => {
+                    recordUsage({
+                        kind: 'browser',
+                        name: profileName,
+                        event: 'close',
+                        source: 'browser',
+                        meta: { task: taskName },
+                    });
+                }).catch(() => { });
                 if (conn.forkedFrom && conn.tasks.size === 0) {
                     conn.cdp.close();
                     killChrome(conn.pid);

package/dist/lib/cli-resources.d.ts

@@ -90,6 +90,15 @@ export declare function hasCommand(cmd: string): boolean;
  * shell, never interpolates strings into a command line.
  */
 export declare function isCliInstalled(manifest: CliManifest): boolean;
+/**
+ * Async, non-blocking sibling of {@link isCliInstalled}. Same dispatch and
+ * Windows-shim retry, but over `execFile` so many manifests can be checked
+ * concurrently — the fix for RUSH-2136, where `agents doctor --json` ran a dozen+
+ * blocking 10s-timeout `spawnSync` checks SERIALLY (measured ~136s on an idle
+ * box). `execFile`'s `timeout` still SIGKILLs a wedged check, so a single
+ * hanging probe can't stall the whole set past 10s.
+ */
+export declare function isCliInstalledAsync(manifest: CliManifest): Promise<boolean>;
 /**
  * Pick the first install method whose required host tool is available.
  * Returns null when none of the declared methods can run on this host.
@@ -151,3 +160,14 @@ export declare function listCliStatus(cwd?: string): {
     statuses: CliStatus[];
     errors: CliManifestError[];
 };
+/**
+ * Async sibling of {@link listCliStatus} that probes every manifest CONCURRENTLY
+ * (RUSH-2136). The sync version runs each blocking `spawnSync` check one after
+ * another, so a dozen host CLIs whose checks are slow serialize into a
+ * multi-minute stall on `agents doctor --json`. This awaits them in parallel, so
+ * total wall time is the slowest single check (bounded at 10s), not their sum.
+ */
+export declare function listCliStatusAsync(cwd?: string): Promise<{
+    statuses: CliStatus[];
+    errors: CliManifestError[];
+}>;

package/dist/lib/cli-resources.js

@@ -18,7 +18,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { spawnSync } from 'child_process';
+import { spawnSync, execFile } from 'child_process';
 import * as yaml from 'yaml';
 import { listResources, resolveResource } from './resources.js';
 import { composeWin32CommandLine } from './platform/index.js';
@@ -304,6 +304,38 @@ export function isCliInstalled(manifest) {
     }
     return false;
 }
+/**
+ * Async, non-blocking sibling of {@link isCliInstalled}. Same dispatch and
+ * Windows-shim retry, but over `execFile` so many manifests can be checked
+ * concurrently — the fix for RUSH-2136, where `agents doctor --json` ran a dozen+
+ * blocking 10s-timeout `spawnSync` checks SERIALLY (measured ~136s on an idle
+ * box). `execFile`'s `timeout` still SIGKILLs a wedged check, so a single
+ * hanging probe can't stall the whole set past 10s.
+ */
+export function isCliInstalledAsync(manifest) {
+    const c = manifest.check;
+    if (c.kind === 'which') {
+        cmdExistsCache.delete(c.cmd);
+        return Promise.resolve(hasCommand(c.cmd));
+    }
+    return new Promise((resolve) => {
+        execFile(c.cmd, c.args, { timeout: 10_000 }, (err) => {
+            if (!err)
+                return resolve(true);
+            // A spawn failure (as opposed to a non-zero exit) surfaces as a string
+            // errno code (ENOENT/EINVAL); a non-zero exit surfaces as a numeric code.
+            // On Windows a `.cmd`/`.bat` shim spawn-fails without a shell — retry once
+            // through the shell, exactly as the sync path does.
+            const spawnFailed = typeof err.code === 'string';
+            if (process.platform === 'win32' && spawnFailed) {
+                const line = composeWin32CommandLine(c.cmd, c.args);
+                execFile(line, { timeout: 10_000, shell: true }, (retryErr) => resolve(!retryErr));
+                return;
+            }
+            resolve(false);
+        });
+    });
+}
 // ─── Method selection ────────────────────────────────────────────────────────
 /**
  * Pick the first install method whose required host tool is available.
@@ -550,3 +582,18 @@ export function listCliStatus(cwd) {
     }));
     return { statuses, errors };
 }
+/**
+ * Async sibling of {@link listCliStatus} that probes every manifest CONCURRENTLY
+ * (RUSH-2136). The sync version runs each blocking `spawnSync` check one after
+ * another, so a dozen host CLIs whose checks are slow serialize into a
+ * multi-minute stall on `agents doctor --json`. This awaits them in parallel, so
+ * total wall time is the slowest single check (bounded at 10s), not their sum.
+ */
+export async function listCliStatusAsync(cwd) {
+    const { manifests, errors } = listCliManifests(cwd);
+    const statuses = await Promise.all(manifests.map(async (manifest) => ({
+        manifest,
+        installed: await isCliInstalledAsync(manifest),
+    })));
+    return { statuses, errors };
+}

package/dist/lib/daemon.js

@@ -803,13 +803,17 @@ export async function runDaemon() {
     };
     const launchHealthInterval = setInterval(() => { void runLaunchHealthCheck(); }, 6 * 60 * 60_000);
     const launchHealthKickoff = setTimeout(() => { void runLaunchHealthCheck(); }, 90_000);
-    // Fleet cache warm: keep the caches that `agents devices list`, `fleet status`,
-    // and `agents view` read cache-first actually fresh, so a default read never
-    // has to ssh out. Two cheap refreshes: (1) this host's auth-health verdicts
-    // (also feeds the `doctor --json` Auth rollup other hosts read), and (2) the
-    // fleet resource-stats cache (one bounded parallel probe of the tailnet). Both
-    // best-effort + overlap-guarded like the probes above. ~every 3 min, plus once
-    // ~60s after startup (staggered off launch).
+    // Fleet cache warm: publish THIS host's row for the caches `agents fleet
+    // status` / `agents devices list` read. PUBLISH-OWN / READ-UNION (RUSH-2061):
+    // each daemon probes only ITSELF and never SSHes another box, so the fleet no
+    // longer pays N² SSH resource probes every 3 minutes (N daemons × N devices) —
+    // the source of the fan-out storm AND the orphaned-probe pile-up. Two cheap
+    // self-only refreshes: (1) this host's auth-health verdicts (also feeds the
+    // `doctor --json` Auth rollup other hosts read), and (2) its fleet-status row
+    // (local resource probe + live-agent workload). Cross-host rows are unioned on
+    // demand by the reader (`agents fleet status`), not pushed by every daemon.
+    // Best-effort + overlap-guarded like the probes above; ~every 3 min, once ~60s
+    // after startup.
     let warmingFleetCache = false;
     const runFleetCacheWarm = async () => {
         if (warmingFleetCache)
@@ -822,13 +826,9 @@ export async function runDaemon() {
             const { getCliVersion } = await import('./version.js');
             const authRows = await probeLocalFleetAuth({ cliVersion: getCliVersion() });
             writeFleetAuthRows(self, authRows);
-            const { loadDevices } = await import('./devices/registry.js');
-            const { planFleetTargets } = await import('./devices/fleet.js');
-            const { loadFleetStats } = await import('./devices/stats-cache.js');
-            const reg = await loadDevices();
-            const probeable = planFleetTargets(reg).filter((t) => !t.skip).map((t) => t.device);
-            const res = await loadFleetStats(probeable, { forceRefresh: true, selfName: self });
-            log('INFO', `fleet cache warm: ${authRows.length} auth row(s), ${res.stats.size} device stat(s)`);
+            const { publishLocalFleetStatus } = await import('./fleet-status.js');
+            const row = await publishLocalFleetStatus(self);
+            log('INFO', `fleet cache warm: ${authRows.length} auth row(s), ${row.agents.running} running agent(s) on ${self}`);
         }
         catch (err) {
             log('ERROR', `fleet cache warm failed: ${err.message}`);
@@ -839,6 +839,41 @@ export async function runDaemon() {
     };
     const fleetCacheInterval = setInterval(() => { void runFleetCacheWarm(); }, 3 * 60_000);
     const fleetCacheKickoff = setTimeout(() => { void runFleetCacheWarm(); }, 60_000);
+    // Adaptive usage refresh: keep the usage cache the `agents run` router reads
+    // (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
+    // This host is the sole writer for its own local accounts. The tick wakes at
+    // the 90s floor, but per-account cadence gates the actual live fetches: an
+    // account racing toward its 5h cap is polled sooner (down to 90s), an idle one
+    // rarely (up to 15min), capped at ~6 provider calls/account/hour and skipped
+    // entirely while its provider is under a 429 backoff. Overlap-guarded like the
+    // probes above; a box signed into no networked-usage account is a clean no-op.
+    let refreshingUsage = false;
+    const runUsageRefreshTick = async () => {
+        if (refreshingUsage)
+            return;
+        refreshingUsage = true;
+        try {
+            const { runUsageRefresh, buildLocalUsageAccounts } = await import('./usage-refresh.js');
+            const { writeClaudeUsageCache } = await import('./usage.js');
+            const { usageRateLimitedUntil } = await import('./usage-backoff.js');
+            const r = await runUsageRefresh({
+                listAccounts: buildLocalUsageAccounts,
+                writeUsageCache: writeClaudeUsageCache,
+                backoffUntil: usageRateLimitedUntil,
+            });
+            if (r.refreshed > 0 || r.failed > 0) {
+                log('INFO', `usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped`);
+            }
+        }
+        catch (err) {
+            log('ERROR', `usage refresh failed: ${err.message}`);
+        }
+        finally {
+            refreshingUsage = false;
+        }
+    };
+    const usageRefreshInterval = setInterval(() => { void runUsageRefreshTick(); }, 90_000);
+    const usageRefreshKickoff = setTimeout(() => { void runUsageRefreshTick(); }, 30_000);
     // RUSH-1817: the startup host decision above is one-shot. If a standalone
     // broker answered agentPing() at daemon start, the daemon declined to host —
     // but should that standalone later die or crash-loop, nothing takes over and
@@ -928,6 +963,8 @@ export async function runDaemon() {
         clearTimeout(launchHealthKickoff);
         clearInterval(fleetCacheInterval);
         clearTimeout(fleetCacheKickoff);
+        clearInterval(usageRefreshInterval);
+        clearTimeout(usageRefreshKickoff);
         clearInterval(brokerSelfHealInterval);
         hostedBroker?.close();
         removeDaemonPid();

package/dist/lib/devices/health-report.d.ts

@@ -2,6 +2,7 @@ import { type DeviceStats } from './health.js';
 import { type HostAuthSummary } from '../auth-health.js';
 import type { OnlineState } from './reachability.js';
 import { type FleetInventory } from './fleet-divergence.js';
+import type { FleetAgentCounts } from '../fleet-status.js';
 export interface FleetCliStatus {
     installed: boolean;
     path: string | null;
@@ -46,6 +47,10 @@ export interface FleetHealthRow {
      *  divergence detection (RUSH-2027). Undefined for an unreachable box or an
      *  older CLI that doesn't emit it. */
     inventory?: FleetInventory;
+    /** This host's live agent workload (running-agent count + per-context / per-
+     *  agent breakdown), from the fleet-status mirror / read-union (RUSH-2061).
+     *  Undefined when no row has been published for the host yet. */
+    agents?: FleetAgentCounts;
 }
 export interface FleetWarning {
     kind: 'unreachable' | 'drift' | 'cli' | 'version-skew' | 'divergence';

package/dist/lib/devices/health-report.js

@@ -445,6 +445,9 @@ export function renderFleetSummary(report, opts = {}) {
             else if (isGenuinelyOffline(row) && row.lastSeen) {
                 marks.push(chalk.gray(`last seen ${formatCheckedAge(Date.parse(row.lastSeen), now)}`));
             }
+            if (row.agents && row.agents.running > 0) {
+                marks.push(chalk.cyan(`${row.agents.running} agent${row.agents.running === 1 ? '' : 's'}`));
+            }
             if (isSelf)
                 marks.push(chalk.cyan('← this machine'));
             const note = marks.length ? `   ${marks.join('   ')}` : '';

package/dist/lib/feed-broadcast.d.ts

@@ -1,3 +1,4 @@
+import type { Meta } from './types.js';
 /** How loudly a post asks to be heard. Ordered — `important` implies milestone. */
 export type FeedPostLevel = 'milestone' | 'important';
 /** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
@@ -6,9 +7,20 @@ export interface FeedSinkConfig {
     /**
      * argv to run, with `{placeholder}` tokens substituted. First element is the
      * program; it is spawned directly (no shell), so quoting is not a concern and
-     * post text can never become shell syntax.
+     * post text can never become shell syntax. Mutually exclusive with `channel`
+     * — a sink is one shape or the other.
      */
-    command: string[];
+    command?: string[];
+    /**
+     * In-process delivery through the same channel-provider registry `agents
+     * send`/`agents notify` use — the composed `{message}` body, no argv, no
+     * spawn. `'owner'` is the address alias (expands to `notify.owner.{channel,to}`
+     * in agents.yaml, same as `agents notify`); any other value is a registered
+     * channel name (or a `notify.transports` mapping) and requires `to`.
+     */
+    channel?: string;
+    /** Recipient for a `channel` sink. Required unless `channel` is the `owner` alias. */
+    to?: string;
     /** Lowest post level that reaches this sink. Defaults to `milestone` (all posts). */
     minLevel?: FeedPostLevel;
 }
@@ -82,7 +94,14 @@ export declare function blockBroadcastContext(block: {
 export declare function blockDeliveryFailure(blocked: boolean, outcomes: SinkOutcome[]): string | undefined;
 export interface PlannedSink {
     name: string;
-    argv: string[];
+    /** Command sink: argv to spawn (mutually exclusive with `channel`). */
+    argv?: string[];
+    /** Channel sink: provider channel name, or the `owner` alias. */
+    channel?: string;
+    /** Channel sink recipient. Unset for the `owner` alias — resolved at delivery. */
+    to?: string;
+    /** Channel sink body — the composed `{message}` for this post. */
+    text?: string;
 }
 export interface SinkOutcome {
     name: string;
@@ -139,11 +158,37 @@ export declare function renderSinkArgv(template: string[], ctx: FeedBroadcastCon
 /**
  * Which sinks this post reaches, in config order. Pure — the dry-run listing and
  * the real fan-out plan through here, so what `--dry-run` shows is what runs.
+ *
+ * A `channel:` sink is gated by the same `minLevel` rule as a `command:` sink —
+ * one level check for both shapes, so a dry-run plan is truthful regardless of
+ * which shape an operator's sink uses.
  */
 export declare function planFeedBroadcast(config: FeedBroadcastConfig | undefined, ctx: FeedBroadcastContext): PlannedSink[];
 /**
- * Run the planned sinks. Each is a direct spawn with a bounded lifetime; a sink
- * that fails or is not installed is reported, never thrown — the post is already
- * written and must not be undone by a mirror that could not be reached.
+ * The effective sink config for a post: the operator's `feed.broadcast`, or —
+ * when that is unset or empty — an implicit fallback straight to
+ * `notify.owner`, for a post worth interrupting someone over.
+ *
+ * Before this, `broadcastPostedEvent`/`broadcastBlock` returned early the
+ * moment `feed.broadcast` was empty, even when `notify.owner` was fully
+ * configured — so the common case (an operator who set up owner notifications
+ * but never wrote a `feed.broadcast` block) produced a `--blocked` post that
+ * looked recorded and reached nobody. `agents notify` already treats
+ * `notify.owner` as the default human destination; this makes an important
+ * feed post/block use that same default instead of requiring a second,
+ * redundant config block that says the same thing.
+ *
+ * The fallback only fires for `important` — a routine `milestone` post stays
+ * record-only, matching the `minLevel` contract every declared sink already
+ * follows. An operator-declared `feed.broadcast` (any non-empty config)
+ * always wins outright; the fallback never layers on top of it.
+ */
+export declare function effectiveBroadcastConfig(config: FeedBroadcastConfig | undefined, level: FeedPostLevel, meta: Meta): FeedBroadcastConfig | undefined;
+/**
+ * Run the planned sinks. A `command:` sink is a direct spawn with a bounded
+ * lifetime; a `channel:` sink delivers in-process. Either way a sink that
+ * fails or is not installed/registered is reported, never thrown — the post
+ * is already written and must not be undone by a mirror that could not be
+ * reached.
  */
-export declare function runFeedBroadcast(planned: PlannedSink[], timeoutMs?: number): SinkOutcome[];
+export declare function runFeedBroadcast(planned: PlannedSink[], meta: Meta, timeoutMs?: number): Promise<SinkOutcome[]>;