@phnx-labs/agents-cli 1.22.51 → 1.22.52

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

package/dist/lib/channels/owner-forward.js

@@ -0,0 +1,116 @@
+import { loadDevices, isDialableDevice } from '../devices/registry.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { RUSH_CHANNELS } from './providers/rush.js';
+import { resolvePeerTarget, sshCapture } from '../session/remote/remote-list.js';
+import { buildRemoteAgentsInvocation, stripClixml } from '../hosts/remote-cmd.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 const OWNER_FORWARD_GUARD_ENV = 'AGENTS_OWNER_NO_FORWARD';
+/** Per-peer SSH deadline for a one-shot owner delivery. */
+const PEER_SEND_TIMEOUT_MS = 15_000;
+/**
+ * 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 function isRushBackedTransport(channel, meta) {
+    const transport = meta.notify?.transports?.[channel] ?? channel;
+    return RUSH_CHANNELS.includes(transport);
+}
+/**
+ * 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 function planOwnerForward(channel, meta, devices, self, opts = {}) {
+    if (opts.guarded)
+        return { candidates: [], skip: 'guarded' };
+    if (!isRushBackedTransport(channel, meta))
+        return { candidates: [], skip: 'not-rush-backed' };
+    const selfId = normalizeHost(self);
+    const capable = devices.filter((d) => d.platform === 'macos' && isDialableDevice(d) && normalizeHost(d.name) !== selfId);
+    const interactiveHost = typeof meta.config?.interactiveHost === 'string'
+        ? normalizeHost(meta.config.interactiveHost)
+        : undefined;
+    const rank = (name) => (interactiveHost && normalizeHost(name) === interactiveHost ? 0 : 1);
+    const candidates = capable
+        .map((d) => normalizeHost(d.name))
+        .sort((a, b) => rank(a) - rank(b));
+    if (candidates.length === 0)
+        return { candidates: [], skip: 'no-capable-peer' };
+    return { candidates };
+}
+async function sendOnPeer(machine, text) {
+    const peer = await resolvePeerTarget(machine);
+    if (!peer)
+        return undefined;
+    const args = ['send', '--to', 'owner', '--text', text, '--json'];
+    // Reuse the one injection-tested remote-command builder every `--device`
+    // dispatch uses (posix `bash -lc` / Windows `-EncodedCommand`), rather than a
+    // second hand-rolled quoting path on a security-sensitive seam. The env map is
+    // the loop guard, exported the same way every remote invocation exports env.
+    const remoteCmd = buildRemoteAgentsInvocation(args, undefined, peer.os, { [OWNER_FORWARD_GUARD_ENV]: '1' });
+    const capture = await sshCapture(peer.target, remoteCmd, PEER_SEND_TIMEOUT_MS);
+    if (capture.code !== 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(stripClixml(capture.stdout));
+        if (parsed && typeof parsed === 'object' && typeof parsed.ok === 'boolean')
+            return parsed;
+    }
+    catch {
+        return undefined;
+    }
+    return 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 async function forwardOwnerNotifyToPeer(text, channel, meta, opts = {}) {
+    // Cheap, I/O-free gate first: a box that already received a forward, or an
+    // owner channel that isn't the macOS-only rush family, can never forward — so
+    // a normal local success/failure never pays a device-registry disk read.
+    if (process.env[OWNER_FORWARD_GUARD_ENV] === '1')
+        return undefined;
+    if (!isRushBackedTransport(channel, meta))
+        return undefined;
+    const self = opts.self ?? machineId();
+    let devices = opts.devices;
+    if (!devices) {
+        try {
+            devices = Object.values(await loadDevices());
+        }
+        catch {
+            return undefined; // no registry, nothing to forward to
+        }
+    }
+    const plan = planOwnerForward(channel, meta, devices, self);
+    if (plan.candidates.length === 0)
+        return undefined;
+    const send = opts.send ?? sendOnPeer;
+    for (const machine of plan.candidates) {
+        const result = await send(machine, text);
+        if (result?.ok)
+            return result;
+    }
+    return undefined;
+}

package/dist/lib/channels/owner-sink.js

@@ -11,6 +11,13 @@
  * after-the-fact `owner failed: …` line. `agents doctor` had no signal for it,
  * which is exactly the gap RUSH-2258 / RUSH-2262 flagged.
  *
+ * At runtime the owner-delivery lane no longer strands this failure: when local
+ * delivery fails on a box that structurally cannot reach the owner,
+ * `forwardOwnerNotifyToPeer` (owner-forward.ts) hands it to a capable macOS peer
+ * over SSH (PHNX-3303). This finding still stands as a diagnostic — the forward
+ * is best-effort and only lands when a reachable mac peer exists, so a box that
+ * cannot deliver locally is worth surfacing regardless.
+ *
  * This probes the SAME transport the lane uses, from the SAME context doctor runs
  * in, so `agents doctor` can fail loud when this box cannot reach the owner. It is
  * deliberately honest about context: `rush whoami` is what tells a real signed-in

package/dist/lib/exec.d.ts

@@ -419,6 +419,14 @@ export interface TmuxWrapContext {
     remoteDispatch: boolean;
     /** Whether a tmux binary is on PATH. */
     tmuxAvailable: boolean;
+    /**
+     * True when this process has a real TTY to attach (`stdout.isTTY`).
+     * A piped `agents run --interactive` (session-tracker tests, CI) has none:
+     * wrapping then treating the failed attach as Ctrl-b d leaked live panes
+     * for a week on yosemite-s0 (PHNX-3293). Remote dispatch still wraps
+     * without a TTY — `--device --no-follow` *wants* a detached pane.
+     */
+    hasTty: boolean;
 }
 /**
  * What to do with an interactive spawn. Three outcomes, not two: a run that

package/dist/lib/exec.js

@@ -1210,6 +1210,12 @@ export function resolveTmuxWrap(ctx) {
         return { kind: 'bare' };
     if (ctx.noTmuxEnv)
         return { kind: 'bare' };
+    // Local interactive with no TTY cannot attach. Wrapping anyway creates a
+    // detached pane, attach returns immediately, and resolveAfterAttach treats
+    // the still-alive pane as Ctrl-b d — the session-tracker test leak.
+    // Remote dispatch is the exception: --no-follow *intends* a detached pane.
+    if (!ctx.hasTty && !ctx.remoteDispatch)
+        return { kind: 'bare' };
     if (!ctx.configEnabled && !ctx.remoteDispatch)
         return { kind: 'bare' };
     // Fail loud rather than launch a remote agent that a blink would kill: the
@@ -1668,6 +1674,7 @@ async function spawnAgent(options) {
         configEnabled: isTmuxEnabled(),
         remoteDispatch: process.env[REMOTE_INTERACTIVE_ENV] === '1',
         tmuxAvailable: isTmuxInstalled(),
+        hasTty: !!process.stdout.isTTY,
     });
     if (tmuxWrap.kind === 'undurable') {
         // Refuse rather than start work a blink would destroy. This is the ONLY

package/dist/lib/feed-broadcast.js

@@ -36,6 +36,7 @@
 import { spawnSync } from 'child_process';
 import { isOwnerAlias, readOwnerDest, resolveSendEnvelope, deliverEnvelope } from './channels/send.js';
 import { lookupTransport } from './channels/resolve.js';
+import { forwardOwnerNotifyToPeer } from './channels/owner-forward.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
 const LEVEL_RANK = { milestone: 0, important: 1 };
 /** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
@@ -473,7 +474,20 @@ async function runChannelSink(sink, meta) {
     if (!provider)
         return { name, ok: false, error };
     const result = await deliverEnvelope(resolved.envelope, meta);
-    return result.ok ? { name, ok: true } : { name, ok: false, error: result.error };
+    if (result.ok)
+        return { name, ok: true };
+    // The owner sink failed locally. When this box structurally cannot reach the
+    // owner (the rush-backed channel is macOS-only, so a headless Linux worker can
+    // never ring the phone — PHNX-3303), hand the delivery to a capable fleet peer
+    // over SSH rather than stranding the important post. Only the `owner` alias
+    // forwards: it resolves the peer's own fleet-synced owner destination, so a
+    // non-owner channel sink with an explicit recipient stays local.
+    if (owner) {
+        const forwarded = await forwardOwnerNotifyToPeer(sink.text ?? '', resolved.envelope.channel, meta);
+        if (forwarded?.ok)
+            return { name, ok: true };
+    }
+    return { name, ok: false, error: result.error };
 }
 /**
  * Run the planned sinks. A `command:` sink is a direct spawn with a bounded