Sessions

One handle, one page, one browser behind it — owned or borrowed. The handle answers which, and close behaves accordingly. When in doubt: will close kill my browser? Owned yes, borrowed never.

Owned by default

open <url> launches a Chromium the engine owns: headless, a throwaway profile, a free loopback port (scanned 9333–9432 — no free port means close something first). The launch floor is Chromium 152.

agent-webmcp open https://example.com# {"handle":"s_…","url":"…","toolCount":0,#  "reapplied":[],"skipped":[]}agent-webmcp open --headed https://example.com# visible window — needs a display (Xvfb or CI drops it)

toolCount is point-in-time: pages expose tools as they load, so 0 means list again, not give up. Records live under the OS temp sessions dir and are stale-safe — a dead browser surfaces as a transport failure on the next verb, never as a corrupt store.

Borrowing a tab

--cdp attaches a tab of a foreign browser instead of launching. The tab gets navigated to your URL — the stated cost of borrowing; the tab is driven from then on, so re-list after anyone else touches it.

agent-webmcp open --cdp http://127.0.0.1:9222 https://example.com# borrows the first page tab (targetId match or URL# substring via target, else the first page tab found)

Borrows record ownBrowser: false and never touch the foreign process: no signals, no profile removal, no shutdown. On close they get best-effort tool cleanup and keep living. Two sessions sharing one tab never double-register — re-apply skips tools the page already ships.

Close discipline

agent-webmcp close <handle> --yes   # {closed:[handle]}agent-webmcp close --all --yes      # {closed[], failed[]}

Close kills only owned browsers: TERM, wait, then KILL, with the throwaway profile removed on every path. Every kill verifies the pid's command line carries the engine's profile marker first — foreign pids are unsignallable by construction. --all never aborts on one dead browser; failures land in failed[] with per-handle reasons. Close what you open; the box collects strays from killed harnesses, so reap by executable identity when timeouts persist.