browser-broker 0.1.0 → 0.3.1

package/dist/src/browser/real.js

@@ -493,9 +493,17 @@ class RealBrowserSession {
      * The address after redirects rather than the one asked for, because those
      * differ constantly and the caller needs the one it got.
      */
-    async navigate(tab, url) {
+    async navigate(tab, url, waitMs) {
         const page = await this.#page(tab);
-        const response = await page.goto(url);
+        // Passed as the navigation's own timeout rather than as a pause taken
+        // afterwards, so a page that arrives early returns early and the argument
+        // only ever costs what the page costs.
+        //
+        // Absent means the library's configured default applies. Spread rather
+        // than passed as `{ timeout: undefined }`, because an explicit undefined
+        // and an omitted key are the same to this library only by convention, and
+        // relying on that convention would make the default this service's to own.
+        const response = await page.goto(url, ...(waitMs === undefined ? [] : [{ timeout: waitMs }]));
         return {
             url: page.url(),
             title: await page.title(),
@@ -1246,6 +1254,18 @@ class RealBrowserSession {
             }
         }
     }
+    /**
+     * Whether this process's connection is still usable.
+     *
+     * Delegates to the flag the driving package already maintains — its
+     * `isConnected()` is declared `(): boolean` and its implementation is a
+     * bare field read (`return this._isConnected`), so this performs no
+     * input/output and cannot throw. That is what {@link BrowserSession.isConnected}
+     * requires of it, because it is consulted before every page verb.
+     */
+    isConnected() {
+        return this.#connection.isConnected();
+    }
     /**
      * End this process's connection. **The browser is unaffected.**
      *
@@ -1295,34 +1315,6 @@ async function connect(options) {
     await session.ensureKeeperTab();
     return session;
 }
-/**
- * Where a configured engine's binary lives, if this process was told.
- *
- * ── What is built here, and what is deliberately not ────────────────
- *
- * All three engines are Chromium over the same remote-debugging protocol, so
- * choosing between them is choosing a binary — which is what makes the hook
- * cheap, and it is the hook `DECISIONS.md` §13i asks for. **The expensive
- * half is explicitly out of scope there**: per-engine executable discovery,
- * per-engine discovery-record locations, per-engine health checks.
- *
- * **So resolution is a lookup of what a caller supplied, never a search.**
- * The engine selects among paths this process was given; it does not go
- * looking for an installation, and it never carries a path of its own.
- * Writing a per-engine install location into this file would name one machine
- * — §1.0's rule forbids that outright, and `check-external-refs` fails on the
- * shape.
- *
- * **What happens when nothing supplied a path for the configured engine** is
- * the case worth being exact about: the launch falls back to the automation
- * library's own Chromium, which is what an unconfigured build launches. That
- * is a real limit and it is named in §13i rather than hidden here — the
- * variables are validated and carried, and the row that resolves an engine to
- * an installed binary is separable work.
- */
-export function executablePathForEngine(engine, supplied) {
-    return supplied?.[engine];
-}
 /**
  * The real driver.
  *
@@ -1342,9 +1334,7 @@ export class RealBrowserDriver {
         if (this.#options.executablePath !== undefined) {
             return this.#options.executablePath;
         }
-        const engine = this.#options.engine;
-        const resolved = engine === undefined ? undefined : executablePathForEngine(engine, this.#options.enginePaths);
-        return resolved ?? chromium.executablePath();
+        return chromium.executablePath();
     }
     /**
      * Attach to a browser that is already running, **having checked the record

package/dist/src/capture/tiers.js

@@ -164,3 +164,56 @@ const TOKENS_PER_PIXEL_DIVISOR = 750;
 export function estimateTokens(width, height) {
     return Math.ceil((width * height) / TOKENS_PER_PIXEL_DIVISOR);
 }
+/**
+ * Describe the shrink, or return nothing when there was not one.
+ *
+ * **Absent rather than `scale: 1` when nothing was reduced**, and the
+ * difference is the one this whole helper is for: a field that is always
+ * present is a field a caller stops reading. Its presence is the signal.
+ */
+export function describeReduction(source, written, tier) {
+    if (written.width >= source.width && written.height >= source.height) {
+        return undefined;
+    }
+    // Taken on the long edge, which is the edge the cap is applied to — so this
+    // is the factor that was actually used rather than one recovered from
+    // whichever dimension happens to round more kindly.
+    const scale = Math.max(source.width, source.height) === 0
+        ? 1
+        : Math.max(written.width, written.height) / Math.max(source.width, source.height);
+    const percent = Math.round(scale * 100);
+    // Named only when there is one, so the sentence never tells a caller already
+    // on the top rung to escalate to it.
+    const higher = HIGHER_TIERS[tier];
+    const remedy = higher === undefined
+        ? `This is the highest rung, so a larger image of the whole page is not available; capture a selector, or read the page as text instead.`
+        : `For more detail pass tier="${higher}"${higher === TIER_REQUIRING_REASON ? ' together with reason' : ''}.`;
+    // The width is called out separately because it is the number that decides
+    // legibility on a tall page, and it is the one a caller reading "scale" on
+    // its own would not think to compare against the viewport.
+    return {
+        sourceWidth: source.width,
+        sourceHeight: source.height,
+        scale: Math.round(scale * 1000) / 1000,
+        note: `This image was REDUCED to about ${String(percent)}% of the page: ` +
+            `${String(source.width)}x${String(source.height)} was written as ` +
+            `${String(written.width)}x${String(written.height)}. ` +
+            `A capture is shrunk so its LONGEST edge fits ${String(TIER_LONGEST_EDGE[tier])}px, so on a page ` +
+            `taller than it is wide the height sets the factor and the width shrinks with it — ` +
+            `${String(written.width)}px of width here. Text may not be legible. ` +
+            remedy,
+    };
+}
+/**
+ * The next rung up from each, and `undefined` at the top.
+ *
+ * A table rather than an ordering computed from {@link TIER_LONGEST_EDGE},
+ * because "which rung does a caller ask for next" is a fact about the
+ * surface's vocabulary — `default` is not requestable by name — and not about
+ * which number is larger.
+ */
+const HIGHER_TIERS = {
+    default: 'detail',
+    detail: 'max',
+    max: undefined,
+};

package/dist/src/cli/adapter.js

@@ -123,19 +123,53 @@ export function parseArguments(rest) {
         const body = word.slice(2);
         const equals = body.indexOf('=');
         if (equals !== -1) {
-            parsed[normaliseKey(body.slice(0, equals))] = body.slice(equals + 1);
+            record(parsed, normaliseKey(body.slice(0, equals)), body.slice(equals + 1));
             continue;
         }
         const next = rest[index + 1];
         if (next === undefined || looksLikeFlag(next)) {
-            parsed[normaliseKey(body)] = true;
+            record(parsed, normaliseKey(body), true);
             continue;
         }
-        parsed[normaliseKey(body)] = next;
+        record(parsed, normaliseKey(body), next);
         index += 1;
     }
     return parsed;
 }
+/**
+ * Write an option, accumulating the ones that may legitimately repeat.
+ *
+ * Assignment was unconditional, so a repeated option kept only its **last**
+ * occurrence. For every option that names one thing that is the right
+ * behaviour and the last word plainly wins. For an option that names *one of
+ * many* it is silent data loss: `--field a=1 --field b=2` filled one field
+ * and reported success, which is worse than the refusal it replaced, because
+ * a refusal is visible.
+ *
+ * Only the options in {@link REPEATABLE} accumulate. Making every option an
+ * array on its second appearance would change the type a reader gets for
+ * `--value` typed twice by accident, and turn a typo into a shape no
+ * operation expects.
+ */
+function record(parsed, key, value) {
+    if (!REPEATABLE.has(key)) {
+        parsed[key] = value;
+        return;
+    }
+    const existing = parsed[key];
+    if (existing === undefined) {
+        parsed[key] = [value];
+        return;
+    }
+    existing.push(value);
+}
+/**
+ * The options that name one of many rather than one thing.
+ *
+ * Keyed by their normalised names. Deliberately a short list: an option
+ * belongs here only when the operation behind it takes a collection.
+ */
+const REPEATABLE = new Set(['field']);
 function normaliseKey(key) {
     return key.replaceAll('-', '_');
 }

package/dist/src/cli/commands.js

@@ -35,6 +35,26 @@ export const OPERATION_COMMANDS = [
         operation: 'claim',
         summary: 'Ask for a lease. Get one tab, or a place in the queue.',
         options: [
+            // **The two a claim is refused for omitting, listed first because they
+            // are the two it is refused for omitting.** Both were absent here while
+            // `claim.session_bounded` and `claim.purpose_bounded` asked for them by
+            // name, which is the worst arrangement available: the refusals are
+            // models of the form — each names the missing thing and says why it
+            // exists — and a caller who did as they asked, under a plausible
+            // spelling, was refused a second time in identical words. A help text
+            // that lists three optional flags and neither required one teaches a
+            // reader how to call this command unsuccessfully.
+            {
+                flag: '--session-id <id>',
+                summary: 'Required. Who is asking. It attributes this lease and every refusal on it in the ' +
+                    'ledger, and it is how the service can tell you when you are queued behind capacity ' +
+                    'you already hold.',
+            },
+            {
+                flag: '--purpose <text>',
+                summary: 'Required, 3 to 200 characters. What the lease is for, in one line, read by whoever ' +
+                    'finds the tab still open.',
+            },
             {
                 flag: '--wait',
                 summary: 'Poll a queued place until it is granted, lost or refused, rather than returning the place.',
@@ -56,7 +76,7 @@ export const OPERATION_COMMANDS = [
     {
         words: ['act'],
         operation: 'act',
-        summary: 'Click, type, fill, press, select, hover, check, scroll, resize, emulate, dialog.',
+        summary: 'Click, type, fill, press, select, hover, check, scroll, resize, emulate, dialog, fill_form.',
         // **Undocumented options are unusable options**, and this command had
         // none listed at all — so `broker act --help` printed `--json` and
         // `--help` and nothing else, for the verb with the most arguments on the
@@ -93,6 +113,16 @@ export const OPERATION_COMMANDS = [
                 flag: '--forced-colours <active|none>',
                 summary: 'For emulate.',
             },
+            {
+                flag: '--accept | --dismiss',
+                summary: 'For dialog, which answer to give. `--prompt-text <text>` is what to type before ' +
+                    'accepting, and cannot accompany a dismissal.',
+            },
+            {
+                flag: '--field <ref>=<value>',
+                summary: 'For fill_form, one field to fill. Repeat it once per field; only the first = ' +
+                    'separates, so a value may contain one.',
+            },
         ],
     },
     {
@@ -142,6 +172,11 @@ export const STANDALONE_COMMANDS = [
         words: ['snapshot'],
         summary: 'Write the operations document to a path and exit.',
         owedBy: 'the row that builds the operations document',
+        options: [
+            { flag: '--out <path>', summary: 'The file to write the document to. Required.' },
+            { flag: '--events <n>', summary: 'How many ledger entries to include.' },
+            { flag: '--feedback <n>', summary: 'How many feedback rows to include.' },
+        ],
     },
     {
         words: ['doctor'],
@@ -222,6 +257,12 @@ export const STANDALONE_COMMANDS = [
                 flag: '--browser <regular|private>',
                 summary: 'Which browser to reconcile. May also be given as the first word.',
             },
+            {
+                flag: '--session-id <id>',
+                summary: 'Optional. Who is asking, so a tab still being opened can be named as your own lease ' +
+                    'rather than as somebody’s. Omitting it is fine and costs only that distinction: ' +
+                    'the report degrades to the general caution, which is the honest answer when nobody said.',
+            },
         ],
     },
     {

package/dist/src/cli/index.js

@@ -11,7 +11,7 @@ import { ArtifactStore } from "../artifacts/store.js";
 import { runDiffs } from "./diffs.js";
 import { runCaptures } from "./telemetry.js";
 import { runImage } from "./image.js";
-import { runDoctorCommand, runEventsCommand, runSnapshotCommand } from "./operations-commands.js";
+import { runDoctorCommand, runEventsCommand, runSnapshotCommand, UnknownFlagError, } from "./operations-commands.js";
 import { explainLoginFailure, runLoginCommand } from "./login-command.js";
 import { runReconcileCommand } from "./reconcile-command.js";
 const defaultStreams = {
@@ -805,6 +805,17 @@ async function runOperationsCommand(command, rest, context) {
         return runEventsCommand(rest, { db: store.db, streams, json });
     }
     catch (error) {
+        // **A mistyped flag is malformed input, not a refused decision.** It is
+        // answered here rather than inside each command because all three parse
+        // their flags the same way and would otherwise each need the same catch —
+        // and because the exit code is the thing a caller branches on: `malformed`
+        // says the vector was wrong, which is what a typo is, while `refused`
+        // would say the service considered the request and declined it. Nothing
+        // was considered; the command never ran.
+        if (error instanceof UnknownFlagError) {
+            streams.err(error.message);
+            return EXIT.malformed;
+        }
         if (error instanceof BrokerError) {
             streams.err(`refused (${error.rule}): ${error.message}`);
             return EXIT.refused;

package/dist/src/cli/operations-commands.js

@@ -14,14 +14,80 @@ import { writeSnapshot } from "../report/snapshot.js";
  * constant is how they stay in step with the route that does.
  */
 export const COMMAND_EXIT = EXIT;
-/** `--name value` and `--name=value`, plus bare `--flag`. */
-export function parseFlags(rest) {
+/**
+ * Flags every command on this route takes, rendered by the help writer rather
+ * than declared per command — so they are always accepted and never appear in
+ * a command's own list of known flags.
+ */
+const UNIVERSAL_FLAGS = ['json', 'help'];
+/**
+ * An unknown flag, named, with the flags that command does accept.
+ *
+ * Thrown rather than returned because {@link parseFlags} answers with a record
+ * and has no room in it for a refusal, and every caller of it is a command
+ * that must stop rather than proceed on a misread vector.
+ */
+export class UnknownFlagError extends Error {
+    // Declared and assigned rather than written as constructor parameter
+    // properties: this build strips types rather than compiling them, and a
+    // parameter property is syntax that needs a compiler to exist at runtime.
+    flag;
+    known;
+    constructor(flag, known) {
+        // Named the way `claim.browser_known` names the browsers: the thing that
+        // was wrong, then the set it should have come from. A caller that mistypes
+        // a flag is one edit from being right, and the edit is only obvious if the
+        // alternatives are on the screen.
+        super(`There is no option named --${flag}. This command accepts ${known
+            .map((name) => `--${name}`)
+            .join(', ')}.`);
+        this.name = 'UnknownFlagError';
+        this.flag = flag;
+        this.known = known;
+    }
+}
+/**
+ * `--name value` and `--name=value`, plus bare `--flag`.
+ *
+ * ── Why an unknown flag is refused rather than dropped ──────────────────
+ *
+ * Because dropping it produced the one failure a good refusal cannot rescue.
+ * A caller typing `--session` instead of `--session-id` had the flag discarded
+ * without comment, so the command ran as though nothing had been passed and
+ * truthfully reported that nothing was there — and any argument riding behind
+ * the bad flag was consumed as its value and lost with it. The message that
+ * came back was correct, and it pointed at the value rather than at the flag
+ * name, which is the one place the error actually was. A refusal that repeats
+ * identically after a caller has complied with it moves their suspicion onto
+ * the wrong thing.
+ *
+ * This is what makes an undocumented flag unrecoverable rather than merely
+ * inconvenient: with no entry in `--help` and no signal from the parser, a
+ * caller has nothing to correct against and no reason to suspect a typo.
+ *
+ * **The known set is passed in by the command**, because only the command
+ * knows it. A parser that guessed would either refuse a flag that works or
+ * accept one that does not, and both reintroduce the silence.
+ *
+ * Omitting `known` accepts everything, which is what an in-process caller
+ * testing the parsing shape itself wants; every shipped command passes its
+ * list.
+ */
+export function parseFlags(rest, known) {
     const parsed = {};
+    const accepted = known === undefined ? undefined : new Set([...known, ...UNIVERSAL_FLAGS]);
     for (let index = 0; index < rest.length; index += 1) {
         const word = rest[index];
         if (word === undefined || !word.startsWith('--')) {
             continue;
         }
+        const name = word.slice(2).split('=')[0] ?? '';
+        if (accepted !== undefined && !accepted.has(name)) {
+            // The command's own flags, without the universal two: those are
+            // rendered by the help writer on every command, so listing them here
+            // would pad the sentence with the two the caller did not get wrong.
+            throw new UnknownFlagError(name, known ?? []);
+        }
         const body = word.slice(2);
         const equals = body.indexOf('=');
         if (equals !== -1) {
@@ -62,7 +128,10 @@ function asNumber(value) {
  * leaving a blank.
  */
 export async function runSnapshotCommand(rest, options) {
-    const flags = parseFlags(rest);
+    // `output` and `path` are long-standing spellings of `--out` that this
+    // command has always read; they are accepted here for that reason, and left
+    // out of the help table because one name is what a table should teach.
+    const flags = parseFlags(rest, ['out', 'output', 'path', 'events', 'feedback']);
     const outputPath = asString(flags.out) ?? asString(flags.output) ?? asString(flags.path);
     if (outputPath === undefined) {
         options.streams.err('broker snapshot needs somewhere to write: --out <path>. It writes one self-contained HTML file and exits.');
@@ -151,7 +220,16 @@ export function runDoctorCommand(options) {
  * caller types reaches the SQL text.
  */
 export function runEventsCommand(rest, options) {
-    const flags = parseFlags(rest);
+    const flags = parseFlags(rest, [
+        'kind',
+        'outcome',
+        'guard',
+        'session-id',
+        'claim-id',
+        'since',
+        'before',
+        'limit',
+    ]);
     const query = {
         kinds: asString(flags.kind)?.split(',') ?? undefined,
         outcome: asString(flags.outcome),

package/dist/src/cli/reconcile-command.js

@@ -1,6 +1,6 @@
 import { DEFAULT_BROWSER_IDS } from "../browser/driver.js";
 import { append } from "../service/events.js";
-import { applyReconciliation, decideReconciliation, readRecordedTabs, } from "../service/reconcile.js";
+import { applyReconciliation, decideReconciliation, readRecordedTabs, settleStrandedTabs, } from "../service/reconcile.js";
 import { COMMAND_EXIT, parseFlags } from "./operations-commands.js";
 /** Timestamps are spelled one way in this store. */
 function now() {
@@ -18,9 +18,13 @@ function isBrowserId(value, browsers) {
  * person who wants both runs it twice and reads two reports.
  */
 export async function runReconcileCommand(rest, options) {
-    const flags = parseFlags(rest);
+    const flags = parseFlags(rest, ['browser', 'session-id']);
     const named = rest.find((word) => !word.startsWith('--'));
     const browser = typeof flags.browser === 'string' ? flags.browser : named;
+    // Optional, and the report degrades honestly without it: a caller that does
+    // not say who it is gets the ordinary message rather than a claim about
+    // ownership nobody established.
+    const callerSession = typeof flags['session-id'] === 'string' ? flags['session-id'] : undefined;
     const browsers = options.browsers ?? DEFAULT_BROWSER_IDS;
     if (browser === undefined) {
         options.streams.err(`broker reconcile needs to be told which browser: ${browsers.join(' or ')}. It asks that browser what it has open, closes pages no live lease owns, and settles rows whose pages are gone.`);
@@ -51,6 +55,13 @@ export async function runReconcileCommand(rest, options) {
     // ── 4. Writing. A database handle and no session.
     const at = now();
     applyReconciliation(options.db, plan.vanishedTabs, at);
+    // Rows left `closing` by a lease that has already ended, whose page this
+    // browser does not have. The vanished-tab path cannot see them — it reads
+    // only tabs of *active* leases — so without this they are unreachable by
+    // anything, forever, while still holding their slot in the partial unique
+    // index. The browser has just said what it has open; that is the answer
+    // those rows were waiting for.
+    const strandedSettled = settleStrandedTabs(options.db, browser, pages.map((page) => page.driverTabId), at);
     for (const tab of plan.vanishedTabs) {
         // §1.6: one row per decision, and this is a decision — a lease was ended
         // by something that was neither the caller nor the clock. `cli` rather
@@ -85,10 +96,14 @@ export async function runReconcileCommand(rest, options) {
     }
     const report = {
         pagesSeen: pages.length,
+        strandedSettled,
         settled: plan.vanishedTabs.map((tab) => tab.tabId),
         closed,
         closeFailures,
         skippedOpening: plan.skippedOpening.length,
+        skippedOpeningOwnedByCaller: callerSession === undefined
+            ? 0
+            : plan.skippedOpening.filter((tab) => tab.sessionId === callerSession).length,
     };
     if (options.json) {
         options.streams.out(JSON.stringify({
@@ -106,16 +121,55 @@ export async function runReconcileCommand(rest, options) {
     }
     return COMMAND_EXIT.accepted;
 }
+/**
+ * Did this run decline to do the thing it was called to do?
+ *
+ * **Two facts together, and neither alone is enough.** Tabs still being
+ * opened block the sweep (`decideReconciliation` leaves them alone, because
+ * closing a page a mid-open lease is about to be handed would be worse than
+ * declining) — but a run that closed pages *and* skipped one did work, and
+ * calling that "nothing was closed" would be false. A run that closed
+ * nothing because there was nothing to close is not declining either; it is
+ * simply a clean run, and telling that caller to try again would send it
+ * back for an answer it already has.
+ *
+ * So the conclusion is drawn only where both hold: something was in the way,
+ * and nothing was swept past it.
+ */
+function nothingClosedPendingRetry(report) {
+    return report.skippedOpening > 0 && report.closed === 0;
+}
 /**
  * The report a person reads.
  *
  * **Every line is a count or an opaque identifier**, which is §1.4's rule
  * made true by there being nothing else available to print: the report type
  * carries no driver name, so this function could not print one if it tried.
+ *
+ * ── Why the outcome is the first line and not the last ──────────────────
+ *
+ * A caller reads the first line and acts on it. When this run declined —
+ * {@link nothingClosedPendingRetry} — the sentence that predicts that
+ * caller's next failure is the one that has to arrive first, because a
+ * headline of `reconciled: <browser>` above four counters reads as
+ * completion, and a reader who takes it at face value stops there and runs
+ * straight back into the state they invoked this to clear. The counters are
+ * still printed, unchanged and in the same order; what moves is the
+ * conclusion, which stops being something the reader has to derive from the
+ * bottom of a list.
+ *
+ * **The headline stops claiming completion on such a run** for the same
+ * reason. `reconciled:` is a claim about what happened, and on a run that
+ * closed nothing and needs invoking again it is not a true one — this is the
+ * defect class this repository keeps finding in itself, a call that succeeds
+ * while delivering less than it announced. The word is kept for the runs
+ * that earned it.
  */
 export function formatReconciliation(browser, report) {
+    const declined = nothingClosedPendingRetry(report);
     const lines = [
-        `reconciled: ${browser}`,
+        declined ? `did not reconcile: ${browser}` : `reconciled: ${browser}`,
+        ...(declined ? [conclusionLine(report)] : []),
         `pages open, not counting the keeper: ${String(report.pagesSeen)}`,
         `pages closed because no live lease owned them: ${String(report.closed)}`,
         `leases ended because their page was gone: ${String(report.settled.length)}`,
@@ -123,15 +177,44 @@ export function formatReconciliation(browser, report) {
     for (const tabId of report.settled) {
         lines.push(`  tab ${tabId}`);
     }
+    // Only when it happened. A line that is present and zero on every healthy
+    // run is noise, and this one describes a state that should be rare.
+    if (report.strandedSettled > 0) {
+        lines.push(`records settled that were waiting on a close nobody was coming to answer: ${String(report.strandedSettled)}`);
+    }
     if (report.closeFailures > 0) {
         // §2.4b: a leaked page, not a leaked lease. Said in those terms so the
         // reader knows what it costs — memory, and not budget.
         lines.push(`${String(report.closeFailures)} page(s) would not close. That is a leaked page and not a leaked lease: the budget is unaffected, and \`broker doctor\` reports them.`);
     }
-    if (report.skippedOpening > 0) {
-        // Said on the run it happened on, because the alternative is a person
-        // reading "0 closed" and concluding there was nothing to close.
-        lines.push(`${String(report.skippedOpening)} tab(s) are still being opened, so nothing was closed on this run — a page seen now may belong to one of them. Run again once they have settled.`);
+    // Said on the run it happened on, because the alternative is a person
+    // reading "0 closed" and concluding there was nothing to close.
+    //
+    // **Printed here only when it was not already printed at the top.** The
+    // conclusion belongs above the counters on a run that declined, and below
+    // them on a run that closed pages anyway — where it is a caveat on real
+    // work rather than the outcome. Either way it is written once, by one
+    // function, so the two positions cannot drift into two wordings.
+    if (report.skippedOpening > 0 && !declined) {
+        lines.push(conclusionLine(report));
     }
     return lines;
 }
+/**
+ * The sentence that tells a caller what to do next.
+ *
+ * **The caution itself does not change when the caller owns the blocking
+ * row.** Closing a page belonging to an in-flight claim would be worse than
+ * declining, and that is true whoever the claim belongs to. What changes is
+ * that the caller is told the remedy is in its own hands: an operator can
+ * otherwise run this repeatedly against a row that is its own lease, held
+ * open for as long as the command keeps being run, with nothing in the
+ * message able to say so.
+ */
+function conclusionLine(report) {
+    const owned = report.skippedOpeningOwnedByCaller;
+    return (`${String(report.skippedOpening)} tab(s) are still being opened, so nothing was closed on this run — a page seen now may belong to one of them.` +
+        (owned > 0
+            ? ` ${String(owned)} of them ${owned === 1 ? 'belongs' : 'belong'} to your own lease — release ${owned === 1 ? 'it' : 'them'}, or run this from another session.`
+            : ' Run again once they have settled.'));
+}

package/dist/src/config/environment.js

@@ -146,39 +146,6 @@ const DECLARATIONS = [
         maximum: 3,
         browserKind: 'clean-room',
     },
-    {
-        /**
-         * Which browser binary the signed-in browsers launch (§6.2).
-         *
-         * **One engine per kind, never per browser**, for the same reason there is
-         * no per-entry private flag: an engine per entry reintroduces the
-         * per-entry attribute this configuration exists without.
-         *
-         * The three accepted words are all Chromium over the same remote-debugging
-         * protocol, which is what makes the choice a binary path rather than a
-         * second driver.
-         */
-        key: 'BROKER_REGULAR_BROWSER_ENGINE',
-        kind: 'enum',
-        fallback: 'msedge',
-        allowed: ['chrome', 'brave', 'msedge'],
-        unit: 'a browser engine',
-    },
-    {
-        /**
-         * Which browser binary the clean-room browsers launch (§6.2).
-         *
-         * **May differ from the signed-in engine**, and separate variables are
-         * what make that expressible: a person signs into the signed-in browser by
-         * hand, so which binary that is can be a matter of what they already use,
-         * while nobody signs into a clean-room browser at all.
-         */
-        key: 'BROKER_PRIVATE_BROWSER_ENGINE',
-        kind: 'enum',
-        fallback: 'msedge',
-        allowed: ['chrome', 'brave', 'msedge'],
-        unit: 'a browser engine',
-    },
 ];
 /** Every variable this build declares. Row #9's walk test reads this. */
 export const DECLARED_VARIABLES = DECLARATIONS.map((d) => d.key);
@@ -407,15 +374,6 @@ export function readEnvironment(options = {}) {
         }
         return value;
     };
-    // The reader already refused anything outside the declared set, so this
-    // narrows a checked value rather than trusting one.
-    const getEngine = (key) => {
-        const value = resolved.get(key);
-        if (value !== 'chrome' && value !== 'brave' && value !== 'msedge') {
-            throw new Error(`${key} was declared as an engine but not resolved as one`);
-        }
-        return value;
-    };
     const regularBrowsers = getList('BROKER_REGULAR_BROWSERS');
     const privateBrowsers = getList('BROKER_PRIVATE_BROWSERS');
     // **A name in both lists is refused rather than resolved**, because the
@@ -440,7 +398,5 @@ export function readEnvironment(options = {}) {
         launchReadinessTimeoutSeconds: getNumber('BROKER_LAUNCH_READINESS_TIMEOUT_SECONDS'),
         regularBrowsers,
         privateBrowsers,
-        regularBrowserEngine: getEngine('BROKER_REGULAR_BROWSER_ENGINE'),
-        privateBrowserEngine: getEngine('BROKER_PRIVATE_BROWSER_ENGINE'),
     };
 }