@phnx-labs/agents-cli 1.22.94 → 1.22.96

package/CHANGELOG.md

@@ -1,15 +1,35 @@
 # Changelog
 
+## 1.22.96
+
+- **`agents browser tabs --all` shows every tab open in the profile browser, yours included (PHNX-4043).** Until now `tabs` listed only the task's own tabs, so an agent sharing an Arc Space, a Comet store, or a Firefox profile with you could not see what else was open. `--all` lists every top-level tab: OWNER names the agents-cli task that owns it, or `you` for a tab no task owns; `*` still marks the task's current tab. Read-only on every backend (Chromium `Target.getTargets`, the Arc Space's tabs, Firefox `browsingContext.getTree`). Source: `cli/src/lib/browser/service.ts` `profileTabs`, `cli/src/commands/browser.ts`.
+
+- **Firefox automation over WebDriver BiDi (PHNX-4043).** `agents browser` now drives
+  Firefox, which dropped the Chrome DevTools Protocol in 129. Every Firefox profile in
+  `profiles.ini` is discovered read-only as a `firefox-<name>` browser profile
+  (`firefox-default`, `firefox-default-release`, …) pinned to that profile directory;
+  agents launch it headless with a debug port (or attach to a running one, failing loud
+  when a portless Firefox already holds the profile). Supported verbs: start, navigate,
+  tab add, tabs, evaluate, refs, click, fill/type, scroll, screenshot, done — with the
+  same same-task reopen semantics as the rest of the service. A trusted pointer click
+  goes through `input.performActions`. Network capture, upload, and PDF fail loud with a
+  structured error naming a Chromium-family profile. Source: `apps/cli/src/lib/browser/drivers/firefox.ts`,
+  `apps/cli/src/lib/browser/firefox-discovery.ts`, `apps/cli/src/lib/browser/service.ts`.
+
+- **Comet's own profiles are browser profiles, and discovered profiles reach the whole fleet (PHNX-4042).** On a Mac, `agents browser profiles list` now shows one profile per entry in Comet's profile menu (`comet-work`, ...), read from Comet's `Local State` and pinned to Comet's real user-data dir and `--profile-directory`, next to the `arc-*` rows for Arc Spaces. Agents and you share one Comet window per profile: agents attach when it runs with remote debugging on the profile's port, launch Comet on your own store when it is not running (over a TCP port, so the instance outlives a daemon restart and the ownership guard can verify it), and fail loud with the relaunch command when it runs without a port. The daemon's fleet-sync tick publishes every discovered profile into this device's declaration, so other boxes list it with `WHERE=<device>` and `--profile arc-gmail` from a worker routes to the Mac that owns it. `AGENTS_COMET_DIR` points discovery at another store. Source: `cli/src/lib/browser/chromium-discovery.ts`, `cli/src/lib/browser/profiles.ts`, `cli/src/lib/browser/chrome.ts`, `cli/src/lib/browser/drivers/local.ts`, `cli/src/lib/daemon/usage-sync-service.ts`.
+
 ## 1.22.94
 
+- **Agents drive your running Arc, one profile per Arc Space (PHNX-2399, macOS).** On a Mac with Arc, `agents browser profiles list` shows every Arc Space as a profile — `arc-gmail`, `arc-work`, `arc-dev`, named after the Space title — discovered read-only from Arc's `User Data/Local State` and `StorableSidebar.json`. A Space already carries its Arc profile's logins, so it is the browser profile agents pick with `--profile`; there is no separate Space flag and nothing to create. `agents browser use arc-gmail` makes it the default. Tabs are created, navigated, evaluated, and closed through Apple Events against the Arc you already have open — no debug port, no relaunch, never a second Arc. Agents only ever touch the tabs they created: durable task state addresses them by stable window, Space, and tab ids, a crash-safe marker intent guards creation, and closing a task removes only its own tabs. Creating a tab makes Arc select it for about 100 ms before the tab you had selected is restored; navigate, evaluate, and close are silent. Native refs, click, fill/type, scroll, and `tab focus` work; screenshots, promise evaluation, trusted input, network/console capture, uploads/downloads, and PDF fail with `ArcNativeCapabilityError` and point at a Chromium-family profile. Source: `cli/src/lib/browser/arc-discovery.ts`, `cli/src/lib/browser/drivers/arc.ts`, `cli/src/lib/browser/arc-dom.ts`, `cli/src/lib/browser/profiles.ts`, `cli/src/lib/browser/service.ts`, `cli/src/commands/browser.ts`.
+
+## 1.22.93
+
 - **An idle reminder is not a permission request — attention is classified from explicit harness evidence, and time-based signals expire (PHNX-3999).** The fleet feed was rendering Claude's `idle_prompt` Notification ("the turn ended and you have been idle") as a `permission` with Approve/Deny — a session whose whole transcript was "reply with exactly: pong" → "pong" got an approval banner — and the state engine labelled any tool call that had run quietly for two minutes a permission too. Now a `notification` block is a `permission` only when its recorded subtype is `permission_prompt` and the session's transcript corroborates it (no tool result or new turn stamped after the block, process alive); the feed-publish hook no longer publishes `idle_prompt` at all, an `idle_prompt` block left on disk yields no request, an `elicitation_dialog` is a question with no invented buttons, and a pending tool call reads as `working` however long it has run. One unresolved record per `host/session/generation` is resolved by later evidence — a transcript event after the block, or a dead process — never by dismissing the banner. What the CLI cannot confirm (a stale hook block with no transcript cursor to check, a notification with no recorded subtype, an older peer's elapsed-time `permission` claim) is the new `unverified` kind: the banner and the `feed watch` stream say "Could not verify request" with an Open terminal action only, and `agents feed answer` refuses it. `computeLiveSignals` now memoizes only the parsed transcript tail on mtime and re-classifies against the current clock every call, so the 30-minute prose-question decay expires on schedule instead of freezing until someone types; rows carry `lastEventMs`, the harness stamp on the last meaningful event. Source: `cli/src/lib/feed/attention.ts`, `cli/src/lib/session/state.ts`, `cli/src/lib/session/active.ts`, `cli/src/lib/feed/feed.ts`, `cli/src/lib/feed/answer.ts`, `cli/src/lib/daemon/attention-notify-service.ts`.
 
 - **AGI Menu 1.1.1: three fixed tabs (PHNX-3999, PHNX-4036).** The `menubar` helper floor moves to 1.1.1, the first release cut from phnx-labs/agi-menu: the status item opens a popover with Sessions (working first, then confirmed requests), Projects (the tracker's projects → milestones with cycle chips → issues, expanding in place, from one `linear projects overview --json` call) and Settings, replacing the long dropdown. Fresh installs and `agents menubar setup` fetch it from the public `menubar/v1.1.1` release. Source: `cli/src/lib/helper-versions.ts`.
 
 - **AGI Menu moved out — the menu-bar helper now lives in `phnx-labs/agi-menu` (PHNX-4036).** `cli/menubar/` (the SwiftPM source, its build/test scripts, and the build-text test) is gone from this repo, the same split AGI EXT got in RUSH-3189. Nothing user-facing changes: `agents menubar setup`/`enable` still download and verify the signed, notarized `MenubarHelper.app.zip` from the `menubar/v<floor>` release tag (`src/lib/helper-versions.ts`), at the same URL, with the same bundle identity and designated-requirement pin — that release is now cut by agi-menu's `scripts/release.sh`, which also uploads a `menubar-source.txt` provenance sidecar. Release tooling never builds the helper again: a new `scripts/stage-menubar-helper.sh` downloads the published `menubar/v<floor>` asset, verifies its sha256, and (on macOS) extracts it into `bin/MenubarHelper.app` behind `codesign --verify --deep --strict`, `spctl --assess`, and the DR-pin gate (`scripts/verify-menubar-helper.sh`, no longer a prepack gate); `--fetch-only` downloads and sha-verifies on any OS. `release-attestation-produce.sh --with-helpers` records the menubar helper-manifest row from that published asset (asset digest = sha256 of the zip, `source` = the sidecar's repo/commit/tag when the release carries one) instead of a fresh build, keyed on `src/lib/helper-versions.ts` as its input — a floor bump is what re-records it; a missing or corrupt release fails closed naming the agi-menu publish step. `remote-sign-mac.sh` stages the published helper on the home base instead of running `swift build`. The installer's dead `cli/menubar/dist/` source candidate is removed; `bin/MenubarHelper.app` (staged, or copied from an agi-menu checkout) remains the working-tree source. Source: `cli/scripts/stage-menubar-helper.sh`, `cli/scripts/release-manifest.sh`, `cli/scripts/release-attestation-produce.sh`, `cli/scripts/remote-sign-mac.sh`, `cli/src/lib/menubar/download-menubar.ts`.
 
-- **Agents drive your running Arc, one profile per Arc Space (PHNX-2399, macOS).** On a Mac with Arc, `agents browser profiles list` shows every Arc Space as a profile — `arc-gmail`, `arc-work`, `arc-dev`, named after the Space title — discovered read-only from Arc's `User Data/Local State` and `StorableSidebar.json`. A Space already carries its Arc profile's logins, so it is the browser profile agents pick with `--profile`; there is no separate Space flag and nothing to create. `agents browser use arc-gmail` makes it the default. Tabs are created, navigated, evaluated, and closed through Apple Events against the Arc you already have open — no debug port, no relaunch, never a second Arc. Agents only ever touch the tabs they created: durable task state addresses them by stable window, Space, and tab ids, a crash-safe marker intent guards creation, and closing a task removes only its own tabs. Creating a tab makes Arc select it for about 100 ms before the tab you had selected is restored; navigate, evaluate, and close are silent. Native refs, click, fill/type, scroll, and `tab focus` work; screenshots, promise evaluation, trusted input, network/console capture, uploads/downloads, and PDF fail with `ArcNativeCapabilityError` and point at a Chromium-family profile. Source: `cli/src/lib/browser/arc-discovery.ts`, `cli/src/lib/browser/drivers/arc.ts`, `cli/src/lib/browser/arc-dom.ts`, `cli/src/lib/browser/profiles.ts`, `cli/src/lib/browser/service.ts`, `cli/src/commands/browser.ts`.
-
 - **A Claude account-slot launch now runs in its own slot home, and worker slots come pre-onboarded (PHNX-3940 follow-up).** `agents run claude --device <worker>` picked an account slot and pinned `CLAUDE_CONFIG_DIR` to it, but the versioned alias (`~/.agents/.cache/shims/claude@<version>`) re-exported the shared version home unconditionally, so the run authenticated as the picked account (the setup-token env survived) while reading and writing config, onboarding state and history in whatever home the version carried — on yosemite-m1 that home belonged to another account and had never onboarded, so every dispatched run opened on Claude Code's theme picker. `buildExecEnv` now stamps a slot launch in `AGENTS_EXEC_HOME`; every shim that pins a config-dir env (claude, grok, opencode, kimi, muse, copilot — bare shim and direct alias, schema 32 / alias 21 — the daemon self-heal or `agents doctor --fix` regenerates on-disk copies) yields its pin to that slot through one shared `slotAwareConfigEnvBash` and consumes the marker before `exec`, so a nested launch never inherits its parent's slot and a bare `<agent>@<version>` from a terminal still gets the version home; the same override was live for all six, codex and cursor already yielded. A re-seed that still reads as unseeded (a slot config file that exists but cannot be parsed) is reported as an error each tick instead of a false "provisioned". Separately, `provisionWorkerSlot` seeded only the identity email into a slot's `.claude.json`, never `hasCompletedOnboarding` — a worker has no human to finish onboarding — so every provisioned slot re-onboarded; it now seeds both, and the daemon's `reconcileLocalWorkerSlots` re-provisions a durable claude slot that lacks either instead of skipping it as "already provisioned", so the slots provisioned before this converge on the next tick. Source: `cli/src/lib/harness/adapter.ts`, `cli/src/lib/harness/adapters/*.ts`, `cli/src/lib/exec.ts`, `cli/src/lib/installations/shims.ts`, `cli/src/lib/claude-account-token.ts`, `cli/src/lib/secrets-policy.ts`, `cli/docs/credential-management.md`.
 
 ## 1.22.92

package/dist/commands/browser.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import { spawnSync } from 'node:child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, formatProfilesTable, editProfile, renameProfile, assertRegistrableProfileName, isProfileLaunchableHere, isAttachOnlyProfile, resolveProfileDataDir, normalizeDataDir, persistDiscoveredArcProfile, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, formatProfilesTable, editProfile, renameProfile, assertRegistrableProfileName, isProfileLaunchableHere, isAttachOnlyProfile, resolveProfileDataDir, normalizeDataDir, persistDiscoveredProfile, } from '../lib/browser/profiles.js';
 import { declaringDevices, migrateCentralBrowserProfiles, profileKind } from '../lib/browser/registry.js';
 import { resolveActor } from '../lib/actor.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
@@ -442,7 +442,7 @@ export async function runBrowserUse(name, opts, interactive = isInteractiveTermi
             console.error(`Available profiles: ${all.map((profile) => profile.name).join(', ')}`);
         return false;
     }
-    await persistDiscoveredArcProfile(selectedName);
+    await persistDiscoveredProfile(selectedName);
     setConfigValue('browser.profile', selectedName);
     const endpoint = Object.values(getEndpointPresets(target))[0]?.target ?? '';
     console.log(`Default browser profile (this machine) is now "${selectedName}" (${target.browser}${endpoint ? `, ${endpoint}` : ''}).`);
@@ -503,7 +503,7 @@ function registerProfilesCommands(browser) {
             console.log(JSON.stringify(allProfiles.map((profile) => ({
                 ...profile,
                 devices: profile.devices,
-                kind: profile.arc ? 'identity' : profileKind(profile.name),
+                kind: profile.arc || profile.firefox ? 'identity' : profileKind(profile.name),
                 isConfiguredDefault: profile.name === configuredDefault,
             })), null, 2));
             return;
@@ -950,6 +950,11 @@ function registerProfilesCommands(browser) {
             console.log(`Arc Space: ${profile.arc.spaceTitle} (${profile.arc.spaceId})`);
             console.log(`Arc profile: ${profile.arc.profileName} (${profile.arc.profileId})`);
         }
+        if (profile.firefox) {
+            console.log(`Firefox profile: ${profile.firefox.profileName}${profile.firefox.isDefault ? ' (default)' : ''}`);
+            if (profile.userDataDir)
+                console.log(`Profile directory: ${profile.userDataDir}`);
+        }
         const presets = getEndpointPresets(profile);
         const defaultName = profile.defaultEndpoint && presets[profile.defaultEndpoint]
             ? profile.defaultEndpoint
@@ -975,7 +980,7 @@ function registerProfilesCommands(browser) {
             console.log(`Headless: true`);
         // Login state per known service: live session + account identity + whether
         // login creds are declared in the profile's secrets bundle.
-        if (profile.arc)
+        if (profile.arc || profile.firefox)
             return;
         const active = await loginsForProfile(profile.name);
         const accounts = await accountsForProfile(profile.name);
@@ -1119,11 +1124,17 @@ function registerProfilesCommands(browser) {
       profile that is in use, the configured default, or the \`auto-chrome\`
       profile a setup wizard created.
 
-      On a Mac with Arc, every Arc Space is listed as a profile (arc-personal,
+      On a Mac with Arc, every Arc Space is listed as a profile (arc-gmail,
       arc-work, ...) discovered read-only from Arc's own metadata — a Space
       already carries its Arc profile's logins, so it IS the browser profile.
       Agents attach to the running Arc through Apple Events and never launch or
-      relaunch it. Point agents at Comet instead when a workflow needs screenshots,
+      relaunch it. Comet's own profiles are listed the same way (comet-work, ...),
+      pinned to Comet's real user-data dir, so agents and you share one Comet
+      window per profile: agents attach when it is running with remote debugging,
+      launch it on your store when it is not running, and fail loud with the
+      relaunch command when it runs without a port. The daemon publishes every
+      discovered profile into this device's declaration, so other fleet boxes list
+      it with WHERE=<this device> and route to it. Point agents at Comet when a workflow needs screenshots,
       downloads, network capture, or trusted input:
         agents browser profiles create agents-comet --browser comet --attach-only
       A CDP \`--attach-only\` profile attaches to a browser you
@@ -1142,7 +1153,7 @@ function registerProfilesCommands(browser) {
             console.error(`Profile "${name}" not found`);
             process.exit(1);
         }
-        if (profile.arc && !isFleetRemoteInvocation()) {
+        if ((profile.arc || profile.firefox) && !isFleetRemoteInvocation()) {
             const routed = resolveBrowserTarget(profile.name);
             if (!routed.local && routed.commandDispatch) {
                 const result = await dispatchBrowserToDevice(routed.device, ['browser', 'profiles', 'doctor', name], 'capture');
@@ -1767,7 +1778,7 @@ function registerTaskCommands(browser) {
         // Discovery is read-only for list/show/doctor. Starting is the explicit
         // adoption point: persist only the agents-cli alias/native identity, never
         // mutate Arc's own profile or Space data.
-        await persistDiscoveredArcProfile(profileName);
+        await persistDiscoveredProfile(profileName);
         // A native endpoint is not CDP and cannot be tunnelled. Re-exec the
         // complete command on the declaring owner, then bind its returned task
         // locally so every later verb follows the same owner from task-index.
@@ -2224,15 +2235,17 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('tabs')
-        .description('List tabs open for the current task')
+        .description('List tabs open for the current task; --all shows every tab open in the profile browser, yours included')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
+        .option('--all', "Every tab open in the profile browser, not only this task's: OWNER names the owning task, or \"you\" for a tab no task owns")
         .option('--json', 'Output machine-readable JSON')
         .action(async (opts) => {
         const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'tab-list',
             task,
+            ...(opts.all ? { all: true } : {}),
         });
         if (!response.ok) {
             if (opts.json) {
@@ -2251,6 +2264,16 @@ function registerTaskCommands(browser) {
             console.log('No tabs open');
             return;
         }
+        if (opts.all) {
+            console.log('TAB'.padEnd(12) + 'OWNER'.padEnd(18) + 'URL');
+            console.log('-'.repeat(88));
+            for (const t of response.tabs) {
+                const owner = t.task ?? 'you';
+                const current = t.current ? ' *' : '';
+                console.log(t.id.slice(0, 11).padEnd(12) + owner.slice(0, 17).padEnd(18) + t.url.slice(0, 55) + current);
+            }
+            return;
+        }
         console.log('TAB'.padEnd(12) + 'URL');
         console.log('-'.repeat(70));
         for (const t of response.tabs) {

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

@@ -38,6 +38,23 @@ export interface LaunchResult {
     port: number;
     wsUrl: string;
 }
+/**
+ * The process that holds a Chromium user-data dir, read from the `SingletonLock`
+ * symlink Chromium keeps inside the dir on macOS and Linux (`<host>-<pid>`,
+ * PHNX-4042). A live pid means a browser already owns that store: a launch on it
+ * would only hand its arguments to the running instance and the requested debug
+ * port would never bind. Windows keeps no lock file, so this reports null there
+ * and `launchBrowser` catches the hand-off by the child's early exit instead.
+ */
+export declare function storeOccupant(userDataDir: string): {
+    pid: number;
+} | null;
+/**
+ * The relaunch that makes a browser holding `userDataDir` attachable: the
+ * ownership guard reads `--user-data-dir` off the running process, so the
+ * owner's normal launch (no flag) can never be verified.
+ */
+export declare function storeRelaunchCommand(browserType: BrowserType, port: number, userDataDir: string, profileDirectory?: string): string;
 /**
  * Resolve a browser-profile secrets bundle into an env map for the child, or an
  * EMPTY map when the bundle is absent, locked, or otherwise unreadable — never a

package/dist/lib/browser/chrome.js

@@ -24,6 +24,10 @@ const BROWSER_PATHS = {
         brave: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
         edge: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
         arc: ['/Applications/Arc.app/Contents/MacOS/Arc'],
+        firefox: [
+            '/Applications/Firefox.app/Contents/MacOS/firefox',
+            '/Applications/Firefox Developer Edition.app/Contents/MacOS/firefox',
+        ],
         custom: [],
     },
     linux: {
@@ -34,6 +38,10 @@ const BROWSER_PATHS = {
         edge: ['/usr/bin/microsoft-edge'],
         // Arc has no Linux build (macOS + Windows only).
         arc: [],
+        // `/usr/bin/firefox` on Ubuntu is the snap wrapper script: it execs the snap
+        // in place, so the pid survives and `--remote-debugging-port` works through
+        // it. The driver reads the real pid from the BiDi handshake anyway.
+        firefox: ['/usr/bin/firefox', '/snap/bin/firefox', '/usr/lib/firefox/firefox', '/opt/firefox/firefox'],
         custom: [],
     },
     win32: {
@@ -63,6 +71,11 @@ const BROWSER_PATHS = {
         // Arc ships a Windows build, but its install path is not yet verified here;
         // leave unlisted (undetected) rather than guess a path that false-positives.
         arc: [],
+        firefox: [
+            `${WIN_PROGRAMFILES}\\Mozilla Firefox\\firefox.exe`,
+            `${WIN_PROGRAMFILES_X86}\\Mozilla Firefox\\firefox.exe`,
+            `${WIN_LOCALAPPDATA}\\Mozilla Firefox\\firefox.exe`,
+        ],
         custom: [],
     },
 };
@@ -236,6 +249,43 @@ export function listInstalledBrowsers(platform = os.platform()) {
     }
     return found;
 }
+/**
+ * The process that holds a Chromium user-data dir, read from the `SingletonLock`
+ * symlink Chromium keeps inside the dir on macOS and Linux (`<host>-<pid>`,
+ * PHNX-4042). A live pid means a browser already owns that store: a launch on it
+ * would only hand its arguments to the running instance and the requested debug
+ * port would never bind. Windows keeps no lock file, so this reports null there
+ * and `launchBrowser` catches the hand-off by the child's early exit instead.
+ */
+export function storeOccupant(userDataDir) {
+    let target;
+    try {
+        target = fs.readlinkSync(path.join(userDataDir, 'SingletonLock'));
+    }
+    catch {
+        return null;
+    }
+    const pid = Number(/-(\d+)$/.exec(target)?.[1]);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        return error.code === 'EPERM' ? { pid } : null;
+    }
+    return { pid };
+}
+/**
+ * The relaunch that makes a browser holding `userDataDir` attachable: the
+ * ownership guard reads `--user-data-dir` off the running process, so the
+ * owner's normal launch (no flag) can never be verified.
+ */
+export function storeRelaunchCommand(browserType, port, userDataDir, profileDirectory) {
+    const app = browserType === 'comet' ? 'Comet' : browserType;
+    const profileFlag = profileDirectory ? ` --profile-directory=${profileDirectory}` : '';
+    return `open -a ${app} --args --remote-debugging-port=${port} --user-data-dir=${userDataDir}${profileFlag}`;
+}
 /**
  * Resolve a browser-profile secrets bundle into an env map for the child, or an
  * EMPTY map when the bundle is absent, locked, or otherwise unreadable — never a
@@ -265,14 +315,25 @@ export async function launchBrowser(profileName, browserType, port, options = {}
 // orphan reaper and `agents browser status` can label processes.
 isElectron = false) {
     const browserPath = findBrowserPath(browserType, customBinary);
+    // A profile discovered from the browser's OWN store (PHNX-4042) launches on
+    // that store — the owner's real user-data dir and profile directory — so the
+    // window agents open is the window the owner uses. Its Preferences are the
+    // owner's and are never rewritten. Anything else runs under a managed dir.
+    const ownerStore = options.userDataDir !== undefined;
     const runtimeDir = getProfileRuntimeDir(profileName);
-    const userDataDir = path.join(runtimeDir, 'chrome-data');
-    fs.mkdirSync(userDataDir, { recursive: true });
-    // Pre-launch Preferences pass: first-launch profile-name stamp, plus (for
-    // real browsers, not Electron apps) the session-cookie persistence pin.
-    // Electron apps manage their own storage and don't read Chromium's
-    // `session.*` prefs, so they get the name stamp only.
-    ensureProfilePreferences(userDataDir, profileName, !isElectron);
+    const userDataDir = options.userDataDir ?? path.join(runtimeDir, 'chrome-data');
+    if (!ownerStore) {
+        fs.mkdirSync(userDataDir, { recursive: true });
+        // Pre-launch Preferences pass: first-launch profile-name stamp, plus (for
+        // real browsers, not Electron apps) the session-cookie persistence pin.
+        // Electron apps manage their own storage and don't read Chromium's
+        // `session.*` prefs, so they get the name stamp only.
+        ensureProfilePreferences(userDataDir, profileName, !isElectron);
+    }
+    // The owner's store is attached over a TCP port rather than the daemon's
+    // private pipe: the instance outlives any one daemon and must stay reachable
+    // (and verifiable by the ownership guard) after a daemon restart.
+    const transport = ownerStore ? 'port' : 'pipe';
     // Chromium on macOS coordinates instances via the SingletonLock file
     // *inside* each user-data-dir. Direct binary spawn with a fresh
     // --user-data-dir creates a fully independent process — the user's
@@ -288,8 +349,9 @@ isElectron = false) {
     // profile never reaches this launcher (see connectLocal / isAttachOnlyProfile).
     const viewport = options.viewport ?? { width: 1512, height: 982 };
     const args = [
-        '--remote-debugging-pipe',
+        transport === 'pipe' ? '--remote-debugging-pipe' : `--remote-debugging-port=${port}`,
         `--user-data-dir=${userDataDir}`,
+        ...(options.profileDirectory ? [`--profile-directory=${options.profileDirectory}`] : []),
         '--disable-background-timer-throttling',
         '--disable-backgrounding-occluded-windows',
         '--disable-renderer-backgrounding',
@@ -311,7 +373,7 @@ isElectron = false) {
         // cookies survive, no ghost tabs — and the task flow creates its own tab
         // over CDP anyway. Electron apps need their window to appear (the CDP
         // driver binds to it), so they skip the flag.
-        ...(isElectron ? [] : ['--no-startup-window']),
+        ...(isElectron || ownerStore ? [] : ['--no-startup-window']),
         ...(options.headless ? ['--headless=new'] : []),
         `--window-size=${viewport.width},${viewport.height}`,
         ...(viewport.x !== undefined && viewport.y !== undefined
@@ -324,26 +386,69 @@ isElectron = false) {
     const env = { ...process.env, ...(await resolveProfileSecretsEnv(secrets)) };
     const child = spawn(browserPath, args, {
         detached: true,
-        stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
+        stdio: transport === 'pipe' ? ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
         env,
     });
     child.unref();
     child.stdout?.resume();
     child.stderr?.resume();
     const pid = child.pid;
-    const writePipe = child.stdio[3];
-    const readPipe = child.stdio[4];
-    if (!writePipe || !readPipe) {
-        throw new Error('Chrome failed to expose CDP pipe file descriptors');
+    let wsUrl;
+    if (transport === 'pipe') {
+        const writePipe = child.stdio[3];
+        const readPipe = child.stdio[4];
+        if (!writePipe || !readPipe) {
+            throw new Error('Chrome failed to expose CDP pipe file descriptors');
+        }
+        wsUrl = registerPipeTransport({ read: readPipe, write: writePipe });
+    }
+    else {
+        wsUrl = (await waitForDevToolsPort(port, profileName, child, { browserType, userDataDir, profileDirectory: options.profileDirectory })).wsUrl;
     }
-    const wsUrl = registerPipeTransport({ read: readPipe, write: writePipe });
     writeProfileRuntime(profileName, {
         pid,
         command: path.basename(browserPath),
         userDataDir,
         kind: isElectron ? 'electron' : 'browser',
     });
-    return { pid, port: 0, wsUrl };
+    return { pid, port: transport === 'pipe' ? 0 : port, wsUrl };
+}
+/**
+ * Poll the DevTools endpoint of a browser just launched with
+ * `--remote-debugging-port` until it answers, or fail loud naming the pid.
+ * Chromium binds the port only after its profile has loaded, which on a real
+ * signed-in store takes a few seconds. A child that exits first never bound
+ * it: on an owner's store that is the singleton hand-off to a browser already
+ * open there (PHNX-4042), so the failure names that instance's relaunch
+ * instead of waiting out the deadline.
+ */
+async function waitForDevToolsPort(port, profileName, child, store, timeoutMs = 20_000) {
+    const pid = child.pid;
+    let exited;
+    child.once('exit', (code, signal) => {
+        exited = code !== null ? `code ${code}` : `signal ${signal}`;
+    });
+    const deadline = Date.now() + timeoutMs;
+    let lastError = '';
+    while (Date.now() < deadline) {
+        if (exited) {
+            const app = store.browserType === 'comet' ? 'Comet' : store.browserType;
+            throw new Error(`${app} (pid ${pid}) exited (${exited}) before serving the DevTools protocol on port ${port} ` +
+                `for profile "${profileName}". A ${app} already open on ${store.userDataDir} takes a new launch ` +
+                `as an argument hand-off and never binds the port; quit it, then relaunch it with remote debugging:\n` +
+                `  ${storeRelaunchCommand(store.browserType, port, store.userDataDir, store.profileDirectory)}\n` +
+                `and retry. If none is open, the browser crashed on start.`);
+        }
+        try {
+            return await discoverBrowserWsUrl(port, 'localhost', profileName);
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    throw new Error(`Browser for profile "${profileName}" (pid ${pid}) did not serve the DevTools protocol on ` +
+        `port ${port} within ${Math.round(timeoutMs / 1000)}s: ${lastError}`);
 }
 export async function attachToChrome(port) {
     const { wsUrl } = await discoverBrowserWsUrl(port);

package/dist/lib/browser/chromium-discovery.d.ts

@@ -0,0 +1,27 @@
+import type { BrowserType } from './types.js';
+export interface ChromiumNativeProfile {
+    browser: BrowserType;
+    /** The agents-cli profile name: `<browser>-<display-name-slug>`. */
+    name: string;
+    /** The browser's user-data dir (its own, never a cache dir). */
+    userDataDir: string;
+    /** Profile directory basename inside the user-data dir. Authoritative id. */
+    profileDirectory: string;
+    /** Display-only name from Local State. */
+    displayName: string;
+}
+export type ChromiumDiscoveryResult = {
+    ok: true;
+    profiles: ChromiumNativeProfile[];
+    userDataDir: string;
+} | {
+    ok: false;
+    kind: 'unsupported' | 'not-installed' | 'invalid';
+    reason: string;
+};
+/** The browser's own user-data dir on this platform, or undefined where it does not ship. */
+export declare function chromiumUserDataDir(browser: BrowserType): string | undefined;
+export declare function discoverChromiumProfilesAt(browser: BrowserType, userDataDir: string): ChromiumDiscoveryResult;
+export declare function discoverChromiumProfiles(browser: BrowserType): ChromiumDiscoveryResult;
+/** Every browser whose native profiles agents-cli discovers on this platform. */
+export declare function discoverableChromiumBrowsers(): BrowserType[];

package/dist/lib/browser/chromium-discovery.js

@@ -0,0 +1,96 @@
+/**
+ * Read-only discovery of a Chromium-family browser's OWN profiles (PHNX-4042).
+ *
+ * Chromium keeps its profiles under one user-data dir: `Local State` lists them
+ * in `profile.info_cache` keyed by directory (`Default`, `Profile 1`, ...) with
+ * the display name the user sees in the profile menu. Each entry becomes one
+ * agents-cli profile (`comet-work`, ...) pinned to that dir and directory, so
+ * the owner and agents share ONE window per profile instead of agents spawning
+ * a rival instance under a cache dir. Nothing here writes to the browser's
+ * files.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Browsers whose native profiles are discovered, and the env var that points tests at another user-data dir. */
+const NATIVE_CHROMIUM = {
+    comet: { dirName: 'Comet', envOverride: 'AGENTS_COMET_DIR' },
+};
+/** The browser's own user-data dir on this platform, or undefined where it does not ship. */
+export function chromiumUserDataDir(browser) {
+    const entry = NATIVE_CHROMIUM[browser];
+    if (!entry)
+        return undefined;
+    const override = process.env[entry.envOverride];
+    if (override)
+        return path.resolve(override);
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', entry.dirName);
+    }
+    if (process.platform === 'win32') {
+        const local = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+        return path.join(local, entry.dirName, 'User Data');
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+export function discoverChromiumProfilesAt(browser, userDataDir) {
+    const localState = path.join(userDataDir, 'Local State');
+    if (!fs.existsSync(localState)) {
+        return { ok: false, kind: 'not-installed', reason: `${browser} Local State not found: ${localState}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(localState, 'utf8'));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            kind: 'invalid',
+            reason: error instanceof SyntaxError
+                ? `${browser} Local State is not valid JSON`
+                : `Cannot read ${browser} Local State: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.profile) || !isRecord(parsed.profile.info_cache)) {
+        return { ok: false, kind: 'invalid', reason: `${browser} Local State has no profile.info_cache map` };
+    }
+    const rows = [];
+    for (const [profileDirectory, value] of Object.entries(parsed.profile.info_cache)) {
+        if (!isRecord(value) || typeof value.name !== 'string' || value.name.trim() === '') {
+            return { ok: false, kind: 'invalid', reason: `${browser} Local State profile ${JSON.stringify(profileDirectory)} has no non-empty name` };
+        }
+        rows.push({
+            browser,
+            name: `${browser}-${slugify(value.name) || 'profile'}`,
+            userDataDir,
+            profileDirectory,
+            displayName: value.name,
+        });
+    }
+    // Two profiles with the same display name stay distinct by their directory.
+    const counts = new Map();
+    for (const row of rows)
+        counts.set(row.name, (counts.get(row.name) ?? 0) + 1);
+    return {
+        ok: true,
+        userDataDir,
+        profiles: rows.map((row) => (counts.get(row.name) ?? 0) > 1 ? { ...row, name: `${row.name}-${slugify(row.profileDirectory)}` } : row),
+    };
+}
+export function discoverChromiumProfiles(browser) {
+    const userDataDir = chromiumUserDataDir(browser);
+    if (!userDataDir) {
+        return { ok: false, kind: 'unsupported', reason: `${browser} profiles are not discovered on this platform` };
+    }
+    return discoverChromiumProfilesAt(browser, userDataDir);
+}
+/** Every browser whose native profiles agents-cli discovers on this platform. */
+export function discoverableChromiumBrowsers() {
+    return Object.keys(NATIVE_CHROMIUM).filter((browser) => chromiumUserDataDir(browser) !== undefined);
+}

package/dist/lib/browser/drivers/firefox.d.ts

@@ -0,0 +1,103 @@
+import type { BrowserProfile, ConnectionKey } from '../types.js';
+/** How agents obtain a live Firefox — matches the CDP driver's launch/attach split. */
+export interface FirefoxConnection {
+    bidi: FirefoxBiDiClient;
+    port: number;
+    /** The Firefox process pid we launched, or 0 when we attached to a running one. */
+    pid: number;
+    /** The BiDi session id from `session.new`. */
+    sessionId: string;
+}
+/**
+ * A verb Firefox-over-BiDi cannot serve (network capture, upload, pdf, trusted
+ * key input, …). Mirrors `ArcNativeCapabilityError`: the service throws it in
+ * the one place the capability is missing, and the message steers the caller to
+ * a Chromium-family profile that has it.
+ */
+export declare class FirefoxCapabilityError extends Error {
+    readonly capability: string;
+    constructor(capability: string, message?: string);
+}
+/** A BiDi error frame carrying the protocol error + human message. */
+export declare class FirefoxBiDiError extends Error {
+    readonly bidiError: string;
+    constructor(bidiError: string, message: string);
+}
+/**
+ * Minimal WebDriver BiDi client: request/response keyed by the `id` field, with
+ * events drained and ignored. Deliberately shaped like `CDPClient` so the
+ * service treats a Firefox connection the same way it treats a CDP one. The
+ * large `maxPayload` matches CDPClient's, so a base64 screenshot of a
+ * content-rich page never trips the socket's decompressed-size cap.
+ */
+export declare class FirefoxBiDiClient {
+    private ws;
+    private nextId;
+    private pending;
+    private closed;
+    get isOpen(): boolean;
+    connect(url: string): Promise<void>;
+    private handleMessage;
+    private handleClose;
+    send<T = Record<string, unknown>>(method: string, params?: Record<string, unknown>): Promise<T>;
+    close(): void;
+}
+/**
+ * The loud error raised when a Firefox already holds this profile but exposes no
+ * BiDi port, so agents cannot attach and must not launch a rival (Firefox is
+ * single-instance per profile dir). Mirrors `attachOnlyRequiredError` in
+ * `drivers/local.ts`: name the exact relaunch that makes the running instance
+ * attachable. Exported so the contract is unit-testable without a real Firefox.
+ */
+export declare function firefoxAttachRequiredError(profile: Pick<BrowserProfile, 'name'> & {
+    firefox?: {
+        profileName: string;
+    };
+}, port: number, profileDir: string): Error;
+/**
+ * Connect a Firefox profile over BiDi: attach if the port is already served,
+ * otherwise launch Firefox and wait for it. Fails loud when a Firefox holds the
+ * profile without a port.
+ */
+export declare function connectFirefox(profile: BrowserProfile, key: ConnectionKey, port: number, opts?: {
+    profileDir: string;
+    headless?: boolean;
+}): Promise<FirefoxConnection>;
+export declare function deserializeBidi(remote: unknown): unknown;
+/** One top-level browsing context (a tab), flattened from `browsingContext.getTree`. */
+export interface BiDiContext {
+    context: string;
+    url: string;
+}
+/** Every top-level tab currently open in this Firefox. */
+export declare function bidiTopLevelContexts(bidi: FirefoxBiDiClient): Promise<BiDiContext[]>;
+/** Open a fresh tab and return its context id. */
+export declare function bidiCreateTab(bidi: FirefoxBiDiClient): Promise<string>;
+/** Navigate a context and wait for the document to finish loading. */
+export declare function bidiNavigate(bidi: FirefoxBiDiClient, context: string, url: string): Promise<void>;
+/** Reload a context in place, waiting for load. */
+export declare function bidiReload(bidi: FirefoxBiDiClient, context: string): Promise<void>;
+/** Close a tab. */
+export declare function bidiCloseTab(bidi: FirefoxBiDiClient, context: string): Promise<void>;
+/** Bring a tab to the foreground (explicit focus only). */
+export declare function bidiActivate(bidi: FirefoxBiDiClient, context: string): Promise<void>;
+/**
+ * Evaluate an expression in a context and return the deserialized value.
+ * `awaitPromise` mirrors the CDP evaluate contract; a thrown/rejected value
+ * surfaces as an Error rather than a silent undefined.
+ */
+export declare function bidiEvaluate(bidi: FirefoxBiDiClient, context: string, expression: string): Promise<unknown>;
+/** Capture a screenshot of the viewport as raw bytes. `quality` is 0–1 for JPEG. */
+export declare function bidiScreenshot(bidi: FirefoxBiDiClient, context: string, format: {
+    type: 'image/png';
+} | {
+    type: 'image/jpeg';
+    quality: number;
+}): Promise<Buffer>;
+/**
+ * A real, trusted left click at viewport coordinates via `input.performActions`
+ * — the pointer path CDP `Input.dispatchMouseEvent` gives Chromium, which Arc
+ * (Apple Events) never had. The service resolves a ref to (x, y) first, exactly
+ * as the CDP click path does.
+ */
+export declare function bidiClickAt(bidi: FirefoxBiDiClient, context: string, x: number, y: number): Promise<void>;