@phnx-labs/agents-cli 1.22.39 → 1.22.41

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

@@ -0,0 +1,104 @@
+/**
+ * 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 from the broker /
+ * machine-local file store (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;
+}
+export 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;
+/**
+ * Start every receiver declared in `webhooks.yaml`. A receiver that cannot start
+ * — an unreadable secret (locked bundle, no webhook secret) or a failed bind
+ * (the port is already taken by a foreground `agents webhooks serve`, another
+ * daemon, or anything else) — is skipped with a loud WARN and does NOT take the
+ * others, or the daemon, down. Returns a handle that stops them all.
+ *
+ * This is async because a bind failure is only observable asynchronously:
+ * `server.listen()` surfaces EADDRINUSE as an `'error'` event, so a `try/catch`
+ * around the start call never sees it and the event reaches the process-level
+ * `uncaughtException` handler (`index.ts`), which exits 1 for the supervisor to
+ * restart — a crash loop that would take the secrets broker, scheduler,
+ * monitors, browser IPC, and self-heal down with it. `waitForListening` is what
+ * turns that into one skipped receiver.
+ */
+export declare function startHostedWebhookReceivers(opts: {
+    log: Logger;
+    /**
+     * How a receiver's signing secrets are resolved. Defaults to
+     * `resolveReceiverSecrets` (the real broker 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

@@ -0,0 +1,215 @@
+/**
+ * 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 from the broker /
+ * machine-local file store (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';
+import { exec } from 'child_process';
+import { getDaemonConfigDir, getRuntimeStateDir } from './state.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { readAndResolveBundleEnv } from './secrets/bundles.js';
+import { startWebhookServer, createFileDeliveryStore, waitForListening } from './triggers/webhook.js';
+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');
+}
+function coerceReceiver(item) {
+    if (!item || typeof item !== 'object')
+        return null;
+    const obj = item;
+    if (typeof obj.bundle !== 'string' || obj.bundle.length === 0)
+        return null;
+    const rc = { bundle: obj.bundle };
+    if (typeof obj.port === 'number' && Number.isInteger(obj.port) && obj.port > 0)
+        rc.port = obj.port;
+    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');
+        const parsed = yaml.parse(raw);
+        const list = parsed && Array.isArray(parsed.receivers) ? parsed.receivers : [];
+        const receivers = list.map(coerceReceiver).filter((r) => r !== null);
+        return { receivers };
+    }
+    catch {
+        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);
+    const next = { receivers: [...existing, 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);
+    if (!removed)
+        return null;
+    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) {
+    const { env } = readAndResolveBundleEnv(bundle, { caller: 'daemon webhook-receiver', agentOnly: true });
+    const secrets = {};
+    if (env.GITHUB_WEBHOOK_SECRET)
+        secrets.github = env.GITHUB_WEBHOOK_SECRET;
+    if (env.LINEAR_WEBHOOK_SECRET)
+        secrets.linear = env.LINEAR_WEBHOOK_SECRET;
+    if (env.SLACK_SIGNING_SECRET)
+        secrets.slack = env.SLACK_SIGNING_SECRET;
+    if (!secrets.github && !secrets.linear && !secrets.slack) {
+        throw new Error(`bundle '${bundle}' has none of GITHUB_WEBHOOK_SECRET, LINEAR_WEBHOOK_SECRET, or SLACK_SIGNING_SECRET`);
+    }
+    return secrets;
+}
+/** Best-effort funnel reconcile: bring the declared public port up, log on failure. */
+function reconcileFunnel(publicPort, localPort, log) {
+    let command;
+    try {
+        command = buildFunnelUpCommand(publicPort, localPort);
+    }
+    catch (err) {
+        log('WARN', `webhook funnel skipped (port ${publicPort}): ${err.message}`);
+        return;
+    }
+    exec(command, (err) => {
+        if (err) {
+            log('WARN', `webhook funnel reconcile failed (public ${publicPort} -> localhost:${localPort}); binding localhost only: ${err.message}`);
+        }
+        else {
+            log('INFO', `webhook funnel up: public ${publicPort} -> localhost:${localPort}`);
+        }
+    });
+}
+/**
+ * Start every receiver declared in `webhooks.yaml`. A receiver that cannot start
+ * — an unreadable secret (locked bundle, no webhook secret) or a failed bind
+ * (the port is already taken by a foreground `agents webhooks serve`, another
+ * daemon, or anything else) — is skipped with a loud WARN and does NOT take the
+ * others, or the daemon, down. Returns a handle that stops them all.
+ *
+ * This is async because a bind failure is only observable asynchronously:
+ * `server.listen()` surfaces EADDRINUSE as an `'error'` event, so a `try/catch`
+ * around the start call never sees it and the event reaches the process-level
+ * `uncaughtException` handler (`index.ts`), which exits 1 for the supervisor to
+ * restart — a crash loop that would take the secrets broker, scheduler,
+ * monitors, browser IPC, and self-heal down with it. `waitForListening` is what
+ * turns that into one skipped receiver.
+ */
+export async function startHostedWebhookReceivers(opts) {
+    const { log } = opts;
+    const resolveSecrets = opts.resolveSecrets ?? resolveReceiverSecrets;
+    const { receivers } = readDaemonWebhooksConfig();
+    const servers = [];
+    for (const receiver of receivers) {
+        const port = receiver.port ?? DEFAULT_WEBHOOK_PORT;
+        let secrets;
+        try {
+            secrets = resolveSecrets(receiver.bundle);
+        }
+        catch (err) {
+            log('WARN', `webhook receiver on :${port} skipped: ${err.message}`);
+            continue;
+        }
+        let server = null;
+        try {
+            server = startWebhookServer({
+                host: '127.0.0.1',
+                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)
+                        parts.push(`routines ${matchedJobNames.join(', ')}`);
+                    if (matchedHandlerNames.length)
+                        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}`);
+                },
+            });
+            await waitForListening(server);
+            servers.push(server);
+            log('INFO', `webhook receiver bound on 127.0.0.1:${port} (bundle ${receiver.bundle})`);
+            if (receiver.funnel)
+                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}`);
+        }
+    }
+    return {
+        count: servers.length,
+        close: () => Promise.all(servers.map((s) => new Promise((resolve) => s.close(() => resolve())))).then(() => undefined),
+    };
+}

package/dist/lib/device-config.d.ts

@@ -1,55 +1,46 @@
 /**
- * Device/user config keys — typed read/write over the central agents.yaml store.
+ * Device/user config keys — typed read/write over the three-layer store.
  *
  * One registry (`CONFIG_KEYS`) maps each CLI dotted name to where it lives:
- *   - user scope     → central `~/.agents/agents.yaml` under `config:` (syncs
- *                      fleet-wide via `agents repo push/pull`)
- *   - device scope   → split by `visibility`, which asks WHO READS IT:
- *       · `shared`   → central `fleet.devices.<name>.config`, because a PEER
- *                      reads it (the ssh keys and platform to dial the box,
- *                      agents.max-concurrent for placement, auto-launch and
- *                      notes for fleet views). Names and non-secret values only
- *                      (a secrets-bundle NAME is fine; a credential never is).
- *       · `machine`  → the owning box's own doc, never the shared file, because
- *                      nothing off-box reads it (browser.profile,
- *                      browser.remote-control, scheduler.enabled,
- *                      daemon.enabled).
+ *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                    fleet-wide via `agents repo push/pull`)
+ *   - device scope → the per-device TRACKED doc
+ *                    `~/.agents/devices/<name>/agents.yaml` under `config:` —
+ *                    conflict-free by construction (each machine writes only
+ *                    its own folder, and the churny auto-written pins no longer
+ *                    share the file)
+ *   - fleet layer  → central `~/.agents/agents.yaml` under
+ *                    `fleet.defaults.config` — fleet-wide defaults written by
+ *                    `agents devices config --fleet <key> <value>`
  *
- * That split exists because "central for everything" put 13 machines on one
- * tracked path and they stopped being able to pull. `browser.remote-control` is
- * also a consent flag — syncing one box's opt-in to the rest was a security bug,
- * not just churn.
+ * Read order for a device-scope key: built-in default < fleet.defaults.config
+ * < per-device config:. Names and non-secret values only (a secrets-bundle
+ * NAME is fine; a credential never is).
  *
  * The device registry (`~/.agents/.history/devices/registry.json`) stays the
  * DISCOVERY cache (address, tailscale snapshot, reachability); the profile
  * fields config can override (ssh.*, platform, user) are overlaid onto it at
  * read time by `lib/devices/resolve-profile.ts`.
  *
- * Legacy stores (per-device `devices/<host>/agents.yaml` config and
- * `.history/devices/auto-launch.json`) are folded into the central block once
- * by `lib/devices/config-migration.ts`, invoked on the first read/write in a
- * process — after migration there is ONE read path, no fallback branches.
+ * Legacy stores (central `fleet.devices.<name>.config`, legacy auto-launch.json,
+ * doc-level defaultBrowserProfile, pins in tracked docs) are folded into this
+ * layout once by `lib/devices/config-migration.ts`, invoked on the first
+ * read/write in a process — after migration there is ONE read path per layer,
+ * no fallback branches.
  *
  * Unset always means today's behavior (the documented default).
  */
 /** Which tier of the agents.yaml store a key lives in. */
 export type ConfigScope = 'user' | 'device';
 /**
- * For a device-scope key: WHO READS IT, which is what decides where it is stored.
+ * For a device-scope key: WHO READS IT. Storage is still the three-layer
+ * store (per-device doc / fleet.defaults.config); visibility only gates
+ * whether a PEER may read or write the key.
  *
- * - `shared`  — a PEER reads it, so it must be visible fleet-wide and lives in the
- *   tracked `fleet.devices.<name>.config`. `ssh.*` and `platform` are the
- *   load-bearing cases: machine A resolves them to build the ssh target for B
- *   (`lib/devices/resolve-profile.ts`), so it cannot ask B for them.
- * - `machine` — only the owning box ever reads it, so it belongs in that box's
- *   own gitignored doc and must never reach the fleet-shared file. Storing these
- *   centrally is what makes 13 machines write one tracked path.
- *
- * Declaring this is MANDATORY for a device-scope key — the union below makes
- * omitting it a compile error, mirroring how `META_KEY_SCOPE` (lib/state.ts) uses
- * an exhaustive `Record<keyof Meta, ...>`. Before this, a new key picked its home
- * by hand with no signal, which is how operator config drifted into the shared
- * file twice.
+ * - `shared`  — a peer reads it (ssh.*, platform, role, caps), so any box
+ *   may set it for any device. Lands in that device's tracked doc.
+ * - `machine` — only the owning box ever reads it (scheduler, daemon, tmux,
+ *   browser consent). Refused for a peer — run it on that box instead.
  */
 export type ConfigVisibility = 'shared' | 'machine';
 /** Value type of a config key — drives validation and `--json` rendering. */
@@ -79,17 +70,21 @@ export type ConfigKeySpec = (ConfigKeySpecBase & {
     scope: 'device';
     visibility: ConfigVisibility;
 });
+/** Which layer set a key's effective value (`default` = unset, built-in behavior). */
+export type ConfigSource = 'user' | 'device' | 'fleet' | 'default';
 /** A key with its resolved value and the layer that set it. */
 export interface ConfigEntry {
     spec: ConfigKeySpec;
-    /** The stored value, or undefined when unset (unset = default behavior). */
+    /** The effective value, or undefined when unset (unset = default behavior). */
     value: unknown;
-    /** Which layer set it; undefined when unset. */
-    layer?: ConfigScope;
+    /** Which layer set the effective value. */
+    source: ConfigSource;
 }
-/** Options scoping a read/write to a specific device (default: this machine). */
+/** Options scoping a read/write: a specific device (default: this machine), or the fleet-defaults layer. */
 export interface ConfigTarget {
     device?: string;
+    /** Write/read the fleet-wide defaults layer (central fleet.defaults.config). */
+    fleet?: boolean;
 }
 /** Roles a device can be marked with — see the `role` key below. */
 declare const DEVICE_ROLES: readonly ["worker", "personal"];
@@ -99,40 +94,31 @@ export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */
 export declare function configKeySpec(name: string): ConfigKeySpec;
 /**
- * Fold the legacy per-device config stores into the central block, once per
+ * Fold the legacy config/pins stores into the current layout, once per
  * process. A failure is loud but non-fatal — config reads must keep working,
  * and the next process retries the fold. Honors AGENTS_SKIP_MIGRATION=1, the
  * same gate bootstrap's runMigration uses (tests pin it so a fork never folds
  * the developer's real ~/.agents as a side effect).
- *
- * Call this ONLY from a lifecycle entry point (daemon boot, `runMigration`).
- * It must never hang off a config read or write: `~/.agents/agents.yaml` is a
- * tracked file shared by every machine in the fleet, so a migration on the read
- * path means an ordinary `agents config get` can dirty the shared file. That is
- * what left yosemite-s0 unable to pull — 13 machines each rewriting one tracked
- * path, on nearly every command.
  */
 export declare function ensureDeviceConfigMigrated(): void;
+/** The fleet-defaults config layer (central `fleet.defaults.config`; {} when unset). */
+export declare function readFleetConfigDefaults(): Record<string, unknown>;
 /**
- * The raw device-scope config block for `device` from the central
- * `fleet.devices.<name>.config` map ({} when unset). This is the single read
- * path post-migration — the profile resolver (`lib/devices/resolve-profile.ts`)
+ * The effective device-scope config block for `device`: fleet.defaults.config
+ * overlaid with the per-device doc's config:. This is the single read path
+ * post-migration — the profile resolver (`lib/devices/resolve-profile.ts`)
  * goes through here. Deliberately does NOT auto-trigger the migration: it
- * serves the hot dial/render paths, and the keys it resolves (ssh.*, platform)
- * are new — they never existed in the legacy stores. Keys with legacy data are
- * read through the public API below, which triggers the fold.
+ * serves the hot dial/render paths. Sync and cheap (small local files).
  */
 export declare function readDeviceConfigValues(device: string): Record<string, unknown>;
-/** Get one config key's value and the layer that set it. */
+/** Get one config key's effective value and the layer that set it. */
 export declare function getConfigValue(name: string, opts?: ConfigTarget): ConfigEntry;
 /**
- * List every known key with its value and the layer that set it.
+ * List every known key with its effective value and the layer that set it.
  *
- * Listing a PEER omits its machine-local keys rather than throwing. Their values
- * live in that box's own doc and are genuinely unknowable from here, but a bulk
- * listing must not hard-fail because one key in the registry is unreadable —
- * `agents devices config <peer>` should still show everything it CAN resolve.
- * Asking for such a key by name still errors, with the `agents ssh` fix named.
+ * Listing a PEER omits its machine-local keys rather than throwing — those
+ * values live on that box and are unknowable from here, but a bulk listing
+ * must not hard-fail. Asking for such a key by name still errors.
  */
 export declare function listConfig(opts?: ConfigTarget): ConfigEntry[];
 /** List user-scope config keys with their values. Used to show inherited settings
@@ -140,9 +126,14 @@ export declare function listConfig(opts?: ConfigTarget): ConfigEntry[];
 export declare function listUserConfig(): ConfigEntry[];
 /** Resolve the explicit usage host, falling back to the user's interactive host. */
 export declare function resolveUsagePrimaryHost(): string | null;
-/** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
+/**
+ * Set a config key (validated). Device-scope keys target this machine unless
+ * `opts.device` names a peer; `opts.fleet` writes the fleet-wide defaults layer
+ * instead. User-scope keys reject `fleet` (they are already fleet-wide).
+ */
 export declare function setConfigValue(name: string, value: unknown, opts?: ConfigTarget): void;
-/** Unset a config key — restores default behavior. No-op when already unset. */
+/** Unset a config key — restores the next layer down (fleet default, then the
+ * built-in default). No-op when already unset at that layer. */
 export declare function unsetConfigValue(name: string, opts?: ConfigTarget): void;
 /** A role an operator marked a device with (`agents devices role <name> <role>`). */
 export type ConfiguredDeviceRole = (typeof DEVICE_ROLES)[number];
@@ -159,13 +150,18 @@ export declare function configuredDeviceRole(name: string): ConfiguredDeviceRole
 /** Mark a device's role fleet-wide; `undefined` clears the mark. */
 export declare function setConfiguredDeviceRole(name: string, role: ConfiguredDeviceRole | undefined): void;
 /**
- * Every device an operator has marked, keyed by device name. Devices with no
- * mark are absent — that absence is what makes the worker allowlist opt-in.
+ * Every device with an effective role, keyed by device name. Layers like every
+ * other device-scope key: the fleet default (central fleet.defaults.config)
+ * applies fleet-wide and the per-device doc wins on conflict. `roster` (the
+ * registered device names) lets a fleet default reach devices that have no doc
+ * of their own; without it only devices with docs are considered — so a
+ * fleet-wide `role` default would silently miss a doc-less device and drop it
+ * from the worker allowlist. Mirrors {@link loadAutoLaunchPreferences}.
  */
-export declare function listConfiguredDeviceRoles(): Record<string, ConfiguredDeviceRole>;
+export declare function listConfiguredDeviceRoles(roster?: string[]): Record<string, ConfiguredDeviceRole>;
 /** The configured automatic-placement pool mode. Unset means `workers`. */
 export declare function autoPoolMode(): AutoPoolMode;
-/** A device's auto-launch flags, as read by the ext's launch ranking. */
+/** A device's auto-launch flags, as read by Factory's launch ranking. */
 export interface AutoLaunchPreference {
     enabled?: boolean;
     preferred?: boolean;
@@ -173,16 +169,22 @@ export interface AutoLaunchPreference {
 /** True if the device is enabled for auto-launch. Unset defaults to true. */
 export declare function isAutoLaunchEnabled(name: string): boolean;
 /** Set whether a device is enabled for auto-launch. Setting the default
- * (enabled) removes the key to keep the block minimal. */
+ * (enabled) removes the key to keep the doc minimal. */
 export declare function setAutoLaunchEnabled(name: string, enabled: boolean): void;
 /** True if the device is preferred for auto-launch ranking. */
 export declare function isAutoLaunchPreferred(name: string): boolean;
 /** Set whether a device is preferred for auto-launch. Setting the default
- * (not preferred) removes the key to keep the block minimal. */
+ * (not preferred) removes the key to keep the doc minimal. */
 export declare function setAutoLaunchPreferred(name: string, preferred: boolean): void;
-/** Every device's auto-launch flags, keyed by device name (set flags only) —
- * the shape the ext's launch ranking consumes. */
-export declare function loadAutoLaunchPreferences(): Record<string, AutoLaunchPreference>;
+/**
+ * Every device's effective auto-launch flags, keyed by device name — the shape
+ * the menu-bar snapshot consumes. Layers like every other device-scope key: the
+ * fleet default (central fleet.defaults.config) applies fleet-wide and the
+ * per-device doc wins on conflict. `roster` (the registered device names) lets
+ * a fleet default reach devices that have no doc of their own; without it only
+ * devices with docs are listed.
+ */
+export declare function loadAutoLaunchPreferences(roster?: string[]): Record<string, AutoLaunchPreference>;
 /** True unless this machine's config disables the routines scheduler. */
 export declare function isSchedulerEnabled(): boolean;
 /**
@@ -212,10 +214,18 @@ export declare function isDaemonEnabled(): boolean;
  */
 export declare function assertDaemonEnabled(): void;
 /**
- * Read the `agents.max-concurrent` cap for each named device from the central
- * config block (no SSH). Devices without a cap are omitted — uncapped is the
- * default. Used as an input to host ranking (teams placement, Factory
- * auto-launch), never as a remote probe.
+ * Idle window (ms) the browser-task reaper (`browser/hygiene.ts`) uses on THIS
+ * machine, or `null` when idle reaping is off (`browser.task-idle-minutes=0`)
+ * — session-dead reaping is unaffected either way. Unset means the default 30
+ * minutes. Read by the daemon's periodic tick and, as the fallback when a
+ * caller omits `--idle-minutes`, by the `gc` IPC action.
+ */
+export declare function resolveBrowserTaskIdleMs(): number | null;
+/**
+ * Read the effective `agents.max-concurrent` cap for each named device (fleet
+ * defaults layered under the per-device doc; no SSH). Devices without a cap
+ * are omitted — uncapped is the default. Used as an input to host ranking
+ * (teams placement, AGI EXT auto-launch), never as a remote probe.
  */
 export declare function readMaxConcurrentCaps(devices: string[]): Record<string, number>;
 export {};