@phnx-labs/agents-cli 1.21.1 → 1.21.3

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);
@@ -468,6 +486,7 @@ export class BrowserService {
             const sessionId = await this.getSessionId(conn, cdpTargetId);
             await conn.cdp.send('Page.navigate', { url }, sessionId);
             await this.saveTaskState(task.profile, conn.tasks);
+            emit('browser.navigate', { profile: task.profile, task: task.name, url, tabId: currentShortId, created: false });
             return { tabId: currentShortId, url, created: false };
         }
         // No current tab - create one
@@ -482,6 +501,7 @@ export class BrowserService {
             task.tabs[shortId] = cdpTargetId;
             task.currentTabId = shortId;
             await this.saveTaskState(task.profile, conn.tasks);
+            emit('browser.navigate', { profile: task.profile, task: task.name, url, tabId: shortId, created: true });
             return { tabId: shortId, url, created: true };
         }
         // Chrome: create new tab
@@ -493,6 +513,7 @@ export class BrowserService {
         task.currentTabId = shortId;
         this.invalidateTargetCache(conn);
         await this.saveTaskState(task.profile, conn.tasks);
+        emit('browser.navigate', { profile: task.profile, task: task.name, url, tabId: shortId, created: true });
         return { tabId: shortId, url, created: true };
     }
     async tabAdd(taskId, url, profileName) {
@@ -687,6 +708,16 @@ export class BrowserService {
         await fs.promises.writeFile(finalPath, buffer);
         const dims = (extension === 'png' ? readPngDimensions(buffer) : readJpegDimensions(buffer)) ??
             { width: 0, height: 0 };
+        emit('browser.screenshot', {
+            profile: profileName,
+            task: task.name,
+            tabId: shortId,
+            path: finalPath,
+            bytes: buffer.length,
+            width: dims.width,
+            height: dims.height,
+            quality,
+        });
         return { path: finalPath, bytes: buffer.length, width: dims.width, height: dims.height };
     }
     /**

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/computer/dispatch.d.ts

@@ -3,6 +3,8 @@ import { type AppInfo } from '../../commands/computer-actions.js';
 import type { VerbDispatcher } from './loop.js';
 declare function rpcMethodFor(verb: string): string;
 declare function toRpcParams(verb: string, input: Record<string, unknown>, pid?: number): Record<string, unknown>;
-export declare function makeVerbDispatcher(client: ComputerClient): VerbDispatcher;
+export declare function makeVerbDispatcher(client: ComputerClient, context?: {
+    host?: string;
+}): VerbDispatcher;
 export { rpcMethodFor, toRpcParams };
 export type { AppInfo };

package/dist/lib/computer/dispatch.js

@@ -5,7 +5,7 @@
 // it names the same RPC methods the explicit `agents computer <verb>` commands
 // call, so the external-agent verb surface is untouched. The daemon stays the
 // single authority on permissions and targeting.
-import { resolveTargetPidDecision } from '../../commands/computer-actions.js';
+import { resolveTargetPidDecision, emitComputerAction } from '../../commands/computer-actions.js';
 // CLI verb -> daemon RPC method. Only the rename cases need listing; the rest
 // pass through by name.
 const RPC_METHOD = {
@@ -102,7 +102,14 @@ function toRpcParams(verb, input, pid) {
 // Build a dispatcher bound to a live client. Every call is a single daemon
 // round-trip; errors are returned (never thrown) so the loop can feed them
 // back to the model as a tool_result.
-export function makeVerbDispatcher(client) {
+//
+// `computer run`'s embedded model loop drives every verb (click, type,
+// screenshot, ...) through THIS single seam rather than the explicit
+// `agents computer <verb>` commands in computer-actions.ts, so it must emit
+// the same `computer.action` event those commands emit — otherwise a session
+// that only used the loop reads back usedComputer=false even though it drove
+// real actions (reviewer-flagged regression on #1864).
+export function makeVerbDispatcher(client, context = {}) {
     return async (call) => {
         const verb = call.name;
         const input = call.input ?? {};
@@ -118,6 +125,7 @@ export function makeVerbDispatcher(client) {
         const res = await client.call(method, params);
         if (res.error)
             return { ok: false, error: `${res.error.code}: ${res.error.message}` };
+        emitComputerAction(verb, pid, { bundle: input.bundle, host: context.host });
         return { ok: true, result: res.result ?? {} };
     };
 }

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/event-stream.d.ts

@@ -18,6 +18,8 @@ export interface UnifiedQuery {
     eventTypes?: EventType[];
     level?: EventLevel;
     agent?: string;
+    /** Only events stamped with this session id (payload `sessionId`, the provenance floor). */
+    sessionId?: string;
     caller?: string;
     command?: string;
     module?: string;

package/dist/lib/event-stream.js

@@ -29,6 +29,8 @@ function matches(r, q) {
         return false;
     if (q.agent && r.agent !== q.agent)
         return false;
+    if (q.sessionId && r.sessionId !== q.sessionId)
+        return false;
     if (q.caller && r.caller !== q.caller)
         return false;
     if (q.command && r.command !== q.command &&
@@ -51,6 +53,7 @@ export function readUnifiedEvents(q = {}) {
         eventTypes: q.eventTypes,
         level: q.level,
         agent: q.agent,
+        sessionId: q.sessionId,
         caller: q.caller,
         command: q.command,
         module: q.module,

package/dist/lib/events.d.ts

@@ -13,7 +13,7 @@
  */
 import type { ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'computer.action' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 /** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
 export declare const EVENT_TYPES: readonly EventType[];
 /** Runtime guard for an event kind arriving from outside this process. */
@@ -208,6 +208,8 @@ export declare function query(options: {
     eventTypes?: EventType[];
     level?: EventLevel;
     agent?: string;
+    /** Only events stamped with this session id (payload `sessionId`, the provenance floor). */
+    sessionId?: string;
     caller?: string;
     command?: string;
     module?: string;

package/dist/lib/events.js

@@ -84,6 +84,7 @@ const EVENT_TYPE_TABLE = {
     'version.install': true, 'version.switch': true, 'version.remove': true,
     'skill.install': true, 'skill.remove': true,
     'browser.launch': true, 'browser.close': true, 'browser.navigate': true, 'browser.screenshot': true,
+    'computer.action': true,
     'secrets.get': true, 'secrets.unlocked': true, 'secrets.create': true, 'secrets.import': true, 'secrets.export': true, 'secrets.view': true, 'secrets.set': true, 'secrets.delete': true, 'secrets.rename': true,
     'cloud.dispatch': true, 'cloud.complete': true, 'cloud.cancel': true, 'cloud.message': true,
     'teams.create': true, 'teams.add': true, 'teams.start': true, 'teams.complete': true, 'teams.disband': true,
@@ -327,7 +328,6 @@ export function detectCaller(env = process.env, stdoutIsTTY = Boolean(process.st
     }
     return { kind: stdoutIsTTY ? 'terminal' : 'script' };
 }
-// ─── Audit attribution ────────────────────────────────────────────────────────
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
  * Emit a structured event to the append-only audit log.
@@ -729,7 +729,7 @@ export function maybeRotate() {
  * @returns Array of event records
  */
 export function query(options) {
-    const { startDate, endDate = new Date(), eventTypes, level, agent, caller, command, module, limit } = options;
+    const { startDate, endDate = new Date(), eventTypes, level, agent, sessionId, caller, command, module, limit } = options;
     const results = [];
     if (!fs.existsSync(eventsDir()))
         return results;
@@ -774,6 +774,8 @@ export function query(options) {
                     continue;
                 if (agent && record.agent !== agent)
                     continue;
+                if (sessionId && record.sessionId !== sessionId)
+                    continue;
                 if (caller && record.caller !== caller)
                     continue;
                 if (command && record.command !== command &&

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[]>;