browser-broker 0.1.0

package/.env.example

@@ -0,0 +1,173 @@
+# Browser Broker — the configuration registry.
+#
+# This file is DOCUMENTATION. Nothing loads it, and no code path reads a file
+# for configuration: configuration is the process environment, full stop.
+# Copy a line into your own environment if you want to change a value.
+#
+# Every variable has a working default, so a fresh install runs with NOTHING
+# set. A variable that is set and cannot be read as its type refuses the spawn
+# and names the variable — falling back to the default silently would run a
+# configuration nobody chose, with nothing to notice it by.
+#
+# The values below are PLACEHOLDERS showing the shape, never real paths.
+#
+# This file lists the variables the store needs before it can open. The rest
+# of the registry lands with the row that owns it, along with the test that
+# walks the declared variables and asserts this file lists every one.
+
+# Where the database file lives.
+# Default: a directory of the service's own under the per-user application-data
+#          location the platform defines — which differs per operating system
+#          and is computed, never written down.
+# Refused at startup if it resolves to a network location: the write-ahead log
+# coordinates through a shared-memory index that requires every process using
+# the database to be on one host, and a mapped network drive is indistinguishable
+# from a local one by its path alone.
+# BROKER_DB=/path/to/broker.db
+
+# Where captures, snapshots and crops are written.
+# Default: as above, in a directory of the service's own.
+# BROKER_ARTIFACTS_ROOT=/path/to/artefacts
+
+# Where the browser profiles live. Each browser launches against this plus its
+# own name, explicitly and mandatorily — never a default profile location.
+# Default: as above, in a directory of the service's own.
+# BROKER_PROFILE_ROOT=/path/to/profiles
+
+# ── The comparison feature's five numbers ────────────────────────────────
+#
+# A diff is an optional argument on a capture: the caller names which earlier
+# capture to compare against, and with no such argument there is no diff and
+# these are never read. Three of the five are copied onto every comparison
+# record, because all three are mutable and all three decided the output — so
+# what an earlier call did, under the numbers in force at the time, stays
+# answerable after any of them moves.
+
+# How different two pixels must be before either counts as changed, from 0 to 1;
+# smaller is more sensitive.
+# Default: 0.1 — the comparison library's own default, which is a better
+#          starting position than a number invented here precisely because it is
+#          not one.
+# Worth knowing before tuning: at this default a change fainter than roughly
+# grey 225 on white is not reported at all.
+# BROKER_DIFF_COLOUR_TOLERANCE=0.1
+
+# The smallest region reported, in SQUARE PIXELS OF AREA.
+# Default: 64
+# Area, with a thin-line allowance — never the shorter side. A filter on the
+# shorter side discards a one-pixel line across a wide page, which is a border,
+# an underline, a focus ring or a rule: the changes most worth catching.
+# BROKER_DIFF_MINIMUM_REGION_AREA=64
+
+# How many regions come back before the result is truncated, smallest first.
+# The result says when it was truncated; a shortened list that did not say so
+# would be a lie about completeness.
+# Default: 12
+# BROKER_DIFF_MAXIMUM_REGIONS=12
+
+# How far apart two changed areas stay separate regions, in pixels.
+# Default: 8
+# BROKER_DIFF_REGION_MERGE_DISTANCE=8
+
+# Context around a crop, in pixels. A tight box with nothing around it can be
+# genuinely unidentifiable.
+# Default: 16
+# BROKER_DIFF_CROP_PADDING=16
+
+# The total tab budget across ALL browsers, and — since a lease is a tab —
+# the same number as the maximum count of live leases. No per-browser cap: the
+# scarce thing is page processes and one costs the same in any browser. The
+# keeper tab in each browser is not counted.
+# Provisional: reasoned from roughly 50-150 MB per idle page process plus two
+#              browser processes, so fifteen is one to two gigabytes.
+# THIS IS THE ONE VALUE ALSO WRITTEN TO THE STORE. Several processes arbitrate
+# against it at the same moment, so the first process to open the store records
+# the value it believes and every later process compares. On a disagreement the
+# later process refuses to start and names both numbers — neither value is
+# adopted and neither is overwritten.
+# Default: 15
+# BROKER_TAB_BUDGET=15
+
+# How long an active lease lives without a call, in seconds.
+# Deliberately NOT given the agreement check the budget gets: two processes
+# disagreeing here expires something early or late, which is degraded behaviour
+# rather than a broken invariant.
+# Default: 600 (ten minutes)
+# BROKER_LEASE_SECONDS=600
+
+# How long a place in the queue lives without a call, in seconds.
+# Deliberately EQUAL to the lease lifetime above. Polling is renewing, so a
+# queued caller holds exactly the instrument an active holder does; and under
+# strict first-in-first-out a queue place held longer blocks everyone behind it,
+# so a generous queued lifetime is the harsher setting rather than the kinder one.
+# Default: 600 (ten minutes)
+# BROKER_QUEUE_SECONDS=600
+
+# How long a launch-race loser waits for the winner's browser to accept a
+# connection before declaring the launch failed, in seconds.
+# The loser polls the winner's discovery record — the same liveness-and-identity
+# check every attach uses — rather than sleeping for this whole duration; this is
+# only the bound on how long that poll runs before giving up.
+# Default: 30
+# BROKER_LAUNCH_READINESS_TIMEOUT_SECONDS=30
+
+# ── The browsers, and what they are called ─────────────────────────
+#
+# Two lists split by kind, rather than one list with a per-entry flag. Which
+# list a name is written in IS its kind, so there is nothing for a name and
+# its kind to disagree about, and nothing needs encoding.
+#
+# A name is what a caller claims by, the name of that browser's profile
+# directory, and its key in the store. Lower-case letters, digits and hyphens,
+# starting with a letter.
+#
+# Each of these refuses the spawn and NAMES THE OFFENDING ENTRY: a duplicate
+# within one list, the same name in both lists, more names than the cap, or a
+# name that is not a usable word.
+#
+# ⚠ READ THIS BEFORE SETTING ALL SIX. The tab budget above does not bound
+# what these cost, because it counts TABS and each browser is a process
+# BEFORE it holds a single tab. So BROKER_TAB_BUDGET=15 with six browsers is
+# six browser processes, plus up to fifteen tabs, plus six keeper tabs that
+# are not counted against the budget at all — six processes and up to
+# twenty-one pages. Reasoned from roughly 50-150 MB per idle page process,
+# that is meaningfully more than the same budget across two browsers, and the
+# budget will not tell you: it is doing its job, and its job is tabs.
+
+# The persistent, signed-in browsers, comma-separated, at most 3.
+# THE FIRST ENTRY IS WHAT AN UNSTATED `browser` RESOLVES TO on browser_claim.
+# Each holds a sign-in a person put there by hand, and each is a separate
+# identity — which is the reason for more than one: tabs within a single
+# browser share its cookie jar, so two identities at once means two browsers.
+# Default: regular
+# BROKER_REGULAR_BROWSERS=regular
+
+# The ephemeral, signed-in-to-nothing browsers, comma-separated, at most 3.
+# Capped separately rather than sharing a total with the list above, because
+# the two kinds are not interchangeable: one shared total could be spent
+# entirely on signed-in browsers, leaving no clean-room browser at all, and
+# clean-room is the one that cannot be substituted for.
+# Default: private
+# BROKER_PRIVATE_BROWSERS=private
+
+# Both caps are refusals, not truncations: naming a fourth browser in either
+# list stops the service at startup and says which variable was wrong, rather
+# than quietly running the first three. `broker doctor` reports on every
+# browser named in both lists above, so a browser added here gains its own
+# discovery and keeper-tab lines in the health report.
+
+# Which browser binary the signed-in browsers launch.
+# Options: chrome, brave, msedge — all Chromium over the same remote-debugging
+#          protocol, which is why the choice is a path rather than a driver.
+# One engine per kind, never per browser: an engine per entry would put an
+# attribute back on the entry, which is what the two lists exist to avoid.
+# Default: msedge
+# BROKER_REGULAR_BROWSER_ENGINE=msedge
+
+# Which browser binary the clean-room browsers launch. MAY DIFFER from the
+# engine above: a person signs into the signed-in browsers by hand, so which
+# binary those are can follow what they already use, while nobody signs into
+# a clean-room browser at all.
+# Options: chrome, brave, msedge
+# Default: msedge
+# BROKER_PRIVATE_BROWSER_ENGINE=msedge

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zaida-3dO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,374 @@
+# Browser Broker
+
+**Several agents, two browsers, no collisions.**
+
+Browser Broker brokers access to a small, fixed set of real browsers. A caller asks for a lease; it
+gets back a secret key and **one tab** it exclusively owns. Every later call carries that key, and the
+service uses it to route the call, to enforce what that caller may touch, and to account for what it
+costs. There is nothing running in the background: the service is started by its caller and exits
+with it, and the browsers outlive any one of them.
+
+## What it gives you
+
+- **A hard ceiling on browser processes.** Concurrency is expressed in tabs inside a fixed set of
+  browsers, so process count is bounded by configuration rather than by how many clients connect. A
+  lease is exactly one tab, so the budget, the pool bound and the number of live leases are one
+  integer that cannot disagree with itself. Need two tabs, claim twice.
+- **Leases, with a queue.** When capacity is full a caller is queued rather than refused, and told
+  its position and when to check back.
+- **Reclamation from callers that die.** Every key carries a time to live that any call renews, so a
+  client that vanishes mid-work returns its capacity on its own. This is the failure a client-side
+  convention cannot cover, because the client that should clean up is the one that is gone. Nothing
+  expires on a timer: every arbitration call first expires whatever has lapsed across the whole
+  store, then answers from the reconciled state.
+- **A shared signed-in profile that no single caller can destroy.** Nothing browser-scoped is
+  exposed. A caller can close its own tab; it cannot close a browser, and no operation reaches a
+  browser outside the ones the service is configured to run.
+- **References, not payloads.** Screenshots and page snapshots are written to disk and returned as a
+  path with its dimensions and size. An agent opens one only when it genuinely needs to look, so a
+  capture is paid for once instead of on every subsequent turn.
+- **A capture policy applied by the thing that takes the capture.** Screenshots come back at a low
+  resolution unless you ask for more, and asking for the most expensive tier costs a stated reason in
+  free text. Nothing is ever refused — going over budget warns loudly and names the cheaper way to
+  get the same answer.
+- **Changed-region review.** A capture can name an earlier capture to compare against, and the
+  regions that actually moved come back as crops — so a repeat review looks at what changed instead
+  of at everything. There is no canonical picture to bless first: a capture is a capture with an
+  identifier, and the caller says which one it means. If that image is missing, the full screenshot
+  comes back with an explanation rather than a refusal.
+- **Nothing to configure before it runs.** Every value is an environment variable with a working
+  default, so a fresh install runs with nothing set, and `.env.example` documents the whole set. The
+  one value several processes must agree on — the tab budget — is written into the store by the first
+  process to open it, and a later process whose environment disagrees refuses to start and names both
+  numbers.
+
+## Surfaces
+
+The rules live in one service layer, and every surface is a thin adapter over it: **twelve tools**,
+served by the caller's own spawned process, and a `broker` command line that runs the same logic in
+the process you typed it in. A shared conformance suite asserts that the same operation and the same
+refusal happen on both.
+
+**Nothing is served over a socket.** The operations view is a self-contained HTML file that a command
+generates and a person opens from disk — a snapshot, labelled with the moment it was taken, which does
+not refresh. It is generated from inside a live session, so it reads each tab's address from the
+browser itself; a browser that does not answer within a timeout renders as unreachable rather than
+hanging the report.
+
+## Install
+
+**Installation is the whole of deployment.** There is no image to pull, no daemon to register and no
+service to keep running: the process is started by whatever calls it and exits with it. So getting it
+working is an install and one more fetch below — there is no step after that.
+
+You need **Node 22.18 or newer**.
+
+### From the registry
+
+The package ships compiled JavaScript, so nothing is built on your machine:
+
+```bash
+npx browser-broker doctor
+```
+
+A client that spawns the tool surface names the same package, and npm revalidates the version on
+every run — so a published release arrives without anything being pulled or rebuilt by hand:
+
+```json
+{
+  "mcpServers": {
+    "browser-broker": { "command": "npx", "args": ["-y", "browser-broker"] }
+  }
+}
+```
+
+Weigh that against spawning a checkout directly: `npx` costs a registry round-trip on every spawn,
+which is several seconds against a fraction of one for a path on disk. A machine that develops this
+service is better off pointing at its own tree; a machine that only *uses* it is better off here.
+
+### From a checkout
+
+For working on the service itself. The sources are TypeScript and run through the runtime's own type
+stripping, so there is no build step in the development path:
+
+```bash
+git clone https://github.com/Zaida-3dO/browser-broker.git
+cd browser-broker
+npm install
+```
+
+That compiles the one runtime dependency's native binding, which is *not* the only part of the install
+that does real work: this repository depends on `playwright-core`, not the full `playwright`
+distribution, precisely because the browser binary is spawned by this service, detached and by path,
+rather than downloaded and managed by the package. `playwright-core` does not fetch a browser on
+install, so a checkout that has never had one fetched by some other tooling has none, and `broker
+doctor`'s automation check will genuinely fail with exit code 11 until you run:
+
+```bash
+npx playwright-core install chromium
+```
+
+Run this once per machine, before the first `broker doctor`. It is the same install mechanism the
+full `playwright` package would run automatically on `npm install`; `playwright-core` just does not
+run it for you. Then run the broker itself:
+
+```bash
+node src/bin/broker.ts
+```
+
+The first run creates the store, brings its schema up to the version the build expects, prints where
+the file is, and exits:
+
+```
+store: <the resolved store location>
+schema: stepped from version 0 to version 1 (1 step(s) applied)
+```
+
+Run it again and it says the schema is already where it should be. **Every spawn does this**, not
+just the first — with no long-lived process, there is no other moment at which it could happen, and a
+caller that has upgraded and one that has not may both start within the same minute.
+
+To get the command on your path as `broker`, link the package from the checkout:
+
+```bash
+npm link          # then: broker --help
+```
+
+### Configuring it
+
+**Nothing needs setting.** Every value is an environment variable with a working default, so the
+install above runs as-is; [`.env.example`](.env.example) documents the whole set, with placeholders
+rather than real values. Nothing reads that file — configuration is the process environment.
+
+The default store location is a directory of the service's own under the per-user application-data
+location your platform defines. It is computed rather than written down anywhere, because writing one
+down would name one machine. To put it somewhere else, set `BROKER_DB`:
+
+```bash
+BROKER_DB=/some/writable/path/broker.db node src/bin/broker.ts
+```
+
+**The browsers are configuration too.** Two lists, at most three names each, defaulting to one of
+each — `regular` and `private`. A name is what a caller claims by and what its profile directory is
+called, and a caller that names no browser gets the first signed-in one:
+
+```bash
+BROKER_REGULAR_BROWSERS=regular,checkout      # persistent, signed in, at most 3
+BROKER_PRIVATE_BROWSERS=private               # ephemeral, at most 3
+BROKER_REGULAR_BROWSER_ENGINE=msedge          # chrome | brave | msedge
+BROKER_PRIVATE_BROWSER_ENGINE=msedge          # may differ from the line above
+```
+
+Two signed-in browsers is how two identities are exercised at once: tabs within one browser share
+its cookie jar, so they are isolated from other browsers and not from each other. **Note that each
+browser is a process before it holds a single tab**, which the tab budget does not count —
+`.env.example` gives the arithmetic beside the variables.
+
+A variable that is set but cannot be read as its type **refuses the spawn and names the variable**,
+rather than quietly falling back to the default — a configuration nobody chose is worse than a
+refusal nobody missed. For a list, the refusal names the offending **entry**: a duplicate within one
+list, a name in both lists, more names than the cap, or a name that is not a usable word. A store location that resolves to a network share is refused for the same
+reason it has to be: the write-ahead log coordinates through shared memory that requires every
+process using the file to sit on one host.
+
+### Pointing a client at the tools
+
+The twelve tools are served over standard input and output by `src/bin/broker-tool.ts`, which speaks
+[the Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18) — revision
+`2025-06-18`, with `2025-03-26` accepted for a client that asks for it. A client spawns that file,
+opens with `initialize`, and the twelve tools are listed to it.
+
+Most clients read a JSON file naming the servers they may spawn. The block is the same shape in all
+of them; put it in whichever file yours reads — commonly `.mcp.json` in a project, or the client's
+own configuration:
+
+```json
+{
+  "mcpServers": {
+    "browser-broker": {
+      "command": "node",
+      "args": ["/absolute/path/to/browser-broker/src/bin/broker-tool.ts"]
+    }
+  }
+}
+```
+
+**The path has to be absolute**, because the client chooses the working directory it spawns from and
+it is rarely the checkout. Nothing else is required: there is no port to configure, no token to
+issue, and no process to have started first — the client starts it, and it exits when the client
+closes the pipe.
+
+To point it at a store other than the default, add the environment to the same block:
+
+```json
+{
+  "mcpServers": {
+    "browser-broker": {
+      "command": "node",
+      "args": ["/absolute/path/to/browser-broker/src/bin/broker-tool.ts"],
+      "env": { "BROKER_DB": "/some/writable/path/broker.db" }
+    }
+  }
+}
+```
+
+Every client sharing a store sees the same leases, which is the point of the store being a file: the
+capacity being arbitrated is one set of browsers, and two clients that could not see each other's
+claims would both think the whole of it was free.
+
+**To check the wiring without a client**, speak the handshake by hand. This writes three messages and
+reads two back — the notification is the one that draws no reply:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | node src/bin/broker-tool.ts
+```
+
+The first response carries the negotiated `protocolVersion`, the server's `capabilities` and its
+`serverInfo`; the second message is a notification and is deliberately not answered; the third lists
+the twelve tools. A client that gets that far will work.
+
+## First run
+
+There is **one step a person performs by hand**, and it happens once: signing the shared browser in.
+Everything else — creating the profiles, starting browsers, adopting them, keeping them alive — the
+service does for itself. This is the whole of it, from a clean clone:
+
+```bash
+git clone https://github.com/Zaida-3dO/browser-broker.git
+cd browser-broker
+npm install
+
+node src/bin/broker.ts init     # create the store and both browser profiles
+node src/bin/broker.ts login    # open a browser and sign in, by hand
+node src/bin/broker.ts doctor   # confirm the sign-in took
+```
+
+**`broker init`** creates the store, steps its schema, and establishes a profile directory for each
+browser. It reports each one as `created` or `found`, which is the distinction worth reading: a
+profile reported as `created` on a machine where you expected a sign-in is the earliest possible
+warning that you are about to be asked to sign in again. It never recreates or clears a profile that
+is already there.
+
+**`broker login`** opens the shared browser, headed, against that profile and hands it to you:
+
+```
+A browser window is open for you to sign in.
+
+  1. Switch to the browser window that just opened. It is the regular browser,
+     running against the profile at regular under the configured
+     profile root — which is the profile every caller will share.
+  2. Go to whichever site you want this service to be signed in to, and sign in
+     normally. This is a real browser and a real sign-in: what you type goes to
+     that site exactly as it would in your own browser.
+  3. Close the window when you are done. Closing it is what ends this step.
+```
+
+Sign in to whatever you want the service to have access to, then **close the window** — that is what
+ends the step. While it is open the browser is not serving callers: anything that asks for it is told
+a person is signing in and to try again shortly, and anything already waiting in the queue keeps its
+place and its timer. A sign-in is a pause, not a cancellation.
+
+Two things it will refuse, both on purpose:
+
+- **A browser with live work on it.** If a caller holds a tab there, signing in would mean driving the
+  window by hand underneath somebody's work. It names the leases holding it; waiting is enough,
+  because every lease expires on its own if its holder stops calling in.
+- **The private browser.** Its profile is discarded when it exits, so a sign-in there would appear to
+  work and leave you signed into nothing.
+
+**Nothing records what you type.** The sign-in is written into the browser's own profile directory by
+the browser itself. This service never sees a credential and stores nothing about one anywhere —
+which is also why there is no way to copy a sign-in between machines: the profile *is* the identity.
+
+**`broker doctor`** then tells you whether it took, without opening a browser:
+
+```
+[ok  ] The regular browser’s profile carries a sign-in
+         The profile holds 1 stored cookie(s), so a session was established and written down.
+```
+
+Before you have signed in, the same line reads:
+
+```
+[--  ] The regular browser’s profile carries a sign-in
+         The profile has a cookie store and it holds no cookies. That is what a profile nobody has
+         signed into looks like — though a site that keeps its session only in local storage would
+         look the same, so this is the absence of evidence rather than evidence of absence.
+```
+
+**It never reports this as a failure**, and it will say `unknown` rather than guess. A profile with no
+session is the ordinary state of every installation until somebody signs in, and a check that went red
+on a working machine is one people learn to ignore. It also cannot see everything: it reads the
+browser's stored cookies, so a site that keeps its session somewhere else is invisible to it, and a
+browser that is still running has not necessarily written its cookies down yet — in that case it says
+so and tells you to close the browser and ask again.
+
+### Checking an install
+
+```bash
+npm run check:install
+```
+
+This spawns the executable as a real process against a temporary store, and asserts it creates the
+file, steps the schema to the version the build expects, answers a command and **exits**. It is what
+continuous integration runs on a clean hosted runner, and it is the check that stands in for the one
+an image build would have given: proof that the thing actually starts.
+
+Run everything the pipeline runs with `npm run check`.
+
+### Recovering from leaked browsers, on Windows
+
+<!-- external-ref-ok-next-line: this repository's own first-party PowerShell tool, named for the reader who needs to find it -->
+The emergency sweep in `scripts/reap-broker-browsers.ps1` reports leaked broker browsers by default
+and does not touch them; pass `-Execute` to terminate what it found, and add `-PruneDirs
+-OlderThanHours <n>` to also clear stale profile directories older than that many hours. Not part of
+the pipeline: a browser this project launches is spawned `detached: true` by design (see the header
+of `src/browser/launch.ts`) so it survives the process that started it, and every known way that
+leak could happen has since been fixed at its source — see the script's own header for the list.
+Keep it installed anyway as insurance against whatever the next one turns out to be, and as the tool
+to run if a machine is already in the frozen state a leak like this can cause. Matches processes by
+profile-directory command line, never by image name, so it cannot touch an unrelated Chrome window
+or this repository's own Playwright MCP tooling; see the script's own SAFETY section.
+
+## Status
+
+Under construction — the store, the executable and the pipeline are in place, the arbitration
+surface is being built, and the one manual step is wired: `broker login` hands a person the shared
+browser and `broker doctor` reports whether the sign-in took. Read [`docs/ROLLOUT.md`](docs/ROLLOUT.md) for taking it from installed to sole route in an order that
+never leaves traffic unarbitrated, [`docs/plans/PLAN.md`](docs/plans/PLAN.md) for how it works,
+[`docs/plans/DECISIONS.md`](docs/plans/DECISIONS.md) for why it is shaped this way, and
+[`docs/plans/MILESTONES.md`](docs/plans/MILESTONES.md) for the work queue, and
+[`RELEASES.md`](RELEASES.md) for what changes between versions — in particular for defaults that
+move, which change an installation that has taken no action.
+
+## Releasing
+
+The development path runs the TypeScript sources directly; the published package cannot, because
+**Node refuses to strip types from any file under a `node_modules` path** and an installed package is
+exactly that. No flag overrides it. So a release compiles to `dist/` and the manifest's `bin` entries
+name the emitted JavaScript.
+
+`prepack` runs the build, so `npm publish` and `npm pack` compile on their own — there is no way to
+publish a stale `dist/`, and no build step to remember.
+
+```bash
+npm version patch      # or minor / major — writes the tag and the commit
+npm publish            # prepack builds, then the tarball goes up
+git push --follow-tags
+```
+
+`npm run check:package` asserts what a published tarball owes: every `bin` target is emitted
+JavaScript rather than a TypeScript source, the whole built tree is included, and the tarball carries
+no tests or plans. It runs in CI. Worth knowing if you touch the `files` field: **npm ships `bin`
+targets whatever `files` says**, so a tarball can contain both executables and none of the modules
+they import — which installs cleanly and dies on first run. That is the case the check exists for.
+
+## Licence
+
+**MIT** — see [`LICENSE`](LICENSE), and `docs/plans/DECISIONS.md` §13e for the reasoning. A public
+repository without a licence file grants no rights to anyone, so the decision alone was never enough;
+the file carries it and `package.json` declares it.

package/RELEASES.md

@@ -0,0 +1,97 @@
+# Release notes
+
+**What changes between versions, and specifically what changes *behaviour* on an installation that
+sets nothing.**
+
+That second half is the reason this file exists rather than the commit log being enough. A new
+setting with a neutral default is not news: an installation that does not set it behaves exactly as
+before. **A changed default is news**, because it moves an installation that has taken no action and
+made no decision. `docs/plans/DECISIONS.md` §6.3 puts a changed default here rather than in a quiet
+edit for that reason.
+
+Entries are newest first. Each names what moved, what an installation has to do about it, and what
+happens if it does nothing.
+
+---
+
+## Unreleased
+
+### The package is published, and it ships compiled JavaScript
+
+**What moved.** The service is installable from the registry as `browser-broker`, so a caller can
+spawn it without a checkout. The manifest's `bin` entries now name emitted JavaScript under `dist/`
+rather than the TypeScript sources.
+
+**Why the build exists**, given that the development path deliberately has none: **Node refuses to
+strip types from any file under a `node_modules` path**, and an installed package is a directory
+under `node_modules`. A manifest whose `bin` named a `.ts` file would install cleanly and then fail
+on the machine of whoever installed it. There is no flag that changes this. The compiler therefore
+runs once per release rather than on every machine that consumes the package, and `erasableSyntaxOnly`
+stays on so the sources still run unbuilt — the two paths execute the same dialect.
+
+**What an installation has to do.** Nothing. A checkout is unaffected: `node src/bin/broker.ts` still
+runs the sources with no build. An installation that would rather not track a checkout can point at
+the package instead, and npm revalidates the version on every spawn:
+
+```json
+{ "command": "npx", "args": ["-y", "browser-broker"] }
+```
+
+**Worth weighing before switching:** `npx` performs a registry round-trip on every spawn, costing
+seconds where a path on disk costs a fraction of one. It buys an upgrade path, not speed.
+
+**One surface changes what it reports.** The tool handshake's `serverInfo.version` was the literal
+`0.0.0` while the package was unversioned, and now reads the manifest — so a client logging it sees
+the released version rather than a placeholder.
+
+
+### ⚠ Behaviour change: the default browser engine is Edge
+
+**What moved.** A browser launched by this service uses **`msedge`** by default. The previous
+behaviour was to launch whatever `chromium.executablePath()` resolved to — the Chromium build the
+automation library had fetched.
+
+**Why.** Edge is present on every Windows machine, so a fresh install runs with nothing set, with no
+separate browser download step. That is `DECISIONS.md` §6.1's *"a fresh install runs with nothing
+set"* applied to the one prerequisite `npm install` genuinely could not cover.
+
+**What an installation has to do.** Nothing, if Edge is acceptable. To keep the prior behaviour, or
+to pick a different browser, set the engine per kind:
+
+```bash
+BROKER_REGULAR_BROWSER_ENGINE=chrome     # chrome | brave | msedge
+BROKER_PRIVATE_BROWSER_ENGINE=chrome     # may differ from the line above
+```
+
+**If it does nothing:** browsers launch under Edge. **Profiles are per browser and are not shared
+between engines**, so an installation whose signed-in profile was established under a different
+binary will find that browser signed out, and a person will be asked to sign in once more with
+`broker login`. Nothing is destroyed — `setup.profile_never_destroyed` still holds, and the earlier
+profile directory is left exactly where it is.
+
+### Browsers are a configured list, and `browser` on a claim is optional
+
+**What moved.** Two things, both reversals of recorded decisions — the argument for each is in
+`DECISIONS.md` §13i:
+
+- **The fixed pair of browsers becomes a bounded list per kind**, at most three each, named in
+  configuration. A name is what a caller claims by and what its profile directory is called.
+- **`browser` on `browser_claim` becomes optional.** Unstated resolves to the first signed-in
+  browser; `regular` or `private` resolves to the first of that kind; a configured name resolves to
+  that browser exactly.
+
+**What an installation has to do.** Nothing. The defaults name one browser of each kind, `regular`
+and `private`, which is the pair that existed before — so an installation that sets nothing has the
+same two browsers under the same two names, and a caller that states `browser` explicitly is
+unaffected.
+
+**Worth reading before configuring more than the default two:** the tab budget counts *tabs*, and
+each browser costs a process **before it holds a single tab**. `BROKER_TAB_BUDGET=15` with six
+browsers is six browser processes, plus up to fifteen tabs, plus six keeper tabs that are not
+counted against the budget at all. `.env.example` states this beside the variables.
+
+**One schema step.** The store gains a `kind` column on `browsers` and drops the check constraint
+that limited a browser's name to two literals. It is applied on the next spawn, like every step, and
+the two existing rows are backfilled to their own kinds. **A store stepped by this build is not
+readable by an earlier one**, which is the ordinary direction — a build refuses a store newer than
+itself rather than downgrading it.