browser-broker 0.1.0 → 0.3.1

package/dist/src/service/operations/claim.js

@@ -5,6 +5,7 @@ import { append } from "../events.js";
 import { hashKey, mintKey } from "../keys.js";
 import { nudgeIfOwnObstacle } from "../nudge.js";
 import { queuePosition, waitEstimateSeconds } from "../queue.js";
+import { countStrandedTabsFor } from "../tabs.js";
 import { CallRefusal } from "../refusals.js";
 import { StorageSeedRefusal, seedRecord, validateStorageSeed, } from "../storage-seed.js";
 /**
@@ -612,6 +613,30 @@ function grant(branch) {
     // last unit and the rest of its work is now queued behind other callers.
     // §2.3a scopes the nudge to a refusal or a queue placement, so nothing is
     // attached here; the ledger already records the grant.
+    // **The count is taken on the handle this transaction is already writing
+    // through**, over the table the INSERT above has just touched, so it costs
+    // no round trip and cannot read a browser's state from a different instant
+    // than the grant did. The threshold is `doctor`'s own definition, imported
+    // rather than restated: two notions of "stranded" in one product is the
+    // defect this note exists to report.
+    const strandedBacklog = strandedBacklogNote(scope.db, browserId, settings.leaseSeconds, scope.adapter);
+    if (strandedBacklog !== undefined) {
+        // The ledger row is the part that is not optional. Each occurrence is
+        // invisible once the caller acts on it, which is exactly why it is
+        // recorded: without a record there is no way to learn that granting into
+        // a browser with a backlog has become common, and *common* is the signal
+        // that something upstream is killing callers mid-lease.
+        append(scope.db, {
+            kind: 'claim_granted',
+            outcome: 'allow',
+            adapter: scope.adapter,
+            claimId,
+            tabId,
+            sessionId: input.sessionId,
+            browserId,
+            detail: { note: 'stranded_backlog', stranded: strandedBacklog.stranded },
+        });
+    }
     return {
         value: {
             outcome: 'granted',
@@ -622,9 +647,47 @@ function grant(branch) {
             expiresAt,
             leaseSeconds: settings.leaseSeconds,
             storageSeed,
+            ...(strandedBacklog === undefined ? {} : { strandedBacklog }),
         },
     };
 }
+/**
+ * The note, when this browser is carrying a backlog worth telling a caller
+ * about.
+ *
+ * ── Why the threshold is one stranded tab ───────────────────────────────
+ *
+ * Not a round number chosen for feel. `doctor` already fails its check at
+ * one, on the reasoning that a report which is clean while any tab waits on a
+ * close nobody will answer is not reporting — and a second, higher threshold
+ * here would mean the claim path and the readiness check disagreeing about
+ * whether the same browser is healthy. **That disagreement is the defect this
+ * note exists to close**, so the two thresholds are the same threshold, read
+ * from the same function.
+ *
+ * The cost of saying it at one is a single extra line on a response, carrying
+ * a true fact, only when a fact is true. The cost of not saying it until some
+ * larger number is a caller working blind through exactly the band where the
+ * backlog is easiest to clear.
+ */
+function strandedBacklogNote(db, browserId, leaseSeconds, adapter) {
+    const stranded = countStrandedTabsFor(db, browserId, leaseSeconds);
+    if (stranded === 0) {
+        return undefined;
+    }
+    // The remedy names the browser rather than saying "the browser", so it can
+    // be run as typed. `doctor` sets that standard and it is why it diagnosed
+    // this in one call.
+    const remedy = adapter === 'cli'
+        ? `broker reconcile ${browserId}`
+        : `broker reconcile ${browserId}, from a shell`;
+    return {
+        stranded,
+        note: `note: ${String(stranded)} tab(s) on ${browserId} are stranded mid-close, which can leave ` +
+            'this browser unable to serve the lease just granted — a page call may report the browser ' +
+            `closed. Run \`${remedy}\` to clear them, and \`broker doctor\` to confirm.`,
+    };
+}
 /**
  * The queue placement: a lease and a key, and no tab.
  *

package/dist/src/service/operations/pages.js

@@ -2,12 +2,13 @@ import { updateSweptTabs } from "../arbitration.js";
 import { append } from "../events.js";
 import { extendLease, resolveLease } from "../leases.js";
 import { resolveOwnedTabOrRefuse } from "../ownership.js";
-import { disposeEvaluationResult, MAX_INLINE_RESULT_BYTES, validateCaptureMode, resolveReadArtifacts, validateAction, validateExpression, validateNavigationTarget, } from "../pages.js";
+import { disposeEvaluationResult, MAX_INLINE_RESULT_BYTES, validateCaptureMode, validateCaptureTier, resolveReadArtifacts, validateAction, validateExpression, validateNavigationTarget, validateNavigationWait, } from "../pages.js";
 import { recordTabOpened, reserveTab } from "../tabs.js";
 import { seedRecord } from "../storage-seed.js";
 import { BrokerError } from "../../errors.js";
 import { sanitiseLabel, stampFromInstant } from "../../artifacts/names.js";
 import { takeCapture } from "../../capture/pipeline.js";
+import { describeReduction } from "../../capture/tiers.js";
 import { capturesTakenBy, recordCapture } from "../capture-store.js";
 import { captureSource } from "../capture-seam.js";
 import { insertComparison } from "../comparison-store.js";
@@ -277,10 +278,22 @@ function withPageDriven(value, work) {
  *
  * The address is checked against the scheme allowlist before anything is
  * written, so a refused scheme leaves no trace but the refusal row.
+ *
+ * The wait is checked after the lease has been resolved rather than before,
+ * because what bounds it is that lease's own promised lifetime. It leaves the
+ * same absence behind: a refusal rolls the transaction back, taking the
+ * renewal with it, so the tab is never asked to go anywhere.
  */
 export function decideNavigate(scope, input) {
     const url = validateNavigationTarget(input.url);
     const { lease, tab, expiresAt } = admit(scope, input, 'navigate');
+    // Bounded by **this lease's own promised lifetime**, read off the row
+    // `admit` just renewed rather than from a settings snapshot. That is the
+    // same source every duration these handlers report comes from, and for the
+    // same reason: a renewal extends by the duration the caller was already
+    // told about, so a ceiling taken from the environment could differ from the
+    // lease the caller is actually holding.
+    const waitMs = validateNavigationWait(input.waitMs, lease.ttlSeconds);
     append(scope.db, {
         kind: 'navigate',
         outcome: 'allow',
@@ -289,14 +302,64 @@ export function decideNavigate(scope, input) {
         tabId: tab.tabId,
         sessionId: lease.sessionId,
         browserId: tab.browserId,
-        detail: { url },
+        // The wait is on the row when the caller asked for one, because the ledger
+        // is what answers *"what was this call actually given"* long after the
+        // call — and an argument that is invisible in the record is one nobody can
+        // check was honoured.
+        detail: { url, ...(waitMs === undefined ? {} : { waitMs }) },
     });
-    const work = afterCommitWork(scope, input, tab, (session, page) => session.navigate(page, url), lease.claimId);
+    // Where the page actually ended up, filled by the after-commit closure
+    // below. Undefined until the browser has answered — and permanently so on a
+    // build with no browser, which is what the getters' fallbacks are for.
+    let arrived;
+    const work = afterCommitWork(scope, input, tab, async (session, page) => {
+        // **The driver's answer is kept, not discarded.** It reports
+        // `page.url()` read after the load settles, plus the title and status,
+        // and this assignment is the whole of the redirect fix: the value was
+        // always available here and was being thrown away.
+        arrived = await session.navigate(page, url, waitMs);
+    }, lease.claimId);
     return {
-        value: withPageDriven({ claimId: lease.claimId, tabId: tab.tabId, expiresAt, url }, work),
+        value: withPageDriven({
+            claimId: lease.claimId,
+            tabId: tab.tabId,
+            expiresAt,
+            // Getters, for the reason `pageDriven` is one — see
+            // {@link withPageDriven}. Read eagerly they would always report the
+            // request and no title, because nothing has run yet. That eager read
+            // is precisely the defect this fix removes, so spelling these as
+            // plain properties would restore it while looking correct.
+            get url() {
+                return arrived?.url ?? url;
+            },
+            get title() {
+                return arrived?.title;
+            },
+            get status() {
+                return arrived?.status;
+            },
+        }, work),
         afterCommit: work.afterCommit,
     };
 }
+/**
+ * What an `emulate` result says about how long its effect lasts.
+ *
+ * A constant rather than an inline literal so there is one place to reword it.
+ *
+ * **What the tests hold it to is the meaning, not the wording.** They match the
+ * parts that have to survive a rewrite — that the effect is scoped to the
+ * connection, and that a path which works is named — rather than the sentence
+ * itself. Equality against the whole string would break on every harmless
+ * rewording while proving less: a note can keep every word and still stop
+ * telling a caller what to do. So a rewrite that keeps the meaning is free, and
+ * one that drops the working path fails.
+ */
+export const EMULATION_SCOPE_NOTE = 'This preference lasts as long as the connection that set it, not as long ' +
+    'as the tab. A later call from a separate invocation will not see it: the ' +
+    'tab survives and the emulation binding does not. To act on it, emulate ' +
+    'and capture within one invocation, or use the tool surface, where one ' +
+    'connection spans the calls.';
 /**
  * `act` (§3.6) — one interaction against an owned tab.
  *
@@ -319,7 +382,17 @@ export function decideAct(scope, input) {
     });
     const work = afterCommitWork(scope, input, tab, (session, page) => session.act(page, request), lease.claimId);
     return {
-        value: withPageDriven({ claimId: lease.claimId, tabId: tab.tabId, expiresAt, action: request.action }, work),
+        value: withPageDriven({
+            claimId: lease.claimId,
+            tabId: tab.tabId,
+            expiresAt,
+            action: request.action,
+            // Derived from the action that was validated, in the one place that
+            // knows which action ran — the same property `pageDriven` is built
+            // for. Spread away on the other twelve so the field's presence is
+            // itself the signal, with no "" to mistake for a scope nobody stated.
+            ...(request.action === 'emulate' ? { emulationScope: EMULATION_SCOPE_NOTE } : {}),
+        }, work),
         afterCommit: work.afterCommit,
     };
 }
@@ -478,9 +551,40 @@ export function decideCapture(scope, input) {
     // before ownership is checked and before a single row is written, so the
     // refusal leaves nothing behind but its own ledger entry.
     validateCaptureMode({ fullPage, selector: input.selector });
+    // Checked here for the same reason and in the same place. The pipeline's own
+    // `refuseArgumentMistakes` still decides whether the top rung carries its
+    // written reason — that rule is not duplicated here, only the one the type
+    // system cannot make on text arriving from a surface.
+    const tier = validateCaptureTier(input.tier);
+    // **Typed as the pipeline's options, not the driver's `CaptureRequest`.**
+    //
+    // This annotation is the defect's whole mechanism, so it is worth naming.
+    // `CaptureRequest` is the *driver* seam — what the browser is told — and it
+    // has no `tier` and no `reason`, correctly: a rung is a decision about the
+    // picture after the shutter, not something a browser is asked for. The
+    // literal below nevertheless packed both in, and the excess-property check
+    // that would ordinarily catch that **does not apply to conditionally spread
+    // properties**, so it compiled silently. The value then had nowhere to go,
+    // and the one call site downstream quietly took only the two fields the
+    // driver type admits.
+    //
+    // Annotating with the type that actually consumes these fields is what makes
+    // the same mistake a compile error next time rather than an inert argument.
     const request = {
         fullPage,
         ...(input.selector === undefined ? {} : { selector: input.selector }),
+        ...(tier === undefined ? {} : { tier }),
+        // Carried whenever it was given, rather than only alongside a tier.
+        //
+        // **A reason passed without a tier is still discarded**, and that is the
+        // pipeline's existing rule rather than something introduced here: it
+        // records a reason "only ever on the tier that requires it", because a
+        // reason attached to a rung nobody had to justify is not evidence of an
+        // escalation. Passing it on regardless keeps that decision in the one
+        // place that makes it, instead of adding a second, quieter version of it
+        // here — the value reaches the rule either way, and this layer does not
+        // get to have an opinion about which reasons are worth carrying.
+        ...(typeof input.reason === 'string' ? { reason: input.reason } : {}),
     };
     const { lease, tab, expiresAt } = admit(scope, input, 'capture');
     append(scope.db, {
@@ -529,16 +633,57 @@ export function decideCapture(scope, input) {
         const taken = await takeCapture({ tabs: session, artifacts }, lease.claimId, page, {
             fullPage,
             ...(request.selector === undefined ? {} : { selector: request.selector }),
+            // **The rung and its justification, which used to stop here.**
+            //
+            // `request` was built with both a dozen lines above — `tier`
+            // validated by `validateCaptureTier`, `reason` carried whenever it
+            // was given — and then this call site spread only `fullPage` and
+            // `selector`, so both died one line before the pipeline that
+            // honours them. Every capture was consequently taken at the default
+            // rung no matter what the caller asked for.
+            //
+            // That is the inert-argument defect `check:argument-reachability`
+            // exists to prevent, one layer below where that check looks: its
+            // rule is that a declared argument is read *at the bridge*, and
+            // `tier` is read there, so the check passed while the value went
+            // nowhere. It is worse than the `wait_ms` case that motivated the
+            // check, because `tier="max"` charges the caller a written
+            // justification first — the caller pays for the escalation, is told
+            // it was accepted, and receives the unescalated picture.
+            ...(request.tier === undefined ? {} : { tier: request.tier }),
+            ...(request.reason === undefined ? {} : { reason: request.reason }),
         }, takenBefore);
         // The row last, describing a file that is already on disk. See
         // `capture-store.ts` for why that order is the rule and not a preference.
         recordCapture(scope.db, lease.claimId, tab.tabId, taken.telemetry);
+        // **What the browser produced, and by how much it was shrunk to fit the
+        // rung** — present exactly when the two differ.
+        //
+        // The pipeline has computed `sourceWidth`/`sourceHeight` all along and
+        // `captures` has stored them all along; this object simply never passed
+        // them on, so the one layer that talks to the caller was the one layer
+        // that could not tell a reduced picture from an unreduced one. A
+        // `full_page` capture of a long article consequently came back at about
+        // sixteen per cent, complete and undistorted and entirely illegible,
+        // with nothing in the response saying so.
+        const reduction = describeReduction({ width: taken.sourceWidth, height: taken.sourceHeight }, { width: taken.width, height: taken.height }, taken.tier);
         written = {
             captureId: taken.captureId,
             path: taken.path,
             width: taken.width,
             height: taken.height,
             bytes: taken.bytes,
+            // Echoed on every capture, reduced or not, because "what did the page
+            // actually measure" is a fact a caller may want either way — and
+            // because a field that appears only on the bad case is a field nobody
+            // learns to read.
+            sourceWidth: taken.sourceWidth,
+            sourceHeight: taken.sourceHeight,
+            tier: taken.tier,
+            // Absent when nothing was shrunk. Its **presence** is the signal, which
+            // is why it is not a `scale: 1` that a caller would learn to skip.
+            ...(reduction === undefined ? {} : { reduced: reduction }),
+            compareHint: `to diff a later capture against this one, pass compare_to: ${taken.captureId}`,
         };
         // ── The diff, when one was asked for (§3.11, §1.9) ──────────────────
         //

package/dist/src/service/operations/status.js

@@ -57,6 +57,14 @@ export function decideStatus(scope, input) {
             checkBackSeconds: checkBack,
             checkBack: advice,
             ...(tab === undefined ? {} : { tabId: tab.tabId }),
+            // **`unknown` rather than `live`, and the difference is the whole
+            // defect.** Everything above is derived from rows and a clock, which is
+            // what a lease is; whether the browser still exists is a fact about the
+            // operating system and cannot be read here without breaking
+            // `arbitration.no_browser_io`. Claiming `live` from this seat would be
+            // asserting the very thing that was measured false — a store believing
+            // in a browser that had been dead for minutes.
+            browser: 'unknown',
         },
     };
 }

package/dist/src/service/pages.js

@@ -98,6 +98,59 @@ export function validateNavigationTarget(url) {
     }
     return candidate;
 }
+/**
+ * Check how long a navigation may take, before anything navigates.
+ *
+ * Returns the wait in milliseconds, or `undefined` when the caller expressed
+ * no opinion and the browser library's own default should apply.
+ *
+ * ── Why the lease is the ceiling, rather than a number somebody picked ──
+ *
+ * `ttlSeconds` is the lifetime this particular lease was promised, converted
+ * to milliseconds. It is the number the bound is *about*: a lease is a tab
+ * (§2.3) and capacity is a fixed total across the browsers (§6.2), so a caller
+ * permitted to wait longer than its own lease lives would sit inside a single
+ * call while the tab it is holding becomes reclaimable — which is the one
+ * thing an expiry exists to make impossible, and it would be reached without
+ * the caller doing anything wrong.
+ *
+ * Any other ceiling would be a literal, and a literal is wrong in both
+ * directions at once: too low and it refuses a slow page an installation with
+ * long leases can perfectly well afford, too high and it reintroduces the
+ * overrun. Derived from the lease, it moves with the configuration that sets
+ * lease lifetimes and needs no separate setting of its own.
+ *
+ * **The lease's row rather than the environment**, which is the discipline
+ * every duration these operations report already keeps: the call carrying the
+ * wait renews the lease by the duration that lease was granted for, so a
+ * ceiling read from the environment could name a lifetime the caller is not
+ * actually holding.
+ *
+ * A wait exactly equal to the lease is allowed rather than refused. The call
+ * carrying it renews the lease first, so both are measured from that instant
+ * and equality is the exact edge rather than an overrun.
+ */
+export function validateNavigationWait(waitMs, ttlSeconds) {
+    if (waitMs === undefined || waitMs === null)
+        return undefined;
+    const maximumMs = ttlSeconds * 1000;
+    // The syntax as well as the semantics, which is the lesson the viewport and
+    // emulate refusals below were both rewritten for: a caller that cannot see
+    // the accepted range from the message has no way to converge except by
+    // guessing, and a refusal that leaves it guessing costs more than the
+    // argument saves.
+    if (typeof waitMs !== 'number' || !Number.isInteger(waitMs) || waitMs <= 0) {
+        throw new PageRefusal('navigate.wait_bounded', `How long to wait for a page is a whole number of milliseconds from 1 to ${String(maximumMs)}, for example \`--wait-ms 5000\`.`, { waitMs, minimumMs: 1, maximumMs });
+    }
+    if (waitMs > maximumMs) {
+        // Named separately from the shape refusal above because the caller's
+        // mistake is a different one: the value is well formed and simply asks for
+        // more than a lease lasts, so the sentence says what the ceiling is and
+        // where it comes from rather than how to write a number.
+        throw new PageRefusal('navigate.wait_bounded', `A wait of ${String(waitMs)}ms is longer than a lease lives (${String(maximumMs)}ms), so the tab would be reclaimable before the navigation returned. Ask for at most ${String(maximumMs)}ms.`, { waitMs, minimumMs: 1, maximumMs });
+    }
+    return waitMs;
+}
 /* ───────────────────────── act (#22, #61–#64) ───────────────────────── */
 /**
  * The refusal that **lists every action by name**.
@@ -581,6 +634,34 @@ export function validateCaptureMode(options) {
         throw new PageRefusal('capture.exclusive_mode', 'A capture takes a selector or the whole page, and this call asked for both. They are different pictures rather than different amounts of one, so nothing here can pick for you: ask for the element, or ask for the page.', { fullPage: true, selector: options.selector });
     }
 }
+/**
+ * The resolution rung a capture was asked for, checked before the pipeline
+ * indexes anything by it.
+ *
+ * ── Why this guard is here and not left to the pipeline ─────────────────
+ *
+ * The pipeline types the field {@link RequestableTier}, so within the service
+ * an unknown rung is a compile error and no check is needed. It stops being a
+ * compile-time question at the surface: a tool call and a command line both
+ * arrive as free text, and an unrecognised word typed by a caller would reach
+ * `TIER_LONGEST_EDGE[tier]`, resolve to `undefined`, and be handed to the
+ * downscaler as a target edge. That is a bad answer arriving quietly, which is
+ * the same family as the inert argument this pair was wired for.
+ *
+ * **`default` is refused as a value even though it is a real tier**, because
+ * it is the rung you get by passing nothing. `RequestableTier` excludes it on
+ * the seam deliberately — "there is deliberately no way to ask for the default
+ * explicitly" is a compile error rather than a line in a document — and this
+ * refusal keeps that true for callers who reach the service through text.
+ */
+export function validateCaptureTier(tier) {
+    if (tier === undefined || tier === null)
+        return undefined;
+    if (tier !== 'detail' && tier !== 'max') {
+        throw new PageRefusal('capture.tier_known', 'A capture tier is "detail" or "max". Omit it for the default resolution — there is no way to ask for the default by name, because passing nothing is how you get it. "max" additionally requires reason, a written explanation in your own words.', { tier, accepted: ['detail', 'max'] });
+    }
+    return tier;
+}
 /**
  * Decide whether a result comes back inline or goes to a file.
  *

package/dist/src/service/reconcile.js

@@ -82,7 +82,9 @@
  * on the assumption the seam holds up its end.
  */
 export function decideReconciliation(pages, recorded) {
-    const skippedOpening = recorded.filter((tab) => tab.driverTabId === null).map((tab) => tab.tabId);
+    const skippedOpening = recorded
+        .filter((tab) => tab.driverTabId === null)
+        .map((tab) => ({ tabId: tab.tabId, sessionId: tab.sessionId }));
     // Every driver name a live lease claims. Built from the rows that have one,
     // which by §1.4's check is exactly the rows that are not `opening`.
     const owned = new Set(recorded
@@ -123,7 +125,8 @@ export function readRecordedTabs(db, browserId) {
     return db
         .prepare(`SELECT tabs.id AS tabId,
               tabs.driver_tab_id AS driverTabId,
-              tabs.claim_id AS claimId
+              tabs.claim_id AS claimId,
+              claims.session_id AS sessionId
          FROM tabs
          JOIN claims ON claims.id = tabs.claim_id
         WHERE tabs.browser_id = ?
@@ -132,6 +135,57 @@ export function readRecordedTabs(db, browserId) {
         ORDER BY tabs.id`)
         .all(browserId);
 }
+/**
+ * Settle rows stranded at `closing` whose page the browser does not have.
+ *
+ * ── Why the vanished-tab path cannot reach these ────────────────────────
+ *
+ * {@link readRecordedTabs} requires `claims.state = 'active'`, and rightly:
+ * a lapsed lease's rows are the sweep's business, not reconciliation's. But
+ * that is exactly the population that strands. A lease ends, its tab is moved
+ * to `closing`, and if the answer is never written back the row is left in a
+ * state meaning "waiting for the tool" — attached to a lease that is no
+ * longer active, and therefore invisible to every later reconciliation.
+ *
+ * A store was found holding 22 such rows, the oldest two days old, every one
+ * with `close_attempts = 0`. The pages had been closed by hand; the rows
+ * could not be reached by anything.
+ *
+ * ── Why this is safe to settle without asking again ─────────────────────
+ *
+ * The caller has just asked the browser what it has open, and passes the
+ * driver names it answered with. A row whose name is not in that list
+ * describes a page this browser does not have, so there is no round trip
+ * outstanding and nothing to wait for — the same reasoning
+ * {@link applyReconciliation} uses for a vanished page, and the sweep uses
+ * for a tab that never opened.
+ *
+ * **A row whose name IS in the list is left alone.** Its page exists, the
+ * close may genuinely still be in flight, and settling it would claim an
+ * answer nobody has given.
+ */
+export function settleStrandedTabs(db, browserId, openDriverTabIds, at) {
+    const stranded = db
+        .prepare(`SELECT tabs.id AS tabId, tabs.driver_tab_id AS driverTabId
+         FROM tabs
+         JOIN claims ON claims.id = tabs.claim_id
+        WHERE tabs.browser_id = ?
+          AND tabs.state = 'closing'
+          AND claims.state <> 'active'
+        ORDER BY tabs.id`)
+        .all(browserId);
+    const open = new Set(openDriverTabIds);
+    const gone = stranded.filter((tab) => tab.driverTabId === null || !open.has(tab.driverTabId));
+    if (gone.length === 0) {
+        return 0;
+    }
+    const placeholders = gone.map(() => '?').join(', ');
+    db.prepare(`UPDATE tabs
+        SET state = 'closed', closed_at = ?, updated_at = ?
+      WHERE id IN (${placeholders})
+        AND state = 'closing'`).run(at, at, ...gone.map((tab) => tab.tabId));
+    return gone.length;
+}
 /**
  * Settle the rows whose pages are gone, and end the leases that held them.
  *
@@ -155,6 +209,24 @@ export function readRecordedTabs(db, browserId) {
  * | `updateSweptTabs` | The lease ended; is there a page to close? | `closing` — the tool is about to be asked |
  * | this | The page is already gone | `closed` — there is nothing to ask |
  *
+ * **`closing` appears in the predicate, and no row reaches it in that
+ * state.** The rows here come from {@link readRecordedTabs} by way of
+ * {@link decideReconciliation}, and that read requires `tabs.state IN
+ * ('opening', 'open')` — so the third value in the predicate below matches
+ * nothing this caller can supply. It is kept as a bound on what the write is
+ * permitted to touch rather than as a population it serves: the statement
+ * says which states this function may move a row out of, and a future caller
+ * that widens its own read cannot silently reopen a `closed` row through it.
+ *
+ * **The stranded-`closing` population is {@link settleStrandedTabs}'s**, not
+ * this function's, and the distinction is load-bearing. Those rows belong to
+ * leases that have already ended, which is precisely why `readRecordedTabs`
+ * (`claims.state = 'active'`) cannot see them and why they need their own
+ * pass. A store was found holding 22 of them, each still occupying its slot
+ * in the partial unique index on `(browser_id, driver_tab_id)`. Reading that
+ * story as this function's would leave the impression the gap is covered
+ * here, and it is not.
+ *
  * A vanished page has no round trip outstanding, so `closing` would assert
  * one that is not, and the row would wait forever for an answer nobody is
  * coming to give — the exact reasoning the sweep uses for a tab that never
@@ -193,7 +265,7 @@ export function applyReconciliation(db, vanished, at) {
     db.prepare(`UPDATE tabs
         SET state = 'closed', closed_at = ?, updated_at = ?
       WHERE id IN (${tabPlaceholders})
-        AND state IN ('opening', 'open')`).run(at, at, ...tabIds);
+        AND state IN ('opening', 'open', 'closing')`).run(at, at, ...tabIds);
     // The lease goes with the tab, because a lease *is* a tab (§2.3): a lease
     // whose tab is gone owns nothing while still counting against the budget,
     // which §3.13 names as a state that should not exist.

package/dist/src/service/runtime.js

@@ -1,3 +1,4 @@
+import { recordTabCloseFailed, recordTabClosed } from "./arbitration.js";
 import { readEnvironment } from "../config/environment.js";
 import { prepareStore } from "../store/open.js";
 import { ArtifactStore } from "../artifacts/store.js";
@@ -70,6 +71,14 @@ export async function createRuntime(options) {
         environment,
         adapter: options.adapter,
         session: browsers.session,
+        // **What makes `status` able to tell the truth about a dead browser.**
+        // Supplied here rather than defaulted inside the broker for the reason
+        // the option's own comment gives: a build that cannot look must report
+        // `unknown` rather than claim the browser is fine. This build can look,
+        // so it does. Note this is the provider's `liveness`, which asks the
+        // operating system — not its memoised session, which is the very thing
+        // that keeps presenting a dead browser as a working connection.
+        checkBrowser: browsers.liveness,
         artifacts,
         // The same provider closes the tabs the sweep orphaned. Without one,
         // `SCHEMA.md` §2.4b's "a leaked tab is not a leaked lease" describes a
@@ -79,8 +88,24 @@ export async function createRuntime(options) {
         closeTab: async (tab) => {
             const session = await browsers.session(tab.browserId);
             const opened = await resolveDriverTab(store.db, tab.tabId);
-            if (opened !== undefined) {
+            if (opened === undefined) {
+                return;
+            }
+            // **The answer is written down either way.** `closing` means "the tool
+            // was asked and has not answered", so a close that returns and is never
+            // recorded leaves a row saying that forever — which is what happened,
+            // 22 rows deep, until a person noticed his browser had filled with
+            // pages no lease owned.
+            //
+            // A failure is recorded rather than thrown: §2.4b's "a leaked tab is
+            // not a leaked lease" means the capacity is already back, and failing
+            // the release over the page would fail a call that did its job.
+            try {
                 await session.closeTab({ browser: tab.browserId, driverTabId: opened });
+                recordTabClosed(store.db, tab.tabId, new Date().toISOString());
+            }
+            catch {
+                recordTabCloseFailed(store.db, tab.tabId, new Date().toISOString());
             }
         },
     });

package/dist/src/service/tabs.js

@@ -121,3 +121,73 @@ export function recordTabOpened(db, tabId, driverTabId) {
         throw new Error(`Tab ${tabId} was not awaiting an open, so the driver name could not be recorded against it.`);
     }
 }
+/**
+ * How many tabs on one browser are waiting on a close that will not come.
+ *
+ * ── Why this is one function and not two ────────────────────────────────
+ *
+ * `broker doctor` and the claim grant both have to answer *"is this browser
+ * carrying a backlog of stranded tabs"*, and a product holding two notions of
+ * "stranded" would be the same defect the backlog itself caused: a caller
+ * told one number by one surface and a different number by another has no way
+ * to tell which is the real one. So the predicate lives here once, and both
+ * read it.
+ *
+ * ── Why the threshold is a lease's own lifetime ─────────────────────────
+ *
+ * Taken from `doctor`'s existing definition rather than invented alongside
+ * it. `closing` means the tool was asked and has not answered — a transient
+ * state measured in a round trip. The honest boundary between "a close is in
+ * flight" and "a close is never happening" 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.
+ *
+ * The comparison is on `updated_at`, which is when the row was moved to
+ * `closing`. A round trip still inside the window is deliberately not
+ * counted, because reporting one would make a healthy release look like a
+ * fault.
+ */
+export function countStrandedTabsFor(db, browserId, leaseSeconds, at = new Date()) {
+    const cutoff = new Date(at.getTime() - leaseSeconds * 1000).toISOString();
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n
+         FROM tabs
+        WHERE browser_id = ?
+          AND state = 'closing'
+          AND updated_at < ?`)
+        .get(browserId, cutoff);
+    return row?.n ?? 0;
+}
+/**
+ * The stranded backlog broken down per browser, heaviest first.
+ *
+ * ── Why a breakdown rather than a total ─────────────────────────────────
+ *
+ * A total is not actionable when the remedy is per-browser. `doctor`'s
+ * remedy line says to run `broker reconcile` against each browser, but a
+ * single total cannot say which ones still need it: an operator who
+ * reconciled `regular` and saw the count fall from 29 to 13 reasonably
+ * concluded reconcile had not worked, when in fact the remaining 13 were all
+ * on `private` and the run had done exactly what it said.
+ *
+ * **Grouped rather than asked per browser from a configured list**, because
+ * the browsers are a configured list per kind and not a fixed pair — a
+ * breakdown assembled from the list this build happens to know about would
+ * silently omit a backlog on a browser that had been reconfigured away, which
+ * is the population most likely to be stranded.
+ *
+ * Only browsers carrying a backlog appear. A row reading zero is not a
+ * finding, and listing every configured browser on every healthy run would
+ * bury the one line that matters.
+ */
+export function strandedTabsByBrowser(db, leaseSeconds, at = new Date()) {
+    const cutoff = new Date(at.getTime() - leaseSeconds * 1000).toISOString();
+    return db
+        .prepare(`SELECT browser_id AS browserId, COUNT(*) AS stranded
+         FROM tabs
+        WHERE state = 'closing'
+          AND updated_at < ?
+        GROUP BY browser_id
+        ORDER BY COUNT(*) DESC, browser_id`)
+        .all(cutoff);
+}