@phnx-labs/agents-cli 1.22.51 → 1.22.53

package/dist/lib/account-registry.js

@@ -12,7 +12,9 @@
  * `{ version: 2, accounts }` view so existing consumers (harness, profiles,
  * exec) keep working — it is now a projection over the account bundles, not a
  * file read. Native OAuth logins are NOT accounts here; they stay native and
- * surface through unified discovery in [[account-catalog]].
+ * surface through unified discovery in [[account-catalog]]. Labels bind to
+ * `(agent, identityKey)` on the central `accounts.native` rows in agents.yaml,
+ * which `agents repo push/pull` already syncs fleet-wide.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -133,8 +135,17 @@ export function readAccountRegistry(base = getUserAgentsDir()) {
 export function findAccount(name, doc = readAccountRegistry()) {
     return doc.accounts[name] ?? Object.values(doc.accounts).find(account => account.name === name) ?? null;
 }
+/**
+ * Effective native accounts: the fleet-shared central store (version-scoped
+ * identities) merged with THIS box's own device doc (device-scoped identities).
+ * A native login is machine-local — its home follows its scope (PHNX-3315), so
+ * a `scope:'device'` identity is read from this box's device doc and never the
+ * shared central agents.yaml (which is where its email/identityKey PII used to
+ * accumulate). On an id collision the device slice wins.
+ */
 export function listNativeAccounts(meta) {
-    return Object.values(meta.accounts?.native ?? {}).map(account => ({ ...account, kind: 'native' }));
+    const merged = { ...meta.accounts?.native, ...meta.deviceAccounts?.native };
+    return Object.values(merged).map(account => ({ ...account, kind: 'native' }));
 }
 /**
  * Resolve one account by name or id across both stores, native first.
@@ -155,8 +166,28 @@ export function findUnifiedAccount(nameOrId, meta, doc) {
     const provider = findAccount(nameOrId, doc ?? readAccountRegistry());
     return provider ? { ...provider, kind: 'provider' } : null;
 }
-function assertUniqueUnifiedName(name, meta, doc) {
-    if (findUnifiedAccount(name, meta, doc))
+function nativeIdentityRows(meta, agent, identityKey) {
+    return listNativeAccounts(meta).filter(account => account.agent === agent && account.identityKey === identityKey);
+}
+/** Every row (central + this box's device store) for the identity that `name`
+ * (id or account name) resolves to. */
+function nativeRowsForNameOrId(meta, name) {
+    const found = listNativeAccounts(meta).find(account => account.id === name || account.name === name);
+    if (!found)
+        return [];
+    return nativeIdentityRows(meta, found.agent, found.identityKey);
+}
+function assertUniqueUnifiedName(name, meta, doc, exceptIds) {
+    const needle = name.toLowerCase();
+    const nativeHits = listNativeAccounts(meta).filter(account => account.id === name || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle);
+    if (nativeHits.some(account => !exceptIds?.has(account.id)))
+        throw new Error(`Account '${name}' already exists.`);
+    // Same laziness as findUnifiedAccount: a native row that already owns this
+    // name (even one we are mutating) means we never open the provider store.
+    if (nativeHits.length > 0)
+        return;
+    const provider = findAccount(name, doc ?? readAccountRegistry());
+    if (provider && !exceptIds?.has(provider.id))
         throw new Error(`Account '${name}' already exists.`);
 }
 export function addNativeAccount(name, agent, identityKey, identityLabel, scope) {
@@ -167,13 +198,28 @@ export function addNativeAccount(name, agent, identityKey, identityLabel, scope)
     if (duplicate)
         throw new Error(`This ${agent} login is already named '${duplicate.name}'.`);
     const account = { id: crypto.randomUUID(), name, kind: 'native', agent, identityKey, identityLabel, scope };
-    updateMeta(current => ({
-        ...current,
-        accounts: {
-            ...current.accounts,
-            native: { ...current.accounts?.native, [account.id]: { id: account.id, name, agent, identityKey, identityLabel, scope } },
-        },
-    }));
+    const entry = { id: account.id, name, agent, identityKey, identityLabel, scope };
+    // A native login's home follows its scope (PHNX-3315): a device-scoped
+    // identity lands in THIS box's device doc (its PII never touches the shared
+    // central agents.yaml); a version-scoped one stays in the fleet-shared store.
+    if (scope === 'device') {
+        updateMeta(current => ({
+            ...current,
+            deviceAccounts: {
+                ...current.deviceAccounts,
+                native: { ...current.deviceAccounts?.native, [account.id]: entry },
+            },
+        }));
+    }
+    else {
+        updateMeta(current => ({
+            ...current,
+            accounts: {
+                ...current.accounts,
+                native: { ...current.accounts?.native, [account.id]: entry },
+            },
+        }));
+    }
     return account;
 }
 /** Create or replace the version-independent label for one native identity. */
@@ -183,30 +229,49 @@ export function labelNativeAccount(agent, identityKey, identityLabel, label, sco
         throw new Error(`${agent} does not expose an email; pass a manual label.`);
     assertNativeLabel(resolvedLabel);
     const meta = readMeta();
-    const existing = listNativeAccounts(meta).find(account => account.agent === agent && account.identityKey === identityKey);
-    const collision = findUnifiedAccount(resolvedLabel, meta);
-    if (collision && collision.id !== existing?.id)
-        throw new Error(`Account '${resolvedLabel}' already exists.`);
-    if (!existing)
+    const matches = nativeIdentityRows(meta, agent, identityKey);
+    assertUniqueUnifiedName(resolvedLabel, meta, undefined, new Set(matches.map(account => account.id)));
+    if (matches.length === 0)
         return addNativeAccount(resolvedLabel, agent, identityKey, identityLabel, scope);
-    updateMeta(current => ({
-        ...current,
-        accounts: {
-            ...current.accounts,
-            native: { ...current.accounts?.native, [existing.id]: { ...current.accounts?.native?.[existing.id], name: resolvedLabel, identityLabel } },
-        },
-    }));
-    return { ...existing, name: resolvedLabel, identityLabel };
+    // Sweep every row for this identity (PHNX-3206), routing the whole sweep to the
+    // store that owns them: all rows for one identityKey share a scope (same agent),
+    // so a device-scoped login lands in this box's device doc, a version-scoped one
+    // in central (PHNX-3315).
+    const rowScope = matches[0].scope;
+    updateMeta(current => {
+        if (rowScope === 'device') {
+            const native = { ...current.deviceAccounts?.native };
+            for (const row of matches)
+                native[row.id] = { id: row.id, name: resolvedLabel, agent, identityKey, identityLabel, scope: rowScope };
+            return { ...current, deviceAccounts: { ...current.deviceAccounts, native } };
+        }
+        const native = { ...current.accounts?.native };
+        for (const row of matches)
+            native[row.id] = { id: row.id, name: resolvedLabel, agent, identityKey, identityLabel, scope: rowScope };
+        return { ...current, accounts: { ...current.accounts, native } };
+    });
+    return { ...matches[0], name: resolvedLabel, identityLabel, scope: rowScope };
 }
 export function bindAccount(nameOrId, target) {
     const meta = readMeta();
     const account = findUnifiedAccount(nameOrId, meta);
     if (!account)
         throw new Error(`Unknown account '${nameOrId}'.`);
-    updateMeta(current => ({
-        ...current,
-        accounts: { ...current.accounts, bindings: { ...current.accounts?.bindings, [target]: account.id } },
-    }));
+    // A binding follows its account: one that targets a device-scoped native login
+    // is itself machine-local and lands in this box's device doc (PHNX-3315);
+    // every other binding stays fleet-shared in central.
+    if (account.kind === 'native' && account.scope === 'device') {
+        updateMeta(current => ({
+            ...current,
+            deviceAccounts: { ...current.deviceAccounts, bindings: { ...current.deviceAccounts?.bindings, [target]: account.id } },
+        }));
+    }
+    else {
+        updateMeta(current => ({
+            ...current,
+            accounts: { ...current.accounts, bindings: { ...current.accounts?.bindings, [target]: account.id } },
+        }));
+    }
     return account;
 }
 export function unbindAccount(nameOrId, target) {
@@ -214,25 +279,43 @@ export function unbindAccount(nameOrId, target) {
     const account = findUnifiedAccount(nameOrId, meta);
     if (!account)
         throw new Error(`Unknown account '${nameOrId}'.`);
-    if (meta.accounts?.bindings?.[target] !== account.id)
+    const inCentral = meta.accounts?.bindings?.[target] === account.id;
+    const inDevice = meta.deviceAccounts?.bindings?.[target] === account.id;
+    if (!inCentral && !inDevice)
         throw new Error(`Account '${account.name}' is not attached to '${target}'.`);
     updateMeta(current => {
-        const bindings = { ...current.accounts?.bindings };
-        delete bindings[target];
-        return { ...current, accounts: { ...current.accounts, bindings } };
+        let next = current;
+        if (current.accounts?.bindings?.[target] === account.id) {
+            const bindings = { ...current.accounts?.bindings };
+            delete bindings[target];
+            next = { ...next, accounts: { ...next.accounts, bindings } };
+        }
+        if (current.deviceAccounts?.bindings?.[target] === account.id) {
+            const bindings = { ...current.deviceAccounts?.bindings };
+            delete bindings[target];
+            next = { ...next, deviceAccounts: { ...next.deviceAccounts, bindings } };
+        }
+        return next;
     });
 }
+/** Every target bound to `accountId`: this box's device-doc bindings merged over
+ * the fleet-shared central bindings (PHNX-3315). */
 export function accountBindings(accountId, meta) {
-    return Object.entries(meta.accounts?.bindings ?? {}).filter(([, id]) => id === accountId).map(([target]) => target).sort();
+    const merged = { ...meta.accounts?.bindings, ...meta.deviceAccounts?.bindings };
+    return Object.entries(merged).filter(([, id]) => id === accountId).map(([target]) => target).sort();
 }
 /** Explicit selection wins over a configured per-harness default. */
 export function resolveAccountSelection(explicit, agent, meta, opts = {}) {
     if (explicit)
         return explicit;
-    const bound = opts.target ? meta.accounts?.bindings?.[opts.target] : undefined;
+    // This box's device-doc bindings win over the fleet-shared central bindings
+    // (PHNX-3315), so a per-box account attachment resolves without touching the
+    // shared file. Defaults are genuinely fleet-shared and stay central.
+    const bindings = { ...meta.accounts?.bindings, ...meta.deviceAccounts?.bindings };
+    const bound = opts.target ? bindings[opts.target] : undefined;
     if (bound)
         return bound;
-    const deviceScoped = meta.accounts?.bindings?.[agent];
+    const deviceScoped = bindings[agent];
     if (deviceScoped)
         return deviceScoped;
     return opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
@@ -285,16 +368,23 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     assertName(newName);
     const doc = readAccountRegistry(base);
     const meta = readMeta();
-    const native = listNativeAccounts(meta).find(account => account.id === oldName || account.name === oldName);
-    if (native) {
-        assertUniqueUnifiedName(newName, meta, doc);
-        updateMeta(current => ({
-            ...current,
-            accounts: {
-                ...current.accounts,
-                native: { ...current.accounts?.native, [native.id]: { ...current.accounts?.native?.[native.id], name: newName } },
-            },
-        }));
+    const rows = nativeRowsForNameOrId(meta, oldName);
+    if (rows.length) {
+        assertUniqueUnifiedName(newName, meta, doc, new Set(rows.map(account => account.id)));
+        // Sweep every row for the identity (PHNX-3206) in its owning store (PHNX-3315).
+        const rowScope = rows[0].scope;
+        updateMeta(current => {
+            if (rowScope === 'device') {
+                const native = { ...current.deviceAccounts?.native };
+                for (const row of rows)
+                    native[row.id] = { ...native[row.id], name: newName };
+                return { ...current, deviceAccounts: { ...current.deviceAccounts, native } };
+            }
+            const native = { ...current.accounts?.native };
+            for (const row of rows)
+                native[row.id] = { ...native[row.id], name: newName };
+            return { ...current, accounts: { ...current.accounts, native } };
+        });
         return;
     }
     const account = findAccount(oldName, doc);
@@ -306,14 +396,24 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
 }
 export function removeAccount(name, base = getUserAgentsDir()) {
     const meta = readMeta();
-    const native = listNativeAccounts(meta).find(account => account.id === name || account.name === name);
-    if (native) {
-        const bindings = accountBindings(native.id, meta);
+    const rows = nativeRowsForNameOrId(meta, name);
+    if (rows.length) {
+        const bindings = [...new Set(rows.flatMap(row => accountBindings(row.id, meta)))].sort();
         if (bindings.length)
-            throw new Error(`Account '${native.name}' is attached to: ${bindings.join(', ')}. Detach it before removing it.`);
+            throw new Error(`Account '${rows[0].name}' is attached to: ${bindings.join(', ')}. Detach it before removing it.`);
+        const ids = new Set(rows.map(row => row.id));
+        // Sweep every row for the identity (PHNX-3206) from its owning store (PHNX-3315).
+        const rowScope = rows[0].scope;
         updateMeta(current => {
+            if (rowScope === 'device') {
+                const accounts = { ...current.deviceAccounts?.native };
+                for (const id of ids)
+                    delete accounts[id];
+                return { ...current, deviceAccounts: { ...current.deviceAccounts, native: accounts } };
+            }
             const accounts = { ...current.accounts?.native };
-            delete accounts[native.id];
+            for (const id of ids)
+                delete accounts[id];
             return { ...current, accounts: { ...current.accounts, native: accounts } };
         });
         return;

package/dist/lib/answer-router.js

@@ -1,3 +1,4 @@
+import { addressabilityRecoveryHint } from './terminal/resolve.js';
 import { injectTargetFromReplyRail } from './session/inject.js';
 /**
  * Match free-text answer against question options.
@@ -123,7 +124,7 @@ export function resolveAnswerRoute(input) {
         return {
             kind: 'refuse',
             reason: 'Agent is parked on a question but has no addressable terminal (no tmux/iterm/pty rail). ' +
-                'Open its terminal and answer there, or run `agents sessions resume <id>` first.',
+                addressabilityRecoveryHint(session),
         };
     }
     // Open block but agent is still looping between tool calls — mailbox is correct.

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

@@ -12,6 +12,50 @@ export declare function getSocketPath(): string;
 /** Is the daemon reachable? A real connect probe on every platform — a socket
  * file existing on disk is not proof a daemon is listening on it. */
 export declare function isDaemonReachable(): Promise<boolean>;
+/**
+ * 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 declare function waitForSocket(_socketPath: string, timeoutMs?: number): Promise<void>;
+/** Outcome of {@link resetBrowserDaemon} — what the wedge-recovery actually did. */
+export interface BrowserDaemonResetResult {
+    /** The daemon was reachable before the reset and a stop was issued. */
+    wasRunning: boolean;
+    /** A leftover `browser.sock` file was unlinked (POSIX only). */
+    socketCleared: boolean;
+}
+/**
+ * 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 declare function resetBrowserDaemon(): Promise<BrowserDaemonResetResult>;
+/**
+ * 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 declare function clearDeadSocketFile(endpoint: string, socketPath: string): Promise<boolean>;
 /**
  * One long-lived connection to the existing browser daemon. Requests are
  * serialized so the daemon's newline-delimited responses always map to the

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

@@ -1,15 +1,19 @@
+import type { BrowserProfileConfig } from '../types.js';
 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 +110,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>;
 /**
@@ -153,6 +176,23 @@ export declare function effectiveLocalPort(profile: BrowserProfile): number | un
  * skip remote profiles in this scan.
  */
 export declare function findFreeProfilePort(): Promise<number>;
+export declare function hasSshEndpoint(endpoints: BrowserProfileConfig['endpoints']): boolean;
+/**
+ * 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 declare function shouldAutoClaimCentralProfile(config: BrowserProfileConfig): boolean;
 /**
  * Refuse a profile whose LOCAL port another profile already owns.
  *