@phnx-labs/agents-cli 1.22.51 → 1.22.53

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:
@@ -391,7 +390,7 @@ function validateRemoteBrowserBinary(binary) {
         throw new Error(`Remote browser binary contains shell metacharacters: ${binary}`);
     }
 }
-function hasSshEndpoint(endpoints) {
+export function hasSshEndpoint(endpoints) {
     const targets = Array.isArray(endpoints)
         ? endpoints
         : Object.values(endpoints).map((preset) => preset.target);
@@ -404,6 +403,31 @@ function hasSshEndpoint(endpoints) {
         }
     });
 }
+/**
+ * Whether the automatic central-tombstone drain (PHNX-3315) may claim `config`
+ * into THIS device's doc during `agents sync`.
+ *
+ * Only REMOTE (`ssh://`) profiles qualify. An `ssh://` endpoint names a specific
+ * host, so the profile is fungible by design — any box resolves it to the same
+ * browser, and a concurrent double-claim across machines is harmless. A
+ * local/`cdp://` profile has NO per-machine ownership signal: "that browser is
+ * installed here" is not "I hold this profile's credentialed session", so two
+ * boxes with the same common browser installed would each auto-claim the same
+ * tombstone on their first post-merge sync and flip it identity->fungible
+ * fleet-wide (the exact logged-out-browser failure this module exists to prevent
+ * — PHNX-3315 review). Local/cdp tombstones stay central for the explicit
+ * `agents browser profiles claim`.
+ */
+export function shouldAutoClaimCentralProfile(config) {
+    if (!hasSshEndpoint(config.endpoints))
+        return false;
+    return isProfileLaunchableHere({
+        name: '_',
+        browser: config.browser,
+        binary: config.binary,
+        endpoints: config.endpoints,
+    });
+}
 /**
  * Refuse a profile whose LOCAL port another profile already owns.
  *

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

@@ -3,7 +3,15 @@ export interface ProfileDeclaration {
     device: string;
     config: BrowserProfileConfig;
 }
-/** Leftover central `browser:` map from before per-device declarations. Empty when none remain. */
+/**
+ * The leftover central `browser:` tombstone from before per-device declarations.
+ * Empty when none remain — and `agents sync` now drains it automatically via
+ * {@link autoEvictCentralBrowserProfiles}, so on a synced box this is empty and
+ * {@link profileRegistry} is the single source of truth. It survives only to
+ * fold in migration and to explain an as-yet-unclaimed profile in a resolve
+ * error (a profile hostable on a peer that has not synced yet), never as a
+ * parallel store callers read for resolution.
+ */
 export declare function centralBrowserProfiles(): Record<string, BrowserProfileConfig>;
 export interface CentralClaimResult {
     claimed: string[];
@@ -12,22 +20,44 @@ export interface CentralClaimResult {
 /**
  * Fold leftover central `browser:` entries into THIS device's declaration file.
  *
- * Never called implicitly, and that is the point. Every device can read the
- * central map, so an implicit claim races: whichever box happens to read first
- * claims the name, {@link profileKind} then reports it `identity`, and the
- * daemon tunnels to that box — which for a fleet-wide `cdp://localhost:*`
- * profile is a logged-out headless browser wearing a credentialed browser's
- * name. That is the exact bug this module exists to remove, and an implicit
- * migration would write it to disk as a stored fact.
+ * The EXPLICIT operator action (`agents browser profiles claim`), run on the
+ * machine that actually owns the browser. It is never called implicitly from a
+ * read, and that is the point: every device can read the central map, so an
+ * implicit claim races — whichever box reads first claims the name, {@link
+ * profileKind} then reports it `identity`, and the daemon tunnels to that box,
+ * which for a fleet-wide `cdp://localhost:*` profile is a logged-out headless
+ * browser wearing a credentialed browser's name. {@link autoEvictCentralBrowserProfiles}
+ * closes that race for the automatic path (host-gated + non-throwing on sync);
+ * this one is the manual, throw-on-conflict counterpart.
  *
- * The claim is an explicit operator action (`agents browser profiles claim`),
- * run on the machine that actually owns the browser. `canHostHere` is supplied
- * by the command layer so this module stays a leaf — it must not import
- * `isProfileLaunchableHere` (that would cycle through chrome.ts → profiles.ts).
- * Only profiles this machine can host are claimed; the rest stay central,
- * undeclared, and fail loudly on resolve.
+ * `canHostHere` is supplied by the command layer so this module stays a leaf —
+ * it must not import `isProfileLaunchableHere` (that would cycle through
+ * chrome.ts → profiles.ts). Only profiles this machine can host are claimed; the
+ * rest stay central, undeclared, and fail loudly on resolve.
  */
 export declare function migrateCentralBrowserProfiles(canHostHere: (config: BrowserProfileConfig) => boolean, name?: string): CentralClaimResult;
+/**
+ * Automatic, self-draining counterpart to {@link migrateCentralBrowserProfiles}:
+ * fold every lingering central `browser:` profile THIS machine can host into its
+ * device doc and clear it from central, so the tombstone drains itself on
+ * `agents sync` with no manual `agents browser profiles claim`.
+ *
+ * Safe to call implicitly, unlike a claim at registry-read time (which races —
+ * see the `profileRegistry does not claim central declarations` guard), but the
+ * CALLER owns one ordering invariant: invoke it AFTER the sync's repo pull. Two
+ * boxes can both host the same profile (`canHostHere` is launchability, not
+ * ownership), so a box acting on a PRE-pull view of central could re-claim a
+ * profile a peer already drained and pushed — both writes land in different
+ * device files with no git conflict, and the profile flips identity->fungible.
+ * Running post-pull means central already reflects peers' drains, so the tombstone
+ * is gone locally before this box looks. The selection is also computed INSIDE
+ * the meta lock, and the path never throws — an unhostable profile or one that
+ * conflicts with an existing local declaration is left central for an explicit
+ * claim rather than wedging the sync. After it runs, {@link profileRegistry} is
+ * the single source of truth: a claimed profile lives in the device doc alone,
+ * never double-counted across the two stores.
+ */
+export declare function autoEvictCentralBrowserProfiles(canHostHere: (config: BrowserProfileConfig) => boolean): CentralClaimResult;
 /**
  * Every profile any device declares, keyed by name to all declaring devices.
  * Reads every `devices/<name>/agents.yaml`; declarations never overwrite.

package/dist/lib/browser/registry.js

@@ -2,34 +2,108 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import * as yaml from 'yaml';
-import { getUserAgentsDir, readMeta, updateMeta } from '../state.js';
+import { getUserAgentsDir, readMeta, updateMeta, withMetaLock, writeMetaUnlocked } from '../state.js';
 function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
-/** Leftover central `browser:` map from before per-device declarations. Empty when none remain. */
+/**
+ * The leftover central `browser:` tombstone from before per-device declarations.
+ * Empty when none remain — and `agents sync` now drains it automatically via
+ * {@link autoEvictCentralBrowserProfiles}, so on a synced box this is empty and
+ * {@link profileRegistry} is the single source of truth. It survives only to
+ * fold in migration and to explain an as-yet-unclaimed profile in a resolve
+ * error (a profile hostable on a peer that has not synced yet), never as a
+ * parallel store callers read for resolution.
+ */
 export function centralBrowserProfiles() {
     const central = readMeta().browser;
     if (!central || Object.keys(central).length === 0)
         return {};
     return { ...central };
 }
+/**
+ * Pick the central `browser:` entries this machine may fold into its device doc.
+ *
+ * A profile is claimable only when `canHostHere` accepts it — the endpoint or
+ * binary resolves to THIS machine — so a `cdp://localhost:*` profile owned by a
+ * peer is never claimed here (the logged-out-headless-browser bug this module
+ * exists to prevent). A name already declared locally with an IDENTICAL config
+ * is folded too, which just drops the redundant central copy. A name declared
+ * locally with a DIFFERENT config is a genuine conflict: `onConflict: 'throw'`
+ * (the explicit `claim` command) surfaces it; `onConflict: 'skip'` (automatic
+ * eviction on sync) leaves it central so a stray duplicate can never wedge a
+ * sync — an operator resolves it with an explicit claim.
+ */
+function selectClaimableCentral(central, local, canHostHere, opts) {
+    const toClaim = {};
+    const skipped = [];
+    for (const [profileName, config] of Object.entries(central)) {
+        if (opts.name && profileName !== opts.name)
+            continue;
+        if (!canHostHere(config)) {
+            skipped.push(profileName);
+            continue;
+        }
+        const existing = local[profileName];
+        if (existing && !isDeepStrictEqual(existing, config)) {
+            if (opts.onConflict === 'throw') {
+                throw new Error(`Cannot migrate browser profile "${profileName}": central agents.yaml and this device's ` +
+                    `agents.yaml declare different configurations. Resolve the duplicate before retrying.`);
+            }
+            skipped.push(profileName);
+            continue;
+        }
+        toClaim[profileName] = config;
+    }
+    return { toClaim, skipped };
+}
+/**
+ * Return `current` with `toClaim` moved out of the central `browser:` map and
+ * into this device's `deviceBrowser` doc. The central key is dropped entirely
+ * once drained, so the tombstone disappears rather than lingering as an empty
+ * map. Pure — the caller applies it under the meta lock.
+ */
+function buildEvictedMeta(current, toClaim) {
+    const legacy = current;
+    const remaining = {};
+    for (const [profileName, config] of Object.entries(legacy.browser ?? {})) {
+        if (!(profileName in toClaim))
+            remaining[profileName] = config;
+    }
+    const { browser: _removed, ...withoutCentralBrowser } = legacy;
+    return {
+        ...withoutCentralBrowser,
+        ...(Object.keys(remaining).length > 0 ? { browser: remaining } : {}),
+        deviceBrowser: { ...current.deviceBrowser, ...toClaim },
+    };
+}
+/**
+ * Commit a claim computed by the EXPLICIT path (`migrateCentralBrowserProfiles`).
+ * `toClaim` was selected from an unlocked snapshot — acceptable for that manual,
+ * deliberate command; the automatic path instead selects INSIDE the lock (see
+ * {@link autoEvictCentralBrowserProfiles}) so an unrelated concurrent write can
+ * never be clobbered by a stale selection.
+ */
+function commitCentralClaim(toClaim) {
+    updateMeta((current) => buildEvictedMeta(current, toClaim));
+}
 /**
  * Fold leftover central `browser:` entries into THIS device's declaration file.
  *
- * Never called implicitly, and that is the point. Every device can read the
- * central map, so an implicit claim races: whichever box happens to read first
- * claims the name, {@link profileKind} then reports it `identity`, and the
- * daemon tunnels to that box — which for a fleet-wide `cdp://localhost:*`
- * profile is a logged-out headless browser wearing a credentialed browser's
- * name. That is the exact bug this module exists to remove, and an implicit
- * migration would write it to disk as a stored fact.
+ * The EXPLICIT operator action (`agents browser profiles claim`), run on the
+ * machine that actually owns the browser. It is never called implicitly from a
+ * read, and that is the point: every device can read the central map, so an
+ * implicit claim races — whichever box reads first claims the name, {@link
+ * profileKind} then reports it `identity`, and the daemon tunnels to that box,
+ * which for a fleet-wide `cdp://localhost:*` profile is a logged-out headless
+ * browser wearing a credentialed browser's name. {@link autoEvictCentralBrowserProfiles}
+ * closes that race for the automatic path (host-gated + non-throwing on sync);
+ * this one is the manual, throw-on-conflict counterpart.
  *
- * The claim is an explicit operator action (`agents browser profiles claim`),
- * run on the machine that actually owns the browser. `canHostHere` is supplied
- * by the command layer so this module stays a leaf — it must not import
- * `isProfileLaunchableHere` (that would cycle through chrome.ts → profiles.ts).
- * Only profiles this machine can host are claimed; the rest stay central,
- * undeclared, and fail loudly on resolve.
+ * `canHostHere` is supplied by the command layer so this module stays a leaf —
+ * it must not import `isProfileLaunchableHere` (that would cycle through
+ * chrome.ts → profiles.ts). Only profiles this machine can host are claimed; the
+ * rest stay central, undeclared, and fail loudly on resolve.
  */
 export function migrateCentralBrowserProfiles(canHostHere, name) {
     const meta = readMeta();
@@ -53,42 +127,64 @@ export function migrateCentralBrowserProfiles(canHostHere, name) {
                 `(its browser/binary isn't installed here). Run this command on the machine that has that browser.`);
         }
     }
-    const toClaim = {};
-    const skipped = [];
-    for (const [profileName, config] of Object.entries(central)) {
-        if (name && profileName !== name)
-            continue;
-        if (!canHostHere(config)) {
-            skipped.push(profileName);
-            continue;
-        }
-        const existing = local[profileName];
-        if (existing && !isDeepStrictEqual(existing, config)) {
-            throw new Error(`Cannot migrate browser profile "${profileName}": central agents.yaml and this device's ` +
-                `agents.yaml declare different configurations. Resolve the duplicate before retrying.`);
-        }
-        toClaim[profileName] = config;
-    }
+    const { toClaim, skipped } = selectClaimableCentral(central, local, canHostHere, {
+        name,
+        onConflict: 'throw',
+    });
     const claimed = Object.keys(toClaim).sort();
     skipped.sort();
     if (claimed.length === 0)
         return { claimed, skipped };
-    updateMeta((current) => {
-        const legacy = current;
-        const remaining = {};
-        for (const [profileName, config] of Object.entries(legacy.browser ?? {})) {
-            if (!(profileName in toClaim))
-                remaining[profileName] = config;
-        }
-        const { browser: _removed, ...withoutCentralBrowser } = legacy;
-        return {
-            ...withoutCentralBrowser,
-            ...(Object.keys(remaining).length > 0 ? { browser: remaining } : {}),
-            deviceBrowser: { ...current.deviceBrowser, ...toClaim },
-        };
-    });
+    commitCentralClaim(toClaim);
     return { claimed, skipped };
 }
+/**
+ * Automatic, self-draining counterpart to {@link migrateCentralBrowserProfiles}:
+ * fold every lingering central `browser:` profile THIS machine can host into its
+ * device doc and clear it from central, so the tombstone drains itself on
+ * `agents sync` with no manual `agents browser profiles claim`.
+ *
+ * Safe to call implicitly, unlike a claim at registry-read time (which races —
+ * see the `profileRegistry does not claim central declarations` guard), but the
+ * CALLER owns one ordering invariant: invoke it AFTER the sync's repo pull. Two
+ * boxes can both host the same profile (`canHostHere` is launchability, not
+ * ownership), so a box acting on a PRE-pull view of central could re-claim a
+ * profile a peer already drained and pushed — both writes land in different
+ * device files with no git conflict, and the profile flips identity->fungible.
+ * Running post-pull means central already reflects peers' drains, so the tombstone
+ * is gone locally before this box looks. The selection is also computed INSIDE
+ * the meta lock, and the path never throws — an unhostable profile or one that
+ * conflicts with an existing local declaration is left central for an explicit
+ * claim rather than wedging the sync. After it runs, {@link profileRegistry} is
+ * the single source of truth: a claimed profile lives in the device doc alone,
+ * never double-counted across the two stores.
+ */
+export function autoEvictCentralBrowserProfiles(canHostHere) {
+    // Read fresh, select, and commit inside ONE meta-lock acquisition. Reading
+    // central before the lock and committing after (the manual path's shape) leaves
+    // a window where a concurrent write on THIS machine changes central/deviceBrowser
+    // between snapshot and commit, so the stale selection would be merged over the
+    // fresher value. Selecting from the state the lock just handed us closes that
+    // window. We write ONLY when something is claimed, so a no-op sync never touches
+    // any doc (writeMetaUnlocked would otherwise re-serialize the device doc every
+    // run). This mirrors updateMeta's own body, minus the unconditional write.
+    return withMetaLock(() => {
+        const meta = readMeta();
+        const central = meta.browser;
+        if (!central || Object.keys(central).length === 0)
+            return { claimed: [], skipped: [] };
+        const local = meta.deviceBrowser ?? {};
+        const { toClaim, skipped } = selectClaimableCentral(central, local, canHostHere, {
+            onConflict: 'skip',
+        });
+        const claimed = Object.keys(toClaim).sort();
+        skipped.sort();
+        if (claimed.length === 0)
+            return { claimed, skipped };
+        writeMetaUnlocked(buildEvictedMeta(meta, toClaim));
+        return { claimed, skipped };
+    });
+}
 /**
  * Every profile any device declares, keyed by name to all declaring devices.
  * Reads every `devices/<name>/agents.yaml`; declarations never overwrite.

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