browser-broker 0.2.0 → 0.3.1

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

@@ -121,16 +121,55 @@ export async function runReconcileCommand(rest, options) {
     }
     return COMMAND_EXIT.accepted;
 }
+/**
+ * Did this run decline to do the thing it was called to do?
+ *
+ * **Two facts together, and neither alone is enough.** Tabs still being
+ * opened block the sweep (`decideReconciliation` leaves them alone, because
+ * closing a page a mid-open lease is about to be handed would be worse than
+ * declining) — but a run that closed pages *and* skipped one did work, and
+ * calling that "nothing was closed" would be false. A run that closed
+ * nothing because there was nothing to close is not declining either; it is
+ * simply a clean run, and telling that caller to try again would send it
+ * back for an answer it already has.
+ *
+ * So the conclusion is drawn only where both hold: something was in the way,
+ * and nothing was swept past it.
+ */
+function nothingClosedPendingRetry(report) {
+    return report.skippedOpening > 0 && report.closed === 0;
+}
 /**
  * The report a person reads.
  *
  * **Every line is a count or an opaque identifier**, which is §1.4's rule
  * made true by there being nothing else available to print: the report type
  * carries no driver name, so this function could not print one if it tried.
+ *
+ * ── Why the outcome is the first line and not the last ──────────────────
+ *
+ * A caller reads the first line and acts on it. When this run declined —
+ * {@link nothingClosedPendingRetry} — the sentence that predicts that
+ * caller's next failure is the one that has to arrive first, because a
+ * headline of `reconciled: <browser>` above four counters reads as
+ * completion, and a reader who takes it at face value stops there and runs
+ * straight back into the state they invoked this to clear. The counters are
+ * still printed, unchanged and in the same order; what moves is the
+ * conclusion, which stops being something the reader has to derive from the
+ * bottom of a list.
+ *
+ * **The headline stops claiming completion on such a run** for the same
+ * reason. `reconciled:` is a claim about what happened, and on a run that
+ * closed nothing and needs invoking again it is not a true one — this is the
+ * defect class this repository keeps finding in itself, a call that succeeds
+ * while delivering less than it announced. The word is kept for the runs
+ * that earned it.
  */
 export function formatReconciliation(browser, report) {
+    const declined = nothingClosedPendingRetry(report);
     const lines = [
-        `reconciled: ${browser}`,
+        declined ? `did not reconcile: ${browser}` : `reconciled: ${browser}`,
+        ...(declined ? [conclusionLine(report)] : []),
         `pages open, not counting the keeper: ${String(report.pagesSeen)}`,
         `pages closed because no live lease owned them: ${String(report.closed)}`,
         `leases ended because their page was gone: ${String(report.settled.length)}`,
@@ -148,22 +187,34 @@ export function formatReconciliation(browser, report) {
         // reader knows what it costs — memory, and not budget.
         lines.push(`${String(report.closeFailures)} page(s) would not close. That is a leaked page and not a leaked lease: the budget is unaffected, and \`broker doctor\` reports them.`);
     }
-    if (report.skippedOpening > 0) {
-        // Said on the run it happened on, because the alternative is a person
-        // reading "0 closed" and concluding there was nothing to close.
-        //
-        // **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.'));
+    // Said on the run it happened on, because the alternative is a person
+    // reading "0 closed" and concluding there was nothing to close.
+    //
+    // **Printed here only when it was not already printed at the top.** The
+    // conclusion belongs above the counters on a run that declined, and below
+    // them on a run that closed pages anyway — where it is a caveat on real
+    // work rather than the outcome. Either way it is written once, by one
+    // function, so the two positions cannot drift into two wordings.
+    if (report.skippedOpening > 0 && !declined) {
+        lines.push(conclusionLine(report));
     }
     return lines;
 }
+/**
+ * The sentence that tells a caller what to do next.
+ *
+ * **The caution itself does not change when the caller owns the blocking
+ * row.** Closing a page belonging to an in-flight claim would be worse than
+ * declining, and that is true whoever the claim belongs to. What changes is
+ * that the caller is told the remedy is in its own hands: an operator can
+ * otherwise run this repeatedly against a row that is its own lease, held
+ * open for as long as the command keeps being run, with nothing in the
+ * message able to say so.
+ */
+function conclusionLine(report) {
+    const owned = report.skippedOpeningOwnedByCaller;
+    return (`${String(report.skippedOpening)} tab(s) are still being opened, so nothing was closed on this run — a page seen now may belong to one of them.` +
+        (owned > 0
+            ? ` ${String(owned)} of them ${owned === 1 ? 'belongs' : 'belong'} to your own lease — release ${owned === 1 ? 'it' : 'them'}, or run this from another session.`
+            : ' Run again once they have settled.'));
+}

package/dist/src/config/environment.js

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

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) => {

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,

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

@@ -8,6 +8,7 @@ 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";
@@ -307,9 +308,37 @@ export function decideNavigate(scope, input) {
         // check was honoured.
         detail: { url, ...(waitMs === undefined ? {} : { waitMs }) },
     });
-    const work = afterCommitWork(scope, input, tab, (session, page) => session.navigate(page, url, waitMs), 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,
     };
 }
@@ -527,6 +556,20 @@ export function decideCapture(scope, input) {
     // 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 }),
@@ -590,16 +633,56 @@ 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/tool/tools.js

@@ -222,9 +222,10 @@ export const TOOL_DEFINITIONS = [
     {
         name: 'browser_navigate',
         operation: 'navigate',
-        description: 'Point your tab at an address. Returns the final address after redirects, the title, the ' +
-            'status, and a path to the accessibility snapshot taken on arrival — a path, because a ' +
-            'snapshot is thousands of tokens and you usually want one part of it.',
+        description: 'Point your tab at an address. Returns the final address after redirects — which is not ' +
+            'always the address you asked for, and is the field to check when you need to know ' +
+            'whether something sent you elsewhere — plus the title and the status. ' +
+            'It does NOT take a snapshot: use browser_read for one.',
         arguments: [
             LEASE_KEY,
             {
@@ -344,7 +345,11 @@ export const TOOL_DEFINITIONS = [
                 type: 'string',
                 required: false,
                 description: '"detail" or "max" for a higher resolution. Omit for the default — there is no way to ' +
-                    'ask for the default by name. "max" also requires reason.',
+                    'ask for the default by name. "max" also requires reason. **A tier raises the LONGEST ' +
+                    'edge, not the width**, so on a full_page capture of a page taller than it is wide the ' +
+                    'height takes the whole budget and the width stays small at every rung — a 1030px-wide ' +
+                    'page 6400px tall is about 165px wide by default and about 414px wide at "max". For ' +
+                    'legible text on a tall page, capture a selector instead, or read the page as text.',
             },
             {
                 name: 'reason',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-broker",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "license": "MIT",
   "description": "Leases over tabs in a fixed set of browsers: bounded capacity, a queue, reclamation, and an enforced capture policy.",
   "type": "module",
@@ -53,7 +53,6 @@
     "dist/",
     ".env.example",
     "README.md",
-    "RELEASES.md",
     "LICENSE"
   ]
 }