@amalgm/browser 0.1.2-preview.35541635545 → 0.1.2-preview.37254096068

package/docs/ARCHITECTURE.md

@@ -1,71 +1,67 @@
 # Architecture
 
-`BrowserProductService` is the product boundary. It composes session and
-profile policy, encrypted cookie coordination, auth bundles, login handoffs,
-and recording lifecycles. Drivers operate physical browsers. Transport
-adapters translate their inputs into this service and do not own browser
-policy.
+`BrowserProductService` is the product boundary. It holds session policy, the
+account, auth bundles, login handoffs, recordings, and the account's cookie
+jar. The driver operates the runtime's one Chrome. Transport adapters turn
+their inputs into service calls and own no browser policy.
 
-## Derivation
+## Flow of one action
 
-The purpose requires one meaning for every browser action across desktop and
-server environments. Therefore:
+1. An adapter picks the session (an explicit `session`, else the caller's
+   `callerId`, else `default`) and calls `createSession`, which creates it or,
+   after a restart, reopens it.
+2. `BrowserService.execute` checks the session is ready and idle, authorizes
+   the action, and takes the session lease.
+3. The driver runs the action through the session's agent-browser daemon, or
+   over CDP for capture and some input, and then syncs cookies.
+4. The service stores the result and emits a sanitized event.
 
-1. A typed action enters `BrowserService`.
-2. The service authorizes it, checks session state and capabilities, and
-   acquires the session lease.
-3. The session's immutable backend selects exactly one driver.
-4. The driver acts on the session's exact page or verified visible surface.
-5. The service persists the transition and emits a sanitized event.
-
-CLI, MCP, REST, and Toolbox all dispatch through the same canonical action
-descriptor array. The generated reachability test calls all 22 actions through
-all five surfaces.
+CLI, MCP, REST, and Toolbox dispatch through one action descriptor array. The
+parity test calls all 22 actions through all five surfaces.
 
 ## Ownership map
 
-- `service.ts`, `product-service.ts` — mutation boundary and product services
-- `sessions/`, `profiles/` — leases and lifecycle policy
-- `drivers/headless/` — `agent-browser`, CDP, profiles, and physical cookies
-- `drivers/electron/` — verified visible driver and host advertisement
-- `drivers/electron/native/` — `WebContentsView` shell, surfaces, policy,
-  downloads, permissions, menus, and native ad blocking
-- `drivers/cdp/` — exact-target capture, input, and cancellable protocol client
-- `cookies/` — encrypted logical authority and adapter reconciliation
-- `auth/` — explicit bundles and TTL-bound human login
-- `recording/` — page screencast, latest-frame sampler, and bounded encoder
-- `persistence/`, `migration/` — SQLite state and idempotent legacy import
-- `adapters/` — CLI, MCP, REST/SSE, and Toolbox projections
+- `service.ts`, `product-service.ts`, `account.ts`: the mutation boundary,
+  product services, and the one browsing identity
+- `sessions/`: leases and pruning
+- `chrome/`: finding, launching, owning, and restarting Chrome; the per-session
+  CDP relay; the Chrome cookie adapter
+- `driver/`: the agent-browser driver, command runner, waits, action evidence,
+  and live-view stream
+- `cdp/`: page capture, screencast, input, and a cancellable protocol client
+- `cookies/`: the encrypted jar, cookie policy, and the coordinator that syncs
+  each browser with the jar
+- `electron/`: the Electron shell (native tabs, policy, downloads,
+  permissions, context menus, ad blocking) and a cookie adapter for its
+  partition
+- `auth/`: named bundles and TTL-bound human login
+- `recording/`: screencast sampling and the bounded WebM encoder
+- `persistence/`, `migration/`: SQLite state and the one-time legacy import
+- `adapters/`: CLI, MCP, REST with SSE and the live-view WebSocket, and Toolbox
 
-## Runtime selection
+## One Chrome, many sessions
 
-Selection happens once before open. A forced backend or explicit CDP endpoint
-wins. A fresh, compatible, loopback Electron host advertisement selects
-Electron only for a desktop owner. Everything else selects headless. A visible
-session never falls back to headless after identity loss.
+A runtime has one `ChromeHost`. Each session reaches it through its own relay
+endpoint, which shows the session only its own tabs and places new tabs in the
+account's browser context. All sessions therefore share one set of cookies.
+See [Chrome runtime](./CHROME.md).
 
 ## Persistence and concurrency
 
-SQLite stores each metadata entity independently, uses WAL and a busy timeout,
-and holds cross-process session leases. Encrypted cookie/auth payloads use
-atomic private files because their security and integrity envelope is a better
-fit than ordinary database rows. Registry and migration writes are
-transactional. A restarted service reopens a persisted ready session through
-its assigned driver before acting.
-
-## Visible surfaces
-
-The Electron host creates native `WebContentsView` pages in the isolated
-Browser partition. Protocol-6 identity combines a session stamp, surface ID,
-marker URL, and declared target type. The driver verifies that identity before
-every action. It may reattach once only when the original surface is genuinely
-gone; ambiguity or mismatch fails before page input.
+SQLite stores each metadata entity separately, uses WAL and a busy timeout,
+and holds cross-process session leases. Encrypted cookie, login, and auth
+payloads live in atomic private files. Registry and migration writes are
+transactional. Sessions are durable: after a restart, a ready session reopens
+when `createSession` names it again. Chrome itself has one owning process per
+root, enforced by the OS-held `<root>/chrome.lease.sqlite` lease.
+`browser.close()` stops admission, cancels and drains admitted work, then stops
+recordings, detaches every session, stops Chrome, and closes the registry.
 
 ## Data movement
 
-Physical Chromium stores remain isolated. Cookie adapters exchange normalized
-records with the encrypted logical jar, never with each other. Deletion is a
-tombstone and timestamp/source ordering makes merges deterministic. Named auth
-bundles are explicit filtered snapshots and can additionally contain supported
-origin storage. Events and ordinary resource projections contain metadata
-only.
+The account's encrypted jar is the store of record for cookies. The
+coordinator keeps each registered browser store in two-way sync with it; the
+runtime registers Chrome's account context. Deletions are tombstones, and
+ordering by timestamp then source makes merges deterministic. Named auth
+bundles are explicit filtered snapshots and can also carry origin storage.
+Events and ordinary resource projections contain metadata only.

package/docs/AUTHENTICATION.md

@@ -1,56 +1,61 @@
 # Authentication and login handoff
 
-Browser separates working profiles, automatic cookies, named auth bundles,
-and human login sessions. None is an alias for another.
+Browser keeps three things apart: the account's automatic cookies (see
+[cookies](./COOKIES.md)), named auth bundles, and human login sessions.
 
 ## Named auth bundles
 
-`browser.auth.save` asks the assigned driver for state, filters it to explicit
-domains, encrypts the payload, and stores only metadata in SQLite. Supported
-payloads can include cookies, localStorage, and sessionStorage. List/get return
-ID, name, profile, domains, storage kinds, and timestamps—never values.
+`browser.auth.save` takes the session's state through agent-browser
+`state save`, filters it to explicit domains (or the page's domain), encrypts
+the payload under `auth-bundles/`, and stores only metadata in SQLite. A
+payload can hold cookies, localStorage, and sessionStorage. List and get
+return ID, name, account (`profileId`), domains, storage kinds, and
+timestamps, never values.
 
-Loading is explicit and requires a capable session. Deleting removes both the
-encrypted payload and metadata. A bundle's profile reference protects that
-profile from pruning.
+`browser.auth.load` writes a bundle into a session through `state load`. All
+sessions share the account's browser context, so loaded cookies are visible to
+every session at once and reach the cookie jar at the next sync. Deleting
+removes both the encrypted payload and the metadata.
 
-Portable export/import re-encrypts a bundle with an explicitly authorized
-32-byte portable key and verifies metadata integrity on import. The portable
-resource is still ciphertext and should be handled as a credential.
+Portable export and import re-encrypt a bundle with an explicitly authorized
+32-byte portable key and verify metadata integrity on import. The portable
+resource is still ciphertext; handle it as a credential.
 
 ## Human login
 
-`browser.login.create` returns a session plus one random token and a
-token-bearing handoff URL. The credential is delivered only in that creation
-result. Browser stores a SHA-256 hash and compares verification values in
-constant time. Ordinary list/get never returns the token.
+`browser.login.create` returns a login session, one random token, and a
+handoff URL (`/browser-auth/<id>?token=<token>`). The token appears only in
+that result. Browser stores its SHA-256 hash and compares in constant time;
+list and get never return it.
 
-TTL defaults to 15 minutes and is clamped from one minute to one hour. A handoff
-uses a durable profile while pending or active:
+TTL defaults to 15 minutes and is clamped to between one minute and one hour.
 
-1. Create the handoff for a target URL and filtered domains.
-2. Activate it after validating the token; Browser opens the owned profile.
-3. Forward browser-scoped CUA screenshot/input while the human signs in.
-4. Complete to save an encrypted named bundle and close the live session, or
-   cancel to close it without saving.
+1. Create the handoff for a target URL and its domains.
+2. Activate it with the token. Browser opens browser session `login-<id>` on
+   the target URL.
+3. Forward screenshots and input (`input` takes a `cua` operation) while the
+   human signs in.
+4. Complete to save a named bundle and close the session, or cancel to close
+   it without saving.
 
-Expired active sessions are closed. Completed, cancelled, and expired tokens
-cannot be reused.
+An expired active login's session is closed. Completed, cancelled, and expired
+tokens cannot be reused. Each change publishes `login.updated`.
+Transitions for one handoff are serialized. Repeating activation returns the
+same active page without restarting navigation or interrupting the person's
+input; cancellation and completion cannot be undone by an earlier activation.
 
-## Transports
+## Presentation
 
-- `electron-surface` presents the verified page in the desktop app.
-- `novnc` uses `AMALGM_BROWSER_NOVNC_PUBLIC_URL` or
-  `AMALGM_BROWSER_NOVNC_URL` when configured.
-- `external` provides a host-integrated handoff.
-
-Transport selection is presentation; the auth lifecycle and profile ownership
-remain Browser rules.
+Every login uses its runtime session's ordinary live view in the canonical
+browser component, including on Electron. New metadata uses `external` and
+`ready`. Legacy `transport` and `liveUrl` inputs remain accepted for tool and
+SDK compatibility, but do not select another browser or transport. Historical
+metadata remains readable; there is no VNC implementation or configuration.
 
 ## Security boundary
 
 Device-local AES-GCM encryption protects against accidental plaintext
-exposure, not an attacker who can read both encrypted files and the local key.
-Treat token-bearing handoff URLs, portable resources, captures, and origin
+exposure, not against an attacker who can read both the encrypted files and
+the local key. Treat handoff URLs, portable resources, captures, and origin
 storage as credentials. They must not enter logs, events, chat history, or
-ordinary resource projections.
+ordinary resource output.

package/docs/AXIOMS.md

@@ -1,19 +1,21 @@
 # Axiom map
 
-[PURPOSE.md](../PURPOSE.md) is the authoritative list of primitives and 19
-product axioms. This document maps them to observable boundaries.
+[PURPOSE.md](../PURPOSE.md) is the authoritative list of primitives and 21
+numbered product axioms. This map ties them to the tests that show them.
 
 | Axioms | Consequence | Evidence |
 | --- | --- | --- |
-| 1–3 | Browser owns state; sessions bind one profile and immutable backend | service and restart contracts |
-| 4–5 | Electron identity is verified; ordinary fallback is headless | identity and advertisement tests |
-| 6–8 | Capabilities are honest; work is cancellable and bounded | driver, CDP, process, and parity tests |
-| 9–13 | Cookie stores are isolated and secrets remain encrypted | cookie, auth, partition, and migration tests |
-| 14 | Capture and recording address the actual page | DPR, target, sampler, and real-runtime tests |
-| 15 | Context enters through ports; events are sanitized | artifact and SSE contracts |
-| 16 | Existing state is imported safely | transactional legacy fixture test |
-| 17–18 | One TypeScript implementation works without Shell, Engine, or Electron | package install and adapter parity tests |
-| 19 | Shell composes one Browser service; Electron is a host adapter | Shell composition and Electron harness tests |
+| 1–3 | Browser owns state; every session browses as the one account | `service.test.ts` account tests |
+| 4 | One owned Chrome, restarted on next use | `real-browser.test.ts` crash recovery and competing-owner tests |
+| 5–6 | Sessions see only their own tabs, reopen after restarts, and stream only themselves | real-browser side-by-side and live-view tests; real-lifecycle CDP and CLI isolation; `service.test.ts` restart reopen |
+| 7–9 | Page identity, cancellation, and bounded output | real-browser duplicate-URL capture; real-lifecycle operation drain; `service`, `process` and `parity` tests |
+| 10–14 | Cookies sync through the encrypted jar without idle scans; secrets stay out of output | `cookies`, `cookie-coordinator`, `cookie-notifications`, `auth`, `adapters` tests; real-browser idle and loopback tests |
+| 15 | Recording proves capture and stays bounded | `recording.test.ts`; real-lifecycle records and decodes page imagery |
+| 16 | Context enters through ports; events are sanitized | `events.test.ts`, `adapters.test.ts` |
+| 17 | Existing state is imported safely | `persistence.test.ts` legacy upgrade |
+| 18–19 | One TypeScript implementation works without Shell, Engine, or Electron | `parity.test.ts`, `surfaces.test.ts`, `verify:pack` |
+| 20 | Shell composes one service; Electron keeps each account in its own partition | `electron-cookies`, `electron-policy` tests; UI's `test:browser` drives real Electron cookie sharing and sign-out through Shell |
+| 21 | agent-browser IPC fits the socket limit | source only (`driver/command.ts`) |
 
 When behavior fails, classify it against this map. If code drifted, restore the
 axiom everywhere it applies. If the axiom is incomplete, update

package/docs/CHROME.md

@@ -0,0 +1,143 @@
+# Chrome runtime
+
+Each runtime runs one headless Chrome. Every session drives its own tabs in
+that Chrome, and every tab browses as the runtime's account. `ChromeHost`
+(`src/chrome/`) owns the Chrome process. `AgentBrowserDriver` (`src/driver/`)
+runs each session's actions through its own agent-browser daemon.
+
+## Finding Chrome
+
+Browser uses the first match:
+
+1. `AMALGM_BROWSER_EXECUTABLE_PATH` (or `AGENT_BROWSER_EXECUTABLE_PATH`). If
+   the path does not exist, launch fails.
+2. An installed Google Chrome, Chrome Canary, Chromium, or Brave in the
+   platform's usual install locations.
+3. Chrome for Testing downloaded by `npx agent-browser install` into
+   `~/.agent-browser/browsers`, newest first.
+
+If nothing is found, the first action fails with `PROCESS_FAILED` and a hint
+to install Chrome.
+
+## Launch
+
+Chrome starts on the first action, not when the service is created. It runs
+`--headless=new` with remote debugging on a random loopback port and its user
+data in `<root>/chrome`. It presents a desktop user agent built from the
+installed Chrome's version and turns off the `AutomationControlled` blink
+feature, so sign-in pages see an ordinary desktop Chrome. Sync, first-run,
+translate, and component-update behavior are off, and the window is 1280×800.
+On Linux, `--no-sandbox` is added only when running as root.
+
+Chrome's native debugging-listening event admits the process, within a
+20-second deadline. Browser attaches its private cookie extension to the
+account's default profile and reconciles it with the encrypted jar
+(see [cookies](./COOKIES.md)). The extension uses one session on the existing
+control connection, independently of the number of pages. Chrome reports a
+worker's context before it runs the worker script, so Browser's bindings can
+arrive before or after that script. Both sides ask to start delivery, and
+whichever comes second starts it; the worker then announces that it is
+observing. Chrome stops an idle extension worker and restarts it for the next
+cookie change; the new worker announces itself again, and that second
+announcement brings one snapshot to cover the stop. Chrome keeps its
+normal platform credential storage; Browser does not request the basic password
+store or mock keychain.
+
+## One owner per root
+
+Only one process may run a root's Chrome. An exclusive SQLite transaction in
+`<root>/chrome.lease.sqlite` holds an OS lease for the process lifetime; another
+owner gets `CONFLICT`. The file is never removed. After a dead owner releases
+the lease, Browser retires its exact Chrome through the random browser endpoint
+in that profile's `DevToolsActivePort`, then starts the replacement. No PID or
+command-line match can authorize killing a process.
+
+## Restart on next use
+
+If Chrome exits, Browser logs a warning and forgets it. The next action starts
+a new Chrome and loads the account's cookies into it. Tabs that were open are
+gone. An action caught by the crash can fail; retry it and it runs in the new
+Chrome.
+
+## Sessions and the relay
+
+Each session is one agent-browser daemon attached with `--cdp` to the session's
+own relay endpoint, `ws://127.0.0.1:<port>/session/<id>`. The relay gives that
+connection a filtered view of the shared Chrome:
+
+- it lists and controls only the session's own tabs;
+- every tab it opens is placed in a new window in the account's browser context;
+- browser-wide methods (`Browser.close`, `Browser.crash`,
+  `Target.createBrowserContext`, `Target.disposeBrowserContext`,
+  `Target.attachToBrowserTarget`, `Target.setAutoAttach`) are refused.
+
+The first time a process uses a session, Browser closes any daemon left by an
+earlier process, then attaches a new one, which opens the session's first tab.
+Closing a session detaches its daemon and closes its tabs in Chrome.
+
+agent-browser's IPC sockets live in a private per-user directory under `/tmp`
+(the OS temporary directory on Windows). Each daemon's name is a digest of the
+real Browser root and the session ID, so long roots and IDs fit the socket
+path limit.
+The daemon uses Browser's own empty configuration and explicit launch inputs;
+ambient agent-browser profiles, sessions and providers cannot alter this
+identity. Page-operation argv travels through the CLI's JSON batch input,
+separate from its global flag parser.
+
+## Capture and input
+
+Snapshots give stable `@eN` references for ordinary DOM actions. Screenshots,
+the `cua` double click, and recording connect straight to the session's page
+over CDP. The relay records the selected target's identity; repeated URLs do
+not make different tabs interchangeable. Without an owned selected target,
+the operation fails with `SURFACE_IDENTITY_FAILED`.
+
+Viewport screenshots are in CSS pixels at any device pixel ratio, and
+full-page capture is capped at 8192×16384. Computer use supports screenshot,
+click, double click, move, scroll, type, keypress, and drag. Use it for canvas,
+WebGL, image-only, or hostile custom controls; prefer snapshot references
+elsewhere.
+
+## Live view
+
+`browser.streamUrl(sessionId)` returns agent-browser's stream for that session,
+`ws://127.0.0.1:<port>`, and turns the stream on if needed. The stream sends
+`status`, `tabs`, and `frame` messages and accepts `input_mouse`,
+`input_keyboard`, and `input_touch`. It shows and drives only that session's
+tabs. Viewers outside the process use the REST route
+`/v1/sessions/<id>/stream` (see [REST](./REST.md)), which also reports the
+selected page's actual Back/Forward availability. Editor shortcuts carry CDP
+editor commands, so they behave consistently in a streamed headless page.
+Navigation observation follows selected-tab and page events; an idle viewer
+does not poll history, and closing it releases its observation connection.
+
+## Shutdown
+
+`browser.close()` stops admission, cancels and drains in-flight operations,
+then stops recordings, detaches every daemon, drains queued cookie changes,
+stops Chrome (SIGTERM, then SIGKILL after 3 seconds), and closes the
+registry. Chrome is also killed if the Node process exits.
+
+## Configuration
+
+- `AMALGM_BROWSER_EXECUTABLE_PATH`: the Chrome executable
+- `AMALGM_AGENT_BROWSER_BIN`: the agent-browser executable. Without it,
+  Browser uses the platform binary shipped with the `agent-browser` package
+  (from `app.asar.unpacked` in packaged Electron apps), then the package's
+  JavaScript wrapper, then `agent-browser` on `PATH`.
+- `AMALGM_FFMPEG`: the ffmpeg executable for recording
+
+## Real verification
+
+`npm run test:real` drives real Chrome and agent-browser against a real site. It
+checks that chats browse side by side as one account, that a viewer can watch
+and drive one chat's live view only with the runtime token, that sign-ins
+survive restarts and follow sign-outs, that a chat keeps browsing after Chrome
+is killed, and that loopback cookies never enter the account. It also measures
+zero cookie scans and history reads while idle, including with a live viewer,
+and verifies background cookie writes and tab-switch history updates. The busy
+page examination starts with 1000 cookies and requires 60 edits to cause zero
+full-store scans, exactly 60 encrypted row writes, and under 120 KB of encoded
+state. Observer reload, worker restart, HttpOnly and partitioned events are exercised in real
+Chrome. Timing/CPU observations describe this local workload, not a universal
+website latency guarantee.

package/docs/CLI.md

@@ -1,51 +1,87 @@
 # CLI
 
-`amalgm-browser` prints stable JSON to stdout and sanitized diagnostics to
-stderr. It never constructs a shell command.
+`amalgm-browser` prints JSON to stdout and sanitized diagnostics to stderr. It
+never constructs a shell command.
+
+## One-shot commands
+
+Each action or resource command is one process. It starts the runtime's
+Chrome, runs, and stops Chrome before exiting. The session record and the
+account's cookies carry over to the next command; the open page does not. A
+follow-up command in the same session starts on a new blank tab.
+
+For multi-step browsing, keep one process running:
+
+- `amalgm-browser mcp` for an MCP client
+- `amalgm-browser serve` for REST
+
+Only one process can run a root's Chrome at a time. While `mcp` or `serve` is
+running, a one-shot command on the same root that needs Chrome fails with
+`CONFLICT`.
 
 ## Actions
 
 ```text
 open <url>                     snapshot
-screenshot [--full-page]      click <target>
-fill <target> <text>           press <key>
-select <target> <value>        eval <script>
-wait [--selector|--url|--ms]   dialog|tab|console|cua --input <json>
-close                          action <name> --input <json>
+screenshot [--full-page]       click <target>
+fill <target> <text> [--submit]
+press <key>                    select <target> <value>
+eval <script>                  wait [--selector css|--url value|--ms n]
+cli <agent-browser args...>    close
+dialog|tab|console|cua --input <json>
+action <name> --input <json>
 ```
 
-Use one `--session` value across related invocations. The generic `action`
-form reaches every canonical action, including recording and auth actions.
+The generic `action` form reaches all 22 actions, including recording and
+auth actions.
+
+Advanced `cli` argv runs page operations in the current session. Browser owns
+process, connection, account, recording and authentication lifecycle; raw CLI
+management commands cannot replace those owners. Operation argv is sent as
+JSON data, so literal text resembling launch flags stays page text.
 
 ## Resources
 
 ```text
-sessions list|get|close|cancel|prune [id]
-profiles list|get|create|update|delete|prune [id]
-auth list|link|save|load|delete [id]
-recordings start|stop|cancel|list|get [id]
-capabilities
+sessions list|get|close|cancel|prune [id] [--max-age-ms n]
+auth list
+auth link --url <url> [--domains a,b] [--ttl-ms n] [--transport t] [--live-url u]
+auth save [name] [--domains a,b]
+auth load <bundleId>
+auth delete <bundleId>
+recordings start [--name n] [--fps n] [--duration-ms n]
+recordings stop|cancel|list|get [id]
 doctor
-serve
+serve [--port 0] [--host 127.0.0.1] [--token t] [--allow-remote]
 mcp
 ```
 
-Common options are `--session`, `--profile`, `--root`, `--cwd`, `--timeout`,
-`--headless`, `--headed`, and `--cdp`. `--cwd` supplies opaque cwd context and
-a local artifact destination; it does not create a Browser workspace model.
+`recordings start` records until `--duration-ms` passes or the process gets
+SIGINT or SIGTERM. In a one-shot command the recorded page is a new blank tab,
+so record through MCP, REST, or the SDK.
 
-`--headed` is an explicit debug choice. Ordinary standalone and background use
-stays headless. `--cdp` attaches to an operator-provided endpoint.
+## Global options
 
-## REST and MCP modes
-
-```sh
-amalgm-browser mcp
-amalgm-browser serve --token "$AMALGM_BROWSER_TOKEN" --port 8787
+```text
+--session <id>  --root <path>  --cwd <project>  --json  --timeout <ms>
 ```
 
-`serve` binds `127.0.0.1` unless `--host` is supplied. A non-loopback host also
-requires `--allow-remote`; bearer authentication remains mandatory.
+- `--session` names the session; the default is `default`.
+- `--root` sets the state root.
+- `--cwd` supplies opaque cwd context and a local artifact destination. It
+  does not create a Browser workspace model.
+- `--json` is accepted; output is always JSON.
+- `--timeout` aborts the command after that many milliseconds and is passed
+  to actions that take `timeoutMs`.
+
+## serve
+
+`serve` binds `127.0.0.1` on a random port unless `--host` or `--port` is
+given, and prints the address to stderr. The bearer token comes from
+`--token` or `AMALGM_BROWSER_TOKEN`. A non-loopback host also requires
+`--allow-remote`. Set `AMALGM_BROWSER_ADAPTER_TOKEN` to enable the internal
+cookie routes. `mcp` and `serve` run until SIGINT or SIGTERM (`mcp` also stops
+when stdin ends), then stop Chrome.
 
 ## Exit codes
 
@@ -55,7 +91,3 @@ requires `--allow-remote`; bearer authentication remains mandatory.
 - `4` resource not found
 - `5` timeout or cancellation
 - `1` other typed failure
-
-Use `--timeout <ms>` to abort a blocking operation. Recording start without a
-duration remains active until SIGINT or SIGTERM, then stops and flushes within
-the encoder deadline.

package/docs/COMPATIBILITY.md

@@ -6,11 +6,13 @@
 - modules: ESM core imports; ESM and generated CommonJS for
   `@amalgm/browser/electron`
 - Electron: optional peer, version 33 or newer
-- Electron surface protocols: writes protocol 6; reads protocols 5 and 6
-- Browser partition: exactly `persist:amalgm-browser`
+- browser: an installed Chrome, Chrome Canary, Chromium, or Brave, or Chrome
+  for Testing (see [Chrome runtime](./CHROME.md))
+- Electron browser partition: `persist:amalgm-browser-<SHA-256 account ID>`;
+  application authentication stays in Electron's default partition
 
-Core and headless imports do not load Electron. The Electron native code is
-available only from `@amalgm/browser/electron`.
+Core imports do not load Electron. The Electron code is available only from
+`@amalgm/browser/electron`.
 
 ## Action identities
 
@@ -22,25 +24,14 @@ Historical aggregate Browser grants, older prefixed IDs, and individual
 `cua_*` names are normalized in the Toolbox compatibility adapter. They are
 not core action aliases and never create doubled Browser prefixes.
 
-## Historical Engine routes and data
+## Legacy data
 
-During a bounded historical cutover, Engine routes may delegate into this SDK.
-They must not remain as a parallel production implementation. Raw cookie
-bootstrap and merge use the restricted adapter transport, not public OpenAPI.
+The versioned importer brings in legacy Engine auth bundles, the saved
+cookie-source bundle with its tombstones, and login sessions, all under the
+runtime's account (see [migration](./MIGRATION.md)).
 
-Legacy Engine profiles, encrypted auth/cookie-source bundles, cookie
-tombstones, and login sessions are supported by the versioned importer. Paths
-and the Electron partition are reused to avoid forced sign-in.
+## agent-browser output
 
-## Backend differences
-
-Capabilities make differences explicit. Electron advertises visible-surface,
-live-login, and ad-blocking behavior. Headless advertises full-page capture and
-does not claim native Electron ad blocking. Unsupported operations return
-`CAPABILITY_UNSUPPORTED`; adapters must not synthesize a substitute.
-
-## Agent-browser envelopes
-
-The headless adapter accepts supported historical JSON result envelopes and
-normalizes them at its boundary. The SDK result union is stable and does not
-expose agent-browser's transport format.
+The driver accepts agent-browser's JSON result envelopes and unwraps them at
+its boundary. The SDK result union is stable and does not expose
+agent-browser's output format.