@phnx-labs/agents-cli 1.22.66 → 1.22.69

package/dist/lib/accounting/usage.js

@@ -318,6 +318,16 @@ export async function getUsageInfo(agentId, options) {
     const source = getUsageSource(agentId);
     return source ? source.fetch(options) : { snapshot: null, error: null };
 }
+/**
+ * Combine a caller-supplied abort signal (the daemon tick deadline) with a
+ * per-fetch timeout, so a provider fetch is bounded by whichever fires first
+ * (PHNX-3608). With no caller signal it degrades to the timeout alone —
+ * byte-identical to the previous `AbortSignal.timeout(ms)` behaviour.
+ */
+function usageFetchSignal(signal, timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
 /** Derive a stable lookup key from account info for usage deduplication. */
 export function getUsageLookupKey(info) {
     return info?.usageKey || info?.accountKey || null;
@@ -421,6 +431,7 @@ export async function getUsageInfoForIdentity(input, opts) {
             organizationId: input.info.organizationId,
             fileOnly: opts?.fileOnly,
             allowInteractiveLogin: opts?.allowInteractiveLogin,
+            signal: opts?.signal,
         });
     }
     const cached = readClaudeUsageCache(usageKey);
@@ -458,6 +469,7 @@ export async function getUsageInfoForIdentity(input, opts) {
     // Explicit refresh: block on the shared device collector.
     return fetchLiveUsageDeduped(input, usageKey, cached, opts?.fileOnly === true, {
         allowInteractiveLogin: opts?.allowInteractiveLogin === true,
+        signal: opts?.signal,
     });
 }
 /**
@@ -489,6 +501,7 @@ async function fetchLiveUsageDeduped(input, usageKey, cached, fileOnly, opts) {
                 usageScope: usageKey,
                 fileOnly,
                 allowInteractiveLogin: opts?.allowInteractiveLogin === true,
+                signal: opts?.signal,
             });
             if (usage.snapshot) {
                 if (!usage.snapshot.capturedAt || usage.snapshot.capturedAt.getTime() <= previousCapturedAt) {
@@ -931,7 +944,7 @@ async function getClaudeUsageInfo(options) {
                 'anthropic-beta': CLAUDE_OAUTH_BETA_HEADER,
                 'User-Agent': getClaudeUserAgent(options?.cliVersion),
             },
-            signal: AbortSignal.timeout(5000),
+            signal: usageFetchSignal(options?.signal, 5000),
         });
         if (!response.ok) {
             if (response.status === 429) {
@@ -1038,7 +1051,7 @@ async function getKimiUsageInfo(options) {
                 Authorization: `Bearer ${accessToken}`,
                 Accept: 'application/json',
             },
-            signal: AbortSignal.timeout(5000),
+            signal: usageFetchSignal(options?.signal, 5000),
         });
         // 401/403 => expired token, 404 => no Kimi For Coding subscription. Either
         // way there are no bars to draw, and the status is what tells them apart.
@@ -1172,7 +1185,7 @@ async function getDroidUsageInfo(options) {
                 Authorization: `Bearer ${accessToken}`,
                 Accept: 'application/json',
             },
-            signal: AbortSignal.timeout(5000),
+            signal: usageFetchSignal(options?.signal, 5000),
         });
         // 401 => revoked/expired token. No bars to draw, and the status says why.
         if (!response.ok) {
@@ -1204,7 +1217,7 @@ async function getDroidUsageInfo(options) {
     }
 }
 /** Probe Claude's OAuth token against the usage endpoint. Never refreshes — reports `expired` for a near-expiry token; see the comment below (RUSH-1822). */
-export async function probeClaudeStatus(home, cliVersion, usageScope) {
+export async function probeClaudeStatus(home, cliVersion, usageScope, signal) {
     // accessTokenCache: the daemon warms this probe every ~3 min per account, so it
     // reads ONLY the file-based setup-token and never the interactive login —
     // transmitting that ACL-bound token to the usage API from a background loop is
@@ -1240,7 +1253,7 @@ export async function probeClaudeStatus(home, cliVersion, usageScope) {
                 'anthropic-beta': CLAUDE_OAUTH_BETA_HEADER,
                 'User-Agent': getClaudeUserAgent(cliVersion),
             },
-            signal: AbortSignal.timeout(8000),
+            signal: usageFetchSignal(signal, 8000),
         });
         if (response.status === 429) {
             noteUsageRateLimited('claude', response.headers.get('retry-after'), { account: usageScope });
@@ -1271,7 +1284,7 @@ export async function probeClaudeStatus(home, cliVersion, usageScope) {
     }
 }
 /** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
-export async function probeKimiStatus(home, usageScope) {
+export async function probeKimiStatus(home, usageScope, signal) {
     const credPath = resolveKimiCredentialPath(home);
     if (!credPath)
         return { status: null, token: 'missing' };
@@ -1301,7 +1314,7 @@ export async function probeKimiStatus(home, usageScope) {
         const response = await fetch(KIMI_USAGES_URL, {
             method: 'GET',
             headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
-            signal: AbortSignal.timeout(8000),
+            signal: usageFetchSignal(signal, 8000),
         });
         if (response.status === 429) {
             noteUsageRateLimited('kimi', response.headers.get('retry-after'), { account: usageScope });
@@ -1313,7 +1326,7 @@ export async function probeKimiStatus(home, usageScope) {
     }
 }
 /** Probe Droid's WorkOS token against the billing-limits endpoint. Never refreshes (single-use rotation — see getDroidUsageInfo). */
-export async function probeDroidStatus(home, usageScope) {
+export async function probeDroidStatus(home, usageScope, signal) {
     const cred = decryptDroidAuthPayload(home || os.homedir());
     const accessToken = cred?.access_token;
     if (typeof accessToken !== 'string' || !accessToken)
@@ -1331,7 +1344,7 @@ export async function probeDroidStatus(home, usageScope) {
         const response = await fetch(DROID_USAGE_URL, {
             method: 'GET',
             headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
-            signal: AbortSignal.timeout(8000),
+            signal: usageFetchSignal(signal, 8000),
         });
         if (response.status === 429) {
             noteUsageRateLimited('droid', response.headers.get('retry-after'), { account: usageScope });
@@ -1887,6 +1900,17 @@ function writeClaudeUsageCacheFile(cache, cachePath) {
 }
 /** Convert a live UsageSnapshot to its JSON-serializable cached form. */
 function serializeClaudeUsageSnapshot(snapshot) {
+    // Persist the union of fresh `windows` and last-known `staleWindows`.
+    // `deserializeClaudeUsageSnapshot` re-runs the freshness gate on read and
+    // re-partitions the serialized windows into fresh vs. stale, so what matters
+    // is that every last-known reading reaches disk. Claude's collector returns
+    // raw windows (no `staleWindows`) and relies on that read-side partition. But
+    // Grok's collector pre-partitions in the fetch, moving an ended-period reading
+    // onto `staleWindows` — serializing only `windows` dropped it, so the very
+    // number a daemon `--refresh` just captured was gone from the next cached
+    // `agents view grok`, which rendered the plan alone (no bar). Include the
+    // stale windows here so the round-trip preserves them for any collector.
+    const persistedWindows = [...snapshot.windows, ...(snapshot.staleWindows ?? [])];
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
         plan: snapshot.plan ?? null,
@@ -1897,7 +1921,7 @@ function serializeClaudeUsageSnapshot(snapshot) {
                 resetsAt: snapshot.unavailable.resetsAt?.toISOString(),
             }
             : undefined,
-        windows: snapshot.windows.map((window) => ({
+        windows: persistedWindows.map((window) => ({
             key: window.key,
             label: window.label,
             shortLabel: window.shortLabel,
@@ -2387,17 +2411,131 @@ function safeStatSync(filePath) {
         return null;
     }
 }
+/**
+ * Resolve the Grok billing log to read usage from.
+ *
+ * `agents view grok` reads usage per INSTALLED VERSION, passing each version's
+ * isolated home (`~/.agents/.history/versions/grok/<ver>`). Grok writes
+ * `unified.jsonl` only to the shared real home `~/.grok/logs/unified.jsonl`
+ * even though GROK_HOME isolates auth/config/models per version. A per-version
+ * log, if one ever appears, still wins; otherwise we return the shared path
+ * marked `shared: true` so the caller can attribute it to at most one identity.
+ * Grok accounts are version-scoped (`NATIVE_ACCOUNT_CAPABILITIES.grok.scope ===
+ * 'version'`) — the shared file has no owner, so it must not be stamped onto
+ * every version home.
+ */
+function resolveGrokBillingLogPath(home) {
+    const rel = ['.grok', 'logs', 'unified.jsonl'];
+    const perVersion = path.join(home || os.homedir(), ...rel);
+    try {
+        if (fs.existsSync(perVersion))
+            return { logPath: perVersion, shared: false };
+    }
+    catch { /* unreadable */ }
+    // `AGENTS_REAL_HOME` is the seam every version-home consumer honors: a
+    // daemon/service-manager child's HOME can be baked to something other than
+    // the account's real home, so os.homedir() alone is not a reliable stand-in.
+    const shared = path.join(process.env.AGENTS_REAL_HOME || os.homedir(), ...rel);
+    if (shared !== perVersion) {
+        try {
+            if (fs.existsSync(shared))
+                return { logPath: shared, shared: true };
+        }
+        catch { /* unreadable */ }
+    }
+    return null;
+}
+/** This home's own `.grok/auth.json` only — never the shared-home fallback. */
+function readGrokAuthIdentity(home) {
+    const authPath = path.join(home, '.grok', 'auth.json');
+    try {
+        if (!fs.existsSync(authPath))
+            return null;
+        const data = JSON.parse(fs.readFileSync(authPath, 'utf-8'));
+        const records = (data && typeof data === 'object' ? [data, ...Object.values(data)] : [])
+            .filter((r) => !!r && typeof r === 'object' && !Array.isArray(r));
+        const account = records
+            .filter((r) => typeof r.refresh_token === 'string' || typeof r.email === 'string' || typeof r.user_id === 'string')
+            .sort((a, b) => String(b.create_time || '').localeCompare(String(a.create_time || '')))[0];
+        if (!account)
+            return null;
+        const userRaw = account.user_id ?? account.principal_id;
+        const userId = typeof userRaw === 'string' && userRaw.trim() ? userRaw.trim() : null;
+        const email = typeof account.email === 'string' && account.email.trim()
+            ? account.email.trim().toLowerCase()
+            : null;
+        if (!userId && !email)
+            return null;
+        return { userId, email };
+    }
+    catch {
+        return null;
+    }
+}
+function grokIdentitiesMatch(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.userId && b.userId)
+        return a.userId === b.userId;
+    if (a.email && b.email)
+        return a.email === b.email;
+    return false;
+}
+function grokIdentityFromBillingPayload(parsed) {
+    const ctx = parsed.ctx && typeof parsed.ctx === 'object' && !Array.isArray(parsed.ctx)
+        ? parsed.ctx
+        : null;
+    const config = ctx?.config && typeof ctx.config === 'object' && !Array.isArray(ctx.config)
+        ? ctx.config
+        : null;
+    const pick = (...cands) => {
+        for (const c of cands) {
+            if (typeof c === 'string' && c.trim())
+                return c.trim();
+        }
+        return null;
+    };
+    const userId = pick(ctx?.user_id, ctx?.userId, ctx?.principal_id, config?.user_id, parsed.user_id);
+    const emailRaw = pick(ctx?.email, config?.email, parsed.email);
+    if (!userId && !emailRaw)
+        return null;
+    return { userId, email: emailRaw ? emailRaw.toLowerCase() : null };
+}
+function sameHomePath(a, b) {
+    return (safeRealpathSync(a) ?? path.resolve(a)) === (safeRealpathSync(b) ?? path.resolve(b));
+}
+/**
+ * Whether the shared `~/.grok` billing log may be attached to this home.
+ * Grok logins are per version home; the shared last line is one account's
+ * meter. Fail loud: never copy it onto every installed identity.
+ */
+function sharedGrokLogAppliesToHome(home, match) {
+    const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
+    const requestedHome = home || os.homedir();
+    const thisId = readGrokAuthIdentity(requestedHome);
+    if (match.identity) {
+        return grokIdentitiesMatch(match.identity, thisId);
+    }
+    // No identity on the line (the live Grok shape). Attribute the reading to
+    // exactly one canonical identity: the real home itself, or the version home
+    // whose own auth.json matches the shared `~/.grok/auth.json`.
+    if (sameHomePath(requestedHome, realHome))
+        return true;
+    return grokIdentitiesMatch(thisId, readGrokAuthIdentity(realHome));
+}
 /** Parse the latest billing info from Grok's unified log. */
 async function getGrokUsageInfo(options) {
     try {
-        const base = options?.home || os.homedir();
-        const logPath = path.join(base, '.grok', 'logs', 'unified.jsonl');
+        const resolved = resolveGrokBillingLogPath(options?.home);
         // No log yet: a benign "nothing recorded here", not a failure (RUSH-3040).
-        if (!fs.existsSync(logPath))
+        if (!resolved)
             return usageNoRecentUsageInfo();
-        const match = await readLatestGrokBilling(logPath);
+        const match = await readLatestGrokBilling(resolved.logPath);
         if (!match)
             return usageNoRecentUsageInfo();
+        if (resolved.shared && !sharedGrokLogAppliesToHome(options?.home, match)) {
+            return usageNoRecentUsageInfo();
+        }
         // Grok has no live usage API (`network: false`) — bars are last-seen from
         // this machine's unified.jsonl only. Drop windows whose billing period has
         // already ended so a stale 100% does not paint "rate-limited" after reset,
@@ -2690,10 +2828,16 @@ async function readLatestGrokBilling(filePath) {
                 return;
             try {
                 const parsed = JSON.parse(line);
-                if (parsed.msg === 'billing: fetched credits config' && parsed.ctx?.config) {
-                    const config = parsed.ctx.config;
+                const ctx = parsed.ctx && typeof parsed.ctx === 'object' && !Array.isArray(parsed.ctx)
+                    ? parsed.ctx
+                    : null;
+                if (parsed.msg === 'billing: fetched credits config' && ctx?.config) {
+                    const config = ctx.config;
                     const windows = [];
-                    if (config.currentPeriod?.end && typeof config.creditUsagePercent === 'number') {
+                    const currentPeriod = config.currentPeriod && typeof config.currentPeriod === 'object'
+                        ? config.currentPeriod
+                        : null;
+                    if (currentPeriod?.end && typeof config.creditUsagePercent === 'number') {
                         // `creditUsagePercent` is Grok's weekly credit consumption (0-100);
                         // the billing period's `end` is when that window resets.
                         // Do NOT coerce a missing percent to 0 — a new period often lands a
@@ -2705,14 +2849,15 @@ async function readLatestGrokBilling(filePath) {
                             label: 'Current week',
                             shortLabel: 'W',
                             usedPercent: Math.max(0, Math.min(100, rawPercent)),
-                            resetsAt: parseDateValue(config.currentPeriod.end),
+                            resetsAt: parseDateValue(currentPeriod.end),
                             windowMinutes: inferWindowMinutes('week'),
                         });
                     }
                     latest = {
                         capturedAt: parseDateValue(parsed.ts),
-                        subscriptionTier: parsed.ctx.subscriptionTier || null,
+                        subscriptionTier: typeof ctx.subscriptionTier === 'string' ? ctx.subscriptionTier : null,
                         windows,
+                        identity: grokIdentityFromBillingPayload(parsed),
                     };
                 }
             }
@@ -2963,7 +3108,7 @@ async function getCursorUsageInfo(options) {
                 Cookie: cookie,
                 Accept: 'application/json',
             },
-            signal: AbortSignal.timeout(5000),
+            signal: usageFetchSignal(options?.signal, 5000),
         });
         // 401/redirect => revoked/expired session. No bars to draw, and the status
         // says why.

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

@@ -163,6 +163,8 @@ export declare function probeAuthHealth(agent: AgentId, home: string | undefined
      * a genuinely live request that surfaces `revoked` immediately.
      */
     forceLive?: boolean;
+    /** Daemon tick deadline signal, combined with each probe fetch's own timeout (PHNX-3608). */
+    signal?: AbortSignal;
 }): Promise<AuthHealth>;
 /** One probed install on a host. */
 export interface AuthProbeRow {
@@ -225,6 +227,12 @@ export declare function probeLocalFleetAuth(opts?: {
     agents?: readonly AgentId[];
     /** Fire real network probes even when fresh usage evidence exists (RUSH-3036) — the `devices ping [--strict]` contract. */
     forceLive?: boolean;
+    /**
+     * Deadline signal from the daemon's supervised auth tick (PHNX-3608). Aborts
+     * the probe's in-flight network work when the tick deadline elapses so it
+     * unwinds instead of leaking a runaway await; on-demand CLI callers omit it.
+     */
+    signal?: AbortSignal;
 }): Promise<AuthProbeRow[]>;
 /** Persist a host's probed rows into the cache (keyed by host+agent+version). */
 export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[]): void;

package/dist/lib/auth-health.js

@@ -347,11 +347,11 @@ export async function probeAuthHealth(agent, home, opts) {
         }
         let probe;
         if (agent === 'claude')
-            probe = await probeClaudeStatus(home, opts?.cliVersion, usageScope);
+            probe = await probeClaudeStatus(home, opts?.cliVersion, usageScope, opts?.signal);
         else if (agent === 'kimi')
-            probe = await probeKimiStatus(home, usageScope);
+            probe = await probeKimiStatus(home, usageScope, opts?.signal);
         else
-            probe = await probeDroidStatus(home, usageScope);
+            probe = await probeDroidStatus(home, usageScope, opts?.signal);
         return { verdict: verdictFromProbe(probe), checkedAt, detail: probeDetail(probe) };
     }
     const info = opts?.info !== undefined ? opts.info : await getAccountInfo(agent, home).catch(() => null);
@@ -426,7 +426,7 @@ export async function probeLocalFleetAuth(opts) {
     // accounts, so no same-account concurrency is left to trip the throttle.
     const perGroup = await Promise.all(groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent)).map(async (group) => {
         const rep = group.probe;
-        const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info, forceLive: opts?.forceLive });
+        const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info, forceLive: opts?.forceLive, signal: opts?.signal });
         health.account = authAccountLabel(rep.info);
         if (health.verdict === 'unconfigured')
             return [];

package/dist/lib/boot-profile.d.ts

@@ -0,0 +1,14 @@
+/** True when `AGENTS_PROFILE_BOOT` is set — callers can skip building label strings. */
+export declare function bootProfileEnabled(): boolean;
+/**
+ * Record a named stage boundary. No-op unless `AGENTS_PROFILE_BOOT` is set, so
+ * this is free to call unconditionally on the launch path.
+ */
+export declare function bootMark(label: string): void;
+/**
+ * Print the collected timeline to stderr, once. Called right before the harness
+ * child is spawned (the end of the pre-exec window) and again as an
+ * `process.on('exit')` backstop for launch paths that error out before spawn.
+ * `reason` labels the final boundary (e.g. `spawn`, `exit`).
+ */
+export declare function flushBootProfile(reason: string): void;

package/dist/lib/boot-profile.js

@@ -0,0 +1,66 @@
+/**
+ * Boot-time profiler for the `agents run` pre-exec phase (PHNX-3585).
+ *
+ * The AGI EXT "New Claude" boot spends the whole `agents run` wrapper cost
+ * BEFORE the harness prints anything — version resolution, account rotation,
+ * config sync, login preflight. This module makes that window measurable
+ * without a debugger: gate it on `AGENTS_PROFILE_BOOT=1` and the run path
+ * stamps named marks, then flushes a per-stage timeline to stderr the instant
+ * before the child is spawned (the moment the wrapper's work ends).
+ *
+ * All marks are `performance.now()` values, which Node measures from
+ * `performance.timeOrigin` ≈ process start — so a mark's absolute value is
+ * "ms since the `agents` process began", and consecutive marks give the cost
+ * of each stage. When the env flag is off, every function here is a couple of
+ * cheap branches and pushes nothing, so it is safe to leave wired on the hot
+ * path (the committed `scripts/bench-boot.sh` benchmark drives it).
+ */
+import { performance } from 'node:perf_hooks';
+const ENABLED = process.env.AGENTS_PROFILE_BOOT === '1' || process.env.AGENTS_PROFILE_BOOT === 'true';
+const marks = [];
+let flushed = false;
+/** True when `AGENTS_PROFILE_BOOT` is set — callers can skip building label strings. */
+export function bootProfileEnabled() {
+    return ENABLED;
+}
+/**
+ * Record a named stage boundary. No-op unless `AGENTS_PROFILE_BOOT` is set, so
+ * this is free to call unconditionally on the launch path.
+ */
+export function bootMark(label) {
+    if (!ENABLED)
+        return;
+    marks.push({ label, at: performance.now() });
+}
+/**
+ * Print the collected timeline to stderr, once. Called right before the harness
+ * child is spawned (the end of the pre-exec window) and again as an
+ * `process.on('exit')` backstop for launch paths that error out before spawn.
+ * `reason` labels the final boundary (e.g. `spawn`, `exit`).
+ */
+export function flushBootProfile(reason) {
+    if (!ENABLED || flushed)
+        return;
+    flushed = true;
+    bootMark(reason);
+    if (marks.length === 0)
+        return;
+    const start = 0; // process start
+    const end = marks[marks.length - 1].at;
+    const width = Math.max(...marks.map((m) => m.label.length));
+    const lines = [];
+    lines.push(`[boot-profile] pre-exec timeline (total ${(end - start).toFixed(1)}ms since process start)`);
+    let prev = start;
+    for (const m of marks) {
+        const delta = m.at - prev;
+        prev = m.at;
+        lines.push(`  ${m.label.padEnd(width)}  +${delta.toFixed(1).padStart(7)}ms   @${m.at.toFixed(1).padStart(8)}ms`);
+    }
+    process.stderr.write(lines.join('\n') + '\n');
+}
+// Backstop: a run that exits before reaching the spawn (a login dead-end, a
+// missing install) still emits whatever stages it reached, so the profile is
+// never silently empty.
+if (ENABLED) {
+    process.on('exit', () => flushBootProfile('exit'));
+}

package/dist/lib/browser/caller-identity.d.ts

@@ -13,6 +13,18 @@ export interface CallerIdentity {
  * agent comm is found.
  */
 export declare function resolveCallerIdentity(env?: NodeJS.ProcessEnv): CallerIdentity;
+/**
+ * The env a `browser --device` dispatch forwards so the HUB resolves the SAME
+ * caller identity the worker would stamp locally. Without it a forwarded verb
+ * lands on the hub with BLANK identity, and the daemon's no-identity task bucket
+ * matches any other no-identity task — so a cold verb could attach to (or a
+ * `done`/`stop` could close) an unrelated agent's or a human's browser. This is
+ * the same surface-parity fix the `run --device` path already carries via
+ * `--env AGENT_LAUNCH_ID` (remote-session-id.ts). Absent fields are omitted so a
+ * genuinely-unidentifiable caller forwards nothing rather than an empty string
+ * that would read as a real (blank) identity on the far side.
+ */
+export declare function callerIdentityEnv(caller: Pick<CallerIdentity, 'sessionId' | 'launchId'>): Record<string, string>;
 /**
  * True when a live task belongs to this caller. Match on sessionId or
  * launchId — either is enough. A task with no recorded identity never

package/dist/lib/browser/caller-identity.js

@@ -141,6 +141,25 @@ export function resolveCallerIdentity(env = process.env) {
     }
     return { actor, sessionId, launchId, agentPid };
 }
+/**
+ * The env a `browser --device` dispatch forwards so the HUB resolves the SAME
+ * caller identity the worker would stamp locally. Without it a forwarded verb
+ * lands on the hub with BLANK identity, and the daemon's no-identity task bucket
+ * matches any other no-identity task — so a cold verb could attach to (or a
+ * `done`/`stop` could close) an unrelated agent's or a human's browser. This is
+ * the same surface-parity fix the `run --device` path already carries via
+ * `--env AGENT_LAUNCH_ID` (remote-session-id.ts). Absent fields are omitted so a
+ * genuinely-unidentifiable caller forwards nothing rather than an empty string
+ * that would read as a real (blank) identity on the far side.
+ */
+export function callerIdentityEnv(caller) {
+    const env = {};
+    if (caller.sessionId)
+        env.AGENT_SESSION_ID = caller.sessionId;
+    if (caller.launchId)
+        env.AGENT_LAUNCH_ID = caller.launchId;
+    return env;
+}
 /**
  * True when a live task belongs to this caller. Match on sessionId or
  * launchId — either is enough. A task with no recorded identity never

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

@@ -4,24 +4,24 @@ import type { IPCRequest, IPCResponse } from './types.js';
 export interface IPCRequestOptions {
     autoStartDaemon?: boolean;
 }
-export declare class BrowserDaemonNotRunningError extends Error {
+export declare class BrowserServiceNotRunningError extends Error {
     constructor();
 }
-export declare function formatBrowserDaemonNotRunningError(): string;
+export declare function formatBrowserServiceNotRunningError(daemonRunning?: boolean): string;
 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>;
+export declare function isBrowserServiceReachable(): Promise<boolean>;
 /**
  * Is a *reachable* daemon actually responsive, or is its event loop wedged
- * (PHNX-3411)? Retries {@link probeDaemonResponsive} up to
+ * (PHNX-3411)? Retries {@link probeBrowserServiceResponsive} 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>;
+export declare function isBrowserServiceResponsive(endpoint?: string, attempts?: number): Promise<boolean>;
 /**
- * Wait until the browser daemon is genuinely reachable, or throw.
+ * Wait until the browser service 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
@@ -30,32 +30,35 @@ export declare function isDaemonResponsive(endpoint?: string, attempts?: number)
  * 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. */
+export declare function waitForBrowserService(_socketPath: string, timeoutMs?: number): Promise<void>;
+/** Outcome of {@link stopBrowserService} — what the service-scoped stop did. */
+export interface BrowserServiceStopResult {
+    /** The browser IPC service was reachable before the stop was requested. */
     wasRunning: boolean;
+    /** The shared daemon stayed running while only browser IPC was stopped. */
+    daemonRunning: 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.
+ * Stop only the daemon-hosted browser IPC service so a subsequent `start` comes
+ * up clean (PHNX-3605). The short-lived browser client persists the
+ * `browser-ipc` service off and asks the daemon to apply that transition over
+ * its existing SIGHUP control path. It never stops or restarts the shared
+ * supervisor, so routines, usage sync, secrets, and every sibling service keep
+ * their process and in-flight work.
  *
- * 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.
+ * Once the endpoint is quiet, a stale socket left by a hard-crashed browser
+ * service is removed. If the daemon event loop itself is wedged and cannot
+ * consume SIGHUP, the endpoint remains reachable and this fails loud with the
+ * deliberate operator-owned whole-daemon restart command; the client never
+ * escalates into that process-wide action itself.
  */
-export declare function resetBrowserDaemon(): Promise<BrowserDaemonResetResult>;
+export declare function stopBrowserService(): Promise<BrowserServiceStopResult>;
 /**
  * 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
+ * window (PHNX-3289 review). Between {@link stopBrowserService}'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
@@ -65,7 +68,7 @@ export declare function resetBrowserDaemon(): Promise<BrowserDaemonResetResult>;
  */
 export declare function clearDeadSocketFile(endpoint: string, socketPath: string): Promise<boolean>;
 /**
- * One long-lived connection to the existing browser daemon. Requests are
+ * One long-lived connection to the existing browser service. Requests are
  * serialized so the daemon's newline-delimited responses always map to the
  * caller that produced them, while the process and socket stay warm between
  * actions.
@@ -85,6 +88,8 @@ export declare class BrowserIPCConnection {
 }
 export declare class BrowserIPCServer {
     private server;
+    /** Filesystem identity of the POSIX binding this server created. */
+    private socketIdentity;
     private service;
     /** Live client connections, so {@link stop} can end them rather than wait. */
     private connections;
@@ -128,21 +133,21 @@ export declare class BrowserIPCServer {
     private handleRequest;
 }
 /**
- * Decide whether a running daemon is stale and must be restarted.
+ * Decide whether a running daemon is stale enough to name an operator refresh.
  *
- * FORWARD ONLY: restart when the daemon is *older* than this CLI so a newer
- * install loads current code. An older CLI rides a newer daemon instead of
- * evicting it — two installs sharing one daemon dir (keyed off $HOME) must
- * not flap the daemon indefinitely.
+ * FORWARD ONLY: recommend a refresh when the daemon is *older* than this CLI.
+ * An older CLI rides a newer daemon without noise. A client never performs the
+ * refresh itself — two installs sharing one daemon dir (keyed off $HOME) must
+ * not flap the daemon or interrupt one another's hosted services.
  *
  * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
- * action reliably — don't churn it on that ambiguous signal.
+ * action reliably — don't recommend an action on that ambiguous signal.
  *
  * When numeric compare cannot order two distinct strings (e.g. two
- * `0.0.0-dev.*` builds), treat the mismatch as a restart so a concrete
- * code change still loads.
+ * `0.0.0-dev.*` builds), surface the mismatch without deciding either client
+ * owns the shared process.
  */
-export declare function shouldRestartStaleDaemon(daemonVersion: string | undefined, clientVersion: string): boolean;
+export declare function shouldRecommendDaemonRefresh(daemonVersion: string | undefined, clientVersion: string): boolean;
 export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;
 /**
  * Fill actor / launchId / sessionId from the calling process when the request