@phnx-labs/agents-cli 1.22.34 → 1.22.37

package/dist/lib/browser/ipc.js

@@ -6,6 +6,23 @@ import { getHelpersDir } from '../state.js';
 import { startDaemon, stopDaemon } from '../daemon.js';
 import { getCliVersion } from '../version.js';
 const SOCKET_NAME = 'browser.sock';
+/**
+ * Backstop for {@link BrowserIPCServer.stop} — how long to wait for the socket
+ * to be released before unlinking it anyway (RUSH-2421).
+ *
+ * This MUST stay well under the daemon's SIGTERM grace window
+ * (`STOP_GRACE_MS`, daemon.ts). `handleShutdown` awaits `stop()`, so a close
+ * that takes as long as the grace window means `stopDaemon` gives up waiting
+ * and escalates to `killTree` — turning every graceful stop into a kill. The
+ * first version of this constant was set to exactly 5000, the same value as
+ * `STOP_GRACE_MS`, and did precisely that whenever a browser client held its
+ * (deliberately) long-lived connection open.
+ *
+ * With connections now ended explicitly in `closeServer`, reaching this
+ * timeout at all means a socket refused to die; 1.5s bounds that without
+ * coming near the grace window.
+ */
+const IPC_CLOSE_TIMEOUT_MS = 1_500;
 export class BrowserDaemonNotRunningError extends Error {
     constructor() {
         super(formatBrowserDaemonNotRunningError());
@@ -153,6 +170,10 @@ export class BrowserIPCConnection {
 export class BrowserIPCServer {
     server = null;
     service;
+    /** Live client connections, so {@link stop} can end them rather than wait. */
+    connections = new Set();
+    /** In-flight stop, so a second SIGTERM awaits the same close, never skips it. */
+    stopping = null;
     constructor(service) {
         this.service = service;
     }
@@ -170,6 +191,12 @@ export class BrowserIPCServer {
             }
         }
         this.server = net.createServer((socket) => {
+            // `net.Server.close()` stops accepting but does not complete until every
+            // EXISTING connection ends, and clients here hold one open on purpose
+            // ("the process and socket stay warm between actions"). Tracking them is
+            // what lets stop() end them deliberately instead of waiting out a timeout.
+            this.connections.add(socket);
+            socket.on('close', () => this.connections.delete(socket));
             let buffer = '';
             socket.on('data', async (data) => {
                 buffer += data.toString();
@@ -229,11 +256,38 @@ export class BrowserIPCServer {
             });
         });
     }
+    /**
+     * Stop accepting, release the binding, and only then resolve.
+     *
+     * RUSH-2421: this used to call `server.close()` and move on. `close()` is
+     * asynchronous — it stops accepting immediately but the binding is not
+     * actually released until the `'close'` event fires — so `stop()` resolved
+     * while the socket (or named pipe) was still held. The daemon's
+     * `handleShutdown` awaits this before it exits, and a successor's
+     * `claimDaemonInstance` waits for that exit as its proof the predecessor's
+     * resources are free (SING-11). Resolving early made that proof false: the
+     * newcomer could bind before the incumbent's binding was gone, which is the
+     * two-servers-on-one-socket orphan the eviction protocol exists to prevent.
+     *
+     * The first version of this waited out a timeout instead, and that made every
+     * graceful daemon stop escalate to `killTree`: `close()` does not complete
+     * while a connection is open, browser clients hold one open on purpose, and
+     * the timeout was set equal to the daemon's own SIGTERM grace window
+     * (`STOP_GRACE_MS`) — so `handleShutdown` was still inside `stop()` when
+     * `stopDaemon` gave up waiting and killed it. So we END the connections
+     * rather than wait for them: `close()` stops accepting, destroying the
+     * tracked sockets lets it complete, and the timeout is only a backstop for a
+     * socket that will not die, deliberately far below `STOP_GRACE_MS`.
+     */
     async stop() {
-        if (this.server) {
-            this.server.close();
-            this.server = null;
-        }
+        // A second SIGTERM must await the SAME stop, not skip past it because
+        // `this.server` was already nulled by the first.
+        if (!this.stopping)
+            this.stopping = this.doStop();
+        return this.stopping;
+    }
+    async doStop() {
+        await this.closeServer();
         if (!IS_WINDOWS) {
             const socketPath = getSocketPath();
             if (fs.existsSync(socketPath)) {
@@ -242,6 +296,28 @@ export class BrowserIPCServer {
         }
         await this.service.shutdown();
     }
+    /** Release the listening binding, resolving only once it is genuinely gone. */
+    closeServer() {
+        const server = this.server;
+        this.server = null;
+        if (!server)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const done = () => { clearTimeout(timer); resolve(); };
+            // Backstop only, for a socket that refuses to die. Far below the daemon's
+            // SIGTERM grace window so a slow close can never be what gets the daemon
+            // killed — the whole point is that the graceful path stays graceful.
+            const timer = setTimeout(done, IPC_CLOSE_TIMEOUT_MS);
+            // `close()` reports an error when the server was never listening —
+            // nothing to release, so that is a completed close, not a failure.
+            server.close(() => done());
+            // `close()` waits for existing connections; ending them is what lets it
+            // finish now instead of at the timeout.
+            for (const socket of this.connections)
+                socket.destroy();
+            this.connections.clear();
+        });
+    }
     async handleRequest(request) {
         if (request.action === 'upload-stage') {
             const source = request.source;
@@ -266,6 +342,7 @@ export class BrowserIPCServer {
                     skipDomainSkill: request.skipDomainSkill,
                     actor: request.actor,
                     launchId: request.launchId,
+                    sessionId: request.sessionId,
                 });
                 return {
                     ok: true,

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

@@ -5,8 +5,9 @@ export declare const DEFAULT_BROWSER_PROFILE_NAME = "default";
  * The device-local configured default profile name (set via
  * `agents browser profiles set-default`), or undefined when unset. When set, it
  * is the profile `agents browser start` resolves to for BOTH the no-`--profile`
- * path and an explicit `--profile default`. Stored per-machine — see
- * `Meta.defaultBrowserProfile`.
+ * path and an explicit `--profile default`. Stored as this machine's
+ * `browser.profile` device-config key (central `fleet.devices.<name>.config`
+ * block — see lib/device-config.ts).
  */
 export declare function getConfiguredDefaultProfileName(): string | undefined;
 export declare function getBrowserRuntimeDir(): string;

package/dist/lib/browser/profiles.js

@@ -1,17 +1,33 @@
 import * as path from 'path';
-import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, writeMeta, } from '../state.js';
+import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, updateMeta, } from '../state.js';
+import { getConfigValue } from '../device-config.js';
 import { findBrowserPath, findFirstInstalledBrowser, isPortInUse } from './chrome.js';
 import { DEFAULT_VIEWPORT } from './devices.js';
 export const DEFAULT_BROWSER_PROFILE_NAME = 'default';
+/**
+ * True for a profile whose contents only make sense on THIS machine, so it must
+ * live in the per-machine doc rather than the fleet-synced agents.yaml.
+ *
+ * Only the auto-detected `default` qualifies: it is generated by probing local
+ * browser installs and a free local port, so its `binary:` is an absolute path
+ * for one OS. Shared fleet-wide it caused a permanent rewrite loop — a macOS box
+ * wrote `/Applications/...`, a Linux box rewrote `/usr/bin/chromium-browser`,
+ * each on every `agents browser start`. Named profiles a user created are real
+ * fleet config and keep syncing.
+ */
+function isMachineLocalProfile(name) {
+    return name === DEFAULT_BROWSER_PROFILE_NAME;
+}
 /**
  * The device-local configured default profile name (set via
  * `agents browser profiles set-default`), or undefined when unset. When set, it
  * is the profile `agents browser start` resolves to for BOTH the no-`--profile`
- * path and an explicit `--profile default`. Stored per-machine — see
- * `Meta.defaultBrowserProfile`.
+ * path and an explicit `--profile default`. Stored as this machine's
+ * `browser.profile` device-config key (central `fleet.devices.<name>.config`
+ * block — see lib/device-config.ts).
  */
 export function getConfiguredDefaultProfileName() {
-    return readMeta().defaultBrowserProfile || undefined;
+    return getConfigValue('browser.profile').value || undefined;
 }
 export function getBrowserRuntimeDir() {
     return getBrowserRuntimeDirRoot();
@@ -82,15 +98,22 @@ function profileToConfig(profile) {
         config.logHost = profile.logHost;
     return config;
 }
-export async function listProfiles() {
+/**
+ * Every profile visible on this machine: the fleet-shared ones plus this
+ * machine's own. A machine-local entry WINS on a name collision — it was written
+ * by this box for this box, whereas the shared copy may carry another OS's
+ * binary path (that mismatch is exactly why `default` moved local).
+ */
+function allProfileConfigs() {
     const meta = readMeta();
-    if (!meta.browser)
-        return [];
-    return Object.entries(meta.browser).map(([name, config]) => configToProfile(name, config));
+    return { ...meta.browser, ...meta.deviceBrowser };
+}
+export async function listProfiles() {
+    const configs = allProfileConfigs();
+    return Object.entries(configs).map(([name, config]) => configToProfile(name, config));
 }
 export async function getProfile(name) {
-    const meta = readMeta();
-    const config = meta.browser?.[name];
+    const config = allProfileConfigs()[name];
     if (!config)
         return null;
     return configToProfile(name, config);
@@ -271,7 +294,8 @@ function hasSshEndpoint(endpoints) {
 }
 export async function createProfile(profile) {
     const meta = readMeta();
-    if (meta.browser?.[profile.name]) {
+    const existingConfigs = allProfileConfigs();
+    if (existingConfigs[profile.name]) {
         throw new Error(`Profile "${profile.name}" already exists`);
     }
     // Collision check. Every CDP/SSH profile ends up listening on (or
@@ -280,8 +304,8 @@ export async function createProfile(profile) {
     // longer need to scope by host. Two profiles that would need the same
     // local port can't both run at the same time.
     const newLocal = effectiveLocalPort(profile);
-    if (newLocal !== undefined && meta.browser) {
-        for (const [existingName, existingConfig] of Object.entries(meta.browser)) {
+    if (newLocal !== undefined) {
+        for (const [existingName, existingConfig] of Object.entries(existingConfigs)) {
             const existingProfile = configToProfile(existingName, existingConfig);
             const existingLocal = effectiveLocalPort(existingProfile);
             if (existingLocal === newLocal) {
@@ -302,25 +326,44 @@ export async function createProfile(profile) {
     if (!hasSshEndpoint(profile.endpoints)) {
         findBrowserPath(profile.browser, profile.binary);
     }
-    meta.browser = meta.browser ?? {};
-    meta.browser[profile.name] = profileToConfig(profile);
-    writeMeta(meta);
+    const config = profileToConfig(profile);
+    if (isMachineLocalProfile(profile.name)) {
+        updateMeta((m) => ({ ...m, deviceBrowser: { ...m.deviceBrowser, [profile.name]: config } }));
+        return;
+    }
+    updateMeta((m) => ({ ...m, browser: { ...m.browser, [profile.name]: config } }));
 }
 export async function updateProfile(profile) {
     const meta = readMeta();
-    if (!meta.browser?.[profile.name]) {
+    const local = meta.deviceBrowser?.[profile.name];
+    if (!local && !meta.browser?.[profile.name]) {
         throw new Error(`Profile "${profile.name}" does not exist`);
     }
-    meta.browser[profile.name] = profileToConfig(profile);
-    writeMeta(meta);
+    const config = profileToConfig(profile);
+    // A profile that already lives machine-locally stays there; so does the auto
+    // `default`, whose binary path and port are specific to this machine.
+    if (local || isMachineLocalProfile(profile.name)) {
+        updateMeta((m) => ({ ...m, deviceBrowser: { ...m.deviceBrowser, [profile.name]: config } }));
+        return;
+    }
+    updateMeta((m) => ({ ...m, browser: { ...m.browser, [profile.name]: config } }));
 }
 export async function deleteProfile(name) {
     const meta = readMeta();
-    if (!meta.browser?.[name]) {
+    const isLocal = !!meta.deviceBrowser?.[name];
+    if (!isLocal && !meta.browser?.[name]) {
         throw new Error(`Profile "${name}" does not exist`);
     }
-    delete meta.browser[name];
-    writeMeta(meta);
+    updateMeta((m) => {
+        if (isLocal) {
+            const next = { ...m.deviceBrowser };
+            delete next[name];
+            return { ...m, deviceBrowser: Object.keys(next).length > 0 ? next : undefined };
+        }
+        const next = { ...m.browser };
+        delete next[name];
+        return { ...m, browser: Object.keys(next).length > 0 ? next : undefined };
+    });
 }
 /**
  * Resolve a profile's endpoint presets into a normalized map regardless of

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

@@ -62,9 +62,11 @@ export interface HealInfo {
 export declare function resolveTaskIdentity(forwarded: {
     actor?: string;
     launchId?: string;
+    sessionId?: string;
 }, resolveLocalActor: () => string): {
     owner: string;
     launchId?: string;
+    sessionId?: string;
 };
 export declare class BrowserService {
     private static readonly SOURCE_PREFIX;
@@ -83,6 +85,8 @@ export declare class BrowserService {
         /** Caller identity, forwarded from the CLI (see IPCRequest.actor/launchId). */
         actor?: string;
         launchId?: string;
+        /** Calling agent session, forwarded from the CLI (see IPCRequest.sessionId). */
+        sessionId?: string;
     }): Promise<{
         task: string;
         name: string;

package/dist/lib/browser/service.js

@@ -15,6 +15,7 @@ import { typeEditorText } from './editor.js';
 import { detectUploadPattern, stageUploadFile, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
 import { emit } from '../events.js';
 import { resolveActor } from '../actor.js';
+import { recordBrowserSession } from '../session/db.js';
 import { sshExecAsync } from '../ssh-exec.js';
 function isPathInside(candidate, dir) {
     const rel = path.relative(dir, candidate);
@@ -235,6 +236,7 @@ export function resolveTaskIdentity(forwarded, resolveLocalActor) {
     return {
         owner: forwarded.actor ?? resolveLocalActor(),
         launchId: forwarded.launchId,
+        sessionId: forwarded.sessionId,
     };
 }
 export class BrowserService {
@@ -348,9 +350,10 @@ export class BrowserService {
             createdAt: Date.now(),
             pid: conn.pid,
             // Identity is forwarded from the caller (see resolveTaskIdentity): WHO
-            // (owner) and WHICH run (launchId). Resolving daemon-side would attribute
-            // every task to the shared daemon's actor (the RUSH-2020 bug).
-            ...resolveTaskIdentity({ actor: opts.actor, launchId: opts.launchId }, () => resolveActor().id),
+            // (owner), WHICH run (launchId), and WHICH agent session (sessionId).
+            // Resolving daemon-side would attribute every task to the shared daemon's
+            // actor (the RUSH-2020 bug).
+            ...resolveTaskIdentity({ actor: opts.actor, launchId: opts.launchId, sessionId: opts.sessionId }, () => resolveActor().id),
         };
         // For Electron, get the existing window as the tab
         if (conn.electron) {
@@ -363,6 +366,30 @@ export class BrowserService {
         }
         conn.tasks.set(taskName, task);
         await this.saveTaskState(effectiveProfileName, conn.tasks);
+        // Durable identity, written ONCE at start and never deleted (RUSH-2549).
+        // tasks.json above stays live state: `stop` drops the task from that map, so
+        // anything recorded only there is gone the moment the task ends -- which is
+        // why every finished task used to list as "unlinked". This row outlives the
+        // task, the daemon, and a reboot. Metadata only: the capture bytes stay on
+        // disk under capture_dir.
+        // Guarded like `emit` below ("logging should never break the CLI",
+        // events.ts): the browser task is already started and registered. An
+        // unwritable session DB must not turn a working `agents browser start` into
+        // a failure -- the cost of a miss is one unlinked row, not a dead browser.
+        try {
+            recordBrowserSession({
+                task: taskName,
+                profile: effectiveProfileName,
+                sessionId: task.sessionId,
+                launchId: task.launchId,
+                actor: task.owner,
+                startedAt: task.createdAt,
+                captureDir: getProfileSessionsDir(effectiveProfileName, taskName),
+            });
+        }
+        catch {
+            // Recording is best-effort; the task itself is live either way.
+        }
         emit('browser.launch', { profile: effectiveProfileName, task: taskName, pid: conn.pid });
         void import('../analytics/usage-db.js').then(({ recordUsage }) => {
             recordUsage({

package/dist/lib/browser/sessions-list.d.ts

@@ -33,10 +33,17 @@ export declare function renderBrowserSessions(groups: ProfileArtifacts[]): strin
 export declare function resolveArtifact(groups: ProfileArtifacts[], selector: string): string | null;
 /** Open a file in the OS default app. Returns true on success. */
 export declare function openArtifact(filePath: string): boolean;
-/** The identity fields this module cares about from a profile's `tasks.json`. */
+/** The identity fields this module cares about for one task. */
 export interface TaskIdentity {
     owner?: string;
     launchId?: string;
+    /**
+     * The agent session that drove the task. Primary identity: it is carried by
+     * every agent process, whereas a launch id is present on a minority of them.
+     * Sourced from the durable `browser_sessions` row, which survives task stop —
+     * `tasks.json` never records it beyond the task's own lifetime (RUSH-2549).
+     */
+    sessionId?: string;
 }
 /**
  * Read a profile's `tasks.json` for the identity of its CURRENTLY LIVE tasks,
@@ -48,6 +55,17 @@ export interface TaskIdentity {
  * browser daemon is running.
  */
 export declare function loadTaskIdentities(profile: string): Map<string, TaskIdentity>;
+/**
+ * Identity for one profile's tasks, durable copy first.
+ *
+ * `browser_sessions` is the source of truth: it is written at task start and
+ * never deleted, so it answers for tasks that have already stopped — the case
+ * `tasks.json` structurally cannot, since `saveTaskState` rewrites that file
+ * from the LIVE task map. The live file is still merged on top for a task that
+ * is running right now, so a task started by an older CLI (no DB row yet) keeps
+ * whatever identity it does have rather than regressing to nothing.
+ */
+export declare function loadDurableTaskIdentities(profile: string): Map<string, TaskIdentity>;
 /** launchId -> indexed session id, built once from every source that records
  *  this join, so a task-heavy profile resolves without re-scanning per task. */
 export interface LaunchSessionIndex {
@@ -85,6 +103,8 @@ export interface BrowserSessionRow {
     task?: string;
     owner?: string;
     launchId?: string;
+    /** The agent session that drove the task, when one was recorded. */
+    sessionId?: string;
     linkStatus: BrowserSessionLinkStatus;
     linkedSession?: SessionMeta;
     /** Newest first. */
@@ -99,7 +119,7 @@ export interface BrowserSessionRow {
  * or session-index dependency and is unit-testable with synthetic data (see
  * {@link buildBrowserSessionRows} for the impure disk/index-reading caller).
  */
-export declare function groupIntoRows(groups: ProfileArtifacts[], taskIdentities: Map<string, Map<string, TaskIdentity>>, resolveLaunch?: (launchId: string) => SessionMeta | null): BrowserSessionRow[];
+export declare function groupIntoRows(groups: ProfileArtifacts[], taskIdentities: Map<string, Map<string, TaskIdentity>>, resolveLaunch?: (launchId: string) => SessionMeta | null, resolveSession?: (sessionId: string) => SessionMeta | null): BrowserSessionRow[];
 /** Build task-first rows for one profile (or every profile with captures),
  *  reading `tasks.json` and resolving launchIds against the live indexes.
  *  The interactive picker's data source. */

package/dist/lib/browser/sessions-list.js

@@ -19,7 +19,7 @@ import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { getBrowserRuntimeDir, getProfileRuntimeDir } from './profiles.js';
 import { formatRelativeTime } from '../session/relative-time.js';
-import { getSessionById } from '../session/db.js';
+import { getSessionById, listBrowserSessionRecords, pruneToolSessions } from '../session/db.js';
 import { listPidSessionEntries } from '../session/pid-registry.js';
 import { loadHookSessionIndex } from '../session/hook-sessions.js';
 import { readRecentActivity } from '../activity.js';
@@ -214,10 +214,40 @@ export function loadTaskIdentities(profile) {
         out.set(name, {
             owner: typeof t.owner === 'string' ? t.owner : undefined,
             launchId: typeof t.launchId === 'string' ? t.launchId : undefined,
+            sessionId: typeof t.sessionId === 'string' ? t.sessionId : undefined,
         });
     }
     return out;
 }
+/**
+ * Identity for one profile's tasks, durable copy first.
+ *
+ * `browser_sessions` is the source of truth: it is written at task start and
+ * never deleted, so it answers for tasks that have already stopped — the case
+ * `tasks.json` structurally cannot, since `saveTaskState` rewrites that file
+ * from the LIVE task map. The live file is still merged on top for a task that
+ * is running right now, so a task started by an older CLI (no DB row yet) keeps
+ * whatever identity it does have rather than regressing to nothing.
+ */
+export function loadDurableTaskIdentities(profile) {
+    const merged = new Map();
+    for (const record of listBrowserSessionRecords(profile)) {
+        merged.set(record.task, {
+            owner: record.actor,
+            launchId: record.launchId,
+            sessionId: record.sessionId,
+        });
+    }
+    for (const [task, live] of loadTaskIdentities(profile)) {
+        const durable = merged.get(task);
+        merged.set(task, {
+            owner: live.owner ?? durable?.owner,
+            launchId: live.launchId ?? durable?.launchId,
+            sessionId: live.sessionId ?? durable?.sessionId,
+        });
+    }
+    return merged;
+}
 /**
  * Build the launchId -> sessionId index from the same three sources
  * `feed-post.ts` `resolvePostIdentity` already uses for this exact problem —
@@ -260,7 +290,7 @@ export function resolveLaunchSession(index, launchId) {
  * or session-index dependency and is unit-testable with synthetic data (see
  * {@link buildBrowserSessionRows} for the impure disk/index-reading caller).
  */
-export function groupIntoRows(groups, taskIdentities, resolveLaunch) {
+export function groupIntoRows(groups, taskIdentities, resolveLaunch, resolveSession) {
     const rows = [];
     for (const g of groups) {
         const identities = taskIdentities.get(g.profile) ?? new Map();
@@ -278,14 +308,24 @@ export function groupIntoRows(groups, taskIdentities, resolveLaunch) {
         for (const [task, artifacts] of byTask) {
             artifacts.sort((a, b) => b.mtimeMs - a.mtimeMs);
             const identity = identities.get(task);
-            const linkedSession = identity?.launchId ? resolveLaunch?.(identity.launchId) ?? null : null;
+            // Session id first: it is the direct answer and the one agents actually
+            // carry. The launchId join stays as the fallback for a task that recorded
+            // only that (an older CLI, or a run whose session id was unset).
+            let linkedSession = null;
+            if (identity?.sessionId && resolveSession)
+                linkedSession = resolveSession(identity.sessionId);
+            if (!linkedSession && identity?.launchId && resolveLaunch) {
+                linkedSession = resolveLaunch(identity.launchId);
+            }
+            const hasIdentityKey = !!(identity?.sessionId || identity?.launchId);
             rows.push({
                 kind: 'task',
                 profile: g.profile,
                 task,
                 owner: identity?.owner,
                 launchId: identity?.launchId,
-                linkStatus: linkedSession ? 'linked' : identity?.launchId ? 'unresolved' : 'unlinked',
+                sessionId: identity?.sessionId,
+                linkStatus: linkedSession ? 'linked' : hasIdentityKey ? 'unresolved' : 'unlinked',
                 linkedSession: linkedSession ?? undefined,
                 artifacts,
                 counts: countByKind(artifacts),
@@ -311,10 +351,18 @@ export function groupIntoRows(groups, taskIdentities, resolveLaunch) {
  *  reading `tasks.json` and resolving launchIds against the live indexes.
  *  The interactive picker's data source. */
 export function buildBrowserSessionRows(profile) {
+    // Retention runs from BOTH listing paths, not just the computer one: a box
+    // that uses `agents browser` and never runs `agents sessions --computer`
+    // would otherwise never sweep either table. Best-effort — a read-only DB
+    // must not break a listing.
+    try {
+        pruneToolSessions();
+    }
+    catch { /* listing must not fail on retention */ }
     const groups = listBrowserSessions(profile);
-    const taskIdentities = new Map(groups.map((g) => [g.profile, loadTaskIdentities(g.profile)]));
+    const taskIdentities = new Map(groups.map((g) => [g.profile, loadDurableTaskIdentities(g.profile)]));
     const index = buildLaunchSessionIndex();
-    return groupIntoRows(groups, taskIdentities, (launchId) => resolveLaunchSession(index, launchId));
+    return groupIntoRows(groups, taskIdentities, (launchId) => resolveLaunchSession(index, launchId), (sessionId) => getSessionById(sessionId));
 }
 /**
  * Search predicate for the interactive picker: task name, profile, the linked

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

@@ -5,6 +5,8 @@ export interface BrowserIPCStreamOptions {
     task?: string;
     actor: string;
     launchId?: string;
+    /** Calling agent session, forwarded onto `start` requests (RUSH-2549). */
+    sessionId?: string;
     autoStartDaemon?: boolean;
 }
 /**

package/dist/lib/browser/stream.js

@@ -53,6 +53,7 @@ export async function runBrowserIPCStream(options) {
                     taskName: request.taskName ?? defaultTask,
                     actor: request.actor ?? options.actor,
                     launchId: request.launchId ?? options.launchId,
+                    sessionId: request.sessionId ?? options.sessionId,
                 };
             }
             else if (!request.task && defaultTask) {

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

@@ -93,6 +93,13 @@ export interface Task {
      * from the caller over IPC. Optional: tasks from before this shipped carry none.
      */
     launchId?: string;
+    /**
+     * The agent session that started this task (`$AGENT_SESSION_ID`), forwarded
+     * from the caller at `start`. The durable copy lives in the `browser_sessions`
+     * table, which survives `stop`; this in-memory/tasks.json copy is the live one
+     * (RUSH-2549).
+     */
+    sessionId?: string;
     /**
      * Per-tab snapshot of the last ref listing captured for that tab
      * (shortId -> {descriptors, opts}). Persisted to tasks.json so a later
@@ -196,6 +203,18 @@ export interface IPCRequest {
     skipDomainSkill?: boolean;
     actor?: string;
     launchId?: string;
+    /**
+     * The calling agent session (`$AGENT_SESSION_ID` / `$AGENTS_SESSION_ID`) —
+     * the id that answers "which agent drove this task" and the one persisted to
+     * `browser_sessions` (RUSH-2549).
+     *
+     * This is the primary identity, not a spare: `launchId` alone was the join
+     * key, and a fleet measurement found it present on only 2 of 5 live agent
+     * processes while a session id was on 5 of 5 — every agent reaching the
+     * browser carries one. It is the same env `stampProvenance()` already reads
+     * for `computer.action` events, so both tool surfaces key on one signal.
+     */
+    sessionId?: string;
 }
 /** Subset of IPCResponse describing a recording start result. */
 export interface RecordStartFields {

package/dist/lib/byok-usage.d.ts

@@ -20,6 +20,8 @@ export interface ByokUsageResult {
     error: string | null;
 }
 export declare function setByokFetchForTest(fn: typeof globalThis.fetch): void;
+export declare const BYOK_REFRESH_INTERVAL_MS: number;
+export declare function setByokCachePathForTest(value: string | null): string | null;
 export declare function resetByokCacheForTest(): void;
 export declare function hasByokProvider(provider: string): boolean;
 export declare function renderByokBar(result: ByokUsageResult): string;
@@ -30,9 +32,14 @@ export declare function renderByokBar(result: ByokUsageResult): string;
  * Returns a `ByokUsageResult` with `budget: null` when the token is absent
  * from the keychain (so the caller can skip rendering a bar without error).
  *
- * Results are SWR-cached per `keychainItem` so harnesses sharing one API key
- * deduplicate to a single network request.
+ * Ordinary reads are cache-only. Explicit refreshes are serialized per provider
+ * credential across every agents-cli process on the device.
  */
 export declare function getByokUsageForHarness(profile: Profile, opts?: {
     forceRefresh?: boolean;
 }): Promise<ByokUsageResult | null>;
+/** Refresh each configured BYOK credential when its daemon-owned snapshot is due. */
+export declare function refreshDueByokUsage(profiles: Profile[], now?: number): Promise<{
+    refreshed: number;
+    skipped: number;
+}>;