browser-broker 0.1.0 → 0.3.1

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.
  *

package/dist/src/service/bridge.js

@@ -175,6 +175,19 @@ export function serviceFor(options) {
                         key,
                         tabId: tabForKey(db, key),
                         url: argument(args, 'url'),
+                        // **Coercion only, never validation** — the same split
+                        // `viewportFrom` documents at length, and here for the same
+                        // reason. A command line produces flat strings and nothing else,
+                        // so a wait that was never coerced would be a number no
+                        // command-line caller could type: it would reach the integer guard
+                        // as text and be refused however correctly it was written.
+                        //
+                        // Whether the number is whole, positive and within the lease is
+                        // the operation's decision, on the ledger. Unparseable text
+                        // becomes `NaN` and is handed on deliberately, so it fails that
+                        // guard and produces the refusal naming the range rather than a
+                        // different one invented here.
+                        waitMs: asInteger(argument(args, 'wait_ms', 'waitMs')),
                     })),
                 };
             }
@@ -222,6 +235,22 @@ export function serviceFor(options) {
                 // told the diff is available, passes it, and gets a capture with no
                 // comparison and nothing saying why.
                 const compareTo = argument(args, 'compare_to', 'compareTo');
+                // The resolution rung and the written justification the top rung
+                // requires. **Coercion only, never validation**, the same split the
+                // wait above keeps: `validateCaptureTier` names the accepted words and
+                // the pipeline decides whether a reason is owed, so an unrecognised
+                // value is handed on deliberately and reaches the rule that can
+                // explain it.
+                //
+                // Read here because the ladder they drive was built end to end and
+                // connected to nothing: the pipeline refuses the top rung without a
+                // reason, the `captures` table carries the column, and the telemetry
+                // rollups query it — while no surface could populate either field. An
+                // escalation rollup with no way to escalate does not report an empty
+                // result, it reports "nobody escalates", which is a fact that is not
+                // one.
+                const tier = argument(args, 'tier');
+                const reason = argument(args, 'reason');
                 return {
                     ...(await broker.capture({
                         key,
@@ -229,6 +258,8 @@ export function serviceFor(options) {
                         ...(fullPage === undefined ? {} : { fullPage: asBoolean(fullPage) }),
                         ...(typeof selector === 'string' ? { selector } : {}),
                         ...(typeof compareTo === 'string' && compareTo.length > 0 ? { compareTo } : {}),
+                        ...(tier === undefined ? {} : { tier }),
+                        ...(reason === undefined ? {} : { reason }),
                     })),
                 };
             }
@@ -358,8 +389,8 @@ function actionFrom(args) {
     const targetRef = argument(args, 'target_ref', 'targetRef');
     const viewport = viewportFrom(args);
     const preferences = preferencesFrom(args);
-    const response = argument(args, 'response');
-    const fields = argument(args, 'fields');
+    const response = responseFrom(args);
+    const fields = fieldsFrom(args);
     return {
         action,
         ...(ref === undefined ? {} : { ref }),
@@ -429,6 +460,121 @@ function viewportFrom(args) {
     }
     return undefined;
 }
+/**
+ * The answer a `dialog` gives, assembled from flat flags.
+ *
+ * The same unreachability {@link viewportFrom} exists for, and it survived the
+ * pull request that fixed that one — recorded there as "known and deliberately
+ * not fixed here", which is a reasonable thing to write once and a poor thing
+ * to leave true.
+ *
+ * `validateAction` wants `response: { accept, promptText? }`, an object whose
+ * first member is a **boolean**. A command line produces flat strings, so
+ * `--response accept`, `--value accept` and `--accept true` all arrived as
+ * something that is not an object and drew the identical refusal:
+ *
+ * > Answering a dialog says whether to accept it or dismiss it.
+ *
+ * Which is what the caller was trying to say. As with a resize, the message
+ * describes the semantics and never the syntax, and no syntax existed.
+ *
+ * `--accept` and `--dismiss` are the two things a caller means, written as
+ * the two words the refusal itself uses. `--prompt-text` carries what to type
+ * before accepting. **Coercion only** — that text may not accompany a
+ * dismissal, and that stays the operation's decision, on the ledger, rather
+ * than being re-decided here.
+ */
+function responseFrom(args) {
+    const given = argument(args, 'response');
+    if (given !== undefined && typeof given === 'object') {
+        return given;
+    }
+    const promptText = argument(args, 'prompt_text', 'promptText');
+    const accept = acceptFrom(args, given);
+    if (accept === undefined) {
+        return given;
+    }
+    return {
+        accept,
+        ...(typeof promptText === 'string' ? { promptText } : {}),
+    };
+}
+/**
+ * Whether the caller said accept or dismiss, across the spellings a person
+ * reaches for. Anything else is left alone so the operation refuses it.
+ */
+function acceptFrom(args, given) {
+    const acceptFlag = argument(args, 'accept');
+    const dismissFlag = argument(args, 'dismiss');
+    // Both flags names opposite intentions, so neither is the answer. Resolving
+    // them by which was read first hands the caller a decision it never made,
+    // and about the one thing a dialog answer decides — the same reasoning that
+    // refuses prompt text alongside a dismissal rather than picking one.
+    //
+    // **Nothing is refused here, deliberately.** This function coerces; the
+    // operation decides. Yielding `undefined` for an unanswerable pair leaves
+    // the assembled response without an `accept`, which the dialog operation
+    // already refuses by name — so the rule stays spelled in one place and
+    // arrives identically whichever route a caller came in on. Inventing a
+    // second rule at this layer would make the same mistake refuse differently
+    // depending on the transport.
+    if (acceptFlag !== undefined && dismissFlag !== undefined) {
+        return undefined;
+    }
+    if (acceptFlag !== undefined) {
+        return acceptFlag === '' || acceptFlag === true || acceptFlag === 'true' ? true : undefined;
+    }
+    if (dismissFlag !== undefined) {
+        return dismissFlag === '' || dismissFlag === true || dismissFlag === 'true' ? false : undefined;
+    }
+    const word = typeof given === 'string' ? given : argument(args, 'value');
+    if (word === 'accept')
+        return true;
+    if (word === 'dismiss')
+        return false;
+    return undefined;
+}
+/**
+ * The fields a `fill_form` fills, assembled from repeated flat pairs.
+ *
+ * Unreachable for the same reason and fixed the same way: the operation wants
+ * an **array of objects**, and a command line has only strings.
+ *
+ * `--field ref=value` is the form, repeated once per field, because that is
+ * what the operation is — a list of pairs — and because a caller already types
+ * `--target` and `--value` for the single-field verbs. Only the first `=`
+ * separates, so a value may contain one.
+ *
+ * **Coercion only.** The bound on how many fields a batch carries, and whether
+ * a reference is a reference, stay inside the operation.
+ */
+function fieldsFrom(args) {
+    const given = argument(args, 'fields');
+    if (given !== undefined && Array.isArray(given)) {
+        return given;
+    }
+    const pairs = argument(args, 'field');
+    const list = Array.isArray(pairs)
+        ? pairs
+        : pairs === undefined
+            ? []
+            : [pairs];
+    if (list.length === 0) {
+        return given;
+    }
+    return list.map((pair) => {
+        if (typeof pair !== 'string') {
+            return pair;
+        }
+        const split = pair.indexOf('=');
+        if (split < 0) {
+            // No separator is not a pair. Handed on so the operation refuses it
+            // and names which field, rather than being silently dropped here.
+            return { ref: pair };
+        }
+        return { ref: pair.slice(0, split), value: pair.slice(split + 1) };
+    });
+}
 /**
  * The media preferences an `emulate` sets, assembled from flat flags.
  *

package/dist/src/service/broker.js

@@ -95,7 +95,58 @@ export function createBroker(options) {
             }
             return result;
         },
-        status: (input) => run('status', input),
+        /**
+         * **After the call returns, so the probe is outside the transaction.**
+         * The same shape `claim` above uses for its seed, and for a stricter
+         * reason: this one talks to a browser, and
+         * `arbitration.no_browser_io` (§2.4b) is what keeps that out of the
+         * arbitration transaction.
+         *
+         * A queued lease is not probed. It holds no tab and is waiting for
+         * capacity rather than using it, so a browser that is down is the
+         * ordinary reason the queue exists — reporting a waiting caller as
+         * expired would end a lease that has nothing wrong with it.
+         */
+        status: async (input) => {
+            const result = await run('status', input);
+            if (result.state !== 'active' || options.checkBrowser === undefined) {
+                return result;
+            }
+            const liveness = await options.checkBrowser(result.browserId);
+            if (liveness !== 'gone') {
+                return { ...result, browser: liveness };
+            }
+            // **The lease is reported `expired`, and this writes nothing.**
+            //
+            // Two things are true at once and the split matters: the browser is
+            // gone, so this lease cannot do anything a lease is for; but the
+            // reclamation that ends leases is the sweep's, inside the arbitration
+            // transaction, and this code is deliberately outside it. Writing here
+            // would be a second writer of lease state racing the one that owns it.
+            //
+            // So this reports the truth without asserting authorship of it, which
+            // is exactly what §2.4's standing rule licenses: **stored state is
+            // provisional, derived state is the truth.** A row saying `active`
+            // against a dead browser is provisional in the same way a lapsed row
+            // is, and a reader that derives correctly renders the same picture
+            // whether or not the row has been swept.
+            //
+            // `tabId` is dropped rather than carried: it names a page in a browser
+            // that does not exist, and handing it back invites a caller to address
+            // it. Nothing owns it to close — the browser took it.
+            const { tabId, ...withoutTab } = result;
+            // Read so that dropping it is a decision the compiler can see rather
+            // than an unused binding a later cleanup would "tidy" back into the
+            // result. The tab is real in the store; what is gone is the browser
+            // holding it, which is why it is omitted here and not closed here.
+            void tabId;
+            return {
+                ...withoutTab,
+                state: 'expired',
+                browser: 'gone',
+                checkBack: `The ${result.browserId} browser this lease was held against is not running: its endpoint did not answer, or answered as a different browser. The lease cannot be used, so it is reported expired rather than active however much time is left on it. Release this lease and claim again — a claim is what starts a browser, and the next one will start a fresh one.`,
+            };
+        },
         release: (input) => run('release', {
             ...input,
             settings,

package/dist/src/service/browser-session.js

@@ -47,6 +47,30 @@ import { StartupRefusal } from "../errors.js";
  * The memo holds the **promise**, not the resolved session, so two verbs
  * racing in the same process await one acquisition rather than starting two.
  *
+ * ── …but a memoised session is checked before it is handed back ──────────
+ *
+ * One session per process is right; *trusting* it for the life of the process
+ * is not. A session is a connection, and a connection can end while the
+ * browser it points at is still running — so a memo that is never revalidated
+ * hands a dead connection to every page verb until the process exits.
+ *
+ * That is not hypothetical and it is why this check exists. It is the
+ * difference between the two surfaces: the command line is one process per
+ * command, so its memo cannot outlive the verb that created it and the state
+ * is unreachable there. The tool surface serves a whole session from one
+ * process, so it is the surface where a stale memo is not merely possible but
+ * eventually certain — and a caller doing the obvious correct thing (release,
+ * claim again, drive the page) got the same dead connection every time, with
+ * no way back from that surface at all.
+ *
+ * So {@link BrowserSessions.session} asks {@link BrowserSession.isConnected}
+ * before returning a settled entry and drops it if the answer is no. **This
+ * is a different question from {@link BrowserSessions.liveness}**, which asks
+ * the machine whether a browser is running: in the state above the browser is
+ * running, so liveness says `live` and correctly evicts nothing. Both checks
+ * are needed because a browser and a connection can each die without the
+ * other.
+ *
  * ── A failed acquisition is not cached ───────────────────────────────────
  *
  * If acquiring throws, the memo is cleared, so the next call tries again. The
@@ -82,20 +106,69 @@ export function browserSessionProvider(options) {
                     // BrowserSessionProviderOptions.artifacts} for why this is the
                     // shared tree rather than one lease's.
                     { outputDirectory: path.join(options.artifacts.root, 'snapshots') }),
-            // **The signed-in engine, carried from this process's one environment
-            // snapshot** (§6.3, `DECISIONS.md` §13i). One driver serves every
-            // browser in this process, so the kind-specific engine cannot be chosen
-            // per session here — see the note on `RealDriverOptions.engine` for
-            // what the value does and does not do, which is what makes one engine
-            // per process the honest shape rather than a shortcut.
-            engine: options.environment.regularBrowserEngine,
         });
     const inFlight = new Map();
     const settled = new Map();
     const session = (browser) => {
         const existing = inFlight.get(browser);
         if (existing !== undefined) {
-            return existing;
+            // ── The memo is checked before it is trusted ──────────────────────
+            //
+            // **This is what stops a dead connection being handed out for the life
+            // of a long-running process.** A settled session is a live connection
+            // over the debugging protocol, and a connection can end while the
+            // browser it points at carries on perfectly well — a browser restart, a
+            // closed target, a dropped protocol socket. When that happens the
+            // session object is still here, still resolved, and every page verb
+            // performed over it fails with `Target page, context or browser has
+            // been closed`.
+            //
+            // Nothing else in this file can catch that state, which is why it
+            // survived a previous fix. The `.catch` below clears only a *rejected*
+            // acquisition, and a session that resolved and later died never
+            // rejects. {@link BrowserSessions.liveness} clears a dead entry, but it
+            // asks the machine whether a browser is **running** — which in this
+            // state is `true` — and it is reached only from `status`, never from a
+            // page verb.
+            //
+            // ── Why it is safe to consult on the hot path ─────────────────────
+            //
+            // `isConnected` reads a flag the connection already maintains. It
+            // performs no input/output and cannot throw, so this adds no round trip
+            // to a call that is about to make several.
+            //
+            // ── Every session answers, because the member is required ─────────
+            //
+            // It was optional first, so that a source unable to observe its
+            // connection could stay silent and be assumed usable. That let the one
+            // production session omit it entirely while `tsc` stayed quiet, and
+            // this guard then took the assume-usable branch on every real call —
+            // shipping a fix that changed nothing. A source that cannot tell now
+            // returns `true` explicitly instead, so the permissive answer is a
+            // decision in the source rather than a hole in it.
+            //
+            // ── Only a settled session can be judged ──────────────────────────
+            //
+            // An entry still in flight has no session to ask yet, and it is
+            // returned untouched: two verbs racing must await one acquisition
+            // rather than starting two, which is the property the promise-valued
+            // memo exists for. An acquisition in progress cannot be stale.
+            const open = settled.get(browser);
+            if (open === undefined || open.isConnected()) {
+                return existing;
+            }
+            // ── Dropped, not detached, and nothing is launched here ───────────
+            //
+            // There is nothing to detach from: the connection is the thing that
+            // ended. Dropping both entries sends this very call through `acquire`,
+            // which makes its own observation and wins or loses the launch race in
+            // the store like any other caller — the same recovery `liveness` takes,
+            // for the same reason it takes it that way. **No browser is ended**
+            // (`browser_scoped.never`, §7.3) and none is started from here: a
+            // second process launching against one profile directory is the
+            // measured silent-collision failure the race exists to prevent.
+            settled.delete(browser);
+            inFlight.delete(browser);
         }
         const acquiring = acquire(driver, browser, options)
             .then((acquired) => {
@@ -111,8 +184,74 @@ export function browserSessionProvider(options) {
         inFlight.set(browser, acquiring);
         return acquiring;
     };
+    const liveness = async (browser) => {
+        const isRunning = options.isRunning ?? browserIsRunning;
+        const profileDir = profileDirectory(options.environment.profileRoot, browser);
+        try {
+            const record = await isRunning(profileDir);
+            // The same two-condition reading `acquire` applies to its own
+            // observation: a record with no identifier failed the identity half,
+            // and a record that failed either half is stale (§1.2c). Stale means
+            // the browser is treated as not running.
+            if (record !== undefined && record.browserUuid !== undefined) {
+                return 'live';
+            }
+            // ── The recovery path, and it is one line for a reason ────────────
+            //
+            // **Forgetting the dead session is what makes reclaiming work.** The
+            // memoised entry is a connection to a browser that is gone, and it is
+            // handed to every page verb for the life of this process — so without
+            // this, a caller that does the obvious correct thing (release, claim
+            // again, drive the page) gets the same dead attachment each time and
+            // there is no way back from the tool surface at all.
+            //
+            // Dropping it sends the next caller through `acquire`, which makes the
+            // observation, loses or wins the launch race in the store like any
+            // other caller, and starts a browser. Nothing here launches anything
+            // itself: a second process launching against one profile directory is
+            // the measured silent-collision failure the race exists to prevent.
+            //
+            // **Nothing is detached and no browser is ended.** There is nothing to
+            // detach from — the browser is the thing that went away — and this
+            // service never ends a browser (`browser_scoped.never`, §7.3).
+            settled.delete(browser);
+            inFlight.delete(browser);
+            // ── A browser that was never started is NOT a browser that died ────
+            //
+            // The distinction is the whole reason this reads the row, and getting
+            // it wrong breaks the ordinary path rather than an edge case: **a lease
+            // is granted before any browser exists.** Acquisition is lazy, so the
+            // normal life of a lease is claim, then status, then a page verb that
+            // finally causes the launch — and on a machine with no browser
+            // installed at all, that launch never comes and the lease is still
+            // perfectly valid for everything that does not need a page.
+            //
+            // Both states look identical from the profile directory: no verified
+            // record either way. What separates them is what the store was told.
+            // `recordLaunched` moves the row to `running`, so a row that says
+            // `running` while nothing answers is a browser that **has died**;
+            // `stopped` is one that was never started, and a lease against it is
+            // waiting for a launch rather than holding a corpse.
+            const row = options.store.db
+                .prepare('SELECT state FROM browsers WHERE id = ?')
+                .get(browser);
+            return row?.state === 'running' ? 'gone' : 'unknown';
+        }
+        catch {
+            // **`unknown`, never `gone`.** A probe that could not be carried out —
+            // an unreadable profile directory, a fetch that threw rather than
+            // answering — has observed nothing, and reporting a browser dead on the
+            // strength of a failed observation would end working leases on a
+            // machine having an unrelated bad moment. Not knowing is a state this
+            // result can express precisely so it does not have to be guessed at.
+            return 'unknown';
+        }
+    };
+    const holds = (browser) => settled.has(browser) || inFlight.has(browser);
     return {
         session,
+        liveness,
+        holds,
         close: async () => {
             for (const open of settled.values()) {
                 try {

package/dist/src/service/comparison.js

@@ -4,13 +4,31 @@ import { reconcileGeometry } from "../diff/geometry.js";
 import { decodePng, encodePng } from "../diff/image.js";
 import { computeMask } from "../diff/mask.js";
 import { extractRegions } from "../diff/regions.js";
-/** A result carrying no diff, with the sentence saying why. */
-function noDiff(settings, explanation, extra = {}) {
+/**
+ * A result carrying no diff, with the sentence saying why.
+ *
+ * **`changed`, `changedPixels` and `changedRatio` are not set here at all** —
+ * not to `false`, not to `0`. Every path into this function is a path on which
+ * no comparison ran, so there is no finding to report, and the shape says so by
+ * having no field rather than by having a field whose value happens to be the
+ * one a real all-clear also produces. `false` and `0` are what a comparison
+ * that ran and found nothing returns; emitting them here would make the two
+ * cases identical to anything reading the fields directly.
+ *
+ * `regions` stays an empty array and `truncated` stays `false` because those
+ * describe the *output listing* rather than a finding about the page: an empty
+ * list of regions is honest about a call that produced no regions, and neither
+ * can be misread as an assertion that the page is unchanged.
+ */
+function noDiff(settings, explanation, 
+// **Typed to exclude the three findings**, rather than a bare
+// `Partial<ComparisonResult>`. The spread below is the one way a caller could
+// put `changed` back into a no-diff result, so the parameter that feeds it
+// does not accept those keys and a future call site trying to pass one is a
+// build failure instead of a silently restored defect.
+extra = {}) {
     return {
         diffed: false,
-        changed: false,
-        changedPixels: 0,
-        changedRatio: 0,
         regions: [],
         overlayPath: null,
         truncated: false,