browser-broker 0.1.0 → 0.3.1

package/.env.example

@@ -155,19 +155,3 @@
 # 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/README.md

@@ -61,23 +61,33 @@ hanging the report.
 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**.
+You need **Node 22.18 or newer**. Either path below also needs a browser binary, which is a separate
+fetch from either install step — see [Browser binary](#browser-binary) once you've picked a path.
 
 ### From the registry
 
-The package ships compiled JavaScript, so nothing is built on your machine:
+The package ships compiled JavaScript, so **nothing is compiled** on your machine. That is not the
+same as nothing to set up: a browser binary is still owed, and this path does not fetch it — see
+[Browser binary](#browser-binary) below before your first `broker doctor`.
 
 ```bash
-npx browser-broker doctor
+npx -p browser-broker broker doctor
 ```
 
+The package installs two executables — `broker`, the command line, and `broker-tool`, the surface a
+client spawns — and neither is named for the package, so `npx browser-broker` cannot tell which you
+meant and refuses. `-p` names the package and the word after it names the executable.
+
 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"] }
+    "browser-broker": {
+      "command": "npx",
+      "args": ["-y", "-p", "browser-broker", "broker-tool"]
+    }
   }
 }
 ```
@@ -97,20 +107,8 @@ 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:
+That compiles the one runtime dependency's native binding. It does not fetch a browser binary — see
+[Browser binary](#browser-binary) below before your first `broker doctor`. Then run the broker itself:
 
 ```bash
 node src/bin/broker.ts
@@ -134,6 +132,23 @@ To get the command on your path as `broker`, link the package from the checkout:
 npm link          # then: broker --help
 ```
 
+### Browser binary
+
+**Neither install path above fetches a browser.** 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 machine 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 applies whether you installed from
+the registry or from a checkout, because it is a fetch neither install step performs. 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.
+
 ### Configuring it
 
 **Nothing needs setting.** Every value is an environment variable with a working default, so the
@@ -155,10 +170,11 @@ 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
 ```
 
+**Every browser launches the automation library's own Chromium**, which a machine fetches once. The
+browser a caller names selects an identity and its profile directory, not a different binary.
+
 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 —
@@ -198,6 +214,24 @@ it is rarely the checkout. Nothing else is required: there is no port to configu
 issue, and no process to have started first — the client starts it, and it exits when the client
 closes the pipe.
 
+**If that configuration file is itself synchronised between machines, an absolute path is the one
+thing in it that cannot travel.** A home directory differs per machine and often per user, so one
+entry naming a checkout is correct on the machine it was written on and names nothing on the other
+— where it fails as a connection that closes immediately, which reads as a broken service rather
+than as a path that does not exist. Give each machine its own entry under its own server name, or
+point the shared entry at the published package, which carries no machine's path:
+
+```json
+{
+  "mcpServers": {
+    "browser-broker": {
+      "command": "npx",
+      "args": ["-y", "-p", "browser-broker", "broker-tool"]
+    }
+  }
+}
+```
+
 To point it at a store other than the default, add the environment to the same block:
 
 ```json
@@ -341,9 +375,7 @@ surface is being built, and the one manual step is wired: `broker login` hands a
 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.
+[`docs/plans/MILESTONES.md`](docs/plans/MILESTONES.md) for the work queue.
 
 ## Releasing
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "browser-broker",
-    "version": "0.1.0",
+    "version": "0.3.1",
     "license": "MIT",
     "description": "Leases over tabs in a fixed set of browsers: bounded capacity, a queue, reclamation, and an enforced capture policy.",
     "type": "module",
@@ -19,12 +19,13 @@
         "check:operations": "node scripts/check-operations.mjs",
         "check:argument-refusals": "node scripts/check-argument-refusals.mjs",
         "check:injected-tests": "node scripts/check-injected-tests.mjs",
+        "check:argument-reachability": "node scripts/check-argument-reachability.mjs",
         "typecheck": "tsc --noEmit",
         "lint": "eslint .",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "test": "node --test \"tests/**/*.test.mjs\" \"tests/**/*.test.ts\"",
-        "check": "npm run check:external-refs && npm run check:doc-links && npm run check:arbitration && npm run check:capture-isolation && npm run check:artifact-path && npm run typecheck && npm run lint && npm run format:check && npm test && npm run check:install && npm run check:operations && npm run check:argument-refusals && npm run check:injected-tests",
+        "check": "npm run check:external-refs && npm run check:doc-links && npm run check:arbitration && npm run check:capture-isolation && npm run check:artifact-path && npm run typecheck && npm run lint && npm run format:check && npm test && npm run check:install && npm run check:operations && npm run check:argument-refusals && npm run check:argument-reachability && npm run check:injected-tests && npm run check:package",
         "check:arbitration": "node scripts/check-arbitration.mjs",
         "check:artifact-path": "node scripts/check-artifact-path.mjs",
         "build": "tsc --project tsconfig.build.json",
@@ -52,7 +53,6 @@
         "dist/",
         ".env.example",
         "README.md",
-        "RELEASES.md",
         "LICENSE"
     ]
 }

package/dist/src/adapter/conformance/cases.js

@@ -320,7 +320,144 @@ export const CONFORMANCE_CASES = [
         operation: 'capture',
         seed: withALiveLease,
         input: {},
-        expect: { outcome: 'accepted' },
+        // §3.11's promised response, asserted as a response rather than as a row
+        // in a database. All three of `sourceWidth`, `sourceHeight` and `tier`
+        // were promised by §3.11 — *"the dimensions written, the dimensions
+        // before shrinking, the file size, the tier"* — computed by the pipeline,
+        // written to the `captures` table, and then **dropped by the service layer
+        // that builds the caller's reply**, for the whole life of the feature.
+        //
+        // Nothing caught it because nothing anywhere compared a response against
+        // the specification that promised it: `check:operations` proves the
+        // binaries reach the service, `check:argument-refusals` polices refusals,
+        // and neither walks from a documented response field to the code meant to
+        // populate it. Naming the fields here is the narrow, non-brittle version
+        // of that check — it binds the spec to the code at the one point both
+        // agree on, without a parser trying to read §3.x's English.
+        expect: {
+            outcome: 'accepted',
+            //
+            // ── Why these ten are not the list, and what bounds it ──────────────
+            //
+            // §3.11 promises more than this case names: an estimated token cost and
+            // how many captures this lease has taken are both in its sentence. They
+            // are deliberately absent here because they are **not in the reply the
+            // caller receives**: `estimatedTokens`, `capturesThisLease` and
+            // `escalation` are fields of the *pipeline's* `CaptureResult`, and
+            // `pages.ts` reshapes that into the `written` object without them. An
+            // assertion naming them would fail against correct code, which is the
+            // one failure a conformance case must never manufacture.
+            //
+            // That gap is real and it is item 557fdcd6's remaining half — a
+            // response still owes §3.11 two fields it does not carry. It is not
+            // closed here, because closing it means changing the response rather
+            // than the test, and this row is about the checks. Named so the next
+            // reader finds a known gap rather than an oversight.
+            //
+            // Spelled `capture.*` because the reply is an envelope: `capture` renews
+            // the lease it was called on, so the value carries `claimId`, `tabId`,
+            // `expiresAt` and `pageDriven` with the picture nested under `capture`.
+            // Naming the path asserts that nesting too.
+            valueFields: [
+                'capture.captureId',
+                'capture.path',
+                'capture.width',
+                'capture.height',
+                'capture.bytes',
+                // The three §3.11 promised and the shipped response omitted for the
+                // whole life of the feature. They are the reason this list exists.
+                'capture.sourceWidth',
+                'capture.sourceHeight',
+                'capture.tier',
+            ],
+        },
+    },
+    {
+        name: 'capture: an escalated tier changes the picture that comes back',
+        operation: 'capture',
+        // ── The assertion `check:argument-reachability` cannot make ───────────
+        //
+        // `tier` was read at the bridge, validated, packed into a request object,
+        // and then dropped at the single `takeCapture` call site, which spread
+        // only `fullPage` and `selector`. Every capture was taken at the default
+        // rung whatever was asked for, and `tier: "max"` charged the caller a
+        // written 8-200 character justification for it. The static check passed
+        // throughout, exactly as its own table says it must: *"a branch that reads
+        // an argument and drops it on the floor passes this."*
+        //
+        // So this case asserts the thing that actually failed: that passing the
+        // argument **changes what comes back**. The runner drives the operation a
+        // second time with `tier` and `reason` removed and requires the two
+        // readings to differ, so a `tier` hard-wired to `"max"` fails here rather
+        // than passing as a constant.
+        //
+        // `max` rather than `detail` because it is the rung that costs a reason,
+        // which puts both arguments on the same case: `reason` is recorded only on
+        // this tier (`pipeline.ts` — *"a reason attached to a capture nobody had to
+        // justify would put noise into the one column the resolution study
+        // reads"*), so the two travel together or not at all.
+        //
+        // ── What this case asserts about `reason`, stated honestly ───────────
+        //
+        // **It asserts that passing `reason` does not prevent the escalation, and
+        // nothing more.** `reason` is genuinely **not observable** from any route:
+        // it is written to the `captures` row and read back by no operation the
+        // conformance suite can reach (`capture-store.ts` exposes `recordCapture`
+        // and `capturesTakenBy`, and neither returns it). So there is no response
+        // field and no driver call in which a dropped `reason` would show.
+        //
+        // It is named in `arguments` regardless, because the baseline must remove
+        // it: `max` without a reason is **refused**, so a baseline that dropped
+        // only `tier` would be measuring a refusal rather than the default rung.
+        // Removing both is what makes the comparison a comparison.
+        //
+        // The one assertion that would close `reason` is a read path to the
+        // capture's own record, which does not exist and is not invented here.
+        seed: withALiveLease,
+        input: {
+            tier: 'max',
+            reason: 'conformance: proving an escalated tier reaches the pipeline that acts on it',
+        },
+        expect: {
+            outcome: 'accepted',
+            effects: [
+                {
+                    arguments: ['tier', 'reason'],
+                    expect: [
+                        {
+                            field: 'capture.tier',
+                            value: 'max',
+                            // The rung a caller lands on with no tier (`DEFAULT_TIER`).
+                            withoutArgument: 'default',
+                        },
+                        {
+                            // The **physical** consequence, not merely the label. `tier`
+                            // could be echoed back by a service that did nothing with it;
+                            // the width cannot. The fake produces 1280x720, so the default
+                            // rung's 1024 long edge shrinks it to 1024x576 while `max`'s
+                            // 2576 leaves it alone — never upscaled (`image.ts`: *"a picture
+                            // smaller than the rung is written as it is"*).
+                            //
+                            // This is the field that would have failed on the shipped
+                            // defect: every capture came back 1024 wide however it was
+                            // asked for.
+                            field: 'capture.width',
+                            value: 1280,
+                            withoutArgument: 1024,
+                        },
+                        {
+                            // The height, for the same reason as the width and as a
+                            // separate reading: the shrink is taken on the **long edge**,
+                            // so a change to `TIER_LONGEST_EDGE` that moved only one
+                            // dimension would leave the other's assertion standing.
+                            field: 'capture.height',
+                            value: 720,
+                            withoutArgument: 576,
+                        },
+                    ],
+                },
+            ],
+        },
     },
     {
         name: 'capture: a selector and a full page together are refused',

package/dist/src/adapter/conformance/run.js

@@ -1,5 +1,47 @@
+import { isDeepStrictEqual } from 'node:util';
 import { ADAPTER_IDS } from "../contract.js";
 import { isWriteOperation, OPERATION_NAMES } from "../operations.js";
+/**
+ * Structural comparison for effect assertions.
+ *
+ * `isDeepStrictEqual` rather than `===`, because an effect may name a
+ * structured field, and rather than `assert.deepStrictEqual`, because this
+ * runner reports findings instead of throwing (see the header).
+ */
+const deepEqual = (a, b) => isDeepStrictEqual(a, b);
+/**
+ * Read a field out of an accepted value, following a dotted path.
+ *
+ * ── Why a path and not a plain key ──────────────────────────────────────
+ *
+ * An accepted value is not flat. `capture` returns the lease's own fields —
+ * `claimId`, `tabId`, `expiresAt`, `pageDriven` — with **the capture itself
+ * nested under `capture`**, because the operation renews the lease it was
+ * called on and the reply says both things. `SCHEMA.md` §3.11's promises are
+ * about the capture object, so a case naming `width` flatly would read
+ * `undefined` from the envelope and report a missing field on a response that
+ * carries it — a finding that is wrong in the most expensive direction, since
+ * it accuses correct code.
+ *
+ * The path is resolved rather than the case being handed the sub-object,
+ * because the envelope is part of what the route returns: a case naming
+ * `capture.tier` asserts the nesting too, and an adapter that quietly
+ * flattened or re-keyed the reply would fail here rather than passing.
+ *
+ * Returns `undefined` for any path that does not resolve, which is the same
+ * answer as a field explicitly set to `undefined` — deliberately, because
+ * both mean "the caller cannot read this" and the assertions are about what
+ * a caller can read.
+ */
+function fieldAt(value, path) {
+    let current = value;
+    for (const step of path.split('.')) {
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[step];
+    }
+    return current;
+}
 /** Roughly four words, the same bar the hygiene gate holds a waiver to. */
 const WAIVER_MINIMUM_WORDS = 4;
 function wordCount(text) {
@@ -151,6 +193,99 @@ export async function runConformance(options) {
                         });
                     }
                 }
+                // ── Response conformance and argument effect ──────────────────────
+                //
+                // Both are assertions about the **accepted value**, which is why they
+                // sit together and why they are checked here rather than in a unit
+                // test: the value has crossed the route boundary by this point, so a
+                // field the service produced and the adapter dropped fails here and
+                // passes everywhere else.
+                if (outcome.outcome === 'accepted' && testCase.expect.outcome === 'accepted') {
+                    for (const field of testCase.expect.valueFields ?? []) {
+                        if (fieldAt(outcome.value, field) === undefined) {
+                            findings.push({
+                                kind: 'accepted-value-missing-a-field',
+                                adapter: adapterId,
+                                operation: testCase.operation,
+                                caseName: testCase.name,
+                                detail: `the accepted value has no "${field}" (it carries ${Object.keys(outcome.value).join(', ') || 'nothing'})`,
+                            });
+                        }
+                    }
+                    for (const effect of testCase.expect.effects ?? []) {
+                        // The same operation, driven again with the effect's arguments
+                        // removed. A fresh subject, because the first run consumed a lease
+                        // and moved the capture count — reusing it would measure the
+                        // second call's accounting rather than the argument.
+                        const baselineInput = Object.fromEntries(Object.entries(seeded.input).filter(([key]) => !effect.arguments.includes(key)));
+                        const baselineSubject = await options.makeService();
+                        let baseline;
+                        try {
+                            const baselineSubstitutions = (await testCase.seed?.apply(baselineSubject.service)) ?? {};
+                            const baselineCase = {
+                                ...testCase,
+                                name: `${testCase.name} (without ${effect.arguments.join(', ')})`,
+                                input: { ...baselineInput, ...baselineSubstitutions },
+                            };
+                            baseline = (await driver.run(baselineSubject.service, baselineCase, {
+                                driverCalls: baselineSubject.driverCalls,
+                                liveClaimCount: baselineSubject.liveClaimCount,
+                            })).outcome;
+                        }
+                        finally {
+                            await baselineSubject.dispose?.();
+                        }
+                        if (baseline.outcome !== 'accepted') {
+                            // Never silently skipped. An effect whose baseline refused would
+                            // otherwise report the same green as one that held.
+                            findings.push({
+                                kind: 'argument-effect-baseline-failed',
+                                adapter: adapterId,
+                                operation: testCase.operation,
+                                caseName: testCase.name,
+                                detail: `dropping ${effect.arguments.join(', ')} was refused (${baseline.code} / ${baseline.rule}), so the effect of those arguments could not be measured`,
+                            });
+                            continue;
+                        }
+                        for (const expectation of effect.expect) {
+                            const actual = fieldAt(outcome.value, expectation.field);
+                            const without = fieldAt(baseline.value, expectation.field);
+                            if (!deepEqual(actual, expectation.value)) {
+                                findings.push({
+                                    kind: 'argument-had-no-effect',
+                                    adapter: adapterId,
+                                    operation: testCase.operation,
+                                    caseName: testCase.name,
+                                    detail: `with ${effect.arguments.join(', ')}, "${expectation.field}" should be ${JSON.stringify(expectation.value)} but was ${JSON.stringify(actual)}`,
+                                });
+                                continue;
+                            }
+                            if (!deepEqual(without, expectation.withoutArgument)) {
+                                findings.push({
+                                    kind: 'argument-had-no-effect',
+                                    adapter: adapterId,
+                                    operation: testCase.operation,
+                                    caseName: testCase.name,
+                                    detail: `without ${effect.arguments.join(', ')}, "${expectation.field}" should be ${JSON.stringify(expectation.withoutArgument)} but was ${JSON.stringify(without)}`,
+                                });
+                                continue;
+                            }
+                            // The guard against a constant. Both readings can be individually
+                            // right and the argument still inert — if the two agree, passing
+                            // the argument changed nothing, whatever the field happens to
+                            // hold. This is the assertion the whole shape exists for.
+                            if (deepEqual(actual, without)) {
+                                findings.push({
+                                    kind: 'argument-had-no-effect',
+                                    adapter: adapterId,
+                                    operation: testCase.operation,
+                                    caseName: testCase.name,
+                                    detail: `"${expectation.field}" is ${JSON.stringify(actual)} whether or not ${effect.arguments.join(', ')} is passed, so the argument is inert`,
+                                });
+                            }
+                        }
+                    }
+                }
                 if (outcome.outcome === 'refused') {
                     // Both readings, because they catch different bugs (§8.2): a guard
                     // that opens a tab and closes it on the way to refusing leaves the

package/dist/src/adapter/conformance/service-subject.js

@@ -150,7 +150,11 @@ export async function makeServiceSubject() {
     return {
         service: runtime.service,
         // The fake's own log, which is what makes "a refusal touched no browser"
-        // checkable rather than asserted.
+        // checkable rather than asserted — and the entries are passed whole, so a
+        // case can also ask what the browser was told, not merely that it was
+        // spoken to. Dropping the arguments here would make a route that forwards
+        // an argument and one that discards it indistinguishable to every case in
+        // the table.
         driverCalls: () => driver.calls,
         // **The same predicate the capacity check uses**, per `driver.ts`'s
         // requirement for this reading — not a count of rows in `claims`, which

package/dist/src/browser/fake.js

@@ -92,6 +92,35 @@ const DEFAULT_COOKIES = [
  * members and there is nothing here that invents a third.
  */
 export class FakeBrowserDriver {
+    /**
+     * A way to end each handed-out session's connection, without ending the
+     * browser.
+     *
+     * ── Why the fake needs to be able to do this at all ─────────────────────
+     *
+     * A connection and the browser it points at have **independent lifetimes**,
+     * and the failure this models is the asymmetry: the browser is running and
+     * answers every liveness question truthfully, while the connection one
+     * process holds has ended. Nothing else in this fake can produce that state
+     * — seeding a failure makes an operation reject, which is a different thing
+     * and one the existing eviction path already handles.
+     *
+     * A test drives it with {@link FakeBrowserDriver.disconnect}; the fake's
+     * own tabs and recorded calls are deliberately left untouched, because the
+     * browser is unaffected.
+     */
+    #disconnectors = [];
+    /**
+     * End the connection on every session handed out for one browser, leaving
+     * the browser itself — its tabs, its call log — exactly as it was.
+     */
+    disconnect(browser) {
+        for (const entry of this.#disconnectors) {
+            if (entry.browser === browser) {
+                entry.end();
+            }
+        }
+    }
     #calls = [];
     #options;
     #openTabs = new Map();
@@ -301,6 +330,14 @@ export class FakeBrowserDriver {
     }
     #session(browser, mode) {
         const description = this.#describe(browser, mode);
+        // Every session this fake hands out starts connected, and only
+        // {@link FakeBrowserDriver.disconnect} changes that. It is per-session
+        // rather than per-browser deliberately: the state under test is *this
+        // connection ended while the browser carried on*, so a later acquisition
+        // for the same browser must come back connected, exactly as a real
+        // re-attach would.
+        let connected = true;
+        this.#disconnectors.push({ browser, end: () => (connected = false) });
         const openTab = (name) => {
             const driverTabId = `fake-tab-${String(this.#nextTabNumber++)}`;
             const failure = this.#enter({ name, browser, tab: { browser, driverTabId } });
@@ -314,6 +351,10 @@ export class FakeBrowserDriver {
         };
         return {
             describe: () => description,
+            // Reads the flag above and asks nothing, which is the contract
+            // {@link BrowserSession.isConnected} states: it is consulted before
+            // every page verb, so it must not perform input/output or throw.
+            isConnected: () => connected,
             openTab: () => openTab('openTab'),
             /**
              * Every page open in this browser **except the keeper tab**.
@@ -402,11 +443,36 @@ export class FakeBrowserDriver {
                 this.#tabsFor(tab.browser).delete(tab.driverTabId);
                 return Promise.resolve();
             },
-            navigate: (tab, url) => {
-                const failure = this.#enter({ name: 'navigate', browser, tab, detail: { url } });
+            navigate: (tab, url, waitMs) => {
+                // The wait is recorded even though nothing here waits, because what a
+                // test needs to assert is that the service *asked* for it. An argument
+                // that is accepted and dropped between the caller and the driver looks
+                // identical from the outside to one that was honoured, and the only
+                // place that difference is observable is this log.
+                //
+                // Recorded as an absent key when the caller omitted it, rather than as
+                // an explicit undefined, so a test can tell "asked for no wait" from
+                // "asked for a wait of nothing".
+                const failure = this.#enter({
+                    name: 'navigate',
+                    browser,
+                    tab,
+                    detail: { url, ...(waitMs === undefined ? {} : { waitMs }) },
+                });
                 if (failure)
                     return Promise.reject(failure);
-                return Promise.resolve({ url, title: `fake page at ${url}`, status: 200 });
+                // **Where the page ARRIVES, which is not always where it was sent.**
+                // Defaults to the requested address, so every existing caller sees
+                // what it always saw; a test that configures `arriveAt` gets a fake
+                // that redirects, which is the only way a fake can exercise the
+                // difference between reporting the request and reporting the result.
+                const options = this.#options.navigate;
+                const arrived = options?.arriveAt?.(url) ?? url;
+                return Promise.resolve({
+                    url: arrived,
+                    title: options?.title?.(arrived) ?? `fake page at ${arrived}`,
+                    status: options?.status === undefined ? 200 : options.status,
+                });
             },
             seedStorage: (tab, entries) => {
                 // **The whole entries list, values included**, and that is deliberate