@phnx-labs/agents-cli 1.22.50 → 1.22.52

package/dist/lib/browser/ipc.js

@@ -69,6 +69,29 @@ const SOCKET_NAME = 'browser.sock';
  * coming near the grace window.
  */
 const IPC_CLOSE_TIMEOUT_MS = 1_500;
+/**
+ * How long {@link waitForSocket} waits for the browser daemon to come up before
+ * failing loud (PHNX-3289).
+ *
+ * The old flat 6s ceiling was the wedge: the shared daemon's browser IPC server
+ * restarts (version reconcile, supervisor restart, a hard-crashed predecessor's
+ * successor claiming the socket), and a client that started its wait *during*
+ * one of those restart windows could burn the whole 6s and throw
+ * `Timeout waiting for browser daemon socket` on an otherwise-healthy daemon. A
+ * browser start/navigate then failed intermittently and self-healed on the next
+ * try. 15s comfortably spans a restart; the stable-probe requirement below is
+ * what keeps a socket that "appears and is immediately destroyed" (#556) from
+ * being mistaken for a ready daemon.
+ */
+const SOCKET_WAIT_TIMEOUT_MS = 15_000;
+/**
+ * Consecutive successful probes required before {@link waitForSocket} declares
+ * the daemon ready. A single accept can land in the sliver between a restarting
+ * server binding and tearing back down; requiring two accepts ~100ms apart means
+ * we only return once the daemon is *staying* up, so the caller's real request
+ * doesn't race a restart it happened to probe mid-flight.
+ */
+const SOCKET_WAIT_STABLE_PROBES = 2;
 export class BrowserDaemonNotRunningError extends Error {
     constructor() {
         super(formatBrowserDaemonNotRunningError());
@@ -78,8 +101,8 @@ export class BrowserDaemonNotRunningError extends Error {
 export function formatBrowserDaemonNotRunningError() {
     return [
         'Browser daemon not running.',
-        'Start it with: agents browser start (auto-picks an installed browser)',
-        'Or pin a profile: agents browser start --profile <name>',
+        'Start it with: agents browser start (uses this machine\'s configured default browser)',
+        'Pick / pin a profile: agents browser use <name>  (or: agents browser start --profile <name>)',
         'List profiles: agents browser profiles list',
     ].join('\n');
 }
@@ -117,15 +140,104 @@ function probeDaemon(endpoint, timeoutMs = 500) {
 export async function isDaemonReachable() {
     return probeDaemon(getIpcEndpoint());
 }
-async function waitForSocket(_socketPath, timeoutMs) {
+/**
+ * Wait until the browser daemon is genuinely reachable, or throw.
+ *
+ * Re-probes across the whole window rather than latching on the first accept, so
+ * it survives an IPC-server restart that happens mid-wait (PHNX-3289): a restart
+ * just resets the consecutive-accept counter, and the loop keeps going until the
+ * daemon is *stably* up or the deadline passes. Bounded and fail-loud — a daemon
+ * that never comes up throws a message naming the endpoint and the budget, never
+ * a silent hang.
+ */
+export async function waitForSocket(_socketPath, timeoutMs = SOCKET_WAIT_TIMEOUT_MS) {
     const endpoint = getIpcEndpoint();
     const deadline = Date.now() + timeoutMs;
+    let consecutive = 0;
     while (Date.now() < deadline) {
-        if (await probeDaemon(endpoint))
-            return;
+        if (await probeDaemon(endpoint)) {
+            consecutive += 1;
+            if (consecutive >= SOCKET_WAIT_STABLE_PROBES)
+                return;
+        }
+        else {
+            // A dropped probe means a restart (or the daemon isn't up yet) — start the
+            // stability count over rather than counting accepts from before the gap.
+            consecutive = 0;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`Timeout waiting for browser daemon socket after ${Math.round(timeoutMs / 1000)}s (${endpoint}).`);
+}
+/** How long {@link resetBrowserDaemon} waits for the endpoint to go quiet after
+ * signalling a stop before it clears the socket and re-checks. Bounded so the
+ * command fails loud instead of hanging on a daemon that will not die. */
+const DAEMON_RESET_QUIESCE_MS = 5_000;
+/**
+ * Clear a wedged browser daemon so a subsequent `start` comes up clean
+ * (PHNX-3289). Stops the shared daemon (the same `stopDaemon` path
+ * `reconcileDaemonVersion` uses for a stale-version restart), waits for the IPC
+ * endpoint to stop accepting, then unlinks any stale `browser.sock` a
+ * hard-crashed daemon left behind — the file a fresh `start` would otherwise
+ * `unlink` blindly, racing whatever still holds it.
+ *
+ * Fails loud: if the endpoint is *still* reachable after the quiesce window, a
+ * live server is holding it and clearing the socket under it would orphan two
+ * servers on one path, so we throw rather than pretend the reset worked. The
+ * daemon auto-restarts on the next browser command.
+ */
+export async function resetBrowserDaemon() {
+    const endpoint = getIpcEndpoint();
+    const wasRunning = await probeDaemon(endpoint);
+    stopDaemon();
+    // Wait for the listener to actually release the endpoint. We must decide
+    // reachability BEFORE touching the socket file: unlinking a path out from
+    // under a live server makes new connects ENOENT (so it would *look* cleared)
+    // while the server keeps running — the two-servers orphan the eviction
+    // protocol exists to prevent. So a still-reachable endpoint fails loud here,
+    // and only a genuinely dead one gets its stale file removed below.
+    const deadline = Date.now() + DAEMON_RESET_QUIESCE_MS;
+    let reachable = wasRunning;
+    while (reachable && Date.now() < deadline) {
         await new Promise((resolve) => setTimeout(resolve, 100));
+        reachable = await probeDaemon(endpoint);
+    }
+    if (reachable) {
+        throw new Error(actionable('Browser daemon is still reachable after stop — a live server is holding the socket.', `Endpoint: ${endpoint}`, 'Next: agents daemon status   (find and stop the process holding it)'));
+    }
+    // Nothing is listening now — clear the leftover socket file a hard-crashed
+    // daemon left behind, so the next `start` binds clean instead of unlinking it
+    // blindly. (Named pipes vanish with their owning process, so Windows has no
+    // stale file to clear.)
+    const socketCleared = IS_WINDOWS ? false : await clearDeadSocketFile(endpoint, getSocketPath());
+    return { wasRunning, socketCleared };
+}
+/**
+ * Remove a leftover browser socket FILE, but only when nothing is listening on
+ * it — re-probing liveness IMMEDIATELY before the unlink to close the TOCTOU
+ * window (PHNX-3289 review). Between {@link resetBrowserDaemon}'s quiesce loop
+ * deciding the endpoint was unreachable and this unlink, a concurrent
+ * `browser start` could bind a NEW listener on the same path; an unconditional
+ * unlink would then delete a LIVE daemon's socket — the exact two-servers orphan
+ * this function exists to prevent. A listener seen here means the wedge is already
+ * resolved (a fresh daemon owns the path), so its socket is left intact. Returns
+ * true only when a genuinely dead file was removed.
+ */
+export async function clearDeadSocketFile(endpoint, socketPath) {
+    if (!fs.existsSync(socketPath))
+        return false;
+    // A listener bound again since the quiesce loop → do not touch its socket.
+    if (await probeDaemon(endpoint))
+        return false;
+    try {
+        fs.unlinkSync(socketPath);
+        return true;
+    }
+    catch {
+        // Raced with a fresh start that already claimed it — the goal (no stale
+        // socket) still holds, so report cleared only when it is genuinely gone.
+        return !fs.existsSync(socketPath);
     }
-    throw new Error('Timeout waiting for browser daemon socket');
 }
 /**
  * One long-lived connection to the existing browser daemon. Requests are
@@ -865,7 +977,7 @@ async function reconcileDaemonVersion(socketPath) {
     stopDaemon();
     startDaemon();
     if (!(await isDaemonReachable())) {
-        await waitForSocket(socketPath, 6000);
+        await waitForSocket(socketPath);
     }
     await new Promise((r) => setTimeout(r, 300));
 }
@@ -968,7 +1080,7 @@ async function prepareIPC(action, opts) {
         }
         startDaemon();
         if (!(await isDaemonReachable())) {
-            await waitForSocket(socketPath, 6000);
+            await waitForSocket(socketPath);
         }
         if (!(await isDaemonReachable())) {
             throw new Error(actionable('Failed to start browser daemon.', `Log: ${getDaemonLogPath()}`, 'Next: agents doctor   (checks for a second agents-cli install)'));

package/dist/lib/browser/profiles.d.ts

@@ -2,14 +2,17 @@ import type { BrowserProfile, ProfileName } from './types.js';
 export type { BrowserProfile } from './types.js';
 export { declaringDevices, profileKind, profileRegistry, type ProfileDeclaration, } from './registry.js';
 /**
- * Name of the profile `ensureDefaultBrowserProfile` auto-detects and pins.
+ * Name of the profile the setup wizards pin as this machine's default browser
+ * (`agents setup`, `agents setup browser`). Older builds also auto-created it
+ * silently on the first `agents browser start`; PHNX-3296 removed that — see
+ * {@link ensureDefaultBrowserProfile}.
  *
  * It is `auto-chrome`, NOT `default`, since RUSH-2709: `default` used to be
  * both this concrete profile AND the alias meaning "whatever profile the user
- * configured", so `--profile default` landed on a literal auto-detected Chrome
- * on one command and on the user's configured Comet on another. The alias now
- * lives alone in {@link DEFAULT_PROFILE_ALIAS} and resolves in exactly one
- * place ({@link resolveProfileRef}).
+ * configured", so `--profile default` landed on a literal Chrome on one command
+ * and on the user's configured Comet on another. The alias now lives alone in
+ * {@link DEFAULT_PROFILE_ALIAS} and resolves in exactly one place
+ * ({@link resolveProfileRef}).
  */
 export declare const DEFAULT_BROWSER_PROFILE_NAME = "auto-chrome";
 /**
@@ -106,33 +109,52 @@ export declare function resolveProfileRef(ref?: string): Promise<string | undefi
  * no profile of that name) goes through {@link ensureDefaultBrowserProfile} —
  * which additionally verifies the resolved default can launch on THIS machine.
  * An undeclared configured default is an error. A declared default whose
- * browser isn't installed here warns and falls through to auto-detect.
+ * browser isn't installed here warns and falls through to an existing profile,
+ * else the actionable throw below.
  *
  * `start` is the only command that launches a browser, so it is the only one
  * that may do those things; routing a filter-only command through this would
- * warn about, and rewrite, config the user never asked it to touch.
+ * warn about config the user never asked it to touch.
  *
- * Throws when the configured default is undeclared, or when no profile exists
- * and no supported browser is installed.
+ * Throws ({@link noDefaultBrowserError}) when the configured default is
+ * undeclared, or when no profile exists that can launch here.
  */
 export declare function resolveProfileRefForStart(ref?: string): Promise<string>;
+/**
+ * The error a bare `agents browser start` raises when this machine has no
+ * launchable default browser. Its own function so the wording — the one thing
+ * the user reads when a browser won't start — stays in one place and is
+ * testable without spawning anything.
+ *
+ * Since PHNX-3296 this is a hard stop, NOT a silent auto-create. The old
+ * behavior probed the installed Chromium-family browsers and minted a
+ * logged-out `auto-chrome` profile on the spot; agents then drove a signed-out
+ * Chrome that popped up on the user's Mac unbidden. Which browser agents drive
+ * is a choice the user makes once, in `agents setup` — never one this code
+ * makes for them.
+ */
+export declare function noDefaultBrowserError(): Error;
 /**
  * Resolve the profile a bare `agents browser start` uses.
  *
  * Order: (1) the device-local configured default (`agents browser use <name>`)
  * when it names a profile that exists and can launch here; (2) an existing
- * auto-detected profile that can launch here; (3) auto-pick the first installed
- * Chromium-family browser and pin `auto-chrome` (or repair a stale legacy
- * `default`) to it.
+ * auto-detected profile (`auto-chrome`, or a legacy `default`) that can launch
+ * here. When neither resolves, THROW ({@link noDefaultBrowserError}) rather than
+ * detect-and-create — see that function for why (PHNX-3296).
  *
  * Two failure modes at the configured-default step are not the same:
  *   - No device declares the name (including a leftover central `browser:`
- *     entry that was never claimed) → throw. Auto-creating `auto-chrome` would
- *     hand the agent a logged-out browser while `browser.profile` still names
- *     the credentialed one.
+ *     entry that was never claimed) → throw. Falling back to a minted profile
+ *     would hand the agent a logged-out browser while `browser.profile` still
+ *     names the credentialed one.
  *   - The name is declared, but its browser/binary is not installed HERE →
- *     warn and fall through. That is a missing binary on this box, not a
- *     missing identity; auto-detect is the existing repair.
+ *     warn and fall through to an existing profile, else the actionable throw.
+ *     That is a missing binary on this box, not a missing identity.
+ *
+ * This RECOGNIZES a pre-existing `auto-chrome`/legacy `default` so installs that
+ * already carry one keep resolving it (and its running browser + runtime dirs),
+ * but it never CREATES one.
  */
 export declare function ensureDefaultBrowserProfile(): Promise<BrowserProfile>;
 /**

package/dist/lib/browser/profiles.js

@@ -4,18 +4,20 @@ import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, updateMeta,
 import { getConfigValue } from '../device-config.js';
 import { machineId } from '../machine-id.js';
 import { declaringDevices, profileRegistry, } from './registry.js';
-import { findBrowserPath, findFirstInstalledBrowser, isPortInUse } from './chrome.js';
-import { DEFAULT_VIEWPORT } from './devices.js';
+import { findBrowserPath, isPortInUse } from './chrome.js';
 export { declaringDevices, profileKind, profileRegistry, } from './registry.js';
 /**
- * Name of the profile `ensureDefaultBrowserProfile` auto-detects and pins.
+ * Name of the profile the setup wizards pin as this machine's default browser
+ * (`agents setup`, `agents setup browser`). Older builds also auto-created it
+ * silently on the first `agents browser start`; PHNX-3296 removed that — see
+ * {@link ensureDefaultBrowserProfile}.
  *
  * It is `auto-chrome`, NOT `default`, since RUSH-2709: `default` used to be
  * both this concrete profile AND the alias meaning "whatever profile the user
- * configured", so `--profile default` landed on a literal auto-detected Chrome
- * on one command and on the user's configured Comet on another. The alias now
- * lives alone in {@link DEFAULT_PROFILE_ALIAS} and resolves in exactly one
- * place ({@link resolveProfileRef}).
+ * configured", so `--profile default` landed on a literal Chrome on one command
+ * and on the user's configured Comet on another. The alias now lives alone in
+ * {@link DEFAULT_PROFILE_ALIAS} and resolves in exactly one place
+ * ({@link resolveProfileRef}).
  */
 export const DEFAULT_BROWSER_PROFILE_NAME = 'auto-chrome';
 /**
@@ -221,14 +223,15 @@ export async function resolveProfileRef(ref) {
  * no profile of that name) goes through {@link ensureDefaultBrowserProfile} —
  * which additionally verifies the resolved default can launch on THIS machine.
  * An undeclared configured default is an error. A declared default whose
- * browser isn't installed here warns and falls through to auto-detect.
+ * browser isn't installed here warns and falls through to an existing profile,
+ * else the actionable throw below.
  *
  * `start` is the only command that launches a browser, so it is the only one
  * that may do those things; routing a filter-only command through this would
- * warn about, and rewrite, config the user never asked it to touch.
+ * warn about config the user never asked it to touch.
  *
- * Throws when the configured default is undeclared, or when no profile exists
- * and no supported browser is installed.
+ * Throws ({@link noDefaultBrowserError}) when the configured default is
+ * undeclared, or when no profile exists that can launch here.
  */
 export async function resolveProfileRefForStart(ref) {
     if (ref && ref !== DEFAULT_PROFILE_ALIAS)
@@ -238,23 +241,45 @@ export async function resolveProfileRefForStart(ref) {
         return ref;
     return (await ensureDefaultBrowserProfile()).name;
 }
+/**
+ * The error a bare `agents browser start` raises when this machine has no
+ * launchable default browser. Its own function so the wording — the one thing
+ * the user reads when a browser won't start — stays in one place and is
+ * testable without spawning anything.
+ *
+ * Since PHNX-3296 this is a hard stop, NOT a silent auto-create. The old
+ * behavior probed the installed Chromium-family browsers and minted a
+ * logged-out `auto-chrome` profile on the spot; agents then drove a signed-out
+ * Chrome that popped up on the user's Mac unbidden. Which browser agents drive
+ * is a choice the user makes once, in `agents setup` — never one this code
+ * makes for them.
+ */
+export function noDefaultBrowserError() {
+    return new Error('No default browser is configured on this machine. ' +
+        'Run `agents setup` (or `agents browser use <name>`) to pick the browser agents should drive. ' +
+        'If this is a headless worker, use the fleet hub instead: `agents config set browser.device <host>`.');
+}
 /**
  * Resolve the profile a bare `agents browser start` uses.
  *
  * Order: (1) the device-local configured default (`agents browser use <name>`)
  * when it names a profile that exists and can launch here; (2) an existing
- * auto-detected profile that can launch here; (3) auto-pick the first installed
- * Chromium-family browser and pin `auto-chrome` (or repair a stale legacy
- * `default`) to it.
+ * auto-detected profile (`auto-chrome`, or a legacy `default`) that can launch
+ * here. When neither resolves, THROW ({@link noDefaultBrowserError}) rather than
+ * detect-and-create — see that function for why (PHNX-3296).
  *
  * Two failure modes at the configured-default step are not the same:
  *   - No device declares the name (including a leftover central `browser:`
- *     entry that was never claimed) → throw. Auto-creating `auto-chrome` would
- *     hand the agent a logged-out browser while `browser.profile` still names
- *     the credentialed one.
+ *     entry that was never claimed) → throw. Falling back to a minted profile
+ *     would hand the agent a logged-out browser while `browser.profile` still
+ *     names the credentialed one.
  *   - The name is declared, but its browser/binary is not installed HERE →
- *     warn and fall through. That is a missing binary on this box, not a
- *     missing identity; auto-detect is the existing repair.
+ *     warn and fall through to an existing profile, else the actionable throw.
+ *     That is a missing binary on this box, not a missing identity.
+ *
+ * This RECOGNIZES a pre-existing `auto-chrome`/legacy `default` so installs that
+ * already carry one keep resolving it (and its running browser + runtime dirs),
+ * but it never CREATES one.
  */
 export async function ensureDefaultBrowserProfile() {
     const configured = getConfiguredDefaultProfileName();
@@ -275,7 +300,7 @@ export async function ensureDefaultBrowserProfile() {
                 `Or unset the default with: agents browser use --unset`);
         }
         console.warn(`warning: configured default browser profile "${configured}" can't launch on this ` +
-            `machine (its browser/binary isn't installed here); falling back to auto-detect. ` +
+            `machine (its browser/binary isn't installed here). ` +
             `Fix with: agents browser use <name>  (or --unset)`);
     }
     // Prefer whichever auto-detected profile this machine already carries: the
@@ -285,38 +310,12 @@ export async function ensureDefaultBrowserProfile() {
     const existing = await getAutoDetectedProfile();
     if (existing && isProfileLaunchableHere(existing))
         return existing;
-    const detected = findFirstInstalledBrowser();
-    if (!detected) {
-        throw new Error('No supported browser found. Install one of: Chrome, Brave, Edge, Chromium, Comet, or Arc, ' +
-            'then re-run `agents browser start`. Or create a profile explicitly with ' +
-            '`agents browser profiles create <name> --browser <chrome|comet|chromium|brave|edge|arc|custom>`. ' +
-            'Note: Safari and Firefox are not supported — agents browser drives over the ' +
-            'Chrome DevTools Protocol, which they don\'t implement.');
-    }
-    const freePort = await findFreeProfilePort();
-    const profile = {
-        // Regenerate under the name that is already on disk when there is one, so a
-        // stale legacy `default` is repaired in place instead of leaving the user
-        // with two auto-detected profiles.
-        name: existing?.name ?? DEFAULT_BROWSER_PROFILE_NAME,
-        description: `Auto-detected ${detected.browserType} profile`,
-        browser: detected.browserType,
-        binary: detected.binary,
-        endpoints: [`cdp://127.0.0.1:${freePort}`],
-        viewport: {
-            width: DEFAULT_VIEWPORT.width,
-            height: DEFAULT_VIEWPORT.height,
-        },
-    };
-    // A stale `default` (auto-created on another OS, unlaunchable here) is
-    // regenerated in place; otherwise this is the first-run create.
-    if (existing) {
-        await updateProfile(profile);
-    }
-    else {
-        await createProfile(profile);
-    }
-    return profile;
+    // No configured default resolves and no existing profile launches here. We
+    // used to auto-detect the first installed browser and silently mint (or
+    // regenerate) an `auto-chrome` profile at this point — that is exactly the
+    // logged-out-Chrome-on-your-Mac bug PHNX-3296 removed. Stop and tell the user
+    // how to choose a browser instead.
+    throw noDefaultBrowserError();
 }
 /**
  * Compute the LOCAL port a profile will occupy at runtime:

package/dist/lib/browser/runtime-state.d.ts

@@ -203,8 +203,10 @@ export declare const PRUNE_REASON_TEXT: Record<PruneReason, string>;
  *   - **the configured default** — this machine resolves a bare
  *     `agents browser start` to it; removing it breaks that command.
  *   - **the auto-detected profile** (`auto-chrome`, or the `default` an older
- *     build wrote) — auto-regenerated by `ensureDefaultBrowserProfile`, so
- *     pruning it is pure churn.
+ *     build wrote) — still recognized and resolved by
+ *     `ensureDefaultBrowserProfile` as this machine's default; since PHNX-3296
+ *     it is no longer re-created on demand, so pruning it forces the user
+ *     back through `agents setup` to get a default browser again.
  *
  * Known limitation: `BrowserProfileConfig` records no creation time, so a
  * profile created seconds ago and not yet started is indistinguishable from an

package/dist/lib/browser/runtime-state.js

@@ -343,8 +343,10 @@ export const PRUNE_REASON_TEXT = {
  *   - **the configured default** — this machine resolves a bare
  *     `agents browser start` to it; removing it breaks that command.
  *   - **the auto-detected profile** (`auto-chrome`, or the `default` an older
- *     build wrote) — auto-regenerated by `ensureDefaultBrowserProfile`, so
- *     pruning it is pure churn.
+ *     build wrote) — still recognized and resolved by
+ *     `ensureDefaultBrowserProfile` as this machine's default; since PHNX-3296
+ *     it is no longer re-created on demand, so pruning it forces the user
+ *     back through `agents setup` to get a default browser again.
  *
  * Known limitation: `BrowserProfileConfig` records no creation time, so a
  * profile created seconds ago and not yet started is indistinguishable from an

package/dist/lib/browser/service.js

@@ -2330,9 +2330,10 @@ export class BrowserService {
         if (!opts.createIfMissing)
             return null;
         // The top-of-function consent gate already refused a fleet-remote create
-        // here — before ensureDefaultBrowserProfile() below can probe local browser
-        // installs and persist an `auto-chrome` profile — so a refused request never
-        // leaves state behind on the target machine.
+        // here — before ensureDefaultBrowserProfile() below resolves a default — so
+        // a refused request never touches the target machine. Since PHNX-3296 that
+        // resolver never mints a profile: with no launchable default it throws, and
+        // the throw surfaces to the caller exactly like any other start failure.
         // Implicit start on the default / named profile.
         let profileName = opts.profile;
         if (!profileName) {

package/dist/lib/channels/owner-forward.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Forward an owner notification to a capable fleet peer over SSH (PHNX-3303).
+ *
+ * The owner's delivery provider for the rush-backed channels (imessage /
+ * telegram / slack / discord via the `rush` CLI) is macOS-only and
+ * keychain-bound, so a headless Linux worker structurally CANNOT ring the
+ * owner's phone: `agents feed post --level important` records the post but the
+ * owner sink fails with `rush CLI not found on PATH`, and the important post
+ * reaches nobody. `probeOwnerSink` (owner-sink.ts) already reports this as the
+ * `owner-sink-unreachable` doctor finding; this module is the runtime answer to
+ * it — instead of stranding the failure, hand the delivery to a reachable macOS
+ * peer that DOES have the provider.
+ *
+ * This mirrors the SSH reroute `agents message` (decideHostTaskRoute →
+ * runOnPeer) and the sessions fan-out already use for work that lives on another
+ * box: pick a reachable peer from the device registry and run the same `agents`
+ * verb there. Here the verb is `agents send --to owner`, which resolves the
+ * peer's own (fleet-synced) owner destination and delivers through its local
+ * rush — so the owner is addressed once, from the one box that can reach them.
+ *
+ * Best-effort seam: it never throws and never blocks the post. When no capable
+ * peer is reachable it resolves `undefined` and the caller keeps its original
+ * clean local error, exactly as before.
+ */
+import type { Meta } from '../types.js';
+import type { SendResult } from './registry.js';
+import type { DeviceProfile } from '../devices/registry.js';
+/**
+ * Env marker set on the forwarded `agents send` so a box that received a
+ * forwarded owner notify never forwards it onward. `agents send` does not route
+ * through this module today, so this is defense-in-depth against a future
+ * consumer wiring forwarding into the send path and creating a fan-out loop.
+ */
+export declare const OWNER_FORWARD_GUARD_ENV = "AGENTS_OWNER_NO_FORWARD";
+/** Why forwarding did not run, so a caller/test can assert the decision. */
+export type OwnerForwardSkip = 'guarded' | 'not-rush-backed' | 'no-capable-peer';
+export interface OwnerForwardPlan {
+    /** Ordered machine ids to try — capable (macOS), reachable, self excluded. */
+    candidates: string[];
+    /** Set when forwarding does not apply; the caller keeps its local error. */
+    skip?: OwnerForwardSkip;
+}
+/**
+ * True when the resolved owner transport is the macOS-only rush family — the
+ * one case a Linux/headless box structurally cannot deliver and a peer can.
+ * `openclaw-telegram` and the local `desktop`/`mailbox` providers are NOT
+ * rush-backed, so a failure there is not a wrong-OS problem and is left as-is.
+ * Mirrors the same `RUSH_CHANNELS.includes(transport)` gate in owner-sink.ts.
+ */
+export declare function isRushBackedTransport(channel: string, meta: Meta): boolean;
+/**
+ * Decide which peers can deliver the owner notification, in try order. Pure —
+ * no I/O — so the channel gate, the recursion guard, self-exclusion, and the
+ * capability/ordering rules are unit-testable without a live tailnet.
+ *
+ * Only macOS peers are candidates: the rush owner transport is macOS-only, so a
+ * Linux/Windows peer could not deliver it either. The configured
+ * `interactive.host` (the box the operator sits at, where rush is signed in) is
+ * tried first when it is among the candidates.
+ */
+export declare function planOwnerForward(channel: string, meta: Meta, devices: DeviceProfile[], self: string, opts?: {
+    guarded?: boolean;
+}): OwnerForwardPlan;
+/**
+ * Deliver `text` to the owner FROM one peer over SSH. Runs the peer's own
+ * `agents send --to owner --text <text> --json`, which resolves that box's
+ * fleet-synced owner destination and delivers through its local provider.
+ * Resolves the parsed `SendResult`, or `undefined` when the peer is
+ * unreachable / not a dialable device / answered with unparseable output —
+ * every one of which means "try the next peer".
+ */
+export type PeerOwnerSender = (machine: string, text: string) => Promise<SendResult | undefined>;
+/**
+ * Try each capable peer in order and return the first successful delivery. A
+ * peer that is unreachable or reports its own delivery failure is skipped and
+ * the next is tried; the first `ok:true` wins and stops the sweep so the owner's
+ * phone rings once. Resolves `undefined` when forwarding does not apply or no
+ * peer delivered — the caller then keeps its original local error.
+ *
+ * The transport (`send`) is injectable so the try-order / first-success / stop
+ * orchestration is testable without a live SSH host; the default runs the real
+ * `agents send --to owner` over SSH.
+ */
+export declare function forwardOwnerNotifyToPeer(text: string, channel: string, meta: Meta, opts?: {
+    self?: string;
+    devices?: DeviceProfile[];
+    send?: PeerOwnerSender;
+}): Promise<SendResult | undefined>;