@phnx-labs/agents-cli 1.22.35 → 1.22.38

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

@@ -0,0 +1,90 @@
+import { type PidSessionEntry } from '../session/pid-registry.js';
+import type { ReapResult, Task } from './types.js';
+/** Default idle window before an untouched task is reaped. */
+export declare const DEFAULT_IDLE_MS: number;
+/**
+ * The slice of `BrowserService` the reaper needs. Structural, so a test drives
+ * it with a stub and `BrowserService` satisfies it without an import — which
+ * also keeps this module off the service's import cycle.
+ */
+export interface ReapableService {
+    listTasks(): Array<{
+        profile: string;
+        task: Task;
+    }>;
+    recordStatus(taskName: string): Promise<{
+        recording: boolean;
+    }>;
+    stop(taskName: string): Promise<{
+        ok: boolean;
+        profile?: string;
+    }>;
+}
+/**
+ * Injectable liveness sources. Same shape as `feed-post.ts`
+ * (`input.listEntries ?? listPidSessionEntries`, feed-post.ts:119) — the
+ * defaults are the real registry and the real process table, so a test can
+ * substitute them without mocking a module.
+ */
+export interface ReapDeps {
+    listEntries?: () => PidSessionEntry[];
+    pidAlive?: (pid: number, startedAtMs?: number) => boolean;
+    sessionIdOfPid?: (pid: number) => string | undefined;
+    sessionLiveOnProcessTable?: (sessionId: string) => Promise<boolean>;
+}
+export interface ReapOptions {
+    /** Idle window in ms. Default {@link DEFAULT_IDLE_MS}. */
+    idleMs?: number;
+    /** Clock, injectable for tests. Default `Date.now()`. */
+    now?: number;
+    /** Report what would be closed without closing anything. */
+    dryRun?: boolean;
+    deps?: ReapDeps;
+}
+export interface LiveIdentities {
+    sessions: Set<string>;
+    launches: Set<string>;
+}
+/**
+ * Session and launch ids belonging to a process that is alive right now.
+ *
+ * Built from the per-pid launch registry, filtered to live pids —
+ * `isPidAlive(pid, startedAtMs)` rather than a bare existence check, so a pid
+ * the OS recycled onto an unrelated process does not read as a live agent.
+ * An entry with no recorded `sessionId` still contributes one when the live
+ * process carries `--session-id` on its argv, which is the RUSH-2384 recovery
+ * path the registry itself documents (pid-registry.ts:102-107).
+ */
+export declare function resolveLiveIdentities(deps?: ReapDeps): LiveIdentities;
+/**
+ * True when the task's owner is PROVABLY gone. The bar is proof, not absence of
+ * evidence, because being wrong here closes a working agent's tabs.
+ *
+ * Only a `sessionId` can carry that proof. It has two independent sources — the
+ * per-pid launch registry, and a live process carrying `--session-id <id>` in
+ * its argv — so a session the registry missed is still caught by the process
+ * table. The registry misses constantly: a wrapper pid exits, a prune sweeps
+ * the entry, or the agent was never launched via `agents run`
+ * (pid-registry.ts:102-107, RUSH-2384).
+ *
+ * A `launchId` has NO second source — the registry is its only witness, and
+ * that witness is the unreliable one. So a task carrying only a `launchId` is
+ * never session-reaped, exactly like a task carrying no identity at all; both
+ * fall through to the idle rule. This is not a corner case: `launchId` is
+ * minted for every run (`exec.ts` `resolveLaunchId`) while `AGENT_SESSION_ID`
+ * is Claude-only and skipped on resume, so treating a missing registry entry as
+ * proof of death would close the tabs of every live codex/droid/grok run whose
+ * launch pid had already exited.
+ *
+ * A live `launchId` still RESCUES a task whose `sessionId` looks dead — proof of
+ * life needs only one witness, unlike proof of death.
+ */
+export declare function taskOwnerIsGone(task: Task, live: LiveIdentities, deps?: ReapDeps): Promise<boolean>;
+/**
+ * Stop every task whose owner is gone or that has sat untouched past `idleMs`.
+ *
+ * Returns what it closed and how many it left alone. A task that is mid-
+ * recording is always left alone: reaping it would truncate a capture the user
+ * asked for, and an in-flight recording is itself proof the task is in use.
+ */
+export declare function reapAbandonedTasks(service: ReapableService, opts?: ReapOptions): Promise<ReapResult>;

package/dist/lib/browser/hygiene.js

@@ -0,0 +1,146 @@
+/**
+ * Abandoned browser-task reaper (RUSH-2622).
+ *
+ * `agents browser done` / `stop` already close a task's tabs, but agents
+ * routinely never call them — the run ends, the process exits, and the task's
+ * tabs stay open in the profile window forever. Over a day of fleet activity
+ * that is dozens of leftover tabs in Comet/Chrome.
+ *
+ * This closes the loop from the other end: a periodic pass that finds tasks
+ * nobody is driving any more and stops them.
+ *
+ * Two independent reasons, both conservative:
+ *
+ *   - `session-dead` — the task recorded WHICH agent session (`sessionId`) or
+ *     WHICH run (`launchId`) started it, and neither is alive on this host.
+ *     That is the honest end of the task: the thing that would have called
+ *     `done` no longer exists.
+ *   - `idle` — nothing has touched the task for `idleMs` (default 30 minutes).
+ *     The catch-all for a task with no recorded identity (a human running
+ *     `agents browser start` by hand) or an agent that stalled without exiting.
+ *
+ * Closing always goes through `BrowserService.stop`, never a direct
+ * `Target.closeTarget`, so history, the session cache, the target cache, and
+ * forked-profile teardown all stay on the one code path that already handles
+ * them. Two things this deliberately never does: touch a tab that is not in
+ * `task.tabs` (a tab the user opened themselves is not ours to close), and kill
+ * the profile window or the browser process because one task went idle.
+ */
+import { isPidAlive, isSessionIdLiveOnProcessTable } from '../session/active.js';
+import { listPidSessionEntries, sessionIdFromLivePid } from '../session/pid-registry.js';
+/** Default idle window before an untouched task is reaped. */
+export const DEFAULT_IDLE_MS = 30 * 60_000;
+/**
+ * Session and launch ids belonging to a process that is alive right now.
+ *
+ * Built from the per-pid launch registry, filtered to live pids —
+ * `isPidAlive(pid, startedAtMs)` rather than a bare existence check, so a pid
+ * the OS recycled onto an unrelated process does not read as a live agent.
+ * An entry with no recorded `sessionId` still contributes one when the live
+ * process carries `--session-id` on its argv, which is the RUSH-2384 recovery
+ * path the registry itself documents (pid-registry.ts:102-107).
+ */
+export function resolveLiveIdentities(deps = {}) {
+    const listEntries = deps.listEntries ?? listPidSessionEntries;
+    const alive = deps.pidAlive ?? isPidAlive;
+    const sessionIdOf = deps.sessionIdOfPid ?? sessionIdFromLivePid;
+    const sessions = new Set();
+    const launches = new Set();
+    for (const entry of listEntries()) {
+        if (!alive(entry.pid, entry.startedAtMs))
+            continue;
+        const sessionId = entry.sessionId ?? sessionIdOf(entry.pid);
+        if (sessionId)
+            sessions.add(sessionId);
+        if (entry.launchId)
+            launches.add(entry.launchId);
+    }
+    return { sessions, launches };
+}
+/**
+ * True when the task's owner is PROVABLY gone. The bar is proof, not absence of
+ * evidence, because being wrong here closes a working agent's tabs.
+ *
+ * Only a `sessionId` can carry that proof. It has two independent sources — the
+ * per-pid launch registry, and a live process carrying `--session-id <id>` in
+ * its argv — so a session the registry missed is still caught by the process
+ * table. The registry misses constantly: a wrapper pid exits, a prune sweeps
+ * the entry, or the agent was never launched via `agents run`
+ * (pid-registry.ts:102-107, RUSH-2384).
+ *
+ * A `launchId` has NO second source — the registry is its only witness, and
+ * that witness is the unreliable one. So a task carrying only a `launchId` is
+ * never session-reaped, exactly like a task carrying no identity at all; both
+ * fall through to the idle rule. This is not a corner case: `launchId` is
+ * minted for every run (`exec.ts` `resolveLaunchId`) while `AGENT_SESSION_ID`
+ * is Claude-only and skipped on resume, so treating a missing registry entry as
+ * proof of death would close the tabs of every live codex/droid/grok run whose
+ * launch pid had already exited.
+ *
+ * A live `launchId` still RESCUES a task whose `sessionId` looks dead — proof of
+ * life needs only one witness, unlike proof of death.
+ */
+export async function taskOwnerIsGone(task, live, deps = {}) {
+    if (!task.sessionId)
+        return false;
+    if (task.launchId && live.launches.has(task.launchId))
+        return false;
+    if (live.sessions.has(task.sessionId))
+        return false;
+    const onProcessTable = deps.sessionLiveOnProcessTable ?? ((id) => isSessionIdLiveOnProcessTable(id));
+    return !(await onProcessTable(task.sessionId));
+}
+/**
+ * Stop every task whose owner is gone or that has sat untouched past `idleMs`.
+ *
+ * Returns what it closed and how many it left alone. A task that is mid-
+ * recording is always left alone: reaping it would truncate a capture the user
+ * asked for, and an in-flight recording is itself proof the task is in use.
+ */
+export async function reapAbandonedTasks(service, opts = {}) {
+    const idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
+    // Fail loud rather than reap everything. A caller-supplied `0` survives `??`
+    // and would close every task including one created a millisecond ago; a
+    // non-numeric value makes every `>=` comparison false and silently disables
+    // idle reaping. Both are worse than an error.
+    if (!Number.isFinite(idleMs) || idleMs <= 0) {
+        throw new Error(`idleMs must be a positive number of milliseconds, got ${String(idleMs)}`);
+    }
+    const now = opts.now ?? Date.now();
+    const deps = opts.deps ?? {};
+    const live = resolveLiveIdentities(deps);
+    const closed = [];
+    let skipped = 0;
+    for (const { profile, task } of service.listTasks()) {
+        if ((await service.recordStatus(task.name)).recording) {
+            skipped++;
+            continue;
+        }
+        let reason;
+        if (await taskOwnerIsGone(task, live, deps)) {
+            reason = 'session-dead';
+        }
+        else if (now - (task.lastActionAt ?? task.createdAt) >= idleMs) {
+            reason = 'idle';
+        }
+        if (!reason) {
+            skipped++;
+            continue;
+        }
+        if (opts.dryRun) {
+            closed.push({ task: task.name, profile, reason });
+            continue;
+        }
+        const result = await service.stop(task.name);
+        if (result.ok) {
+            closed.push({ task: task.name, profile: result.profile ?? profile, reason });
+        }
+        else {
+            // `stop` reports not-found only when the task already left the map — a
+            // concurrent `done`, or a profile torn down mid-pass. Nothing was closed,
+            // so it is not reported as closed.
+            skipped++;
+        }
+    }
+    return { closed, skipped };
+}

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

@@ -34,9 +34,39 @@ export declare class BrowserIPCConnection {
 export declare class BrowserIPCServer {
     private server;
     private service;
+    /** Live client connections, so {@link stop} can end them rather than wait. */
+    private connections;
+    /** In-flight stop, so a second SIGTERM awaits the same close, never skips it. */
+    private stopping;
     constructor(service: BrowserService);
     start(): Promise<void>;
+    /**
+     * 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`.
+     */
     stop(): Promise<void>;
+    private doStop;
+    /** Release the listening binding, resolving only once it is genuinely gone. */
+    private closeServer;
     private handleRequest;
 }
 /**

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;
@@ -264,8 +340,10 @@ export class BrowserIPCServer {
                     url: request.url,
                     endpointName: request.endpoint,
                     skipDomainSkill: request.skipDomainSkill,
+                    fresh: request.fresh,
                     actor: request.actor,
                     launchId: request.launchId,
+                    sessionId: request.sessionId,
                 });
                 return {
                     ok: true,
@@ -275,6 +353,17 @@ export class BrowserIPCServer {
                     skill: result.skill,
                 };
             }
+            // The out-of-process seam onto the abandoned-task reaper: the daemon
+            // owns the live BrowserService, so a CLI verb (`agents browser gc`) can
+            // only reach `reapAbandoned` through IPC. The daemon's own periodic tick
+            // calls the service method directly.
+            case 'gc': {
+                const reaped = await this.service.reapAbandoned({
+                    idleMs: request.idleMinutes !== undefined ? request.idleMinutes * 60_000 : undefined,
+                    dryRun: request.dryRun,
+                });
+                return { ok: true, reaped };
+            }
             case 'done': {
                 if (!request.task) {
                     return { ok: false, error: 'Task required' };

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