scenescout 1.0.0

package/dist/engine/memory.js

@@ -0,0 +1,1116 @@
+import fs from "node:fs";
+import path from "node:path";
+import { normalizePath, shortHash } from "./fingerprint.js";
+/** 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"). */
+const CHROME_ROUTE_SHARE = 0.6;
+/**
+ * …OR on this many routes outright. A section shell (an admin sub-nav across 35
+ * of 99 routes) is below the majority share but is still one component repeated,
+ * not 35 separate surfaces.
+ */
+const CHROME_ABSOLUTE_ROUTES = 10;
+/** Pseudo-route the deduplicated shell surface is reported under. */
+export const SHARED_CHROME_ROUTE = "(shared layout chrome)";
+/**
+ * Outcome prefix for "this navigation was bounced to a login page".
+ *
+ * Distinct from a permission redirect on purpose. A permission redirect is a
+ * true fact about the app that should satisfy the completion contract for that
+ * role; an auth-loss bounce is a fact about OUR credentials expiring, and
+ * counting it as coverage let one dead token certify every route a run had not
+ * reached yet.
+ */
+export const AUTH_LOSS_PREFIX = "authloss:";
+/**
+ * Paths that look like a login screen.
+ *
+ * Duplicated deliberately rather than imported: memory.ts is the storage layer
+ * and must not depend on the engine layer. The duplication is not left on
+ * trust — policy-test.ts compares the two patterns' sources directly and fails
+ * if they drift, which the previous "kept in sync by the migration test"
+ * comment claimed but no test actually did.
+ */
+export const LOGIN_ROUTE_RE_STORAGE = /\/(login|signin|sign-in|auth)(\/|$)/;
+const LOGIN_ROUTE_RE = LOGIN_ROUTE_RE_STORAGE;
+/**
+ * Key an attempted route by the role that attempted it.
+ *
+ * No separator character: the role comes from the auth fixture's BASENAME, so
+ * it can never contain "/", and every route starts with one. Splitting at the
+ * first "/" is therefore unambiguous. A space looked like the obvious
+ * separator and was wrong — `qa admin.json` yields the role "qa admin", whose
+ * key would split into a role "qa" that does not exist, quietly crediting that
+ * route's coverage to the wrong identity.
+ */
+function roleRouteKey(role, route) {
+    return `${role}${route.startsWith("/") ? "" : "/"}${route}`;
+}
+/**
+ * Secrets an app leaks into its own error UI must not be re-published by the
+ * tool that found them. Findings quote app output verbatim, and that output has
+ * in practice included partial provider API keys; `.scenescout/` is gitignored
+ * but still gets zipped and attached to tickets. Keep a short prefix so the
+ * finding stays actionable, drop the rest.
+ */
+const SECRET_PATTERNS = [
+    // Needs the environment marker (sk_live_…) or a digit in the tail, or it
+    // eats ordinary identifiers: "pk_customer_identifier" became "pk_[redacted]".
+    [/\b(sk|pk|rk)[-_](?:(?:live|test|proj)[-_][A-Za-z0-9]{8,}|(?=[A-Za-z0-9]*\d)[A-Za-z0-9]{8,})/g, "$1_[redacted]"],
+    [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, "gh?_[redacted]"],
+    [/\bAKIA[0-9A-Z]{12,}/g, "AKIA[redacted]"],
+    // Keep the scheme that actually matched: rewriting a Basic-auth finding to
+    // say "Bearer" silently changes what the finding claims.
+    // Same entropy requirement as the keyword rule: "Basic authentication-required"
+    // is prose, and redacting it rewrote a sentence into nonsense.
+    [/\b(Bearer|Basic)\s+(?=[A-Za-z0-9._~+/=-]*\d)[A-Za-z0-9._~+/=-]{16,}/gi, "$1 [redacted]"],
+    [/\beyJ[A-Za-z0-9._-]{20,}/g, "eyJ[redacted-jwt]"],
+    // Keyword-led values need an entropy signal — a digit AND a letter, no
+    // internal word breaks. Without it this matched ordinary English: "Password
+    // requirements are not enforced" became "Password [redacted] are not
+    // enforced", and a mangled finding just reads as the agent writing nonsense.
+    [/\b(api[-_]?key|secret|password|token)(["'\s:=]+)(?=[A-Za-z0-9._~+/=-]*\d)(?=[A-Za-z0-9._~+/=-]*[A-Za-z])[A-Za-z0-9._~+/=]{12,}/gi, "$1$2[redacted]"],
+];
+/**
+ * Strip anything that looks like a credential from text we are about to persist.
+ *
+ * Silent edits are their own hazard, so a redaction announces itself: a reader
+ * who sees mangled-looking text needs to know the tool did it deliberately.
+ */
+export function redactSecrets(text) {
+    let out = text;
+    let hits = 0;
+    for (const [re, replacement] of SECRET_PATTERNS) {
+        out = out.replace(re, (...args) => {
+            hits += 1;
+            return replacement.replace(/\$(\d)/g, (_, n) => String(args[Number(n)] ?? ""));
+        });
+    }
+    return hits > 0 ? `${out} [${hits} secret${hits === 1 ? "" : "s"} redacted]` : out;
+}
+const EMPTY = { version: 1, states: {}, findings: [] };
+/**
+ * Fold another process's memory into ours, losing nothing from either side.
+ *
+ * Two SceneScout processes on one project each hold a full snapshot and each
+ * write the whole document, so whoever flushed last silently erased the
+ * other's findings — a run could finish with a report that omits half of what
+ * was found, with no error anywhere. Rather than lock (which would have to
+ * survive crashes), re-read before writing and merge.
+ *
+ * Every rule is idempotent, because a flush may merge the same foreign state
+ * repeatedly: counters take the MAX rather than summing, booleans OR, and sets
+ * union. Summing would inflate run counts on every subsequent flush.
+ */
+export function mergeMemory(mine, theirs) {
+    const out = { ...theirs, ...mine, version: 1 };
+    out.states = { ...theirs.states };
+    for (const [fp, ours] of Object.entries(mine.states)) {
+        const other = theirs.states[fp];
+        if (!other) {
+            out.states[fp] = ours;
+            continue;
+        }
+        const elements = { ...other.elements };
+        for (const [key, el] of Object.entries(ours.elements)) {
+            const prev = elements[key];
+            elements[key] = {
+                exercised: (prev?.exercised ?? false) || el.exercised,
+                // Keep whichever action was actually recorded; ours wins a tie.
+                ...((el.lastAction ?? prev?.lastAction) ? { lastAction: el.lastAction ?? prev?.lastAction } : {}),
+                absentStreak: Math.min(prev?.absentStreak ?? 0, el.absentStreak ?? 0),
+            };
+        }
+        out.states[fp] = {
+            ...ours,
+            firstSeen: ours.firstSeen < other.firstSeen ? ours.firstSeen : other.firstSeen,
+            visits: Math.max(ours.visits, other.visits),
+            elements,
+        };
+    }
+    const byId = new Map();
+    for (const f of theirs.findings)
+        byId.set(f.id, f);
+    for (const f of mine.findings) {
+        const other = byId.get(f.id);
+        if (!other) {
+            byId.set(f.id, f);
+            continue;
+        }
+        // Later knowledge wins on the mutable fields; a resolution is only kept if
+        // the other side did not go on to re-find it as a regression.
+        const newer = f.foundAt >= other.foundAt ? f : other;
+        const older = newer === f ? other : f;
+        byId.set(f.id, {
+            ...newer,
+            runs: Math.max(f.runs, other.runs),
+            evidence: newer.evidence ?? older.evidence,
+            regressedAt: newer.regressedAt ?? older.regressedAt,
+        });
+    }
+    out.findings = [...byId.values()];
+    const unionRecord = (a, b) => (a || b ? { ...(b ?? {}), ...(a ?? {}) } : undefined);
+    out.discoveredRoutes = unionRecord(mine.discoveredRoutes, theirs.discoveredRoutes);
+    out.attemptedRoutes = unionRecord(mine.attemptedRoutes, theirs.attemptedRoutes);
+    out.designElements = unionRecord(mine.designElements, theirs.designElements);
+    out.pageScores = { ...(theirs.pageScores ?? {}) };
+    for (const [route, score] of Object.entries(mine.pageScores ?? {})) {
+        const other = out.pageScores[route];
+        if (!other || score.at >= other.at)
+            out.pageScores[route] = score;
+    }
+    if (Object.keys(out.pageScores).length === 0)
+        delete out.pageScores;
+    out.routeFacts = { ...(theirs.routeFacts ?? {}) };
+    for (const [route, facts] of Object.entries(mine.routeFacts ?? {})) {
+        const other = out.routeFacts[route] ?? {};
+        out.routeFacts[route] = {
+            audited: facts.audited || other.audited || undefined,
+            mutated: facts.mutated || other.mutated || undefined,
+            journeys: Math.max(facts.journeys ?? 0, other.journeys ?? 0) || undefined,
+            journeysCompleted: Math.max(facts.journeysCompleted ?? 0, other.journeysCompleted ?? 0) || undefined,
+        };
+    }
+    if (Object.keys(out.routeFacts).length === 0)
+        delete out.routeFacts;
+    out.roleAccess = { ...(theirs.roleAccess ?? {}) };
+    for (const [role, routes] of Object.entries(mine.roleAccess ?? {})) {
+        out.roleAccess[role] = { ...(out.roleAccess[role] ?? {}), ...routes };
+    }
+    if (Object.keys(out.roleAccess).length === 0)
+        delete out.roleAccess;
+    return out;
+}
+const MAX_DISCOVERED_ROUTES = 300;
+/** Shared finding-similarity helpers (used by live dedup and retro-merge). */
+function findingTokens(s) {
+    return new Set(s
+        .toLowerCase()
+        .replace(/[^a-z0-9/ ]+/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 2)
+        // crude stemming so entries/entry, displays/display collide
+        .map((t) => t.replace(/ies$/, "y").replace(/(?<=\w{3})e?s$/, "")));
+}
+function findingJaccard(a, b) {
+    const inter = [...a].filter((t) => b.has(t)).length;
+    const union = new Set([...a, ...b]).size;
+    return union === 0 ? 0 : inter / union;
+}
+/**
+ * Distinctive literals — quoted or parenthesized fragments like
+ * `"(role not recorded)"` or `"Document not found"`. Two findings on the same
+ * route sharing one are the same bug however the prose around it is phrased.
+ */
+function findingLiterals(...texts) {
+    const out = new Set();
+    for (const text of texts) {
+        if (!text)
+            continue;
+        for (const m of text.matchAll(/"([^"]{8,80})"|'([^']{8,80})'|\(([^)]{8,80})\)|“([^”]{8,80})”/g)) {
+            const literal = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? "").toLowerCase().trim();
+            if (literal)
+                out.add(literal);
+        }
+    }
+    return out;
+}
+/**
+ * Canonical `METHOD /path STATUS` triples named by a finding's evidence.
+ *
+ * `evidence` exists to be a MACHINE signature, so when two findings name the
+ * same endpoint failing the same way they are the same bug — whichever page
+ * the tester happened to be on when they wrote it up. Ids in the path collapse
+ * (`/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) {
+    const out = new Set();
+    if (!evidence)
+        return out;
+    const endpoints = [...evidence.matchAll(/\b(GET|POST|PUT|PATCH|DELETE)\s+(?:https?:\/\/[^/\s]+)?(\/[A-Za-z0-9/_.:{}$-]*)/gi)];
+    for (const [i, m] of endpoints.entries()) {
+        const method = m[1].toUpperCase();
+        const path = normalizePath(m[2].replace(/\/+$/, "") || "/").toLowerCase();
+        // Each endpoint takes the status from its OWN window — the text between it
+        // and the next endpoint mentioned. Pairing every endpoint with every status
+        // in the string invented signatures that were never claimed: evidence
+        // reading "list loads (GET /api/x 200) but POST /api/x returns 500" also
+        // produced "GET /api/x 500", which then merged — and silently discarded —
+        // a genuine, separate finding about the GET. Two-endpoint evidence is
+        // ordinary prose ("this works, that doesn't"), not an edge case.
+        // The status must FOLLOW its endpoint. Reading one from earlier in the
+        // string turned a quantity into a status — "list shows 500 items; GET
+        // /api/items 200" claimed a 500 on an endpoint the evidence said returned
+        // 200. So `GET /api/x 404` written as "404 on GET /api/x" yields only
+        // `GET /api/x` and will not merge with the same bug written the other way
+        // round: a visible duplicate, which is the safe direction to fail, since
+        // the alternative discards a finding.
+        const from = (m.index ?? 0) + m[0].length;
+        const to = i + 1 < endpoints.length ? (endpoints[i + 1].index ?? evidence.length) : evidence.length;
+        const status = /\b([45]\d{2})\b/.exec(evidence.slice(from, to))?.[1];
+        out.add(status ? `${method} ${path} ${status}` : `${method} ${path}`);
+    }
+    return out;
+}
+/**
+ * Same endpoint, same failure — regardless of which route it was filed from.
+ * The route-scoped rules below cannot see this: one agent filed the analytics
+ * 404 from the page that calls it, another from a different page, so two
+ * findings for one bug survived a run. Requires evidence on BOTH sides and an
+ * exact triple match, so it stays a machine-signal match, never a fuzzy one.
+ */
+function sharesEndpointSignature(a, b) {
+    if (!a.evidence || !b.evidence)
+        return false;
+    const aSigs = endpointSignatures(a.evidence);
+    if (aSigs.size === 0)
+        return false;
+    for (const sig of endpointSignatures(b.evidence))
+        if (aSigs.has(sig))
+            return true;
+    return false;
+}
+/**
+ * The cross-route merge rule, with the two guards a bare signature match needs.
+ *
+ * - NEVER absorb into a RESOLVED finding. Without evidence identical enough to
+ *   count as a regression, a signature match would increment the old entry's
+ *   run count and return it — so a genuinely new bug on an endpoint that once
+ *   had a fixed bug would never appear in the report at all. A duplicate is
+ *   visible and cheap; a swallowed finding is neither.
+ * - Require the same CATEGORY. One endpoint+status can carry two different
+ *   bugs (a `security` 403 and a `ux-confusing` 403; a 400 for a bad date and a
+ *   400 for a zero quantity), and the loser's title, detail and severity are
+ *   discarded on merge.
+ */
+function sameEndpointBug(existing, incoming) {
+    if (existing.status === "resolved")
+        return false;
+    if (existing.category !== incoming.category)
+        return false;
+    return sharesEndpointSignature(existing, incoming);
+}
+function sameFinding(a, b) {
+    const aEv = a.evidence?.toLowerCase().replace(/\s+/g, " ").trim();
+    const bEv = b.evidence?.toLowerCase().replace(/\s+/g, " ").trim();
+    if (aEv && bEv && aEv === bEv)
+        return true;
+    // A shared distinctive literal (e.g. "Document not found anymore") marks the
+    // same bug even when two sessions wrote DIFFERENT evidence strings. The
+    // literal must be one the finding is ABOUT — i.e. quoted in at least one of
+    // the two TITLES. Drawing it from detail prose as well merged unrelated bugs
+    // that merely described the same screen: a data-integrity finding and a
+    // layout finding on one page both quoted the UI strings they saw, shared
+    // them, and collapsed into one. Matching a title literal against the other
+    // finding's full text keeps the intended case (one states the string in its
+    // title, the other mentions it in its detail).
+    const aTitleLits = findingLiterals(a.title);
+    const bTitleLits = findingLiterals(b.title);
+    if (aTitleLits.size > 0 || bTitleLits.size > 0) {
+        const aAll = findingLiterals(a.title, a.detail, a.evidence);
+        const bAll = findingLiterals(b.title, b.detail, b.evidence);
+        for (const lit of aTitleLits)
+            if (bAll.has(lit))
+                return true;
+        for (const lit of bTitleLits)
+            if (aAll.has(lit))
+                return true;
+    }
+    // Both carry evidence and neither matched above: distinct bugs, however
+    // similar the titles — never fuzzy-merge across differing evidence.
+    if (aEv && bEv)
+        return false;
+    return findingJaccard(findingTokens(a.title), findingTokens(b.title)) >= 0.5;
+}
+/** Per-project directory for memory, session logs, and reports. */
+export const MEMORY_DIRNAME = ".scenescout";
+/** What the directory was called before the tool was renamed. */
+export const LEGACY_MEMORY_DIRNAME = ".scenecraft";
+/**
+ * Carry a project's memory across the rename. Coverage, findings and notes are
+ * the whole point of cross-run memory; starting an empty `.scenescout/` next to
+ * a full legacy directory would silently throw every earlier run away and
+ * re-report every known finding as new.
+ *
+ * Only when the new directory does not exist yet — once both are present the
+ * new one is authoritative and the old one is left for the user to delete.
+ * Returns a note for the attach output, or null when there was nothing to do.
+ */
+export function adoptLegacyMemoryDir(projectDir, isAlive = pidAlive) {
+    const current = path.join(projectDir, MEMORY_DIRNAME);
+    const legacy = path.join(projectDir, LEGACY_MEMORY_DIRNAME);
+    if (fs.existsSync(current) || !fs.existsSync(legacy))
+        return null;
+    // A pre-rename engine that is still running holds absolute paths into the
+    // legacy directory. Moving it away makes every later write of that run fail,
+    // and the only trace is a stderr line nobody reads. Leave it until it exits.
+    const owner = liveOwnerPid(legacy, isAlive);
+    if (owner !== null) {
+        return `A pre-rename engine (pid ${owner}) is still using ${LEGACY_MEMORY_DIRNAME}/, so its memory was NOT moved — this run starts empty. Close that session and re-attach to carry the earlier coverage and findings over.`;
+    }
+    try {
+        fs.renameSync(legacy, current);
+    }
+    catch (err) {
+        // Two engines attaching at once both pass the guard above; the loser's
+        // rename fails because the winner already moved it. That is success.
+        if (fs.existsSync(current))
+            return null;
+        // A read-only checkout must not break attach; say what was lost instead.
+        return `Could not move ${LEGACY_MEMORY_DIRNAME}/ to ${MEMORY_DIRNAME}/ (${err.message}) — this run starts without the earlier memory.`;
+    }
+    return `Moved this project's memory from ${LEGACY_MEMORY_DIRNAME}/ to ${MEMORY_DIRNAME}/ (the tool was renamed); earlier coverage and findings are kept.`;
+}
+/** Signal 0 probes existence. EPERM means the process exists but is another user's — still alive. */
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err?.code === "EPERM";
+    }
+}
+/** The pid named by a memory directory's status.json, when that process is still running and is not us. */
+function liveOwnerPid(dir, isAlive) {
+    try {
+        const st = JSON.parse(fs.readFileSync(path.join(dir, "status.json"), "utf8"));
+        return st.pid && st.pid !== process.pid && isAlive(st.pid) ? st.pid : null;
+    }
+    catch {
+        return null; // no status file, or a truncated one: nothing is provably using it
+    }
+}
+/**
+ * Keep our artifacts out of the tested project's commits.
+ *
+ * We write memory.json, rolling session logs, status.json and report.md into
+ * the project under test, so `.scenescout/` turns up as untracked and a single
+ * `git add -A` sweeps a test tool's scratch data into someone else's history.
+ *
+ * The ignore rule goes INSIDE our own directory rather than in the project's
+ * root .gitignore: git reads nested .gitignore files, `*` makes every file
+ * here invisible, and a directory holding only ignored files never appears in
+ * `git status`. That gets the same result without editing a file we do not
+ * own, and it disappears cleanly when someone deletes the directory.
+ *
+ * Best-effort and idempotent — a read-only checkout must never break attach,
+ * and an existing file is left exactly as the user left it.
+ */
+function writeSelfIgnore(dir) {
+    try {
+        const ignorePath = path.join(dir, ".gitignore");
+        if (fs.existsSync(ignorePath))
+            return null;
+        fs.writeFileSync(ignorePath, "# SceneScout exploratory-test artifacts: memory, session logs, status, report.\n" +
+            "# Self-ignoring so a `git add -A` in the tested project can never commit them.\n" +
+            "*\n");
+        return `Wrote ${MEMORY_DIRNAME}/.gitignore so these test artifacts stay out of your commits.`;
+    }
+    catch {
+        return null; // housekeeping must never break a run
+    }
+}
+/**
+ * Persistent exploration memory, stored in `.scenescout/` inside the
+ * tested project. This is what makes run N+1 not repeat run N: visited state
+ * fingerprints, per-element exercise status, and deduplicated findings.
+ */
+export class MemoryStore {
+    dir;
+    data;
+    memoryPath;
+    sessionLogPath;
+    /** Rolling in-session action log (also the repro-trace source). */
+    actionLog = [];
+    /** Set when the on-disk memory could not be loaded — surfaced to the driver instead of silently resetting. */
+    loadWarning = null;
+    /** Set when we added ourselves to the project's .gitignore — reported, never silent. */
+    gitIgnoreNote;
+    /** Set when this attach moved a pre-rename memory directory into place. */
+    legacyDirNote;
+    /** When this session started — findings re-seen after this are "current", older ones "historical". */
+    sessionStart = new Date().toISOString();
+    /**
+     * Resources created by THIS RUN (safe-write): id → collection paths.
+     *
+     * Deliberately lives on the shared MemoryStore rather than per-engine:
+     * every named session attached to a project shares one store, and a
+     * multi-role run is conceptually ONE test. Role A creating a record that
+     * role B must then act on (submit → approve, raise → investigate) is the
+     * entire point of multi-role testing, so ownership has to be shared or
+     * every handoff gets blocked as "not yours". Not persisted to disk —
+     * ownership must never outlive the process that did the creating.
+     */
+    ownedIds = new Map();
+    /** Human-readable creation log for this run — becomes the report's cleanup list. */
+    createdResources = [];
+    constructor(projectDir) {
+        this.dir = path.join(projectDir, MEMORY_DIRNAME);
+        this.legacyDirNote = adoptLegacyMemoryDir(projectDir);
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.gitIgnoreNote = writeSelfIgnore(this.dir);
+        this.memoryPath = path.join(this.dir, "memory.json");
+        this.sessionLogPath = path.join(this.dir, `session-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`);
+        this.sweepStaleTemps();
+        this.data = this.load();
+        this.fileSig = this.currentSig();
+        this.retroMerge();
+        this.reclassifyLegacyAuthLoss();
+    }
+    /**
+     * Re-file pre-v0.17 login bounces as auth-loss.
+     *
+     * Before this release every redirect was written as `landed:<route>`, so a
+     * run whose token died mid-way recorded `landed:/login` for each route it
+     * failed to reach — and those entries still satisfy the completion contract
+     * for every role. Without this migration the upgrade quietly carries the
+     * exact defect the release fixes: an old memory.json goes on certifying
+     * routes nobody ever saw.
+     */
+    reclassifyLegacyAuthLoss() {
+        const map = this.data.attemptedRoutes;
+        if (!map)
+            return;
+        let changed = false;
+        for (const [key, outcome] of Object.entries(map)) {
+            if (!outcome.startsWith("landed:"))
+                continue;
+            if (!LOGIN_ROUTE_RE.test(outcome.slice("landed:".length)))
+                continue;
+            map[key] = `${AUTH_LOSS_PREFIX}${outcome.slice("landed:".length)}`;
+            changed = true;
+        }
+        if (changed)
+            this.flush();
+    }
+    /**
+     * Merge stored duplicate findings recorded before smarter dedup existed
+     * (paraphrased titles across sessions). Applies the same three-tier match
+     * used by addFinding; keeps the earliest entry, sums runs.
+     */
+    retroMerge() {
+        const findings = this.data.findings;
+        if (findings.length < 2)
+            return;
+        const kept = [];
+        let merged = 0;
+        for (const f of findings) {
+            const fRoute = f.state.split("#")[0];
+            const dupOf = kept.find((k) => (k.state.split("#")[0] === fRoute && sameFinding(k, f)) || sameEndpointBug(k, f));
+            if (dupOf) {
+                dupOf.runs += f.runs;
+                if (!dupOf.evidence && f.evidence)
+                    dupOf.evidence = f.evidence;
+                if (f.status === "resolved")
+                    dupOf.status = "resolved";
+                merged += 1;
+            }
+            else {
+                kept.push(f);
+            }
+        }
+        if (merged > 0) {
+            this.data.findings = kept;
+            this.flush();
+        }
+    }
+    /** Record link-harvested routes (class → navigable example); returns how many were new. */
+    addDiscoveredRoutes(entries) {
+        const map = this.data.discoveredRoutes ?? {};
+        let added = 0;
+        for (const { route, example } of entries) {
+            if (Object.keys(map).length >= MAX_DISCOVERED_ROUTES)
+                break;
+            if (!(route in map)) {
+                map[route] = example;
+                added += 1;
+            }
+        }
+        if (added > 0) {
+            this.data.discoveredRoutes = map;
+            this.save();
+        }
+        return added;
+    }
+    get discoveredRoutes() {
+        return this.data.discoveredRoutes ?? {};
+    }
+    /**
+     * Record that a route was attempted but landed elsewhere (e.g. auth-redirect).
+     *
+     * Keyed by ROLE as well as route. A permission redirect is a fact about one
+     * role — "the operator cannot reach /admin" must not also mean "nobody needs
+     * to test /admin", which is what a role-blind key silently asserted: the
+     * low-privilege role bouncing off an admin route erased that route from the
+     * ADMIN's gap ledger permanently.
+     */
+    markAttempted(route, outcome, role = "default") {
+        const map = this.data.attemptedRoutes ?? {};
+        const key = roleRouteKey(role, route);
+        if (map[key] !== outcome) {
+            map[key] = outcome;
+            this.data.attemptedRoutes = map;
+            this.save();
+        }
+    }
+    /**
+     * Routes this role attempted, and how they resolved. `authloss:` outcomes are
+     * excluded — a navigation the session's dead credentials bounced to a login
+     * page is not evidence the route was covered, and treating it as such let an
+     * expired token silently certify the whole remaining route list.
+     */
+    attemptedByRole(role = "default") {
+        const out = {};
+        for (const [key, outcome] of Object.entries(this.data.attemptedRoutes ?? {})) {
+            if (outcome.startsWith(AUTH_LOSS_PREFIX))
+                continue;
+            const sep = key.indexOf("/");
+            // A key that STARTS with "/" carries no role prefix — that is the shape
+            // written before attempts were role-scoped. Honour it for every role
+            // rather than dropping coverage a previous run legitimately earned.
+            if (sep === 0)
+                out[key] = outcome;
+            else if (sep > 0 && key.slice(0, sep) === role)
+                out[key.slice(sep)] = outcome;
+        }
+        return out;
+    }
+    /** Every attempt, flattened to route → outcome, for reporting. */
+    get attemptedRoutes() {
+        const out = {};
+        for (const [key, outcome] of Object.entries(this.data.attemptedRoutes ?? {})) {
+            const sep = key.indexOf("/");
+            out[sep <= 0 ? key : key.slice(sep)] = outcome;
+        }
+        return out;
+    }
+    /** Record the latest design-audit score for a route. */
+    setPageScore(route, score) {
+        const map = this.data.pageScores ?? {};
+        map[route] = score;
+        this.data.pageScores = map;
+        this.save();
+    }
+    get pageScores() {
+        return this.data.pageScores ?? {};
+    }
+    /** Merge testing facts for a route (audited / mutated / journey count). */
+    markRouteFact(route, fact) {
+        const map = this.data.routeFacts ?? {};
+        const rec = map[route] ?? {};
+        if (fact.audited)
+            rec.audited = true;
+        if (fact.mutated)
+            rec.mutated = true;
+        if (fact.journeys)
+            rec.journeys = (rec.journeys ?? 0) + fact.journeys;
+        if (fact.journeysCompleted)
+            rec.journeysCompleted = (rec.journeysCompleted ?? 0) + fact.journeysCompleted;
+        map[route] = rec;
+        this.data.routeFacts = map;
+        this.save();
+    }
+    get routeFacts() {
+        return this.data.routeFacts ?? {};
+    }
+    /** Record that `role` reached (or was denied) `route`. Denials never overwrite a recorded "reached" — flaky redirects must not erase real access. */
+    recordRoleAccess(role, route, outcome) {
+        const all = this.data.roleAccess ?? {};
+        const forRole = all[role] ?? {};
+        if (forRole[route] === "reached" && outcome !== "reached")
+            return;
+        if (forRole[route] === outcome)
+            return;
+        forRole[route] = outcome;
+        all[role] = forRole;
+        this.data.roleAccess = all;
+        this.save();
+    }
+    get roleAccess() {
+        return this.data.roleAccess ?? {};
+    }
+    // ---- ASSUMPTIONS.md — cumulative WRITTEN knowledge about the tested app. ----
+    // memory.json stores coverage booleans; this stores understanding: what the
+    // app is for, who each role is and what they do, conventions, constraints
+    // ("an order can only ship once approved"). It compounds across
+    // runs, so run N+1 starts smarter than run N — in prose a human can read
+    // and correct.
+    get assumptionsPath() {
+        return path.join(this.dir, "ASSUMPTIONS.md");
+    }
+    static ASSUMPTION_SECTIONS = ["app-model", "roles", "conventions", "constraints", "risks", "glossary"];
+    static sectionHeading(section) {
+        const titles = {
+            "app-model": "App model — what this application is and does",
+            roles: "Roles & personas — who uses it and what each role is FOR",
+            conventions: "Conventions — patterns the app follows (naming, flows, UI idioms)",
+            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",
+        };
+        return `## ${titles[section] ?? section}`;
+    }
+    readAssumptions() {
+        if (!fs.existsSync(this.assumptionsPath))
+            return "(no ASSUMPTIONS.md yet — record what you learn with scout_note as you explore)";
+        return fs.readFileSync(this.assumptionsPath, "utf8");
+    }
+    /** Append one dated, attributed bullet under a section; exact-duplicate notes are dropped. Returns whether it was new. */
+    addAssumption(section, note, attribution) {
+        // Notes are free prose the agent often builds from app output; this file is
+        // the one most likely to be pasted into a ticket.
+        const clean = redactSecrets(note.trim().replace(/\s+/g, " "));
+        if (!clean)
+            return false;
+        let content = fs.existsSync(this.assumptionsPath)
+            ? fs.readFileSync(this.assumptionsPath, "utf8")
+            : `# Assumptions — cumulative knowledge about this application\n\nWritten by SceneScout runs; corrections welcome — the tester reads this file at the start of every session.\n`;
+        // Dedupe on the note text itself, ignoring the date/attribution prefix.
+        if (content.includes(`— ${clean}`))
+            return false;
+        const heading = MemoryStore.sectionHeading(section);
+        const bullet = `- (${new Date().toISOString().slice(0, 10)}, ${attribution}) — ${clean}`;
+        if (content.includes(heading)) {
+            content = content.replace(heading, `${heading}\n${bullet}`);
+        }
+        else {
+            content += `\n${heading}\n${bullet}\n`;
+        }
+        fs.writeFileSync(this.assumptionsPath, content);
+        return true;
+    }
+    /** Mark a finding resolved; returns it or null. */
+    resolveFinding(id) {
+        const f = this.data.findings.find((x) => x.id === id);
+        if (!f)
+            return null;
+        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)
+                return raw;
+            this.loadWarning = `memory.json has unknown version ${String(raw.version)} — starting fresh.`;
+        }
+        catch (err) {
+            // Never silently overwrite the (possibly recoverable) history — cross-run
+            // memory is the product promise. Preserve the corrupt file and say so.
+            const backup = `${this.memoryPath}.corrupt-${Date.now()}`;
+            try {
+                fs.renameSync(this.memoryPath, backup);
+                this.loadWarning = `memory.json was corrupt (${err instanceof Error ? err.message : err}); preserved as ${path.basename(backup)}, starting fresh.`;
+            }
+            catch {
+                this.loadWarning = "memory.json is corrupt and could not be preserved — starting fresh.";
+            }
+        }
+        return structuredClone(EMPTY);
+    }
+    saveTimer = null;
+    /**
+     * Debounced save: coverage bookkeeping calls this several times per action,
+     * and serialising the whole history synchronously each time is the main
+     * per-action latency cost. Coalesce writes; findings and shutdown call
+     * flush() directly for durability. The JSONL action log remains the
+     * per-event durable trail either way.
+     */
+    save() {
+        if (this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            try {
+                this.flush();
+            }
+            catch (err) {
+                // A background debounced write has no caller to report to — a
+                // failure here (deleted project dir, disk full, permissions) must
+                // not crash the whole engine process over a transient filesystem
+                // issue. But it also must not vanish: without this, every write
+                // from here on silently stops persisting and nothing downstream
+                // (scout_coverage, the final report) would know coverage tracking
+                // broke. Log it (stderr — safe under stdio MCP transport, which
+                // owns stdout) and store it for the next scout_coverage/scout_close to
+                // surface. Explicit flush() callers (resolveFinding, scout_close, …)
+                // still throw and are handled at the MCP tool boundary directly.
+                const msg = err instanceof Error ? err.message : String(err);
+                this.lastSaveError = msg;
+                console.error(`[scenescout] background memory write failed: ${msg}`);
+            }
+        }, 500);
+        // Deliberately NOT unref'd: a pending coverage write briefly holds the
+        // process open so an exit without scout_close still lands the last save.
+    }
+    /** 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;
+    /**
+     * Write memory.json now (atomic: a crash mid-write must not truncate the
+     * history file).
+     *
+     * The temp file carries this process's pid and a counter. A fixed `.tmp`
+     * path meant two SceneScout processes on one project interleaved their
+     * writes into a single inode, and whichever rename landed second published
+     * a half-and-half document that failed to parse on the next load — the
+     * rename made the publish atomic but not the write that fed it. The cost is
+     * that an interrupted flush leaks a temp file rather than self-overwriting,
+     * so the constructor sweeps them.
+     *
+     * Not pretty-printed: nobody hand-reads a multi-megabyte history file, and
+     * the indentation was ~40% of the bytes written on every single finding.
+     *
+     * MERGE BEFORE WRITE. Each process holds a full snapshot and writes the whole
+     * document, so a straight write makes the last flush win outright and erases
+     * whatever another process recorded meanwhile — silently, since the write
+     * itself succeeds. If the file changed under us, fold it in first.
+     */
+    flush() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        if (this.changedUnderUs()) {
+            const theirs = this.readForMerge();
+            if (theirs)
+                this.data = mergeMemory(this.data, theirs);
+        }
+        const tmp = `${this.memoryPath}.${process.pid}.${this.tmpCounter++}.tmp`;
+        try {
+            fs.writeFileSync(tmp, JSON.stringify(this.data));
+            fs.renameSync(tmp, this.memoryPath);
+        }
+        catch (err) {
+            try {
+                fs.rmSync(tmp, { force: true });
+            }
+            catch {
+                /* the write already failed; a leftover temp file is the lesser problem */
+            }
+            throw err;
+        }
+        this.fileSig = this.currentSig();
+        this.lastSaveError = null;
+    }
+    tmpCounter = 0;
+    /** mtime+size of the file as WE last left it; a mismatch means someone else wrote. */
+    fileSig = "";
+    currentSig() {
+        try {
+            const st = fs.statSync(this.memoryPath);
+            return `${st.mtimeMs}:${st.size}`;
+        }
+        catch {
+            return "";
+        }
+    }
+    changedUnderUs() {
+        const sig = this.currentSig();
+        return sig !== "" && sig !== this.fileSig;
+    }
+    /** Re-read the on-disk document for merging. Never destructive: a corrupt or
+     *  half-written file just means there is nothing to merge this time. */
+    readForMerge() {
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.memoryPath, "utf8"));
+            return raw.version === 1 ? raw : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Remove temp files a crashed process left behind. The pid-scoped name that
+     * fixed interleaved writes also stopped them self-overwriting, so an
+     * interrupted flush now leaks one file per crash instead of reusing one.
+     */
+    sweepStaleTemps() {
+        try {
+            const prefix = `${path.basename(this.memoryPath)}.`;
+            for (const name of fs.readdirSync(this.dir)) {
+                if (name.startsWith(prefix) && name.endsWith(".tmp")) {
+                    fs.rmSync(path.join(this.dir, name), { force: true });
+                }
+            }
+        }
+        catch {
+            /* housekeeping only — never block a run over a leftover file */
+        }
+    }
+    /**
+     * Append to the action log — the choke point where redaction belongs.
+     *
+     * Redacting only a finding's title/detail/evidence left the same secrets
+     * flowing by a parallel route: `repro` is built from these entries, and a
+     * `type` step logs the text that was typed (a password, during an auth-flow
+     * pass) while every entry carries a full URL that may hold `?token=…`. Both
+     * land in memory.json and are rendered into the report. One filter here
+     * covers the log, the repro traces and the JSONL trail at once.
+     */
+    logAction(entry) {
+        const full = {
+            at: new Date().toISOString(),
+            ...entry,
+            url: redactSecrets(entry.url),
+            ...(entry.target === undefined ? {} : { target: redactSecrets(entry.target) }),
+            ...(entry.result === undefined ? {} : { result: redactSecrets(entry.result) }),
+        };
+        this.actionLog.push(full);
+        fs.appendFileSync(this.sessionLogPath, JSON.stringify(full) + "\n");
+    }
+    /** Record a visit to a state; returns whether it was new. */
+    visitState(fingerprint, url, route, elementKeys) {
+        let rec = this.data.states[fingerprint];
+        const isNew = !rec;
+        if (!rec) {
+            rec = { url, route, firstSeen: new Date().toISOString(), visits: 0, elements: {} };
+            this.data.states[fingerprint] = rec;
+        }
+        rec.visits += 1;
+        const present = new Set(elementKeys);
+        for (const key of elementKeys) {
+            if (!rec.elements[key])
+                rec.elements[key] = { exercised: false };
+            rec.elements[key].absentStreak = 0;
+        }
+        // Prune ghosts: dynamic elements (list rows, ordinal-suffixed duplicates)
+        // that vanish for 3 consecutive visits would otherwise make coverage
+        // permanently unreachable and steer exploration at phantoms.
+        for (const [key, entry] of Object.entries(rec.elements)) {
+            if (present.has(key))
+                continue;
+            entry.absentStreak = (entry.absentStreak ?? 0) + 1;
+            if (entry.absentStreak >= 3 && !entry.exercised)
+                delete rec.elements[key];
+        }
+        this.save();
+        return isNew;
+    }
+    markExercised(fingerprint, key, action) {
+        const rec = this.data.states[fingerprint];
+        if (!rec)
+            return;
+        // Refuse a key this state never listed. Creating one on demand turned any
+        // caller that derived a key slightly differently from the collector into a
+        // source of phantom coverage: the invented element counted as exercised
+        // (and was never pruned, because pruning skips exercised entries) while the
+        // real control stayed an open gap. A miss must record nothing.
+        if (!rec.elements[key])
+            return;
+        rec.elements[key].exercised = true;
+        rec.elements[key].lastAction = action;
+        this.save();
+    }
+    wasExercised(fingerprint, key) {
+        return this.data.states[fingerprint]?.elements[key]?.exercised ?? false;
+    }
+    /**
+     * Add a finding; dedups against previous runs in three tiers:
+     * 1. same route + same normalized `evidence` signature (strongest — survives title rephrasing),
+     * 2. exact title hash,
+     * 3. same route + high title-token overlap (an LLM re-describing the same bug
+     *    across sessions rarely reuses the exact words — Jaccard catches it).
+     * Returns [finding, isNew].
+     */
+    addFinding(input) {
+        // Redact BEFORE the id is derived, so a re-found finding whose quoted
+        // secret differs by a character still hashes to the same id.
+        const f = {
+            ...input,
+            title: redactSecrets(input.title),
+            detail: redactSecrets(input.detail),
+            // The page URL is persisted AND printed in the report. A finding filed on
+            // a reset/invite/magic-link page carries that page's `?token=…`.
+            url: redactSecrets(input.url),
+            evidence: input.evidence ? redactSecrets(input.evidence) : input.evidence,
+        };
+        const route = f.state.split("#")[0];
+        const id = shortHash(`${f.category}|${f.title.toLowerCase().trim()}|${route}`);
+        const existing = this.data.findings.find((x) => x.id === id || (x.state.split("#")[0] === route && sameFinding(x, f)) || sameEndpointBug(x, f));
+        if (existing) {
+            existing.runs += 1;
+            existing.foundAt = new Date().toISOString();
+            if (!existing.evidence && f.evidence)
+                existing.evidence = f.evidence;
+            // Re-finding a RESOLVED finding is a regression — reopen it loudly
+            // rather than letting it hide in the report's completed section. But a
+            // FUZZY match must never resurrect a fixed bug: telling someone a
+            // regression landed when it did not is far more costly than carrying a
+            // visible duplicate, and it corrupts the one signal that says whether a
+            // fix held. Demand an exact identity match (same category+title+route) or
+            // an identical evidence signature before reopening.
+            const exactMatch = existing.id === id ||
+                (!!existing.evidence &&
+                    !!f.evidence &&
+                    existing.evidence.toLowerCase().replace(/\s+/g, " ").trim() === f.evidence.toLowerCase().replace(/\s+/g, " ").trim());
+            if (existing.status === "resolved" && exactMatch) {
+                existing.status = "open";
+                existing.regressedAt = existing.foundAt;
+            }
+            this.flush();
+            return [existing, false];
+        }
+        // Repro trace scoped to the finding's route: everything since the action
+        // that landed there, not 12 lines of unrelated cross-module noise.
+        const routeOf = (url) => {
+            try {
+                return url.split("?")[0].replace(/^https?:\/\/[^/]+/, "") || "/";
+            }
+            catch {
+                return url;
+            }
+        };
+        const log = this.actionLog;
+        let start = Math.max(0, log.length - 12);
+        for (let i = log.length - 1; i >= 0 && i >= log.length - 12; i--) {
+            if (routeOf(log[i].url) !== routeOf(f.url)) {
+                start = i; // include the transition action itself
+                break;
+            }
+            start = i;
+        }
+        const finding = {
+            ...f,
+            id,
+            repro: log
+                .slice(start)
+                .slice(-12)
+                .map((a) => `${a.action}${a.target ? ` ${a.target}` : ""} @ ${a.url}`),
+            foundAt: new Date().toISOString(),
+            runs: 1,
+        };
+        this.data.findings.push(finding);
+        this.flush();
+        return [finding, true];
+    }
+    get findings() {
+        return this.data.findings;
+    }
+    get states() {
+        return this.data.states;
+    }
+    /**
+     * Coverage aggregated by ROUTE, not by state fingerprint: the same sidebar
+     * rendered in 30 states of one route is one set of elements, not 30. An
+     * element counts as exercised when it was exercised in ANY state of the
+     * route. (`state` in the result therefore holds a route.)
+     */
+    coverage() {
+        const byRoute = this.elementsByRoute();
+        // Shared layout CHROME (sidebar nav, header, breadcrumbs) is one set of
+        // components, not one set per route — clicking "nav-documents" on /admin is
+        // the same click as on /. Counting it per route inflated the denominator by
+        // thousands (a 99-route app reported 8329 elements, most of them the same
+        // ~40 shell controls) and turned the unexplored list into a wall of the
+        // identical eight nav links. Fold it into a single global surface,
+        // exercised if it was exercised ANYWHERE.
+        const isChrome = this.chromePredicate(byRoute);
+        const chrome = new Map();
+        let elementsTotal = 0;
+        let elementsExercised = 0;
+        const unexercised = [];
+        for (const [route, elements] of byRoute) {
+            const own = [];
+            // The route's OWN element count — deduped across states and with shared
+            // chrome removed, i.e. exactly the denominator `own` is a subset of.
+            // computeGaps compares these two to decide "nothing was ever touched
+            // here"; deriving the total any other way (e.g. re-counting raw state
+            // elements) makes it larger than `own` can ever be, and a genuinely
+            // untouched route silently drops out of the gap ledger.
+            let ownTotal = 0;
+            for (const [key, done] of elements) {
+                if (isChrome(key)) {
+                    chrome.set(key, (chrome.get(key) ?? false) || done);
+                    continue;
+                }
+                elementsTotal += 1;
+                ownTotal += 1;
+                if (done)
+                    elementsExercised += 1;
+                else
+                    own.push(key);
+            }
+            if (own.length > 0)
+                unexercised.push({ state: route, keys: own, total: ownTotal });
+        }
+        // Chrome counted once, at the end, as its own pseudo-route.
+        const chromeLeft = [];
+        for (const [key, done] of chrome) {
+            elementsTotal += 1;
+            if (done)
+                elementsExercised += 1;
+            else
+                chromeLeft.push(key);
+        }
+        if (chromeLeft.length > 0) {
+            unexercised.push({ state: SHARED_CHROME_ROUTE, keys: chromeLeft, total: chrome.size });
+        }
+        return { states: Object.keys(this.data.states).length, elementsTotal, elementsExercised, unexercised };
+    }
+    /**
+     * Remember which styled-element signatures the design audit saw on a route.
+     *
+     * Parallel to the coverage census and thresholded identically, but keyed the
+     * way the audit sees elements (tag/testid + text) rather than by ARIA role —
+     * the two cannot share a key space, and the audit needs its own to recognise
+     * un-testid'd shell elements across routes.
+     */
+    recordDesignElements(route, signatures) {
+        const map = this.data.designElements ?? {};
+        map[route] = [...new Set(signatures)];
+        this.data.designElements = map;
+        this.save();
+    }
+    /** Signatures seen on enough routes to be the shared shell rather than page content. */
+    designChromeKeys() {
+        const map = this.data.designElements ?? {};
+        const routes = Object.keys(map);
+        const perKey = new Map();
+        for (const sigs of Object.values(map)) {
+            for (const sig of sigs)
+                perKey.set(sig, (perKey.get(sig) ?? 0) + 1);
+        }
+        const minRoutes = Math.min(Math.max(CHROME_MIN_ROUTES, Math.ceil(routes.length * CHROME_ROUTE_SHARE)), CHROME_ABSOLUTE_ROUTES);
+        const keys = new Set();
+        if (routes.length < CHROME_MIN_ROUTES)
+            return keys;
+        for (const [sig, n] of perKey)
+            if (n >= minRoutes)
+                keys.add(sig);
+        return keys;
+    }
+    /** Element keys folded per route, exercised-in-any-state. */
+    elementsByRoute() {
+        const byRoute = new Map();
+        for (const rec of Object.values(this.data.states)) {
+            let route = byRoute.get(rec.route);
+            if (!route) {
+                route = new Map();
+                byRoute.set(rec.route, route);
+            }
+            for (const [key, v] of Object.entries(rec.elements)) {
+                route.set(key, (route.get(key) ?? false) || v.exercised);
+            }
+        }
+        return byRoute;
+    }
+    /** "Does this element key belong to the shared shell?" — see coverage(). */
+    chromePredicate(byRoute) {
+        const routeCount = byRoute.size;
+        const routesPerKey = new Map();
+        for (const elements of byRoute.values()) {
+            for (const key of elements.keys())
+                routesPerKey.set(key, (routesPerKey.get(key) ?? 0) + 1);
+        }
+        // Only meaningful once there are enough routes to tell "on every page" from
+        // "on the two pages that exist"; require a majority of them.
+        const chromeMinRoutes = Math.min(Math.max(CHROME_MIN_ROUTES, Math.ceil(routeCount * CHROME_ROUTE_SHARE)), CHROME_ABSOLUTE_ROUTES);
+        return (key) => routeCount >= CHROME_MIN_ROUTES && (routesPerKey.get(key) ?? 0) >= chromeMinRoutes;
+    }
+}