scenescout 3.2.0 → 3.4.0

package/dist/engine/memory.js

@@ -25,6 +25,47 @@ export const FINDING_CATEGORIES = [
     "missing-testid",
     "other",
 ];
+/**
+ * Most states a route may keep. A route accumulates one state per distinct
+ * element set, so a register with filters, tabs and paging produces dozens;
+ * one project reached 6,075 states across 48 routes, a 36 MB history parsed
+ * and re-serialised on every save. Coverage is asked per ROUTE, so keeping the
+ * most recent states of each route preserves every answer the gap ledger
+ * needs while dropping the long tail nothing will ask about again.
+ */
+export const MAX_STATES_PER_ROUTE = 40;
+/**
+ * The states to keep. Never drops one a finding points at — a finding's repro
+ * trace and its route identity are read back from it — and never drops the
+ * newest of a route, so a route that was visited stays visited.
+ *
+ * Returns the pruned map rather than mutating, so the rule can be table-tested.
+ */
+export function pruneStates(states, findings, perRoute = MAX_STATES_PER_ROUTE) {
+    const pinned = new Set(findings.map((f) => f.state));
+    const byRoute = new Map();
+    for (const entry of Object.entries(states)) {
+        const route = entry[1].route;
+        const list = byRoute.get(route);
+        if (list)
+            list.push(entry);
+        else
+            byRoute.set(route, [entry]);
+    }
+    const kept = {};
+    let dropped = 0;
+    for (const list of byRoute.values()) {
+        // Newest first, so the survivors are the ones a next run will meet again.
+        list.sort((a, b) => (b[1].lastSeen ?? b[1].firstSeen).localeCompare(a[1].lastSeen ?? a[1].firstSeen));
+        list.forEach(([fp, rec], index) => {
+            if (index < perRoute || pinned.has(fp))
+                kept[fp] = rec;
+            else
+                dropped += 1;
+        });
+    }
+    return { kept, dropped };
+}
 /** An element class must appear on this many routes at minimum before it can count as shared chrome. */
 const CHROME_MIN_ROUTES = 4;
 /** …and on at least this share of all visited routes (a majority — "it's on every page"). */
@@ -209,8 +250,39 @@ export function mergeMemory(mine, theirs) {
     }
     if (Object.keys(out.roleAccess).length === 0)
         delete out.roleAccess;
+    // Lanes commonly run in SEPARATE processes — that is the point of a lane —
+    // so without this the spread at the top would keep one process's decisions
+    // and drop every other lane's, which is the exact bug this merge exists to
+    // prevent for findings. Keyed so merging the same foreign document twice is
+    // idempotent.
+    const byDecision = new Map();
+    for (const d of theirs.laneDecisions ?? [])
+        byDecision.set(decisionKey(d), d);
+    for (const d of mine.laneDecisions ?? [])
+        byDecision.set(decisionKey(d), d);
+    out.laneDecisions = [...byDecision.values()].sort((a, b) => a.at.localeCompare(b.at)).slice(-MAX_LANE_DECISIONS);
+    if (out.laneDecisions.length === 0)
+        delete out.laneDecisions;
     return out;
 }
+/**
+ * What makes two stored decisions the same judgement.
+ *
+ * Deliberately NOT the timestamp. `at` is stamped when the planner folds the
+ * reply, not when the lane judged, so relaying one reply twice — which the
+ * protocol invites, since a refused report is asked for again — wrote every
+ * decision a second time and doubled the lane's weight in the calibration.
+ * Identity is what was decided, so re-folding the same reply is a no-op.
+ */
+function decisionKey(d) {
+    return [d.lane, d.observation, d.verdict, d.severity ?? "", d.category ?? "", d.confidence, d.evidence ?? ""].join("|");
+}
+/**
+ * Most lane decisions kept. Calibration wants a few dozen; a long-lived
+ * project would otherwise accumulate every decision ever made and re-serialise
+ * them on each save, which is what made an old history slow to open.
+ */
+export const MAX_LANE_DECISIONS = 1000;
 const MAX_DISCOVERED_ROUTES = 300;
 /** Shared finding-similarity helpers (used by live dedup and retro-merge). */
 function findingTokens(s) {
@@ -254,7 +326,22 @@ function findingLiterals(...texts) {
  * (`/api/users/7` and `/api/users/9` are one endpoint) so a per-record repro
  * does not read as a per-record bug.
  */
-function endpointSignatures(evidence) {
+/**
+ * The signatures that identify a BUG: only those carrying a failure status.
+ *
+ * A bare `POST /api/orders` says which endpoint was involved, not what went
+ * wrong — a double submit and an accepted negative quantity both name it, and
+ * are two bugs. Exported so calibration applies the store's own rule instead
+ * of a second copy of this regex, which is what it had.
+ */
+export function failingSignatures(evidence) {
+    return new Set([...endpointSignatures(evidence)].filter((sig) => /\s[45]\d{2}$/.test(sig)));
+}
+/**
+ * The endpoint signatures a piece of evidence names: method + normalised path,
+ * with the failure status when one follows.
+ */
+export function endpointSignatures(evidence) {
     const out = new Set();
     if (!evidence)
         return out;
@@ -297,11 +384,10 @@ function sharesEndpointSignature(a, b) {
     // `POST /api/orders` (the endpoint answered 2xx, or no status was named)
     // says which endpoint was involved, not what went wrong: a double submit
     // and an accepted negative quantity both name it, and are two bugs.
-    const failing = (evidence) => new Set([...endpointSignatures(evidence)].filter((sig) => /\s[45]\d{2}$/.test(sig)));
-    const aSigs = failing(a.evidence);
+    const aSigs = failingSignatures(a.evidence);
     if (aSigs.size === 0)
         return false;
-    for (const sig of failing(b.evidence))
+    for (const sig of failingSignatures(b.evidence))
         if (aSigs.has(sig))
             return true;
     return false;
@@ -684,9 +770,34 @@ export class MemoryStore {
             constraints: "Constraints — rules discovered the hard way (gates, preconditions, limits)",
             risks: "Risks & watchpoints — fragile areas worth re-testing every run",
             glossary: "Glossary — domain terms and what they mean here",
+            setup: "Setup — how to get this app into a testable state (how a login state is regenerated, what has to be running)",
         };
         return `## ${titles[section] ?? section}`;
     }
+    /**
+     * What earlier runs recorded about getting this app testable, if anything.
+     *
+     * Read back by the auth-failure message. A storage state expires on a timer
+     * nobody remembers, and "regenerate it" is advice the reader already had;
+     * the command that worked last time is the part worth keeping, and it is
+     * exactly the kind of thing a run pays to find out and then forgets.
+     */
+    setupRecipe() {
+        if (!fs.existsSync(this.assumptionsPath))
+            return [];
+        const text = fs.readFileSync(this.assumptionsPath, "utf8");
+        const heading = MemoryStore.sectionHeading("setup");
+        const start = text.indexOf(heading);
+        if (start === -1)
+            return [];
+        const rest = text.slice(start + heading.length);
+        const end = rest.indexOf("\n## ");
+        return (end === -1 ? rest : rest.slice(0, end))
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.startsWith("- "))
+            .map((l) => l.slice(2).trim());
+    }
     readAssumptions() {
         if (!fs.existsSync(this.assumptionsPath))
             return "(no ASSUMPTIONS.md yet — record what you learn with scout_note as you explore)";
@@ -716,6 +827,45 @@ export class MemoryStore {
         fs.writeFileSync(this.assumptionsPath, content);
         return true;
     }
+    /** What the lanes decided, oldest first. Empty on a project that has never run one. */
+    get laneDecisions() {
+        return this.data.laneDecisions ?? [];
+    }
+    /**
+     * Record what a lane decided. Called once per accepted lane report, so the
+     * confidence it stated can be checked later against what the run filed.
+     * Free text from the lane is redacted like every other stored string: an
+     * observation is written by a model reading the app under test.
+     */
+    addLaneDecisions(lane, decisions) {
+        if (decisions.length === 0)
+            return 0;
+        const list = this.data.laneDecisions ?? [];
+        const seen = new Set(list.map(decisionKey));
+        let added = 0;
+        for (const d of decisions) {
+            const record = {
+                ...d,
+                lane,
+                observation: redactSecrets(d.observation).slice(0, 200),
+                evidence: d.evidence === null ? null : redactSecrets(d.evidence).slice(0, 200),
+            };
+            if (seen.has(decisionKey(record)))
+                continue;
+            seen.add(decisionKey(record));
+            list.push(record);
+            added += 1;
+        }
+        this.data.laneDecisions = list.slice(-MAX_LANE_DECISIONS);
+        if (added > 0)
+            this.flush();
+        // What survives the cap. Appends go to the tail and the cap keeps the
+        // tail, so all of `added` survives unless the call itself exceeds the cap.
+        // Measuring it as growth instead looked right and was not: `list` aliases
+        // the stored array, so the "before" length was read after the appends and
+        // every call after the first reported nothing kept — while storing fine.
+        return Math.min(added, MAX_LANE_DECISIONS);
+    }
     /** Mark a finding resolved; returns it or null. */
     resolveFinding(id) {
         const f = this.data.findings.find((x) => x.id === id);
@@ -725,13 +875,43 @@ export class MemoryStore {
         this.flush();
         return f;
     }
+    /**
+     * Record what a re-test of this finding found. "gone" resolves it; the other
+     * two leave it open and stamp the confirmation, which is what lets the report
+     * stop describing a finding somebody checked yesterday as unverified.
+     */
+    verifyFinding(id, verdict, note) {
+        const f = this.data.findings.find((x) => x.id === id);
+        if (!f)
+            return null;
+        f.verdict = verdict;
+        f.verifiedAt = new Date().toISOString();
+        if (note)
+            f.verifyNote = redactSecrets(note).slice(0, 500);
+        else
+            delete f.verifyNote;
+        if (verdict === "gone")
+            f.status = "resolved";
+        this.flush();
+        return f;
+    }
     load() {
         if (!fs.existsSync(this.memoryPath))
             return structuredClone(EMPTY);
         try {
             const raw = JSON.parse(fs.readFileSync(this.memoryPath, "utf8"));
-            if (raw.version === 1)
+            if (raw.version === 1) {
+                // Prune once, on open: the long tail of per-route states is what makes
+                // an old history slow to parse and re-serialise, and it answers no
+                // question the gap ledger asks. Findings and the newest states of
+                // every route are kept, so coverage does not regress.
+                const { kept, dropped } = pruneStates(raw.states ?? {}, raw.findings ?? []);
+                if (dropped > 0) {
+                    raw.states = kept;
+                    this.prunedStates = dropped;
+                }
                 return raw;
+            }
             this.loadWarning = `memory.json has unknown version ${String(raw.version)} — starting fresh.`;
         }
         catch (err) {
@@ -783,6 +963,8 @@ export class MemoryStore {
         // Deliberately NOT unref'd: a pending coverage write briefly holds the
         // process open so an exit without scout_close still lands the last save.
     }
+    /** How many states the last open pruned. Reported once, so a shrinking history is never silent. */
+    prunedStates = 0;
     /** Set when a debounced background write failed — cleared on the next successful write. Surfaced by scout_coverage/scout_close so a broken persistence path is never silently invisible. */
     lastSaveError = null;
     /**
@@ -907,6 +1089,7 @@ export class MemoryStore {
             this.data.states[fingerprint] = rec;
         }
         rec.visits += 1;
+        rec.lastSeen = new Date().toISOString();
         const present = new Set(elementKeys);
         for (const key of elementKeys) {
             if (!rec.elements[key])

package/dist/engine/oracles.js

@@ -137,6 +137,15 @@ export class OracleMonitor {
     noteInjection(detail, url) {
         this.record({ kind: "dom_injection", severity: "high", detail, url });
     }
+    /**
+     * The page contradicted a request that was refused during the same action:
+     * a refused list rendered as an empty state, or a refused save reported as a
+     * success. Found by the engine's DOM scan (claims.ts), like injections, so
+     * it is reported through here rather than by a page event.
+     */
+    noteContradiction(c, url) {
+        this.record({ kind: c.kind, severity: "high", detail: c.detail, url });
+    }
     record(v) {
         if (isPolicyInduced(v, this.lastPolicyBlockAt === null ? null : Date.now() - this.lastPolicyBlockAt)) {
             this.policyAttributed += 1;

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/report.js

@@ -1,8 +1,11 @@
 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 { calibrate, formatCalibration } from "./calibration.js";
+import { formatPace, measurePace } from "./pace.js";
 function playwrightSkeleton(f) {
     const routeClass = f.state.split("#")[0].split("?")[0];
     let gotoPath = routeClass;
@@ -68,6 +71,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 +399,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 +518,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 +548,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 +608,18 @@ 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 ?? [])));
+    }
+    // Only on a run that used lanes, and only once enough of them have been
+    // judged for the number to mean anything; formatCalibration decides both.
+    lines.push(...formatCalibration(calibrate(memory.laneDecisions, memory.findings)));
     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");
+}