browser-broker 0.1.0 → 0.2.0

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

@@ -111,8 +111,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/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,7 +2,7 @@ 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";
@@ -277,10 +277,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 +301,36 @@ 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);
+    const work = afterCommitWork(scope, input, tab, (session, page) => session.navigate(page, url, waitMs), lease.claimId);
     return {
         value: withPageDriven({ claimId: lease.claimId, tabId: tab.tabId, expiresAt, url }, 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 +353,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 +522,26 @@ 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);
     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, {
@@ -539,6 +600,7 @@ export function decideCapture(scope, input) {
             width: taken.width,
             height: taken.height,
             bytes: taken.bytes,
+            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.
  *