@phnx-labs/agents-cli 1.22.57 → 1.22.58

package/dist/lib/account-registry.js

@@ -20,6 +20,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import * as yaml from 'yaml';
+import chalk from 'chalk';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { getUserAgentsDir, readMeta, updateMeta } from './state.js';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken } from './secrets/index.js';
@@ -307,18 +308,19 @@ export function accountBindings(accountId, meta) {
 /** Explicit selection wins over a configured per-harness default. */
 export function resolveAccountSelection(explicit, agent, meta, opts = {}) {
     if (explicit)
-        return explicit;
+        return { id: explicit, source: 'explicit' };
     // 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;
+        return { id: bound, source: 'binding' };
     const deviceScoped = bindings[agent];
     if (deviceScoped)
-        return deviceScoped;
-    return opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
+        return { id: deviceScoped, source: 'binding' };
+    const defaulted = opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
+    return defaulted ? { id: defaulted, source: 'default' } : undefined;
 }
 function profileConsumers(name, base) {
     const dir = path.join(base, 'profiles');
@@ -371,19 +373,30 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     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).
+        // Sweep every row for the identity (PHNX-3206) in its owning store (PHNX-3315)
+        // and any per-harness default that points to the old name or row ids.
         const rowScope = rows[0].scope;
+        const idsToRename = new Set([oldName, ...rows.map(row => row.id)]);
         updateMeta(current => {
+            const defaults = { ...current.accounts?.defaults };
+            for (const [agent, value] of Object.entries(defaults)) {
+                if (idsToRename.has(value))
+                    defaults[agent] = newName;
+            }
+            const next = { ...current, accounts: { ...current.accounts, defaults } };
             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 } };
+                next.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 } };
+            else {
+                const native = { ...current.accounts?.native };
+                for (const row of rows)
+                    native[row.id] = { ...native[row.id], name: newName };
+                next.accounts = { ...next.accounts, native };
+            }
+            return next;
         });
         return;
     }
@@ -391,6 +404,15 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     if (!account)
         throw new Error(`Unknown account '${oldName}'.`);
     assertUniqueUnifiedName(newName, meta, doc);
+    const idsToRename = new Set([account.name, account.id]);
+    updateMeta(current => {
+        const defaults = { ...current.accounts?.defaults };
+        for (const [agent, value] of Object.entries(defaults)) {
+            if (idsToRename.has(value))
+                defaults[agent] = newName;
+        }
+        return { ...current, accounts: { ...current.accounts, defaults } };
+    });
     renameBundle(account.name, newName); // moves metadata + secret, preserves ACCOUNT_ID
     renameProfileConsumers(account.name, newName, base);
 }
@@ -422,7 +444,7 @@ export function removeAccount(name, base = getUserAgentsDir()) {
     if (!account)
         throw new Error(`Unknown account '${name}'.`);
     const bindings = accountBindings(account.id, meta);
-    const defaults = Object.entries(meta.accounts?.defaults ?? {}).filter(([, id]) => id === account.id).map(([agent]) => agent);
+    const defaults = Object.entries(meta.accounts?.defaults ?? {}).filter(([, value]) => value === account.id || value === account.name).map(([agent]) => agent);
     if (bindings.length || defaults.length) {
         const refs = [...bindings.map(target => `binding ${target}`), ...defaults.map(agent => `default ${agent}`)];
         throw new Error(`Account '${account.name}' is still referenced by: ${refs.join(', ')}. Detach or clear those references before removing it.`);
@@ -505,9 +527,20 @@ export function resolveSpawnAccount(explicit, agent, version, meta, opts = {}) {
     const selection = resolveAccountSelection(explicit, agent, meta, { useDefault: opts.useDefault, target });
     if (!selection)
         return null;
-    const unified = findUnifiedAccount(selection, meta);
-    if (!unified)
-        throw new Error(`Unknown account '${selection}'.`);
+    const unified = findUnifiedAccount(selection.id, meta);
+    if (!unified) {
+        // A stale per-harness default is a preference, not a hard requirement: the
+        // machine stays runnable by falling back to balanced rotation. Bindings and
+        // explicit --account are intentional, so they still fail loud.
+        if (selection.source === 'default') {
+            process.stderr.write(chalk.yellow(`[agents] default account '${selection.id}' for ${agent} no longer exists on this machine; falling back to balanced selection. Clear the stale default with: agents accounts clear-default ${agent}\n`));
+            return null;
+        }
+        const remedy = selection.source === 'binding'
+            ? `Detach the stale binding with: agents accounts detach ${selection.id} ${target}`
+            : `Add an account named '${selection.id}' or remove the --account override.`;
+        throw new Error(`Unknown account '${selection.id}' for ${agent} harness. ${remedy}`);
+    }
     if (unified.kind === 'native') {
         if (unified.agent !== agent) {
             throw new Error(`Account '${unified.name}' is a ${unified.agent} login and cannot authenticate the ${agent} harness.`);

package/dist/lib/accounting/capacity.d.ts

@@ -10,15 +10,26 @@
  * floor, so an account racing toward its 5h cap loses priority before it maxes.
  */
 export declare const PROJECTION_HORIZON_MIN = 30;
+/**
+ * The weight an account with NO usage snapshot draws. Absence of a usage signal
+ * is NOT capacity (specifications.md GWT-E5c, SING-1a): a null snapshot means
+ * "unverifiable", not "empty" — on a worker box every account reads null
+ * (setup-token lacks the `user:profile` scope, RUSH-2392), so scoring null as
+ * full capacity made the blind pool's top pick an account that was actually
+ * weekly-exhausted (PHNX-3392). Floored at 1, never 0: an all-unverified pool
+ * must still draw a pick rather than strand the launch.
+ */
+export declare const UNVERIFIED_WEIGHT = 1;
 /**
  * Weight one candidate by remaining routing capacity, deprioritized by how soon
  * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
+ * an account with no live snapshot is NOT full-capacity — absence of a usage
+ * signal is not evidence of headroom, so it draws `UNVERIFIED_WEIGHT` and any
+ * verified-healthy account outranks it (GWT-E5c). `minutesToLimit` (the daemon's
+ * burn-rate projection on the 5h session window) then scales that base: >=
+ * horizon (or unknown) keeps full weight, and closer-to-cap scales toward the
+ * floor of 1 — so a launch avoids an account projected to cap soon, not just a
+ * 100%-maxed one. Pure + exported so the deprioritization is unit-tested
+ * directly (a weighted-random draw is not).
  */
 export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;

package/dist/lib/accounting/capacity.js

@@ -10,19 +10,30 @@
  * floor, so an account racing toward its 5h cap loses priority before it maxes.
  */
 export const PROJECTION_HORIZON_MIN = 30;
+/**
+ * The weight an account with NO usage snapshot draws. Absence of a usage signal
+ * is NOT capacity (specifications.md GWT-E5c, SING-1a): a null snapshot means
+ * "unverifiable", not "empty" — on a worker box every account reads null
+ * (setup-token lacks the `user:profile` scope, RUSH-2392), so scoring null as
+ * full capacity made the blind pool's top pick an account that was actually
+ * weekly-exhausted (PHNX-3392). Floored at 1, never 0: an all-unverified pool
+ * must still draw a pick rather than strand the launch.
+ */
+export const UNVERIFIED_WEIGHT = 1;
 /**
  * Weight one candidate by remaining routing capacity, deprioritized by how soon
  * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
+ * an account with no live snapshot is NOT full-capacity — absence of a usage
+ * signal is not evidence of headroom, so it draws `UNVERIFIED_WEIGHT` and any
+ * verified-healthy account outranks it (GWT-E5c). `minutesToLimit` (the daemon's
+ * burn-rate projection on the 5h session window) then scales that base: >=
+ * horizon (or unknown) keeps full weight, and closer-to-cap scales toward the
+ * floor of 1 — so a launch avoids an account projected to cap soon, not just a
+ * 100%-maxed one. Pure + exported so the deprioritization is unit-tested
+ * directly (a weighted-random draw is not).
  */
 export function capacityWeight(usedPercent, minutesToLimit) {
-    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
+    const base = usedPercent === null ? UNVERIFIED_WEIGHT : Math.max(1, 100 - usedPercent);
     if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
         return base;
     const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));

package/dist/lib/accounting/usage-sync.d.ts

@@ -1,8 +1,9 @@
 import { type DeviceProfile } from '../devices/registry.js';
 import { type ConfiguredDeviceRole } from '../device-config.js';
-import { type CachedUsageSnapshot } from './usage.js';
+import { type CachedUsageSnapshot, type UsageSnapshot } from './usage.js';
 /** How long a single peer push may take before it is abandoned for this tick. */
 export declare const USAGE_PUSH_DEADLINE_MS = 20000;
+export declare const USAGE_PULL_DEADLINE_MS = 20000;
 /** The stdin envelope the `__usage-ingest` verb reads. `v` guards the shape. */
 export interface UsageSyncPayload {
     v: 1;
@@ -62,6 +63,33 @@ export interface UsageSyncDeps {
         message?: string;
     };
 }
+export interface UsagePullResult {
+    pulledFrom: string | null;
+    merged: number;
+    skipped: string | null;
+    error: string | null;
+}
+export interface UsagePullDeps {
+    selfRole?: () => ConfiguredDeviceRole | undefined;
+    listDevices?: () => DeviceProfile[];
+    listRoles?: () => Record<string, ConfiguredDeviceRole>;
+    isPinned?: (name: string) => boolean;
+    exportRows?: () => Record<string, CachedUsageSnapshot>;
+    readRow?: (usageKey: string) => Pick<UsageSnapshot, 'windows'> | null;
+    ingestRows?: (rows: Record<string, CachedUsageSnapshot>) => number;
+    /** Read the versioned payload from the primary. Default: ssh `__usage-export`. */
+    pull?: (device: DeviceProfile) => {
+        ok: boolean;
+        stdout?: string;
+        message?: string;
+    };
+}
+/**
+ * Pull usage from the fleet's primary headed device when this worker's local
+ * cache is empty or contains an expired row. `personal` is the primary role;
+ * a `desktop` is used only when the fleet has no personal device.
+ */
+export declare function pullUsageFromPrimary(deps?: UsagePullDeps): UsagePullResult;
 /**
  * Push the local identity-keyed usage snapshot to every reachable, pinned,
  * non-headed peer. A no-op on a non-headed box or when the local cache is empty.

package/dist/lib/accounting/usage-sync.js

@@ -25,16 +25,17 @@
  * The planner is pure so tests cover every skip/push branch with no SSH.
  */
 import { sshExec } from '../ssh-exec.js';
-import { buildRemoteAgentsInvocation, buildWindowsStdinAgentsCommand, remoteShellFor } from '../hosts/remote-cmd.js';
+import { buildRemoteAgentsInvocation, buildWindowsStdinAgentsCommand, remoteShellFor, stripClixml } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { loadDevicesSync } from '../devices/registry.js';
 import { sshTargetFor } from '../devices/connect.js';
 import { isHostPinned } from '../devices/known-hosts.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
 import { isHeadedDeviceRole, listConfiguredDeviceRoles, selfConfiguredDeviceRole, } from '../device-config.js';
-import { exportClaudeUsageCacheRows } from './usage.js';
+import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, readClaudeUsageCache, } from './usage.js';
 /** How long a single peer push may take before it is abandoned for this tick. */
 export const USAGE_PUSH_DEADLINE_MS = 20_000;
+export const USAGE_PULL_DEADLINE_MS = 20_000;
 /**
  * Decide, per peer, whether to push the local usage snapshot. Pure.
  *
@@ -84,6 +85,79 @@ function defaultUsagePush(device, payload) {
         return { ok: false, message: res.stderr.trim() || `remote exit ${res.code}` };
     return { ok: true };
 }
+/** Production pull: read the primary's cache through its hidden export verb. */
+function defaultUsagePull(device) {
+    const target = sshTargetFor(device);
+    const os = resolveRemoteOsSync(device.name);
+    const remoteCmd = buildRemoteAgentsInvocation(['__usage-export'], undefined, os);
+    const res = sshExec(target, remoteCmd, { timeoutMs: USAGE_PULL_DEADLINE_MS });
+    if (res.timedOut)
+        return { ok: false, message: 'timed out' };
+    if (res.code !== 0)
+        return { ok: false, message: res.stderr.trim() || `remote exit ${res.code}` };
+    return { ok: true, stdout: res.stdout };
+}
+/**
+ * Pull usage from the fleet's primary headed device when this worker's local
+ * cache is empty or contains an expired row. `personal` is the primary role;
+ * a `desktop` is used only when the fleet has no personal device.
+ */
+export function pullUsageFromPrimary(deps = {}) {
+    const result = { pulledFrom: null, merged: 0, skipped: null, error: null };
+    if ((deps.selfRole ?? selfConfiguredDeviceRole)() !== 'worker') {
+        result.skipped = 'this device is not a worker';
+        return result;
+    }
+    const localRows = (deps.exportRows ?? exportClaudeUsageCacheRows)();
+    const readRow = deps.readRow ?? readClaudeUsageCache;
+    const localEntries = Object.entries(localRows);
+    if (localEntries.length > 0 && localEntries.every(([key, row]) => {
+        const fresh = readRow(key);
+        return fresh !== null && fresh.windows.length === row.windows.length;
+    })) {
+        result.skipped = 'local usage cache is fresh';
+        return result;
+    }
+    const devices = deps.listDevices?.() ?? Object.values(loadDevicesSync());
+    const roles = deps.listRoles?.() ?? (deps.listDevices
+        ? listConfiguredDeviceRoles(devices.map((device) => device.name))
+        : listConfiguredDeviceRoles());
+    const isPinned = deps.isPinned ?? isHostPinned;
+    const primary = devices
+        .filter((device) => roles[device.name] === 'personal')
+        .concat(devices.filter((device) => roles[device.name] === 'desktop'))
+        .find((device) => device.tailscale?.online !== false && isPinned(device.name));
+    if (!primary) {
+        result.error = 'no reachable, pinned personal or desktop device is configured as the usage primary';
+        return result;
+    }
+    const outcome = (deps.pull ?? defaultUsagePull)(primary);
+    if (!outcome.ok) {
+        result.error = outcome.message ?? 'pull failed';
+        return result;
+    }
+    let payload;
+    try {
+        // A Windows usage primary's `agents.ps1` shim prepends a PowerShell CLIXML
+        // progress banner to stdout, exactly as every other remote-JSON boundary
+        // strips (remote-cmd.ts:325). Without this, a headed Windows box (win-mini
+        // is a live fleet device) makes every pull fail as "malformed JSON", the
+        // worker's cache stays null, and the PHNX-3392 capacity floor silently
+        // becomes the only thing standing between a blind pool and an exhausted pick.
+        payload = JSON.parse(stripClixml(outcome.stdout ?? ''));
+    }
+    catch {
+        result.error = 'primary returned malformed JSON';
+        return result;
+    }
+    if (!payload || payload.v !== 1 || typeof payload.rows !== 'object' || payload.rows === null || Array.isArray(payload.rows)) {
+        result.error = 'primary returned an unrecognized usage-sync payload shape';
+        return result;
+    }
+    result.pulledFrom = primary.name;
+    result.merged = (deps.ingestRows ?? ingestPeerClaudeUsageRows)(payload.rows);
+    return result;
+}
 /**
  * Push the local identity-keyed usage snapshot to every reachable, pinned,
  * non-headed peer. A no-op on a non-headed box or when the local cache is empty.

package/dist/lib/accounting/usage.js

@@ -284,6 +284,12 @@ const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
 const EMPTY = '\u2591';
 const PARTIAL_BLOCKS = ['', '\u258F', '\u258E', '\u258D', '\u258C', '\u258B', '\u258A', '\u2589'];
+// A window we EXPECTED but have no reading for \u2014 e.g. Claude's 5h "session"
+// window when the account has no usage in the current rolling window, so the
+// usage API returns five_hour.utilization = null and no session bar is written.
+// It must read as neither 0% (EMPTY '\u2591') nor 100% (FULL '\u2588') \u2014 a full block was
+// alarming and looked maxed-out \u2014 so use a dashed row that says "no data".
+const NO_DATA = '\u2504';
 /** Construct the benign no-local-log result without overloading `error`. */
 export function usageNoRecentUsageInfo() {
     return { snapshot: null, error: null, [USAGE_BENIGN_STATE]: 'no-recent-usage' };
@@ -590,7 +596,7 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
             : selected.map((window) => ({ window, shortLabel: window.shortLabel }));
         const windowParts = windowsToRender.map(({ window, shortLabel }, index) => {
             if (!window) {
-                const missing = chalk.red(`${shortLabel}: ${FULL.repeat(COMPACT_BAR_LEN)} unavailable`);
+                const missing = chalk.dim(`${shortLabel}: ${NO_DATA.repeat(COMPACT_BAR_LEN)} unavailable`);
                 return index < windowsToRender.length - 1 ? padToWidth(missing, 20) : missing;
             }
             const bar = renderCompactUsageBar(window.usedPercent);

package/dist/lib/auth-mint.d.ts

@@ -143,7 +143,17 @@ export interface MintAndSeedResult {
  */
 export declare function mintAndSeed(input: MintAndSeedInput): Promise<MintAndSeedResult>;
 export declare function resolveSyncTargets(fleet: boolean, devices: string[]): Promise<string[]>;
-/** True when a Claude setup-token is already seeded on this box (setup status). */
+/**
+ * True when a Claude setup-token is already seeded on this box (setup status).
+ *
+ * Read-only status probe (`agents setup`, `agents doctor`) — the reserved
+ * auth-bundle check below MUST NOT crash the whole command because the
+ * keychain could not be reached (e.g. the macOS Keychain helper source is
+ * unavailable — PHNX-3385); `bundleExists()`/`hasKeychainToken()` document
+ * themselves as failing loud, but that contract is for destructive-write
+ * guards, not a diagnostic. An unreachable keychain here just means "cannot
+ * confirm the reserved bundle," reported honestly rather than propagated.
+ */
 export declare function hasMintedSetupToken(): {
     ready: boolean;
     detail: string;

package/dist/lib/auth-mint.js

@@ -414,18 +414,33 @@ async function syncMintedBundles(accountName, device) {
         return { device, ok: false, message: err instanceof Error ? err.message : String(err) };
     }
 }
-/** True when a Claude setup-token is already seeded on this box (setup status). */
+/**
+ * True when a Claude setup-token is already seeded on this box (setup status).
+ *
+ * Read-only status probe (`agents setup`, `agents doctor`) — the reserved
+ * auth-bundle check below MUST NOT crash the whole command because the
+ * keychain could not be reached (e.g. the macOS Keychain helper source is
+ * unavailable — PHNX-3385); `bundleExists()`/`hasKeychainToken()` document
+ * themselves as failing loud, but that contract is for destructive-write
+ * guards, not a diagnostic. An unreachable keychain here just means "cannot
+ * confirm the reserved bundle," reported honestly rather than propagated.
+ */
 export function hasMintedSetupToken() {
     const records = Object.values(readAccountRegistry().accounts);
     const setup = records.filter((a) => a.auth === 'setup-token' && a.provider === 'anthropic');
     if (setup.length) {
         return { ready: true, detail: `${setup.length} Claude setup-token account${setup.length === 1 ? '' : 's'}` };
     }
-    if (bundleExists(AUTH_BUNDLE) && bundleBackend(AUTH_BUNDLE) === 'file') {
-        const bundle = readBundle(AUTH_BUNDLE);
-        const keys = Object.keys(bundle.vars).filter((k) => k.startsWith('CLAUDE_CODE_OAUTH_TOKEN_'));
-        if (keys.length)
-            return { ready: true, detail: `reserved auth bundle (${keys.length} account key${keys.length === 1 ? '' : 's'})` };
+    try {
+        if (bundleExists(AUTH_BUNDLE) && bundleBackend(AUTH_BUNDLE) === 'file') {
+            const bundle = readBundle(AUTH_BUNDLE);
+            const keys = Object.keys(bundle.vars).filter((k) => k.startsWith('CLAUDE_CODE_OAUTH_TOKEN_'));
+            if (keys.length)
+                return { ready: true, detail: `reserved auth bundle (${keys.length} account key${keys.length === 1 ? '' : 's'})` };
+        }
+    }
+    catch (err) {
+        return { ready: false, detail: `could not check the reserved auth bundle: ${err.message}` };
     }
     return { ready: false, detail: 'no Claude setup-token minted — agents accounts mint claude' };
 }

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

@@ -12,6 +12,14 @@ 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>;
+/**
+ * Is a *reachable* daemon actually responsive, or is its event loop wedged
+ * (PHNX-3411)? Retries {@link probeDaemonResponsive} up to
+ * {@link RESPONSIVENESS_PROBE_ATTEMPTS} times so a single transient miss (a GC
+ * pause) never condemns a healthy daemon; returns true as soon as any attempt
+ * gets a reply, and false only when every attempt fails.
+ */
+export declare function isDaemonResponsive(endpoint?: string, attempts?: number): Promise<boolean>;
 /**
  * Wait until the browser daemon is genuinely reachable, or throw.
  *

package/dist/lib/browser/ipc.js

@@ -92,6 +92,31 @@ const SOCKET_WAIT_TIMEOUT_MS = 15_000;
  * doesn't race a restart it happened to probe mid-flight.
  */
 const SOCKET_WAIT_STABLE_PROBES = 2;
+/**
+ * How long a single {@link probeDaemonResponsive} attempt waits for the daemon to
+ * answer a trivial `version` request before giving up (PHNX-3411).
+ *
+ * A unix-socket `connect` succeeds at the KERNEL level the moment the connection
+ * is queued in the listen backlog — it does NOT require the server's event loop
+ * to run. So a daemon whose event loop is blocked (e.g. a long synchronous burst
+ * on the shared loop) still passes {@link isDaemonReachable}: the socket accepts,
+ * but the request is never serviced. The live symptom on zion was exactly this —
+ * `browser.sock` accepted every connection while the daemon re-indexed sessions,
+ * then never replied, so cross-device browser drives hung or surfaced a confusing
+ * bare socket timeout. Requiring an actual reply is the only probe that tells a
+ * healthy daemon apart from a wedged one.
+ */
+const RESPONSIVENESS_PROBE_TIMEOUT_MS = 1_500;
+/**
+ * Consecutive missed {@link probeDaemonResponsive} attempts before a *reachable*
+ * daemon is declared wedged. One missed reply can be a transient GC pause on an
+ * otherwise-healthy loop, so a single failure never condemns the daemon; a daemon
+ * that cannot answer a trivial `version` request across this whole window has a
+ * genuinely blocked event loop. The added latency (attempts × timeout) is paid
+ * ONLY on the wedged path — where the alternative was an indefinite hang — while
+ * a healthy daemon answers the first attempt in ~1ms.
+ */
+const RESPONSIVENESS_PROBE_ATTEMPTS = 3;
 export class BrowserDaemonNotRunningError extends Error {
     constructor() {
         super(formatBrowserDaemonNotRunningError());
@@ -140,6 +165,57 @@ function probeDaemon(endpoint, timeoutMs = 500) {
 export async function isDaemonReachable() {
     return probeDaemon(getIpcEndpoint());
 }
+/**
+ * Can the daemon actually REPLY right now? Opens a connection and requires a
+ * parseable response to a `version` request within `timeoutMs`. Unlike
+ * {@link probeDaemon} (which resolves on the kernel-level `connect`), this only
+ * succeeds when the daemon's event loop is running and services the request — so
+ * it is the one probe that distinguishes a healthy daemon from a wedged one whose
+ * loop is blocked (PHNX-3411). Resolves false on connect error, timeout, an early
+ * close, or an unparseable reply. `version` is the right probe: its handler is
+ * trivial and synchronous (never touches the browser), so a slow reply means the
+ * loop is blocked, not that a real action is in flight.
+ */
+function probeDaemonResponsive(endpoint, timeoutMs = RESPONSIVENESS_PROBE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const sock = net.createConnection(endpoint);
+        let buffer = '';
+        let done = false;
+        const finish = (ok) => { if (done)
+            return; done = true; clearTimeout(timer); sock.destroy(); resolve(ok); };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        sock.on('connect', () => { sock.write(JSON.stringify({ action: 'version' }) + '\n'); });
+        sock.on('data', (data) => {
+            buffer += data.toString();
+            const idx = buffer.indexOf('\n');
+            if (idx === -1)
+                return;
+            try {
+                const resp = JSON.parse(buffer.slice(0, idx));
+                finish(resp.ok === true);
+            }
+            catch {
+                finish(false);
+            }
+        });
+        sock.on('error', () => finish(false));
+        sock.on('close', () => finish(false));
+    });
+}
+/**
+ * Is a *reachable* daemon actually responsive, or is its event loop wedged
+ * (PHNX-3411)? Retries {@link probeDaemonResponsive} up to
+ * {@link RESPONSIVENESS_PROBE_ATTEMPTS} times so a single transient miss (a GC
+ * pause) never condemns a healthy daemon; returns true as soon as any attempt
+ * gets a reply, and false only when every attempt fails.
+ */
+export async function isDaemonResponsive(endpoint = getIpcEndpoint(), attempts = RESPONSIVENESS_PROBE_ATTEMPTS) {
+    for (let i = 0; i < attempts; i++) {
+        if (await probeDaemonResponsive(endpoint))
+            return true;
+    }
+    return false;
+}
 /**
  * Wait until the browser daemon is genuinely reachable, or throw.
  *
@@ -1087,6 +1163,17 @@ async function prepareIPC(action, opts) {
         }
         await new Promise((r) => setTimeout(r, 300));
     }
+    // The socket accepts connections — but a unix-socket `connect` succeeds at the
+    // kernel level even when the daemon's event loop is blocked and never services
+    // the request (PHNX-3411). Require a real reply before treating the daemon as
+    // usable, so a wedged daemon fails LOUD with an accurate, actionable error
+    // instead of the confusing bare socket timeout / indefinite hang the browser
+    // verb would otherwise hit (including inside reconcileDaemonVersion's own
+    // version probe, which has no response timeout). Skipped for callers that opt
+    // out of auto-start — they want the clean BrowserDaemonNotRunningError instead.
+    if (autoStartDaemon && !(await isDaemonResponsive(getIpcEndpoint()))) {
+        throw new Error(actionable('Browser daemon is running but unresponsive — its event loop is blocked, so it accepts the connection but never replies.', `Endpoint: ${getIpcEndpoint()}`, `Log: ${getDaemonLogPath()}`, 'Next: agents browser stop --daemon   (resets the wedged daemon; the next browser command restarts it)'));
+    }
     // Before serving a real request, make sure the daemon isn't running stale
     // code. Skips the internal `version` probe (avoids recursion) and callers
     // that opt out of auto-start. No-ops once reconciled or when versions match.

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

@@ -534,6 +534,25 @@ export declare class BrowserService {
      * tasks.json entries. Used before identity-based resolution so a daemon
      * restart does not make the caller's tasks invisible.
      */
+    /**
+     * Register a freshly-rehydrated connection, unless a concurrent rehydrate won
+     * the race and already registered one for this key. `attachRunningProfile`
+     * awaits an ssh-tunnel spawn / CDP connect, so two commands landing right
+     * after a daemon restart can each build a connection for the same key; the
+     * loser must be released instead of silently overwriting the winner (whose
+     * `cleanup` would then never run).
+     *
+     * The subtlety is the SSH tunnel: when the loser's `connectSSH` landed after
+     * the winner's tunnel had already bound the local port, `isOwnTunnel` makes it
+     * **reuse** that same OS process (`drivers/ssh.ts`) — so both connections carry
+     * the same `pid`/`port`. Calling the loser's `cleanup()` then does
+     * `tunnel.kill()` on the SHARED process and breaks the winner's live CDP. So
+     * when the loser shares the winner's tunnel we close ONLY the loser's own CDP
+     * socket and leave the tunnel to the winner; only a loser that spawned its own
+     * distinct tunnel gets the full `cleanup()` (else it would leak). Returns the
+     * winning connection to use.
+     */
+    private registerRehydratedConnection;
     private rehydrateAllFromDisk;
     /**
      * On a RAM miss, scan profile runtime dirs for a tasks.json entry matching