scenescout 3.1.1 → 3.3.0

package/dist/engine/pace.js

@@ -0,0 +1,112 @@
+/**
+ * Log entries that are not actions: a stated task, an attach, the note that a
+ * resource was created. They carry no browser work and take no time, so
+ * counting them inflates the action count and drags the median gap toward
+ * zero. One real run logged 325 entries of which 107 were stated tasks.
+ */
+const MARKER_ACTIONS = new Set(["task", "attach", "created-resource", "journey:start", "journey:end", "record:full", "record:failed"]);
+/** Whether a log entry represents work the browser actually did. */
+export function isActing(action) {
+    return !MARKER_ACTIONS.has(action);
+}
+/** A gap longer than this is the agent thinking, not the browser working. */
+export const IDLE_GAP_MS = 30_000;
+/** A session with no action for this long is probably forgotten, and is holding a browser for nothing. */
+export const STALE_SESSION_MS = 5 * 60_000;
+function median(sorted) {
+    if (sorted.length === 0)
+        return 0;
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+}
+/**
+ * The pace of each session in the log, and of the run as a whole. `nowMs` is
+ * passed rather than read so the numbers are the same every time they are
+ * computed from the same log.
+ */
+export function measurePace(log, nowMs, attached = []) {
+    const stillOpen = new Set(attached);
+    const bySession = new Map();
+    for (const entry of log) {
+        if (!isActing(entry.action))
+            continue;
+        const name = entry.session ?? "default";
+        const list = bySession.get(name);
+        if (list)
+            list.push(entry);
+        else
+            bySession.set(name, [entry]);
+    }
+    const sessions = [];
+    let first = Number.POSITIVE_INFINITY;
+    let last = 0;
+    for (const [session, entries] of bySession) {
+        const times = entries.map((e) => Date.parse(e.at)).filter((t) => Number.isFinite(t));
+        if (times.length === 0)
+            continue;
+        times.sort((a, b) => a - b);
+        first = Math.min(first, times[0]);
+        last = Math.max(last, times[times.length - 1]);
+        const gaps = [];
+        for (let i = 1; i < times.length; i += 1)
+            gaps.push(times[i] - times[i - 1]);
+        const spanMs = times[times.length - 1] - times[0];
+        const idleMs = gaps.filter((g) => g > IDLE_GAP_MS).reduce((sum, g) => sum + g, 0);
+        sessions.push({
+            session,
+            actions: entries.length,
+            spanMs,
+            medianGapMs: median([...gaps].sort((a, b) => a - b)),
+            maxGapMs: gaps.length > 0 ? Math.max(...gaps) : 0,
+            idleShare: spanMs > 0 ? idleMs / spanMs : 0,
+            quietMs: Math.max(0, nowMs - times[times.length - 1]),
+            framed: entries.filter((e) => e.frame).length,
+        });
+    }
+    sessions.sort((a, b) => b.actions - a.actions);
+    return {
+        sessions,
+        spanMs: sessions.length > 0 ? last - first : 0,
+        actions: sessions.reduce((sum, x) => sum + x.actions, 0),
+        // Only a session that is STILL ATTACHED can be holding a browser. A lane
+        // that finished and closed is quiet because it is gone, and warning about
+        // it told the reader to close something that no longer exists — which is
+        // what the first run of this report did for six of its eleven sessions.
+        quiet: sessions.filter((s) => s.quietMs > STALE_SESSION_MS && stillOpen.has(s.session)).map((s) => s.session),
+    };
+}
+/** Milliseconds as a person says them: 45s, 4m12s, 1h03m. */
+export function sayDuration(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    if (total < 60)
+        return `${total}s`;
+    const minutes = Math.floor(total / 60);
+    if (minutes < 60)
+        return `${minutes}m${String(total % 60).padStart(2, "0")}s`;
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+/**
+ * The run's pace as report lines. Says what the numbers mean, because "idle
+ * 84%" reads as a fault in the engine when it is a description of how the
+ * agent paced itself.
+ */
+export function formatPace(pace) {
+    if (pace.sessions.length === 0)
+        return [];
+    const lines = [
+        `## How the run was paced`,
+        ``,
+        `${pace.actions} action(s) over ${sayDuration(pace.spanMs)}. Stated tasks and attaches are not counted: they take no time. Idle share is time the browser stood still waiting for the agent, not time the engine spent working.`,
+        ``,
+        `| Session | Actions | Span | Median gap | Longest gap | Idle | Frames |`,
+        `|---|---:|---:|---:|---:|---:|---:|`,
+    ];
+    for (const s of pace.sessions) {
+        lines.push(`| ${s.session} | ${s.actions} | ${sayDuration(s.spanMs)} | ${sayDuration(s.medianGapMs)} | ${sayDuration(s.maxGapMs)} | ${Math.round(s.idleShare * 100)}% | ${s.framed} |`);
+    }
+    lines.push(``);
+    if (pace.quiet.length > 0) {
+        lines.push(`⚠ Held a browser with nothing to do for over ${sayDuration(STALE_SESSION_MS)}: ${pace.quiet.join(", ")}. A session waiting for its turn should be closed and re-attached when it is needed.`, ``);
+    }
+    return lines;
+}

package/dist/engine/policy.js

@@ -22,7 +22,11 @@ const DESTRUCTIVE_PATTERNS = [
     /\breset\b(?!\s+(filters?|zoom|search|view|sort|order|form|password|layout|columns?|selection|preferences?|defaults?))/i,
     /\bdiscard\b/i,
     /\bcancel subscription\b/i,
-    /\bsign(?: |-)?off\b/i,
+    // The verb: a control that signs the user off, alone or after another verb
+    // ("Save and sign off"). The noun is how approval apps label things, and it
+    // is told by the word before it ("Needs sign-off", "Awaiting sign-off",
+    // "Send for sign-off"); those destroy nothing. Same shape as the reset rule.
+    /(?<!\b(?:needs?|awaiting|awaits|pending|requires?|required|for|before|after|without|of|the|a|an|its|their|your|my)\s)\bsign(?: |-)?off\b/i,
     // The tool is generic — destructive labels come in many languages.
     /\b(eliminar|borrar|suprimir)\b/i, // es
     /\b(excluir|apagar|remover)\b/i, // pt
@@ -74,8 +78,55 @@ export function isDestructiveWire(url, body) {
 }
 /** Auth/session flows must work even under strict write policies (login, token refresh, logout). */
 export const AUTH_FLOW_RE = /\/(auth|login|logout|signin|sign-in|signup|sign-up|session|token|verify|oauth|sso|password)\b/i;
+/**
+ * A control's label is a verb phrase: "Delete", "Remove user", "Archive the
+ * project". A card or tile that is a button carries prose in its accessible
+ * name, the title then a sentence about it ("Manager Approves or rejects
+ * orders that need sign-off."), and a destructive word in that sentence
+ * describes what the thing is for; it is not the command the click sends, the
+ * same distinction the wire policy draws for words inside a POST body.
+ *
+ * So a label that is prose, longer than this many words AND containing a
+ * sentence, is judged by its head, the first few words, where the imperative
+ * lives: a match counts only when it STARTS there. The pattern still sees the
+ * whole label, so "reset filters" straddling the boundary keeps the context
+ * its exemption looks ahead at. Everything else is judged whole: a short
+ * label, a long one with no sentence in it ("Yes, I am sure I want to delete
+ * this"), a script written without spaces.
+ *
+ * A confirm button whose long label ends in a full stop and puts the verb
+ * late is the residue this lets through. The wire policy below still blocks
+ * the DELETE, PUT, PATCH or verb-path POST it would send; a plain POST to a
+ * neutral path passes in read-only, as it does for any control this list does
+ * not name.
+ */
+export const LABEL_HEAD_WORDS = 6;
+/** The head: up to LABEL_HEAD_WORDS whitespace-separated words from the start. */
+const HEAD_RE = new RegExp(`^\\s*(?:\\S+\\s+){0,${LABEL_HEAD_WORDS - 1}}\\S+`);
+/** A sentence ends in the label: a full stop, question or exclamation mark followed by space or the end. */
+const SENTENCE_RE = /[.!?](?:\s|$)/;
+/**
+ * Where a match must start to count: the end of the head for prose, the end
+ * of the label for everything else.
+ */
+function matchLimit(label) {
+    if (!SENTENCE_RE.test(label))
+        return label.length;
+    const head = HEAD_RE.exec(label);
+    if (!head || head[0].length === label.trimEnd().length)
+        return label.length;
+    return head[0].length;
+}
 export function isDestructive(...labels) {
-    return labels.some((label) => typeof label === "string" && label.length > 0 && DESTRUCTIVE_PATTERNS.some((re) => re.test(label)));
+    return labels.some((label) => {
+        if (typeof label !== "string" || label.length === 0)
+            return false;
+        const limit = matchLimit(label);
+        return DESTRUCTIVE_PATTERNS.some((re) => {
+            const m = re.exec(label);
+            return m !== null && m.index < limit;
+        });
+    });
 }
 export function destructiveRefusal(label, mode = "read-only") {
     return (`REFUSED by ${mode} policy: "${label}" matches a destructive-action pattern. ` +

package/dist/engine/report.js

@@ -1,8 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { SHARED_CHROME_ROUTE } from "./memory.js";
+import { sayVerification } from "./verify.js";
 import { feedForSession } from "./live.js";
 import { buildReplayHtml, evidenceFor } from "./replay.js";
+import { formatPace, measurePace } from "./pace.js";
 function playwrightSkeleton(f) {
     const routeClass = f.state.split("#")[0].split("?")[0];
     let gotoPath = routeClass;
@@ -68,6 +70,24 @@ function projectName(dir) {
     const parent = path.dirname(dir);
     return path.basename(parent) || path.basename(dir) || "project";
 }
+/**
+ * How long ago a finding was last seen, for the historical index. A finding
+ * nobody has re-confirmed in four months is a different thing from one seen
+ * last week, and the report should not make a reader open both to find out.
+ */
+export function describeAge(foundAt, nowMs) {
+    const seen = Date.parse(foundAt);
+    if (!Number.isFinite(seen))
+        return "?";
+    const days = Math.floor((nowMs - seen) / 86_400_000);
+    if (days <= 0)
+        return "today";
+    if (days === 1)
+        return "1 day";
+    if (days < 60)
+        return `${days} days`;
+    return `${Math.floor(days / 30)} months`;
+}
 /** Every session that did anything, with its steps in order — what the HTML replays. */
 function replaySessions(memory) {
     const names = [...new Set(memory.actionLog.map((e) => e.session ?? "default"))];
@@ -378,6 +398,7 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     const lines = [];
     const resolved = findings.filter((f) => f.status === "resolved");
     const open = findings.filter((f) => f.status !== "resolved");
+    const now = Date.now();
     const current = open.filter((f) => f.foundAt >= memory.sessionStart);
     const historical = open.filter((f) => f.foundAt < memory.sessionStart);
     lines.push(`# SceneScout Report`);
@@ -496,6 +517,11 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
             lines.push(`- **Evidence:** \`${f.evidence}\``);
         lines.push(`- **Where:** \`${f.state}\` (${f.url})`);
         lines.push(`- **Seen in runs:** ${f.runs}`);
+        // Only printed once somebody has re-tested it. A finding nobody has looked
+        // at again says nothing here, which is the honest thing for it to say.
+        if (f.verdict && f.verifiedAt) {
+            lines.push(`- **Re-tested:**${sayVerification(f).replace(/^ · /, " ")}${f.verifyNote ? ` — ${f.verifyNote}` : ""}`);
+        }
         lines.push(``);
         lines.push(f.detail);
         lines.push(``);
@@ -521,18 +547,47 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     if (historical.length > 0) {
         lines.push(`## Historical findings — not re-verified this session (${historical.length})`);
         lines.push(``);
-        lines.push(`Recorded in earlier runs and not re-confirmed. Re-test before acting; resolve fixed ones with \`scout_resolve <id>\`.`);
-        lines.push(``);
-        for (const f of historical)
-            renderFinding(f);
+        if (extras?.history === "full") {
+            lines.push(`Recorded in earlier runs and not re-confirmed. Re-test before acting; \`scout_verify\` hands them back in re-test order and records what each re-test found.`);
+            lines.push(``);
+            for (const f of historical)
+                renderFinding(f);
+        }
+        else {
+            // An index, not the findings themselves. One project reached 412
+            // historical findings and printing each in full made the report 1.75 MB
+            // — a document nobody opens, in which the eleven findings the run
+            // actually made were buried. Each row carries what decides whether to
+            // re-test it; the detail is one scout_report {history:"full"} away.
+            lines.push(`Recorded in earlier runs and NOT re-confirmed by this one, so none of it is evidence about the build under test. Listed as an index: ` +
+                `work it down with \`scout_verify\`, which hands back these findings in re-test order and records what each re-test found, ` +
+                `and pass \`history: "full"\` to scout_report for the full text.`, ``, `| Sev | Id | Age | Runs | Re-tested | Title |`, `|---|---|---:|---:|---|---|`);
+            for (const f of historical) {
+                const retested = f.verdict && f.verifiedAt ? `${f.verdict} ${f.verifiedAt.slice(0, 10)}` : "never";
+                lines.push(`| ${SEVERITY_ICON[f.severity]} | \`${f.id}\` | ${describeAge(f.foundAt, now)} | ${f.runs} | ${retested} | ${escapeTableCell(f.title)} |`);
+            }
+            lines.push(``);
+        }
     }
     if (resolved.length > 0) {
         lines.push(`## ✅ Resolved (${resolved.length})`);
         lines.push(``);
         lines.push(`Fixed and verified (or confirmed no longer reproducing). A resolved finding that is re-found reopens automatically and is flagged as a regression above.`);
         lines.push(``);
-        for (const f of resolved)
-            renderFinding(f, true);
+        if (extras?.history === "full") {
+            for (const f of resolved)
+                renderFinding(f, true);
+        }
+        else {
+            // The least actionable content in the document: these are fixed. On one
+            // project they were 314 findings and 783 KB — nearly half the report,
+            // none of it anything to do. The index keeps the record without the bulk.
+            lines.push(`| Sev | Id | Fixed | Title |`, `|---|---|---:|---|`);
+            for (const f of resolved) {
+                lines.push(`| ${SEVERITY_ICON[f.severity]} | \`${f.id}\` | ${describeAge(f.foundAt, now)} ago | ${escapeTableCell(f.title)} |`);
+            }
+            lines.push(``);
+        }
     }
     if (extras?.createdResources && extras.createdResources.length > 0) {
         lines.push(`## Data created by this session (cleanup list)`);
@@ -552,6 +607,15 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
         }
         lines.push(``);
     }
+    // How the run was paced. A reader who sees a session that did four actions
+    // in an hour learns more from that than from another coverage percentage.
+    // Omitted where the report is compared byte for byte, since it is timing.
+    // The sessions still attached, so the stale-browser warning names only the
+    // ones that could act on it. A lane that finished and closed is quiet
+    // because it is gone.
+    if (extras?.pace !== false) {
+        lines.push(...formatPace(measurePace(memory.actionLog, Date.now(), extras?.attachedSessions ?? [])));
+    }
     const markdown = lines.join("\n");
     const outPath = path.join(memory.dir, "report.md");
     const htmlPath = path.join(memory.dir, "report.html");

package/dist/engine/request.js

@@ -0,0 +1,144 @@
+/**
+ * Calling the app's own API with the UI bypassed.
+ *
+ * A refusal shown by hiding or disabling a button is not a refusal. Confirming
+ * that the server refuses the same action is the single most valuable check a
+ * permission pass makes, and until now it could only be done outside the tool
+ * — in a shell, with curl and a hand-extracted token — so none of that
+ * evidence reached the report. A whole validation run's permission matrices
+ * lived in shell history and vanished with it.
+ *
+ * The request is made by the PAGE, not beside it. That matters twice over:
+ * it goes through the same interception the write policy is enforced on, so a
+ * safe-write session cannot delete a record it does not own by calling the
+ * endpoint instead of clicking; and it carries the session's own credentials,
+ * because it is the same origin with the same cookies.
+ *
+ * Bearer schemes are handled by replaying the Authorization header the app
+ * itself last sent, which the engine already sees on every intercepted
+ * request. Nothing here knows what a token looks like or where an app keeps
+ * one, so nothing here is tuned to any app.
+ *
+ * Everything in this file is pure so it can be table-tested; the one
+ * `page.evaluate` lives in browser.ts.
+ */
+/** Methods a session may replay. Anything else is refused before it reaches the page. */
+export const REPLAYABLE_METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+/** Most of a response body that reaches the agent. A JSON list can be megabytes; the signature is in the first lines. */
+export const BODY_MAX = 2000;
+/** Response headers worth reporting. "Identical response" means status, body AND headers, so the ones that commonly differ are kept. */
+export const REPORTED_HEADERS = ["content-type", "content-length", "location", "www-authenticate", "retry-after", "x-request-id", "cache-control"];
+/**
+ * The path to call, resolved against the attached origin and fenced to it.
+ * Navigation is fenced the same way: a run attached to one app must not be
+ * able to make its browser talk to another host just because a path was
+ * spelled as a full URL.
+ */
+export function resolveRequestUrl(baseUrl, path) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return { problem: "No path given. Pass a path such as /api/things, or a full URL on the attached origin." };
+    let target;
+    let base;
+    try {
+        base = new URL(baseUrl);
+        target = new URL(trimmed, base);
+    }
+    catch {
+        return { problem: `Could not read ${JSON.stringify(trimmed)} as a path or a URL.` };
+    }
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+        return { problem: `Only http and https can be requested; ${target.protocol} cannot.` };
+    }
+    if (target.origin !== base.origin) {
+        return {
+            problem: `${target.origin} is not the origin this session is attached to (${base.origin}). A session talks to its own app only; attach another session to test another host.`,
+        };
+    }
+    return { url: target.toString() };
+}
+/** The method, upper-cased, or the reason it cannot be replayed. */
+export function resolveMethod(method) {
+    const upper = (method ?? "GET").trim().toUpperCase();
+    if (!REPLAYABLE_METHODS.includes(upper)) {
+        return { problem: `${upper} is not a method this can replay. Use one of: ${REPLAYABLE_METHODS.join(", ")}.` };
+    }
+    return { method: upper };
+}
+/**
+ * The script the page runs. Built as one expression so it can be evaluated
+ * directly, with every value passed through JSON rather than interpolated as
+ * code: a header value or a body is data from the agent, and a quote in it
+ * must not be able to end the string it sits in.
+ *
+ * `credentials: "include"` so the session's cookies go with it, and the
+ * app's own Authorization header is replayed when one has been seen.
+ */
+export function buildRequestScript(input) {
+    const { url, method, body, headers } = input;
+    const init = { method, credentials: "include", headers };
+    if (body !== undefined && method !== "GET" && method !== "HEAD")
+        init.body = body;
+    return (`(async () => { const started = Date.now();` +
+        ` const res = await fetch(${JSON.stringify(url)}, ${JSON.stringify(init)});` +
+        ` const text = await res.text();` +
+        ` const headers = {}; res.headers.forEach((v, k) => { headers[k] = v; });` +
+        ` return { status: res.status, statusText: res.statusText, headers, body: text.slice(0, ${BODY_MAX * 2}), full: text.length, ms: Date.now() - started, url: res.url }; })()`);
+}
+/** The headers to send: what the caller asked for, plus the app's own auth and a JSON content type when a body is present. */
+export function requestHeaders(input) {
+    const out = {};
+    // The app's own header first, so an explicit one from the caller wins — that
+    // is how a session tests what happens with a different or absent credential.
+    if (input.auth)
+        out["authorization"] = input.auth;
+    if (input.body !== undefined)
+        out["content-type"] = "application/json";
+    for (const [name, value] of Object.entries(input.given ?? {}))
+        out[name.toLowerCase()] = value;
+    return out;
+}
+/** The raw result of the in-page fetch, reduced to what the agent and the report need. */
+export function toReplayResult(raw) {
+    const kept = {};
+    for (const name of REPORTED_HEADERS) {
+        const value = raw.headers[name];
+        if (value !== undefined)
+            kept[name] = value;
+    }
+    return {
+        status: raw.status,
+        statusText: raw.statusText,
+        headers: kept,
+        body: raw.body.slice(0, BODY_MAX),
+        truncated: raw.full > BODY_MAX,
+        ms: raw.ms,
+        url: raw.url,
+    };
+}
+/** The signature a finding carries for this call: the line that dedups the same refusal across runs. */
+export function replaySignature(method, url, status) {
+    let path = url;
+    try {
+        const parsed = new URL(url);
+        path = parsed.pathname + parsed.search;
+    }
+    catch {
+        // Not a URL we can shorten; the whole string is the signature.
+    }
+    return `${method} ${path} ${status}`;
+}
+/** What the agent reads back. Leads with the signature, because that is what a finding quotes. */
+export function formatReplay(method, result) {
+    const lines = [replaySignature(method, result.url, result.status) + (result.statusText ? ` ${result.statusText}` : ""), `took ${result.ms} ms`];
+    const headers = Object.entries(result.headers);
+    if (headers.length > 0)
+        lines.push(headers.map(([k, v]) => `${k}: ${v}`).join(" · "));
+    if (result.body.length > 0) {
+        lines.push("", result.body + (result.truncated ? `\n… truncated at ${BODY_MAX} characters` : ""));
+    }
+    else {
+        lines.push("", "(empty body)");
+    }
+    return lines.join("\n");
+}

package/dist/engine/settle.js

@@ -0,0 +1,97 @@
+/**
+ * How long to wait after an action before reading the page.
+ *
+ * This used to be a flat 400 ms sleep on every action, for a good reason:
+ * `waitForLoadState("networkidle")` latches once reached and then resolves
+ * instantly forever after, so it cannot be used to wait out the request an
+ * action just fired, and draining the oracles before that request lands would
+ * misattribute its violations to the next step.
+ *
+ * The floor was still the wrong shape. Measured against a demo app, a snapshot
+ * cost 740 ms of which 400 ms was the sleep — 54% of the wall time — and a run
+ * of 203 actions spent 81 seconds asleep. Meanwhile a page slower than 400 ms
+ * got cut off exactly when it mattered.
+ *
+ * The engine already intercepts every request, so it knows what is in flight.
+ * Waiting on THAT, with a quiet window after the last one starts, is both
+ * faster on a page that answers quickly and more patient with one that does
+ * not. The old constant survives as a ceiling rather than a floor.
+ *
+ * The same rule carries the deliberate slow-down: a run being watched by a
+ * person taking notes wants a fixed pace, not the fastest one. `paceMs` is a
+ * floor a session asks for; unset, a session goes as fast as its page allows.
+ */
+/** No request has started for this long and none is in flight: the page has settled. */
+export const QUIET_MS = 120;
+/** Longest to wait for requests to drain, however busy the page is. A page that never goes quiet must not stall the run. */
+export const SETTLE_CAP_MS = 2000;
+/** How often the wait re-checks. */
+export const SETTLE_TICK_MS = 20;
+/**
+ * Whether to keep waiting. Split out from the browser so the rule can be
+ * table-tested: it is the difference between a run that is fast and one that
+ * reads a page before it has finished changing.
+ */
+export function shouldKeepWaiting(state) {
+    // A pace a session asked for is a floor on the whole wait, and it is the
+    // only reason to wait once everything else says the page is ready.
+    if (state.elapsedMs < state.paceMs)
+        return true;
+    // Never longer than the cap, whatever the page is doing.
+    if (state.elapsedMs >= SETTLE_CAP_MS)
+        return false;
+    // Something is still out: wait for it, up to the cap.
+    if (state.inFlight > 0)
+        return true;
+    // Nothing in flight and nothing recent. The action itself is the last event
+    // that could still produce a request, so the quiet window runs from whichever
+    // of the two is later. Without this, an action whose request comes back
+    // through a hop — a click that posts to a service worker, which then fetches —
+    // is read while the page is between the two, and the request lands during the
+    // NEXT action, which is then blamed for it.
+    return Math.min(state.sinceLastStartMs, state.elapsedMs) < QUIET_MS;
+}
+/** A pace a session asked for, clamped. Negative or absurd values are a typo, not an instruction. */
+export const PACE_MAX_MS = 60_000;
+export function normalizePace(paceMs) {
+    if (typeof paceMs !== "number" || !Number.isFinite(paceMs) || paceMs <= 0)
+        return 0;
+    return Math.min(Math.round(paceMs), PACE_MAX_MS);
+}
+/** What the attach result says about a deliberate pace, or nothing when the session runs at full speed. */
+export function describePace(paceMs) {
+    if (paceMs <= 0)
+        return "";
+    return `\n⏱ PACE: at least ${paceMs} ms between actions, so a person can follow along. Unset it with paceMs: 0 to go as fast as the page allows.`;
+}
+/**
+ * Waiting for a client-side redirect that has not happened yet.
+ *
+ * A guard that redirects on a timer after hydration issues no request until it
+ * fires, so there is nothing for the request-based settle above to wait on:
+ * it goes quiet, the URL is read, and the page reports the route it was asked
+ * for rather than the login page it actually bounced to. The old flat 400 ms
+ * sleep covered this by accident, and removing it made the bounce invisible
+ * whenever a loaded machine delayed the timer past the quiet window.
+ *
+ * So where a BOUNCE VERDICT is about to be made — attach judging a storage
+ * state, navigate judging coverage — the URL is watched until it has held
+ * still, rather than read once. This is paid per navigation, not per action.
+ */
+/**
+ * How long the URL must hold still before a bounce verdict is believed.
+ *
+ * This is a window, not a guarantee: a guard slower than it still lands after
+ * the verdict. What it buys is the realistic case — a guard written to fire
+ * promptly, delayed by a loaded machine — which is the one that made this
+ * project's own CI fail intermittently on a 40 ms timer.
+ */
+export const URL_QUIET_MS = 400;
+/** Longest to watch. A page redirecting in a loop must not hold up the run. */
+export const URL_CAP_MS = 3000;
+/** Whether to keep watching the URL before judging where the page landed. */
+export function keepWatchingUrl(w) {
+    if (w.elapsedMs >= URL_CAP_MS)
+        return false;
+    return w.sinceChangeMs < URL_QUIET_MS;
+}