scenescout 3.13.0 → 3.14.0

package/dist/engine/browser.js

@@ -5,21 +5,25 @@ import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./f
 import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore, redactSecrets, TASK_SET } from "./memory.js";
 import { normalizeTask } from "./task.js";
 import { CLAIM_SCAN_SCRIPT, findContradictions } from "./claims.js";
+import { POSTMESSAGE_BINDING, describeTokenPost, postMessageCaptureScript, tokenHits, tokenPostKey } from "./postmessage.js";
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
+import { captureClip } from "./capture.js";
 import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, frameLines, hasVisibleFrame, frameElementKey, frameLabel, masksForeignName, MASKED_NAME, capForeignName, stripForeignHref, frameToPageRect, displayName, missingName, placeholderOnly, placeholderEvidence, describeControl, labelFlag, } from "./collector.js";
 import { OracleMonitor, formatViolations, httpErrorDetail } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
-import { describeStep, FLOW_AFTER_LAST_STEP_MS, FLOW_STEP_TIMEOUT_MS, isAction, matchRequest, parseTarget, splitRefusals, TARGET_HELP, urlMatches, } from "./flow.js";
+import { describeStep, FLOW_AFTER_LAST_STEP_MS, isAction, matchRequest, parseTarget, splitRefusals, TARGET_HELP, urlMatches, } from "./flow.js";
 import { framePath, RECORD_MAX_FRAMES } from "./replay.js";
 import { keepWatchingUrl, normalizePace, SETTLE_TICK_MS, shouldKeepWaiting } from "./settle.js";
 import { buildRequestScript, formatReplay, replaySignature, requestHeaders, resolveMethod, resolveRequestUrl, toReplayResult } from "./request.js";
-import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, unloadWriteInterception, } from "../browsers.js";
+import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, unloadWriteInterception, closeWaitsForLeavingWrites, } from "../browsers.js";
 import { revealedLines } from "./hover.js";
 import { FORMS_INVENTORY_SCRIPT, FORM_PROBE_BODY, formProbeExpression, formIdentity, formStatus, FORMS_READ_FAILED, FORMS_SUBMIT_UNMATCHED, isEmptySubmit, sameControl, isNavigationTeardown, submits, tracksForm, } from "./forms.js";
 import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
-import { ACTION_TIMEOUT_MS, performScroll, probeFocusIndicators, probeOverlays, scrollContainer } from "./probes.js";
+import { DEFAULT_TIME_LIMITS, explainTimeout, limitHint, resolveTimeLimits } from "./limits.js";
+import { performScroll, probeFocusIndicators, probeOverlays, scrollContainer } from "./probes.js";
+import { boundedTeardown } from "./teardown.js";
 import { BROWSER_MARKER, reapOrphanBrowsers } from "./reaper.js";
 import { planUploadOptions, resolveDiskUpload } from "./uploads.js";
 import { answersWithRefusal, destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, policyRefusal, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, embedOfRequest, hostileForEmbed, trustedEmbedOrigins, MAX_TRUSTED_EMBEDS, trustsForeignWrite, embedProbeRefusal, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, WriteRule, } from "./policy.js";
@@ -27,6 +31,8 @@ import { scanProject } from "../scan.js";
 import { analyzeDesign, DESIGN_COLLECT_SCRIPT } from "./design.js";
 import { acceptMatches, generatedUpload } from "./fixtures.js";
 import { bodyDigest, headerOf, isReadMethod, judgeUnseenWrite, pausedRequestBytes, RoutedWrites, UnseenRefusals, unseenWriteSource, } from "./unload.js";
+import { loginCommand, permissionNote, resolveAttachAuth, roleLabel, sessionStorageInitScript, splitProfile, summarizeState, writeProfile, } from "./profiles.js";
+import { acquireLock, brokerEnabled, lockPathFor, planRefresh, presentedToken, profileAfterRotation, REFRESH_BROKER_ENV, refreshTokenSlots, rotatedFromResponse, rotationStored, swapProfileToken, swapRequest, } from "./refresh.js";
 const SETTLE_MS = 400;
 /**
  * Request URL → pathname, falling back to the raw string for anything
@@ -184,6 +190,12 @@ const SCREENCAST_PAGELESS_TICKS = 20;
 const RECORD_SHOT_TIMEOUT_MS = 2500;
 export class BrowserEngine {
     browser = null;
+    /** How long an action and a page load may take; set at attach (limits.ts). */
+    limits = DEFAULT_TIME_LIMITS;
+    /** The limits this session runs with, so the server can size its watchdogs to them. */
+    get timeLimits() {
+        return this.limits;
+    }
     context = null;
     page = null;
     oracles = new OracleMonitor();
@@ -211,13 +223,26 @@ export class BrowserEngine {
     /** Origins named as trusted embeds (policy.ts trustsEmbedWrite decides when that counts). */
     trustedEmbeds = new Set();
     trustNotice = "";
-    /** Human label for the auth identity driving this session (the server sets it from the storage-state filename). */
+    /** Human label for the auth identity driving this session: the role, the storage-state file's name, or anonymous. Set by attach. */
     role = "anonymous";
+    /** How the attached session signed in: a role profile, a storage-state file, or not at all. */
+    auth = { kind: "none" };
     /** Named-session id (the server sets it; every engine shares one MemoryStore, so
      *  per-session reads of the interleaved action log must filter by this). */
     sessionKey = "default";
     /** Login-bounce streak, the SESSION AUTH LOST verdict, and the per-call notice. */
     authLoss = new AuthLossTracker();
+    /**
+     * The refresh broker for a role session: the role's profile, and the
+     * refresh tokens this session last loaded from it (never printed). Null
+     * when the session is not attached by role, the broker is off, or the
+     * profile holds no refresh token.
+     */
+    refresh = null;
+    /** Write-backs still waiting on a response, so close() lets them release their lock. */
+    refreshTasks = new Set();
+    /** What the broker did this session, for the lane report: counts only. */
+    refreshCounts = { refreshed: 0, swapped: 0, failed: 0 };
     /** UI-label blocking applies only in read-only mode (safe-write enforces at the network layer instead). */
     get readOnly() {
         // observe is read-only and then some: every UI-level refusal applies to it too.
@@ -518,6 +543,8 @@ export class BrowserEngine {
      * as long as the browser, so a page closed at the end still meets it.
      */
     routedWrites = new RoutedWrites();
+    /** Requests the route handler is still judging, by the page that sent them: a page is closed only once its own are answered. */
+    routesInFlight = new Map();
     /** Writes refused at the browser level, so the driver's own report of them (a redirect hop failing) is known as the policy's doing. */
     unseenRefusals = new UnseenRefusals();
     /** Whether the write policy stopped this request, at the route handler or at the browser level. */
@@ -635,6 +662,38 @@ export class BrowserEngine {
             this.oracles.noteContradiction(found, url);
         }
     }
+    /** postMessage-token findings already reported this session, by route, receiving frame, path and shape. */
+    tokenPostsReported = new Set();
+    /**
+     * What the capture script handed back from a postMessage to "*": classified
+     * here (postmessage.ts) and dropped, so no value outlives this call. Only the
+     * path, shape and masked preview reach the oracle log.
+     */
+    noteTokenPosts(frame, entries) {
+        const hits = tokenHits(entries);
+        if (hits.length === 0)
+            return;
+        let pageUrl;
+        let frameUrl;
+        let embed;
+        try {
+            const page = frame.page();
+            pageUrl = page.url();
+            frameUrl = frame.url();
+            embed = frame === page.mainFrame() ? null : this.foreignOriginOf(frame);
+        }
+        catch {
+            // The frame went away between the call and its report: nothing left to attribute it to.
+            return;
+        }
+        for (const hit of hits) {
+            const key = tokenPostKey(hit, pageUrl, frameUrl);
+            if (this.tokenPostsReported.has(key))
+                continue;
+            this.tokenPostsReported.add(key);
+            this.oracles.noteTokenPost(describeTokenPost(hit, frameUrl), pageUrl, embed);
+        }
+    }
     /** Contradiction signatures already reported this session — the same refused endpoint on every page must not flood the run. */
     contradictionsReported = new Set();
     async scanForInjections() {
@@ -667,9 +726,45 @@ export class BrowserEngine {
         return this.page !== null;
     }
     async attach(opts) {
+        // Resolved before anything is closed, so a bad role, a missing profile or
+        // a time limit out of bounds leaves a live session as it was.
+        const limits = resolveTimeLimits(opts, process.env);
+        const auth = resolveAttachAuth({ projectDir: opts.projectDir, url: opts.url, role: opts.role, storageStatePath: opts.storageStatePath });
+        const brokered = brokerEnabled({ roleSession: auth.kind === "role", option: opts.refreshBroker, env: process.env[REFRESH_BROKER_ENV] });
+        const storageStatePath = auth.kind === "none" ? undefined : auth.storageStatePath;
+        if (storageStatePath && !fs.existsSync(storageStatePath)) {
+            throw new Error(`storageStatePath does not exist: ${storageStatePath}`);
+        }
+        // Read and checked here, also before anything is closed. Playwright restores
+        // the storage state; sessionStorage, which it has no field for, is put back
+        // by an init script before the app's own code runs.
+        let profile;
+        if (storageStatePath) {
+            try {
+                profile = splitProfile(JSON.parse(fs.readFileSync(storageStatePath, "utf8")));
+            }
+            catch (err) {
+                throw new Error(`could not load the storage state at ${storageStatePath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         await this.close();
-        if (opts.storageStatePath && !fs.existsSync(opts.storageStatePath)) {
-            throw new Error(`storageStatePath does not exist: ${opts.storageStatePath}`);
+        this.limits = limits;
+        this.auth = auth;
+        this.role = roleLabel(auth);
+        this.authLoss.beginSession(auth.kind, this.role);
+        let profileNote = "";
+        this.refresh = null;
+        this.refreshCounts = { refreshed: 0, swapped: 0, failed: 0 };
+        if (auth.kind === "role") {
+            const note = permissionNote(auth.storageStatePath, fs.statSync(auth.storageStatePath).mode);
+            if (note)
+                profileNote = `\n⚠ ${note}`;
+            if (brokered) {
+                const read = this.readRoleProfile();
+                const known = read.ok ? refreshTokenSlots(read.state) : [];
+                if (known.length > 0)
+                    this.refresh = { projectDir: opts.projectDir, role: auth.role, file: auth.storageStatePath, known, spent: [] };
+            }
         }
         this.currentMode = opts.mode ?? "read-only";
         this.writeRule = new WriteRule(this.currentMode);
@@ -698,6 +793,7 @@ export class BrowserEngine {
         this.blockedRequests = [];
         this.watchedResponses = [];
         this.contradictionsReported = new Set();
+        this.tokenPostsReported = new Set();
         this.pendingCreations = new Set();
         this.baseUrl = opts.url.replace(/\/$/, "");
         this.embedMoves = new EmbedMoveTracker(this.baseUrl);
@@ -753,12 +849,18 @@ export class BrowserEngine {
             this.engineName = opts.browser ?? defaultEngine(process.env);
             this.browser = await this.launchWithRecovery(this.engineName, opts.headed ?? false);
             this.context = await this.browser.newContext({
-                storageState: opts.storageStatePath,
+                storageState: profile?.storageState,
                 viewport: opts.viewport ?? { width: 1280, height: 900 },
                 serviceWorkers: serviceWorkerPolicy(this.engineName),
             });
+            const restoreSession = sessionStorageInitScript(profile?.sessionStorage ?? []);
+            if (restoreSession)
+                await this.context.addInitScript(restoreSession);
             if (!sharedWorkersAllowed(this.mode))
                 await this.context.addInitScript(REMOVE_SHARED_WORKER_SCRIPT);
+            // The postMessage-token oracle: every frame's postMessage is wrapped, and a "*" call hands its longer strings here.
+            await this.context.exposeBinding(POSTMESSAGE_BINDING, (source, entries) => this.noteTokenPosts(source.frame, entries));
+            await this.context.addInitScript(postMessageCaptureScript());
             this.page = await this.context.newPage();
         }
         catch (err) {
@@ -846,7 +948,7 @@ export class BrowserEngine {
         });
         // Write policy — enforced on the wire, where the truth lives.
         if (this.mode !== "destructive") {
-            await this.context.route("**/*", async (route) => {
+            const judge = async (route) => {
                 const req = route.request();
                 const method = req.method();
                 // Read once, as the request arrives: the rule the page sent it under (policy.ts WriteRule), not whatever holds after an await below.
@@ -999,7 +1101,8 @@ export class BrowserEngine {
                     return route.continue();
                 }
                 return refuse();
-            });
+            };
+            await this.context.route("**/*", (route) => this.judgeTracked(route, judge));
             // Chromium never routes a write a page sends as it is being left; it is judged at the browser level instead.
             if (unloadWriteInterception(this.engineName) === "browser-fetch" && this.browser) {
                 try {
@@ -1012,12 +1115,17 @@ export class BrowserEngine {
                 }
             }
         }
+        // The refresh broker. Registered after the write policy so it runs first
+        // and hands every request on to it: a refresh it lets through is still
+        // judged by the policy like any other request.
+        if (this.refresh)
+            await this.context.route("**/*", (route) => this.brokerRefresh(route));
         // Popups / target=_blank: adopt same-origin pages as the active page (with
         // oracles attached); close foreign-origin popups so exploration cannot
         // silently escape the app under test.
         this.context.on("page", (newPage) => {
             newPage
-                .waitForLoadState("domcontentloaded", { timeout: 10000 })
+                .waitForLoadState("domcontentloaded", { timeout: this.limits.backNavMs })
                 .then(() => {
                 if (newPage === this.page || newPage.isClosed())
                     return;
@@ -1037,7 +1145,7 @@ export class BrowserEngine {
                     this.lastSnap = null;
                 }
                 else {
-                    void BrowserEngine.leaveAndClose(newPage);
+                    void this.leaveAndClose(newPage);
                 }
             })
                 .catch(() => { });
@@ -1045,12 +1153,13 @@ export class BrowserEngine {
         this.wireDialogHandler(this.page);
         this.wireEmbedMoves(this.page);
         try {
-            await this.page.goto(opts.url, { waitUntil: "domcontentloaded", timeout: 20000 });
+            await this.page.goto(opts.url, { waitUntil: "domcontentloaded", timeout: this.limits.navMs });
         }
         catch (err) {
             // Don't leave a half-attached engine (leaked browser, snapshots of about:blank).
             await this.close();
-            throw new Error(`Could not load ${opts.url} — is the app running? (${err instanceof Error ? err.message.split("\n")[0] : err})`);
+            const explained = explainTimeout(err, "nav", this.limits.navMs);
+            throw new Error(`Could not load ${opts.url} — is the app running? (${explained instanceof Error ? explained.message.split("\n")[0] : explained})`);
         }
         await this.settle();
         this.logAction({ action: "attach", url: this.page.url() });
@@ -1062,16 +1171,19 @@ export class BrowserEngine {
         // Whether a bounce verdict can matter later: only a session carrying
         // credentials has any to lose, and only it pays for watching the URL on
         // every navigation. An anonymous crawl keeps its full speed.
-        this.watchesForBounce = Boolean(opts.storageStatePath);
+        this.watchesForBounce = Boolean(storageStatePath);
         const landed = await this.stableUrl();
-        const authFailed = Boolean(opts.storageStatePath) && this.authLoss.isLoginRedirect(normalizePath(opts.url), landed, this.baseUrl);
+        const authFailed = Boolean(storageStatePath) && this.authLoss.isLoginRedirect(normalizePath(opts.url), landed, this.baseUrl);
         // An earlier run may have written down how this app's login state is
         // regenerated. "Regenerate it" is advice the reader already had; the
         // command that worked last time is the part worth keeping.
         const recipe = authFailed ? this.memory.setupRecipe() : [];
         const authWarning = authFailed
-            ? `\n⚠ AUTH FAILED — the storage state at ${opts.storageStatePath} did not produce a signed-in session: ` +
-                `attaching landed on ${landed}, a login page. Regenerate it (its token has most likely expired) and re-attach. ` +
+            ? `\n⚠ AUTH FAILED — the storage state at ${storageStatePath} did not produce a signed-in session: ` +
+                `attaching landed on ${landed}, a login page. ` +
+                (auth.kind === "role"
+                    ? `Record it again with \`${loginCommand(auth.role, this.baseUrl)}\` (its session has most likely expired) and re-attach. `
+                    : `Regenerate it (its token has most likely expired) and re-attach. `) +
                 `Continuing now tests a logged-out app.` +
                 (recipe.length > 0
                     ? `\n  Recorded by an earlier run under setup:\n${recipe.map((line) => `    · ${line}`).join("\n")}`
@@ -1080,11 +1192,12 @@ export class BrowserEngine {
         return (`Attached to ${this.page.url()} (mode=${this.mode}` +
             `${this.engineName === "chromium" ? "" : `, browser=${this.engineName}, service workers blocked because their requests cannot be intercepted here`}` +
             `${focusAdvanceKey(this.engineName, process.platform) === "Tab" ? "" : `, keyboard: Tab stops only at text fields in this browser — press Alt+Tab to reach buttons and links`}` +
-            `${opts.storageStatePath ? `, auth=${opts.storageStatePath}` : ""}). ` +
+            `${auth.kind === "role" ? `, role=${auth.role}` : auth.kind === "file" ? `, auth=${auth.storageStatePath}` : ""}). ` +
             `Memory: ${this.memory.dir}.${this.memory.loadWarning ? ` WARNING: ${this.memory.loadWarning}` : ""}` +
             (this.memory.prunedStates > 0 ? ` Trimmed ${this.memory.prunedStates} old page state(s) from the history; coverage is unchanged.` : "") +
             `${this.memory.legacyDirNote ? ` ${this.memory.legacyDirNote}` : ""}` +
             `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""}${this.trustNotice} Call scout_snapshot to see the current state.` +
+            profileNote +
             authWarning);
     }
     /** Whether the page was moved off the app by one of its embeds (policy.ts EmbedMoveTracker). */
@@ -1670,7 +1783,7 @@ export class BrowserEngine {
             const policyAbortedNavigation = url.startsWith("chrome-error://") && this.blockedRequests.length > 0;
             this.logAction({ action, target, url });
             this.logAction({ action: policyAbortedNavigation ? "write-policy:navigation-blocked" : "origin-fence:bounced", target: url.slice(0, 200), url });
-            await page.goBack({ waitUntil: "domcontentloaded", timeout: 10000 }).catch(() => { });
+            await page.goBack({ waitUntil: "domcontentloaded", timeout: this.limits.backNavMs }).catch(() => { });
             url = page.url();
             this.refs.clear();
             const blocked = this.drainBlocked();
@@ -2045,6 +2158,15 @@ export class BrowserEngine {
             ? `\n⚠ READ-ONLY notice: this action fired state-changing requests — server state may have mutated despite ${this.mode} mode: ${list}${extra}. Consider whether this flow should be avoided or the environment confirmed disposable.`
             : `\n(state-changing requests: ${list}${extra})`;
     }
+    /** Run one action or page load; a timeout it throws names the limit that ran out and how to raise it. */
+    async withinLimit(kind, work) {
+        try {
+            return await work();
+        }
+        catch (err) {
+            throw explainTimeout(err, kind, kind === "action" ? this.limits.actionMs : this.limits.navMs);
+        }
+    }
     /**
      * Click a locator the way a real user's click resolves, not the way
      * Playwright's strict actionability protocol insists on. `.click()` polls
@@ -2174,6 +2296,9 @@ export class BrowserEngine {
         });
     }
     async click(ref, clicks = 1) {
+        return this.withinLimit("action", () => this.clickNow(ref, clicks));
+    }
+    async clickNow(ref, clicks = 1) {
         const page = this.requirePage();
         const { el, liveLabel } = await this.resolveForAction(ref);
         const refusal = this.actionPolicyCheck(el, liveLabel);
@@ -2195,7 +2320,7 @@ export class BrowserEngine {
         // button or an input can submit a form; nothing else is asked.
         const form = !el.frame && (el.tag === "button" || el.tag === "input") ? await this.probeForm(clickTarget) : null;
         const formState = { fp: this.currentFingerprint, elements: [...this.refs.values()] };
-        const { forced } = await this.resilientClick(clickTarget, ACTION_TIMEOUT_MS, clicks);
+        const { forced } = await this.resilientClick(clickTarget, this.limits.actionMs, clicks);
         this.memory.markExercised(this.currentFingerprint, el.key, clicks > 1 ? `click×${clicks}` : "click");
         this.noteFormSubmit(formState, "click", form);
         const result = await this.afterAction(clicks > 1 ? `click×${clicks}` : "click", `${el.role} "${el.name}"`);
@@ -2252,21 +2377,21 @@ export class BrowserEngine {
                     return { existing: n.value, caretAppendable: typeof n.selectionStart === "number" };
                 }
                 return { existing: "", caretAppendable: false };
-            }, undefined, { timeout: ACTION_TIMEOUT_MS }));
+            }, undefined, { timeout: this.limits.actionMs }));
         }
         catch (err) {
             throw new Error(`Could not read the field's existing content before typing — aborting rather than risk overwriting it (${err instanceof Error ? err.message.split("\n")[0] : err}). Take a new scout_snapshot and retry.`);
         }
         const { existing, caretAppendable } = state;
         if (replace || !existing || text === "") {
-            await locator.fill(text, { timeout: ACTION_TIMEOUT_MS });
+            await locator.fill(text, { timeout: this.limits.actionMs });
             return existing && (replace || text === "") ? ` (replaced existing content ${JSON.stringify(existing.slice(0, 60))})` : "";
         }
         const appendNote = ` (APPENDED after existing content ${JSON.stringify(existing.slice(0, 60))} — pass replace=true to overwrite instead)`;
         if (!caretAppendable) {
             // Data-typed inputs (number, email, date): concatenate without a
             // separator — an injected space would invalidate the value.
-            await locator.fill(existing + text, { timeout: ACTION_TIMEOUT_MS });
+            await locator.fill(existing + text, { timeout: this.limits.actionMs });
             return appendNote;
         }
         // Native append: focus, move the caret to the end, insert via the
@@ -2287,7 +2412,7 @@ export class BrowserEngine {
                 sel?.removeAllRanges();
                 sel?.addRange(range);
             }
-        }, undefined, { timeout: ACTION_TIMEOUT_MS });
+        }, undefined, { timeout: this.limits.actionMs });
         // Space only at a word-to-word boundary: "@mention " + "hi" needs none,
         // "user@" + "x" must not become "user@ x".
         const separator = /\w$/.test(existing) && /^\w/.test(text) ? " " : "";
@@ -2295,6 +2420,9 @@ export class BrowserEngine {
         return appendNote;
     }
     async type(ref, text, pressEnter = false, replace = false) {
+        return this.withinLimit("action", () => this.typeNow(ref, text, pressEnter, replace));
+    }
+    async typeNow(ref, text, pressEnter = false, replace = false) {
         const page = this.requirePage();
         const { el, liveLabel } = await this.resolveForAction(ref);
         if (el.role === "file") {
@@ -2341,7 +2469,7 @@ export class BrowserEngine {
             // After the fill, before the key: the fields as they are when it submits.
             const form = !el.frame && el.tag === "input" ? await this.probeForm(locator) : null;
             const formState = { fp: this.currentFingerprint, elements: [...this.refs.values()] };
-            await locator.press("Enter", { timeout: ACTION_TIMEOUT_MS });
+            await locator.press("Enter", { timeout: this.limits.actionMs });
             this.noteFormSubmit(formState, "enter", form);
         }
         this.memory.markExercised(this.currentFingerprint, el.key, "type");
@@ -2356,6 +2484,9 @@ export class BrowserEngine {
      * fixture unless `filePath` names one inside the attached project.
      */
     async upload(opts) {
+        return this.withinLimit("action", () => this.uploadNow(opts));
+    }
+    async uploadNow(opts) {
         this.actionStartedAt = Date.now();
         const page = this.requirePage();
         let el = null;
@@ -2411,7 +2542,7 @@ export class BrowserEngine {
         if ("refused" in target)
             return refuse(target.refused);
         const { input, chooser, how } = target;
-        const meta = await (input ? input.evaluate(describeFileInput, undefined, { timeout: ACTION_TIMEOUT_MS }) : chooser.element().evaluate(describeFileInput)).catch(() => ({ accept: null, multiple: false, label: "", disabled: false, probed: false }));
+        const meta = await (input ? input.evaluate(describeFileInput, undefined, { timeout: this.limits.actionMs }) : chooser.element().evaluate(describeFileInput)).catch(() => ({ accept: null, multiple: false, label: "", disabled: false, probed: false }));
         // setInputFiles never checks `disabled` — it would report success on a
         // control no user can operate.
         if (meta.disabled) {
@@ -2421,14 +2552,14 @@ export class BrowserEngine {
         const mutationsBefore = this.mutationRequests.length;
         const blockedBefore = this.blockedRequests.length;
         if (chooser)
-            await chooser.setFiles(file.payload, { timeout: ACTION_TIMEOUT_MS });
+            await chooser.setFiles(file.payload, { timeout: this.limits.actionMs });
         else
-            await input.setInputFiles(file.payload, { timeout: ACTION_TIMEOUT_MS });
+            await input.setInputFiles(file.payload, { timeout: this.limits.actionMs });
         // The set call succeeding means the browser took the payload — not that
         // the app kept it. Read the input back: an app that rejects client-side
         // clears it, and then nothing would ever be sent on submit.
         const kept = await (input
-            ? input.evaluate((node) => node.files?.length ?? 0, undefined, { timeout: ACTION_TIMEOUT_MS })
+            ? input.evaluate((node) => node.files?.length ?? 0, undefined, { timeout: this.limits.actionMs })
             : chooser.element().evaluate((node) => node.files?.length ?? 0)).catch(() => -1);
         const inputDesc = [
             meta.label ? `"${meta.label}"` : null,
@@ -2464,7 +2595,7 @@ export class BrowserEngine {
             return { input: fileInputs.first(), chooser: null, how: "set on the page's only file input" };
         }
         const isFileInput = await locator
-            .evaluate((node) => node instanceof HTMLInputElement && node.type === "file", undefined, { timeout: ACTION_TIMEOUT_MS })
+            .evaluate((node) => node instanceof HTMLInputElement && node.type === "file", undefined, { timeout: this.limits.actionMs })
             .catch(() => false);
         if (isFileInput)
             return { input: locator, chooser: null, how: "set directly on the file input" };
@@ -2473,8 +2604,8 @@ export class BrowserEngine {
         // outlasts the click's own — forced retry included — plus a grace period
         // after it, for apps that fetch an upload URL before opening the picker. A
         // wait shorter than the click reported such controls as "uploads nothing".
-        const opened = page.waitForEvent("filechooser", { timeout: ACTION_TIMEOUT_MS + FORCED_CLICK_TIMEOUT_MS + CHOOSER_GRACE_MS }).catch(() => null);
-        await this.resilientClick(locator, ACTION_TIMEOUT_MS);
+        const opened = page.waitForEvent("filechooser", { timeout: this.limits.actionMs + FORCED_CLICK_TIMEOUT_MS + CHOOSER_GRACE_MS }).catch(() => null);
+        await this.resilientClick(locator, this.limits.actionMs);
         const chooser = await Promise.race([opened, page.waitForTimeout(CHOOSER_GRACE_MS).then(() => null)]);
         if (chooser)
             return { input: null, chooser, how: "via the file chooser the click opened" };
@@ -2580,11 +2711,14 @@ export class BrowserEngine {
      * look, not an interaction, and the element still deserves a click.
      */
     async hover(ref) {
+        return this.withinLimit("action", () => this.hoverNow(ref));
+    }
+    async hoverNow(ref) {
         const page = this.requirePage();
         const { el } = await this.resolveForAction(ref);
         const { before, bodyBefore, churning } = await this.hoverBaselines();
         const locator = this.scopeOf(el).locator(`xpath=${el.xpath}`);
-        await locator.hover({ timeout: ACTION_TIMEOUT_MS });
+        await locator.hover({ timeout: this.limits.actionMs });
         // Wiggle inside the element: pointer-tracking libraries distinguish real
         // movement from a single synthetic hover event.
         const box = await locator.boundingBox().catch(() => null);
@@ -2618,6 +2752,9 @@ export class BrowserEngine {
             this.memory.recordSelectChoice(fingerprint, key, labels, label);
     }
     async select(ref, value) {
+        return this.withinLimit("action", () => this.selectNow(ref, value));
+    }
+    async selectNow(ref, value) {
         const page = this.requirePage();
         const { el, liveLabel } = await this.resolveForAction(ref);
         const refusal = this.actionPolicyCheck(el, liveLabel);
@@ -2638,7 +2775,7 @@ export class BrowserEngine {
         }
         const loc = this.scopeOf(el).locator(`xpath=${el.xpath}`);
         const options = el.tag === "select" ? await readSelectOptions(loc) : null;
-        const picked = await loc.selectOption(value, { timeout: ACTION_TIMEOUT_MS });
+        const picked = await loc.selectOption(value, { timeout: this.limits.actionMs });
         this.memory.markExercised(this.currentFingerprint, el.key, "select");
         if (options)
             this.recordSelectChoice(this.currentFingerprint, el.key, options, picked);
@@ -2706,6 +2843,9 @@ export class BrowserEngine {
      */
     static ACTIVATION_KEY_RE = /^(Enter|NumpadEnter|Space| )$/i;
     async press(key) {
+        return this.withinLimit("action", () => this.pressNow(key));
+    }
+    async pressNow(key) {
         this.actionStartedAt = Date.now();
         const page = this.requirePage();
         const refusal = await this.vetFocusedActivation(key);
@@ -2779,7 +2919,7 @@ export class BrowserEngine {
         // A notice describes ONE navigation. Clearing up front means a notice left
         // undelivered by a previous throw can never prepend itself to this result.
         this.authLoss.clear();
-        await page.goto(url, { waitUntil: "domcontentloaded", timeout: 20000 });
+        await this.withinLimit("nav", () => page.goto(url, { waitUntil: "domcontentloaded", timeout: this.limits.navMs }));
         // Settle BEFORE judging where we landed. A client-side auth guard redirects
         // after hydration, not during goto, so reading page.url() here showed the
         // requested path and the bounce went unnoticed — which is precisely how a
@@ -2803,7 +2943,293 @@ export class BrowserEngine {
             throw new Error(`${notice}${msg}`);
         }
         this.recordNavigationOutcome(url, await this.landedUrl(page));
-        return this.authLoss.take() + settled;
+        // Only after a navigation that finished: one that threw leaves its verdict standing.
+        const plan = this.authLoss.takeReattach();
+        if (!plan)
+            return this.authLoss.take() + settled;
+        // The loss this navigation declared is answered once, from the role's latest
+        // saved profile, and the session goes back to the page it asked for.
+        const applied = await this.applyLatestProfile();
+        if (!applied.ok) {
+            this.authLoss.abortReattach(applied.why);
+            return this.authLoss.take() + settled;
+        }
+        const returnUrl = plan.returnTo;
+        let recovered;
+        try {
+            await this.withinLimit("nav", () => page.goto(returnUrl, { waitUntil: "domcontentloaded", timeout: this.limits.navMs }));
+            recovered = await this.afterAction("navigate", returnUrl);
+        }
+        catch (err) {
+            this.recordNavigationOutcome(returnUrl, await this.landedUrl(page));
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`${this.authLoss.take()}${msg}`);
+        }
+        this.recordNavigationOutcome(returnUrl, await this.landedUrl(page));
+        return this.authLoss.take() + recovered;
+    }
+    /**
+     * Replace this session's cookies and storage with its role's saved profile,
+     * read from disk now: another process may have recorded it again since this
+     * session attached. Same context, same page, same listeners and write policy;
+     * only the sign-in changes. Never prints the profile's contents.
+     */
+    async applyLatestProfile() {
+        if (this.auth.kind !== "role" || !this.context)
+            return { ok: false, why: "this session was not attached by role" };
+        const read = this.readRoleProfile();
+        if (!read.ok)
+            return read;
+        const applied = await this.applyState(read.state);
+        if (!applied.ok)
+            return applied;
+        // setStorageState has no sessionStorage: the latest profile's is seeded once more in each tab, as the page loads.
+        const reseed = sessionStorageInitScript(splitProfile(read.state).sessionStorage, { generation: `reattach-${Date.now()}` });
+        if (reseed) {
+            try {
+                await this.context.addInitScript(reseed);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    why: `the browser took its saved cookies and storage, but its session storage could not be put back (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`,
+                };
+            }
+        }
+        this.logAction({ action: "reattach", target: `role ${this.auth.role}`, url: this.page?.url() ?? "" });
+        return { ok: true };
+    }
+    /** The role's saved profile as it is on disk now, checked to be a storage state. Never printed. */
+    readRoleProfile() {
+        if (this.auth.kind !== "role")
+            return { ok: false, why: "this session was not attached by role" };
+        const file = this.auth.storageStatePath;
+        let state;
+        try {
+            state = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            const reason = err instanceof SyntaxError ? "it is not valid JSON" : err instanceof Error ? err.message.split("\n")[0] : String(err);
+            return { ok: false, why: `its saved profile at ${file} could not be read (${reason})` };
+        }
+        const checked = summarizeState(state);
+        if (!checked.ok)
+            return { ok: false, why: `its saved profile at ${file} is not a storage state (${checked.error})` };
+        // A malformed sessionStorage list is refused here, before anything is applied.
+        try {
+            splitProfile(state);
+        }
+        catch (err) {
+            return { ok: false, why: `its saved profile at ${file} could not be split (${err instanceof Error ? err.message : String(err)})` };
+        }
+        return { ok: true, state };
+    }
+    /**
+     * Replace this context's cookies and storage with a profile, in place: same
+     * pages, listeners and policy. Playwright is handed only what it restores;
+     * the profile's sessionStorage list is not part of its storage state.
+     */
+    async applyState(state) {
+        if (!this.context)
+            return { ok: false, why: "no browser is open" };
+        let storageState;
+        try {
+            storageState = splitProfile(state).storageState;
+        }
+        catch (err) {
+            return { ok: false, why: `the saved profile could not be split (${err instanceof Error ? err.message : String(err)})` };
+        }
+        try {
+            await this.context.setStorageState(storageState);
+        }
+        catch (err) {
+            return { ok: false, why: `the browser refused its saved profile (${err instanceof Error ? err.message.split("\n")[0] : String(err)})` };
+        }
+        // What the session now holds is what it knows as the role's tokens.
+        if (this.refresh)
+            this.rememberTokens(refreshTokenSlots(state));
+        return { ok: true };
+    }
+    /**
+     * The refresh broker's route handler. A request carrying none of the role's
+     * refresh tokens is handed on untouched. One carrying one waits for the
+     * role's refresh lock; holding it, the session re-reads the profile, loads
+     * it and sends the current token in place of a spent one when another
+     * session rotated it meanwhile, and keeps the lock until the page has
+     * stored the rotation and it is written back. A lock that cannot be had is
+     * reported and the request dropped: sending a token another session may
+     * have spent is what revokes the family. Token values are never logged.
+     */
+    async brokerRefresh(route) {
+        const broker = this.refresh;
+        const req = route.request();
+        if (!broker)
+            return route.fallback();
+        const headers = await req.allHeaders().catch(() => req.headers());
+        const wire = { url: req.url(), body: req.postData(), headers };
+        // Spent tokens too: a page still holding one would otherwise send it unbrokered.
+        const sent = presentedToken(wire, [...broker.known, ...broker.spent]);
+        if (!sent)
+            return route.fallback();
+        const where = `${req.method()} ${pathnameOf(req.url())}`;
+        let lock;
+        try {
+            lock = await acquireLock(lockPathFor(broker.file));
+        }
+        catch (err) {
+            this.refreshCounts.failed += 1;
+            this.logAction({
+                action: "refresh-broker:dropped",
+                target: `${where} (${err instanceof Error ? err.message : String(err)})`,
+                url: this.page?.url() ?? "",
+            });
+            await route.abort("blockedbyclient").catch(() => { });
+            return;
+        }
+        let handedOn = false;
+        try {
+            const read = this.readRoleProfile();
+            if (!read.ok)
+                throw new Error(read.why);
+            const plan = planRefresh(sent, refreshTokenSlots(read.state));
+            let presented = sent;
+            let overrides = {};
+            if (plan.kind === "swap") {
+                // Another session rotated the token while this one waited: load what it saved, and send the current token.
+                const applied = await this.applyState(read.state);
+                if (!applied.ok)
+                    throw new Error(applied.why);
+                const swapped = swapRequest(wire, sent.value, plan.to.value);
+                overrides = {
+                    ...(swapped.url ? { url: swapped.url } : {}),
+                    ...(swapped.body !== undefined ? { postData: swapped.body } : {}),
+                    ...(swapped.headers ? { headers: swapped.headers } : {}),
+                };
+                presented = plan.to;
+                this.refreshCounts.swapped += 1;
+            }
+            this.logAction({
+                action: "refresh-broker",
+                target: `${where} with ${presented.slot}${plan.kind === "swap" ? " (rotated by another session; loaded its profile)" : plan.kind === "unknown" ? " (no longer in the profile; sent as is)" : ""}`,
+                url: this.page?.url() ?? "",
+            });
+            handedOn = true;
+            if (plan.kind === "unknown") {
+                // The profile holds another sign-in now: send this one on, and leave the profile alone.
+                lock.release();
+                await route.fallback(overrides);
+                return;
+            }
+            const task = this.writeBackAfter(req, presented, lock).finally(() => this.refreshTasks.delete(task));
+            this.refreshTasks.add(task);
+            await route.fallback(overrides);
+        }
+        catch (err) {
+            if (!handedOn) {
+                lock.release();
+                this.refreshCounts.failed += 1;
+                this.logAction({
+                    action: "refresh-broker:dropped",
+                    target: `${where} (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`,
+                    url: this.page?.url() ?? "",
+                });
+                await route.abort("blockedbyclient").catch(() => { });
+            }
+        }
+    }
+    /**
+     * Once the refresh is answered, write the rotation back over the profile
+     * and release the lock. The page's own state is saved once it holds the
+     * rotated token, so the next session gets the access token with it; a page
+     * that has not stored it in time has the token read from the response
+     * instead. A refused or failed refresh changes nothing on disk.
+     */
+    async writeBackAfter(req, presented, lock) {
+        const broker = this.refresh;
+        try {
+            let timer;
+            const res = await Promise.race([
+                req.response().finally(() => clearTimeout(timer)),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(null), 30000);
+                }),
+            ]);
+            if (!broker)
+                return;
+            if (!res || !res.ok()) {
+                const why = res ? `answered ${res.status()}` : "had no response";
+                this.logAction({
+                    action: "refresh-broker:not-saved",
+                    target: `${presented.slot}: the refresh ${why}; the profile was left as it was`,
+                    url: this.page?.url() ?? "",
+                });
+                return;
+            }
+            let state = null;
+            for (let waited = 0; waited <= 5000; waited += 50) {
+                const now = await this.context?.storageState().catch(() => null);
+                if (now && rotationStored(now, presented)) {
+                    const onDisk = this.readRoleProfile();
+                    state = profileAfterRotation(now, onDisk.ok ? onDisk.state : null);
+                    break;
+                }
+                await new Promise((r) => setTimeout(r, 50));
+            }
+            if (!state) {
+                const body = await res.text().catch(() => "");
+                const rotated = rotatedFromResponse(body, await res.headerValues("set-cookie").catch(() => []));
+                const read = this.readRoleProfile();
+                if (rotated && read.ok)
+                    state = swapProfileToken(read.state, presented.value, rotated);
+            }
+            if (!state) {
+                this.refreshCounts.failed += 1;
+                this.logAction({
+                    action: "refresh-broker:not-saved",
+                    target: `${presented.slot}: the page stored no rotated token and the response named none`,
+                    url: this.page?.url() ?? "",
+                });
+                return;
+            }
+            writeProfile(broker.projectDir, broker.role, state);
+            this.rememberTokens(refreshTokenSlots(state));
+            this.refreshCounts.refreshed += 1;
+        }
+        catch (err) {
+            this.refreshCounts.failed += 1;
+            this.logAction({
+                action: "refresh-broker:not-saved",
+                target: `${presented.slot}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+                url: this.page?.url() ?? "",
+            });
+        }
+        finally {
+            lock.release();
+        }
+    }
+    /** Take `now` as the role's current tokens; the ones it replaces are kept as spent, so a page that still sends one is caught. */
+    rememberTokens(now) {
+        if (!this.refresh)
+            return;
+        const replaced = this.refresh.known.filter((k) => !now.some((n) => n.value === k.value));
+        this.refresh.spent = [...replaced, ...this.refresh.spent].slice(0, 20);
+        this.refresh.known = now;
+    }
+    /** What the refresh broker did this session, or "" when it did nothing. Counts only. */
+    refreshSummary() {
+        const { refreshed, swapped, failed } = this.refreshCounts;
+        if (refreshed + swapped + failed === 0)
+            return "";
+        const parts = [`refreshed role '${this.role}''s token ${refreshed} time${refreshed === 1 ? "" : "s"} under the role's lock`];
+        if (swapped > 0)
+            parts.push(`${swapped} of them after another session had rotated it`);
+        if (failed > 0)
+            parts.push(`${failed} refresh${failed === 1 ? "" : "es"} could not be brokered (see the action log)`);
+        return parts.join("; ");
+    }
+    /** What this session's one automatic re-attach did, or "" when it never re-attached. */
+    reattachSummary() {
+        return this.authLoss.reattachSummary();
     }
     /** Where did we ASK to go, where did we END UP, and does that count as coverage? */
     recordNavigationOutcome(requestedUrl, landedUrl) {
@@ -2815,12 +3241,12 @@ export class BrowserEngine {
             this.memory?.markAttempted(requestedRoute, outcome, this.role);
             this.memory?.recordRoleAccess(this.role, requestedRoute, outcome);
         }
-        this.authLoss.record({ requestedRoute, landedRoute, bounced, role: this.role });
+        this.authLoss.record({ requestedRoute, landedRoute, bounced, role: this.role, target: requestedUrl });
     }
     async goBack() {
         this.actionStartedAt = Date.now();
         const page = this.requirePage();
-        await page.goBack({ waitUntil: "domcontentloaded", timeout: 10000 }).catch(() => { });
+        await page.goBack({ waitUntil: "domcontentloaded", timeout: this.limits.backNavMs }).catch(() => { });
         return this.afterAction("back", "");
     }
     /** The full route contract: scanned filesystem routes ∪ link-discovered route classes. */
@@ -2918,7 +3344,12 @@ export class BrowserEngine {
         }
         const summary = [];
         const problems = [];
-        for (const path of targets) {
+        this.authLoss.beginBatch();
+        // A queue rather than the list itself: a session that re-attaches mid-sweep
+        // visits the routes its loss bounced again, straight after.
+        const queue = [...targets];
+        for (let i = 0; i < queue.length; i++) {
+            const path = queue[i];
             const url = `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
             if (!this.isSameOrigin(url)) {
                 summary.push(`${path} — SKIPPED (off-origin)`);
@@ -2928,11 +3359,12 @@ export class BrowserEngine {
             this.oracles.drain(false); // discard pre-route leftovers WITHOUT marking their signatures as reported
             let status = "ERR";
             try {
-                const resp = await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });
+                const resp = await page.goto(url, { waitUntil: "domcontentloaded", timeout: this.limits.crawlNavMs });
                 status = resp?.status() ?? "no-response";
             }
             catch (err) {
-                const reason = err instanceof Error ? err.message.split("\n")[0] : String(err);
+                const explained = explainTimeout(err, "nav", this.limits.crawlNavMs);
+                const reason = explained instanceof Error ? explained.message.split("\n")[0] : String(explained);
                 // Not retried by later crawls in this process (a check would otherwise try it
                 // on every discovery round). Deliberately not written to memory: one outage
                 // must not count a route as covered in every later run's gap ledger.
@@ -2944,6 +3376,9 @@ export class BrowserEngine {
                 // a browser that shows no error page simply lets the wait time out.
                 await page.waitForEvent("framenavigated", { predicate: (f) => f === page.mainFrame(), timeout: 1500 }).catch(() => undefined);
                 summary.push(`${path} — LOAD FAILED`);
+                // The page a re-attach went back to never loaded, so nothing says whether it worked.
+                if (this.authLoss.reattaching)
+                    this.authLoss.abortReattach(`the page it went back to, ${path}, did not load (${reason})`);
                 problems.push(`${path}: ${reason}`);
                 this.crawlHealth.push({
                     path,
@@ -2987,7 +3422,7 @@ export class BrowserEngine {
             // Feeds the streak. The per-route notice is discarded — crawl already
             // flags AUTH-REDIRECT per route in its own summary, and the verdict for
             // the sweep as a whole is emitted once at the end via batchVerdict().
-            this.authLoss.record({ requestedRoute, landedRoute: route, bounced: loginRedirect, role: this.role });
+            this.authLoss.record({ requestedRoute, landedRoute: route, bounced: loginRedirect, role: this.role, target: path });
             this.authLoss.clear();
             // Error-status routes render but would otherwise be re-crawled forever —
             // an attempt with the status satisfies the contract.
@@ -3031,6 +3466,27 @@ export class BrowserEngine {
                     .join("\n");
                 problems.push(`${path}${loginRedirect ? " → redirected to login (auth missing/expired?)" : ""}${deadEnd ? " → dead end" : ""}${detail ? `\n${detail}` : ""}`);
             }
+            // A role session that lost its sign-in on this route re-attaches once
+            // and visits the routes the loss bounced again, next. Their bounced
+            // results leave the crawl's data, so a check reads the signed-in visit.
+            const plan = this.authLoss.takeReattach({ revisits: (t) => targets.includes(t) });
+            if (plan) {
+                const applied = await this.applyLatestProfile();
+                if (!applied.ok) {
+                    this.authLoss.abortReattach(applied.why);
+                }
+                else {
+                    // Only this sweep's own paths: a streak that began with scout_navigate holds full URLs the sweep cannot join to its base.
+                    const again = [plan.returnTo, ...plan.retry];
+                    this.crawlHealth = this.crawlHealth.filter((h) => !(h.loginRedirect && again.includes(h.path)));
+                    for (let k = problems.length - 1; k >= 0; k--) {
+                        if (again.some((p) => problems[k].startsWith(`${p} → redirected to login`)))
+                            problems.splice(k, 1);
+                    }
+                    queue.splice(i + 1, 0, ...again);
+                    summary.push(`↻ re-attached from role '${this.role}''s saved profile; visiting ${again.join(", ")} again`);
+                }
+            }
         }
         // Crawl leaves the page wherever it ended — refs from before are gone.
         this.refs.clear();
@@ -3164,11 +3620,11 @@ export class BrowserEngine {
                             preState = await this.stateHolding(probe, preState, preState !== null && preState === lastCapture);
                             form = { kind: "click", probe };
                         }
-                        forcedClick = (await this.resilientClick(loc, ACTION_TIMEOUT_MS)).forced;
+                        forcedClick = (await this.resilientClick(loc, this.limits.actionMs)).forced;
                     }
                     else if (step.action === "hover") {
                         const { before, bodyBefore, churning } = await this.hoverBaselines();
-                        await loc.hover({ timeout: ACTION_TIMEOUT_MS });
+                        await loc.hover({ timeout: this.limits.actionMs });
                         const { revealed } = await this.detectHoverReveal(before, bodyBefore, churning);
                         transcript.push(revealed.length > 0
                             ? `   hover revealed: ${revealed.join(" · ").slice(0, 300)}`
@@ -3192,12 +3648,12 @@ export class BrowserEngine {
                                 preState = await this.stateHolding(probe, preState, preState !== null && preState === lastCapture);
                                 form = { kind: "enter", probe };
                             }
-                            await loc.press("Enter", { timeout: ACTION_TIMEOUT_MS });
+                            await loc.press("Enter", { timeout: this.limits.actionMs });
                         }
                     }
                     else if (step.action === "select") {
                         const options = await readSelectOptions(loc);
-                        const picked = await loc.selectOption(step.value ?? "", { timeout: ACTION_TIMEOUT_MS });
+                        const picked = await loc.selectOption(step.value ?? "", { timeout: this.limits.actionMs });
                         if (options)
                             chose = { options, picked };
                     }
@@ -3290,7 +3746,7 @@ export class BrowserEngine {
                 const diagnosticLine = actionabilityDiagnostic(fullMsg);
                 let hint = "";
                 if (/Timeout/i.test(firstLine)) {
-                    hint = ` (timeout${diagnosticLine ? ` — ${diagnosticLine}` : ""} — the target may no longer match: element relabeled, removed, or genuinely covered by an overlay; re-snapshot to see current state)`;
+                    hint = ` (timeout${diagnosticLine ? ` — ${diagnosticLine}` : ""} — the target may no longer match: element relabeled, removed, or genuinely covered by an overlay; re-snapshot to see current state. Or ${limitHint("action", this.limits.actionMs)})`;
                 }
                 else if (/Input of type "file" cannot be filled/i.test(firstLine)) {
                     hint = ` (this is a file input — use an {action:"upload"} step, or scout_upload)`;
@@ -3376,7 +3832,7 @@ export class BrowserEngine {
                     violations.push({ path, violation: { kind: v.kind, severity: v.severity, detail: v.detail, url: v.url, ...(v.embed ? { embed: v.embed } : {}) } });
         };
         const poll = async (done) => {
-            const until = Date.now() + FLOW_STEP_TIMEOUT_MS;
+            const until = Date.now() + this.limits.actionMs;
             for (;;) {
                 if (done())
                     return true;
@@ -3402,7 +3858,9 @@ export class BrowserEngine {
                     const current = this.requirePage();
                     if (step.action === "navigate") {
                         const url = `${this.baseUrl}${step.target}`;
-                        const resp = await current.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });
+                        const resp = await current
+                            .goto(url, { waitUntil: "domcontentloaded", timeout: this.limits.crawlNavMs })
+                            .catch((err) => Promise.reject(explainTimeout(err, "nav", this.limits.crawlNavMs)));
                         await this.settle();
                         const status = resp?.status() ?? null;
                         if (status !== null && status >= 400) {
@@ -3422,11 +3880,11 @@ export class BrowserEngine {
                     else if (step.action === "click" || step.action === "type" || step.action === "select") {
                         const loc = BrowserEngine.locatorFor(current, parseTarget(step.target)).first();
                         const found = await loc
-                            .waitFor({ state: "visible", timeout: FLOW_STEP_TIMEOUT_MS })
+                            .waitFor({ state: "visible", timeout: this.limits.actionMs })
                             .then(() => true)
                             .catch(() => false);
                         if (!found) {
-                            failure = `nothing visible matches ${step.target} within ${FLOW_STEP_TIMEOUT_MS / 1000}s`;
+                            failure = `nothing visible matches ${step.target} within ${this.limits.actionMs / 1000}s — ${limitHint("action", this.limits.actionMs)}`;
                         }
                         else {
                             const label = ((await loc.getAttribute("aria-label").catch(() => null)) ??
@@ -3436,10 +3894,10 @@ export class BrowserEngine {
                                 refusal = destructiveRefusal(label || step.target, this.mode);
                             }
                             else if (step.action === "click") {
-                                await loc.click({ timeout: FLOW_STEP_TIMEOUT_MS });
+                                await loc.click({ timeout: this.limits.actionMs });
                             }
                             else if (step.action === "select") {
-                                await loc.selectOption(step.value, { timeout: FLOW_STEP_TIMEOUT_MS });
+                                await loc.selectOption(step.value, { timeout: this.limits.actionMs });
                             }
                             else {
                                 await this.noteProbe(step.value, step.target);
@@ -3450,7 +3908,7 @@ export class BrowserEngine {
                                     if (this.readOnly && isDestructive(submitLabel))
                                         refusal = destructiveRefusal(submitLabel, this.mode);
                                     else
-                                        await loc.press("Enter", { timeout: FLOW_STEP_TIMEOUT_MS });
+                                        await loc.press("Enter", { timeout: this.limits.actionMs });
                                 }
                             }
                             if (!refusal)
@@ -3460,11 +3918,11 @@ export class BrowserEngine {
                     else if (step.action === "expect-text") {
                         const visible = current.getByText(step.text, { exact: false }).filter({ visible: true }).first();
                         const ok = await visible
-                            .waitFor({ state: "visible", timeout: FLOW_STEP_TIMEOUT_MS })
+                            .waitFor({ state: "visible", timeout: this.limits.actionMs })
                             .then(() => true)
                             .catch(() => false);
                         if (!ok)
-                            failure = `no visible text ${JSON.stringify(step.text)} within ${FLOW_STEP_TIMEOUT_MS / 1000}s`;
+                            failure = `no visible text ${JSON.stringify(step.text)} within ${this.limits.actionMs / 1000}s — ${limitHint("action", this.limits.actionMs)}`;
                     }
                     else if (step.action === "expect-url") {
                         const ok = await poll(() => urlMatches(step.pattern, this.page?.url() ?? ""));
@@ -3479,7 +3937,7 @@ export class BrowserEngine {
                     }
                 }
                 catch (err) {
-                    failure = firstLine(err);
+                    failure = firstLine(explainTimeout(err, "action", this.limits.actionMs));
                 }
                 await this.scanForInjections().catch(() => { });
                 await this.scanForContradictions().catch(() => { });
@@ -3524,9 +3982,9 @@ export class BrowserEngine {
             this.blockedRequests = [];
             this.oracles.drain(false);
             this.setMode(crawlMode);
-            // Pages the session no longer drives are closed only now, at about:blank and under the held rule: in Firefox a
-            // page closed straight after it is left sent its leaving beacon unjudged about one time in forty.
-            await BrowserEngine.settleWithin(Promise.allSettled(context.pages().map((p) => (p === this.page ? undefined : p.close().catch(() => { })))), 5000);
+            // Pages the session no longer drives are closed only now, at about:blank and under the held rule, and each only
+            // once what it sent as it was left has been judged (leftSettled).
+            await BrowserEngine.settleWithin(Promise.allSettled(context.pages().map(async (p) => (p === this.page ? undefined : (await this.leftSettled(p), await p.close().catch(() => { }))))), 5000);
             page.off("websocket", onSocket);
             context.off("response", onResponse);
             this.refs.clear();
@@ -3579,7 +4037,9 @@ export class BrowserEngine {
      */
     async scroll(to, by, target) {
         this.actionStartedAt = Date.now();
-        const { refused, note } = target ? await scrollContainer(this.requirePage(), target, to, by) : await performScroll(this.requirePage(), to, by);
+        const { refused, note } = target
+            ? await scrollContainer(this.requirePage(), target, to, by, this.limits.actionMs)
+            : await performScroll(this.requirePage(), to, by);
         if (refused)
             return refused;
         const amount = Math.trunc(by ?? 600);
@@ -3593,6 +4053,53 @@ export class BrowserEngine {
         this.logAction({ action: "screenshot", url: page.url() });
         return { base64: buf.toString("base64"), mimeType: "image/jpeg" };
     }
+    /**
+     * A PNG of one element: its bounds plus `margin`, scrolled into view, from a
+     * real screenshot. Found by `ref` from the latest snapshot, or by `key` (its
+     * identity, which the same element has on another deployment of the app),
+     * in which case the page is read afresh to find it. Reads only: nothing is
+     * clicked, and the write policy is not involved. The rectangle's rules are
+     * capture.ts.
+     */
+    async captureElement(target, margin) {
+        const page = this.requirePage();
+        let el;
+        if (target.ref) {
+            el = this.refs.get(target.ref);
+            if (!el)
+                throw new Error(`Unknown ref "${target.ref}". Refs are only valid from the latest scout_snapshot — take a new snapshot.`);
+            if (page.url() !== this.snapshotUrl) {
+                this.refs.clear();
+                throw new Error(`Page URL changed since the last snapshot (now ${page.url()}). Take a new scout_snapshot.`);
+            }
+        }
+        else if (target.key) {
+            await this.settle();
+            // Keys carry an ordinal (collect), so the third of three same-named buttons is found as the third.
+            const { elements } = await this.collect();
+            el = elements.find((e) => e.key === target.key);
+            if (!el)
+                throw new Error(`No element with the key "${target.key}" on ${page.url()}.`);
+        }
+        else {
+            throw new Error("Give the ref of the element to capture, from the latest scout_snapshot.");
+        }
+        const locator = this.scopeOf(el).locator(`xpath=${el.xpath}`).first();
+        await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
+        const box = await locator.boundingBox({ timeout: 5000 });
+        if (!box)
+            throw new Error(`${el.name || el.key} is not displayed, so it has no picture.`);
+        const viewport = page.viewportSize() ?? (await page.evaluate("({ width: innerWidth, height: innerHeight })"));
+        const clip = captureClip(box, margin, viewport);
+        if (!clip)
+            throw new Error(`${el.name || el.key} is outside the viewport, so it has no picture.`);
+        const png = await page.screenshot({ type: "png", clip, animations: "disabled" });
+        this.logAction({ action: "capture", target: el.key.slice(0, 200), url: page.url() });
+        // Found by key, the refs were rebuilt without a snapshot: none of them may be acted on.
+        if (target.key)
+            this.refs.clear();
+        return { png, key: el.key, label: el.name, url: page.url() };
+    }
     /**
      * What the live view shows next to a session's name. The task is what the
      * agent said the session is for; the objective is the goal of the journey it
@@ -3794,16 +4301,55 @@ export class BrowserEngine {
             return;
         await page.goto("about:blank", { timeout: 3000 }).catch(() => { });
     }
+    /** Run the route handler's judgement of one request, recorded against the page that sent it until it is answered. */
+    async judgeTracked(route, judge) {
+        let page = null;
+        try {
+            page = route.request().frame().page();
+        }
+        catch {
+            /* no frame: a service worker's request, which no page's close waits on */
+        }
+        const judging = judge(route);
+        if (!page) {
+            await judging;
+            return;
+        }
+        let pending = this.routesInFlight.get(page);
+        if (!pending)
+            this.routesInFlight.set(page, (pending = new Set()));
+        pending.add(judging);
+        try {
+            await judging;
+        }
+        finally {
+            pending.delete(judging);
+            if (pending.size === 0)
+                this.routesInFlight.delete(page);
+        }
+    }
     /**
-     * Close a page the engine will not drive, after leaving it (`leave`), so what it sends on its way out meets the policy.
-     * Known limit: in Firefox, a close straight after the leave has let the page's leaving beacon out unjudged (seen 2 times
-     * in 80 under load). replayFlow's hand-back closes pages only once every page is at about:blank; this and `close` do not yet.
+     * Wait, after a page has been left, until the route handler has answered every request the page sent on its way out,
+     * where a close could otherwise let one out unjudged (browsers.ts closeWaitsForLeavingWrites). A round trip to the
+     * page first, so a request the browser reported before answering it has reached the route handler (0 of 80 escaped in
+     * the unload smoke loop with it). A page that cannot answer (closed, or crashed) has nothing more to send: the catch.
      */
-    static async leaveAndClose(page) {
+    async leftSettled(page) {
+        if (page.isClosed() || !closeWaitsForLeavingWrites(this.engineName))
+            return;
+        await BrowserEngine.settleWithin(page.evaluate(() => 0).catch(() => { }), 2000);
+        await BrowserEngine.settleWithin(Promise.allSettled([...(this.routesInFlight.get(page) ?? [])]), 2000);
+    }
+    /** Close a page the engine will not drive, after leaving it (`leave`) and the policy has judged what it sent on its way out. */
+    async leaveAndClose(page) {
         await BrowserEngine.leave(page);
+        await this.leftSettled(page);
         await page.close().catch(() => { });
     }
     async close() {
+        // A refresh write-back holds the role's lock: let it finish or give up, so no other session waits on a closed one.
+        if (this.refreshTasks.size > 0)
+            await BrowserEngine.settleWithin(Promise.allSettled([...this.refreshTasks]), 10000);
         // Marks the end of the time this session held a browser, so the pace
         // section can say how long it was held with nothing happening. Only when a
         // browser is actually open: attach() closes first, and a close of nothing
@@ -3813,7 +4359,7 @@ export class BrowserEngine {
         // Every page is left before it is closed, while the write policy still holds, so what a page sends on its way out
         // is judged and its refusal logged before the flush below.
         const pages = this.context?.pages() ?? [];
-        await BrowserEngine.settleWithin(Promise.allSettled(pages.map((p) => BrowserEngine.leave(p))), 5000);
+        await BrowserEngine.settleWithin(Promise.allSettled(pages.map(async (p) => (await BrowserEngine.leave(p), await this.leftSettled(p)))), 5000);
         // Pending debounced coverage writes must land before the process can exit.
         try {
             this.memory?.flush();
@@ -3826,14 +4372,9 @@ export class BrowserEngine {
                 this.memory.lastSaveError = err instanceof Error ? err.message : String(err);
         }
         // Bounded teardown: a wedged renderer must not hang scout_close forever.
-        // If teardown overruns the cap, the leftover process is reaped by the
-        // orphan cleaner on the next attach (or server start).
-        await BrowserEngine.settleWithin((async () => {
-            for (const p of this.context?.pages() ?? [])
-                await p.close().catch(() => { });
-            await this.context?.close().catch(() => { });
-            await this.browser?.close().catch(() => { });
-        })(), 8000);
+        // Past the cap the browser is still closed, on the objects taken here
+        // (teardown.ts): these fields are cleared below.
+        await boundedTeardown(this.context, this.browser, 8000);
         this.page = null;
         this.context = null;
         this.browser = null;