browser-broker 0.1.0 → 0.2.0

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.',
+            },
         ],
     },
     {
@@ -222,6 +252,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({
@@ -123,6 +138,11 @@ 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.
@@ -131,7 +151,19 @@ export function formatReconciliation(browser, report) {
     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.`);
+        //
+        // **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 once ran this four times against a row that was its own lease,
+        // held open while it ran the command, with nothing in the message able to
+        // say so.
+        const owned = report.skippedOpeningOwnedByCaller;
+        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.` +
+            (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.'));
     }
     return lines;
 }

package/dist/src/doctor/checks.js

@@ -190,6 +190,70 @@ export function checkSchemaVersion(found) {
             : 'Any spawn steps the schema. Run the service once; this command reports and does not step.',
     };
 }
+/**
+ * That no tab has been waiting on a close nobody is coming to answer.
+ *
+ * ── The report that said nothing ────────────────────────────────────────
+ *
+ * `closing` means the tool was asked and has not answered. That is a
+ * transient state measured in a round trip, so a row sitting in it for hours
+ * is not slow — it is waiting for an answer that will never arrive, because
+ * the process that would have written it exited long ago.
+ *
+ * This check exists because a store was found holding 22 such rows while
+ * `broker doctor` reported **exit code 0**. Eight real pages were open on
+ * the operator's browser, owned by no lease, and the only reason anybody
+ * noticed was that a person looked at his own browser and thought there were
+ * too many tabs. A report that is clean while that is true is not reporting.
+ *
+ * ── Why the threshold is a lease's own lifetime ─────────────────────────
+ *
+ * The number has to separate "a close is in flight" from "a close is never
+ * happening", and the honest boundary is the one the system already uses to
+ * decide a caller is gone: if a lease may be declared lapsed after this long
+ * without contact, a round trip outstanding for longer is not pending.
+ * Taking the threshold from configuration rather than writing one down keeps
+ * the two from drifting apart.
+ *
+ * ── Why the count is broken down per browser ────────────────────────────
+ *
+ * The remedy is per-browser, so a single total cannot say which browsers
+ * still need it. An operator who reconciled one browser and watched the total
+ * fall from 29 to 13 reasonably concluded reconcile had not worked; the
+ * remaining 13 were all on the other browser, and the run had done exactly
+ * what it said. The breakdown is what makes the remaining work obvious, and
+ * the remedy names the browsers rather than saying "each browser" — the
+ * browsers are a configured list per kind rather than a fixed pair, so
+ * "each" is not something a reader can enumerate from the message alone.
+ */
+export function checkStrandedTabs(byBrowser, thresholdSeconds) {
+    const stranded = byBrowser.reduce((total, entry) => total + entry.stranded, 0);
+    if (stranded === 0) {
+        return {
+            group: 'store',
+            id: 'store.stranded_tabs',
+            title: 'No tab is waiting on a close that will not come',
+            status: 'ok',
+            detail: 'Every tab has either been closed or is still within a close round trip.',
+        };
+    }
+    return {
+        group: 'store',
+        id: 'store.stranded_tabs',
+        title: 'No tab is waiting on a close that will not come',
+        status: 'failed',
+        detail: `${String(stranded)} tab(s) have been waiting on a close for longer than ` +
+            `${String(thresholdSeconds)} seconds, which is how long a lease may go without contact ` +
+            'before it is declared lapsed. A close outstanding for longer is not in flight. ' +
+            `Per browser: ${byBrowser
+                .map((entry) => `${String(entry.stranded)} on ${entry.browserId}`)
+                .join(', ')}.`,
+        remedy: `Run \`broker reconcile\` against each browser named above: ${byBrowser
+            .map((entry) => `\`broker reconcile ${entry.browserId}\``)
+            .join(', ')}. It asks what the browser actually has open, ` +
+            'closes pages no live lease owns, and settles the records whose page is gone.',
+    };
+}
 export function checkAutomation(probe) {
     if (probe.present === undefined) {
         return {

package/dist/src/doctor/report.js

@@ -1,9 +1,10 @@
 import { SIGNABLE_BROWSER } from "../service/operations/sign-in.js";
 import { readTabBudget } from "../operations/status.js";
 import { classifySignIn } from "../service/signin-recovery.js";
+import { strandedTabsByBrowser } from "../service/tabs.js";
 import { readStoreVersion } from "../store/schema/step.js";
 import { inspectProfileSession } from "./session.js";
-import { checkAbandonedSignIn, checkAutomation, checkCaptureSurface, checkDiscoveryRecord, checkKeeperTab, checkRootWritable, checkSchemaVersion, checkSignInSession, checkStoreLocation, checkStorePresent, checkTabBudget, exitCodeFor, } from "./checks.js";
+import { checkAbandonedSignIn, checkAutomation, checkCaptureSurface, checkDiscoveryRecord, checkKeeperTab, checkRootWritable, checkSchemaVersion, checkStrandedTabs, checkSignInSession, checkStoreLocation, checkStorePresent, checkTabBudget, exitCodeFor, } from "./checks.js";
 /**
  * Run the preconditions.
  *
@@ -75,6 +76,14 @@ export function runDoctor(environment, db, probes = {}) {
     // otherwise.
     checks.push(checkAbandonedSignIn(signInBrowser, classifySignIn(db === undefined ? undefined : readSignInOwner(db, signInBrowser), probes.processIsRunning)));
     checks.push(checkTabBudget(storedBudget, probes.configuredTabBudget ?? null));
+    // Counted here rather than in the check, which takes a number so it stays
+    // testable without a store. A store that is absent yields no count and the
+    // check is not run at all: "no store" is already reported by its own row,
+    // and a second row saying zero stranded tabs would read as reassurance
+    // drawn from nothing.
+    if (db !== undefined) {
+        checks.push(checkStrandedTabs(strandedTabsByBrowser(db, environment.leaseSeconds), environment.leaseSeconds));
+    }
     return {
         checks,
         exitCode: exitCodeFor(checks),

package/dist/src/service/arbitration.js

@@ -381,6 +381,67 @@ export function updateSweptTabs(db, tabs, now) {
         .all(...ids);
     return pending;
 }
+/**
+ * Record how a close went, after the browser has answered.
+ *
+ * ── The half of the lifecycle that was never written ────────────────────
+ *
+ * `updateSweptTabs` moves a tab to `closing`, and the schema says what that
+ * means: *"the tool was asked and has not answered"*. Something has to write
+ * the answer down, and nothing did — so a tab that closed perfectly well sat
+ * at `closing` for the life of the store, with `close_attempts` at zero
+ * because no code path had ever incremented it.
+ *
+ * The cost was not cosmetic. `closing` is one of the states the partial
+ * unique index on `(browser_id, driver_tab_id)` covers, so every stranded
+ * row kept holding its slot; and a state meaning "asked, no answer" that is
+ * never resolved makes the ledger disagree with the browser permanently,
+ * which is worse than either being wrong on its own — the ledger is what
+ * every guard reads.
+ *
+ * ── Why the attempt is counted even when it succeeds ────────────────────
+ *
+ * `close_attempts` is what distinguishes *tried and failed* from *never
+ * tried*, and that distinction is the whole diagnostic value of the column.
+ * A field investigation found 22 stranded rows and could say with certainty
+ * that the close had never been attempted, rather than having to guess
+ * whether the browser was refusing — because the counter was zero rather
+ * than absent.
+ *
+ * ── Why a failure is not an error the caller sees ───────────────────────
+ *
+ * `SCHEMA.md` §2.4b: **a leaked tab is not a leaked lease.** The capacity is
+ * already back; what is left is a page. Turning that into a thrown error
+ * would fail a release that actually succeeded at the thing releases are for.
+ * So a failure is recorded as `close_failed` on a row that stays `closing`
+ * — visible, selectable, and reclaimable by reconciliation — rather than
+ * raised.
+ */
+export function recordTabClosed(db, tabId, at) {
+    db.prepare(`UPDATE tabs
+        SET state = 'closed',
+            closed_at = ?,
+            close_failed = 0,
+            close_attempts = close_attempts + 1,
+            updated_at = ?
+      WHERE id = ?
+        AND state = 'closing'`).run(at, at, tabId);
+}
+/**
+ * Record that a close was attempted and the browser did not do it.
+ *
+ * The row stays `closing`, which is the honest state: the page may well
+ * still be there. What changes is that it is now *known* to have been tried,
+ * which is what `close_failed` is for and what reconciliation selects on.
+ */
+export function recordTabCloseFailed(db, tabId, at) {
+    db.prepare(`UPDATE tabs
+        SET close_failed = 1,
+            close_attempts = close_attempts + 1,
+            updated_at = ?
+      WHERE id = ?
+        AND state = 'closing'`).run(at, tabId);
+}
 /**
  * Record what the sweep did, on the call that performed it.
  *