aztrx-cli 0.4.5 → 0.5.2

package/dist/core/replay.js

@@ -2,13 +2,39 @@ import { EventBus } from "./eventBus.js";
 import { launchChromium } from "./browser.js";
 import { attachInterceptor } from "./interceptor.js";
 import { fingerprintOf } from "./classifier.js";
+/**
+ * How long to let a freshly-navigated page settle before acting on it.
+ *
+ * The walker waits this long after its own `page.goto` before it touches
+ * anything, so every recorded selector was resolved against a page that had
+ * been given 300ms to render — a replay that clicks the instant the navigation
+ * commits is asking for something the recording never was.
+ *
+ * Measured on a real Next.js app rather than guessed: with no settle, every
+ * action after a `navigate` was skipped — `count()` does not wait, so an
+ * element that is not in the DOM *yet* is indistinguishable from one that is
+ * gone, and the skip is silent — and a bug that fires on every single click
+ * came back `unreliable` 0/3. With 300ms it reproduced 3/3.
+ */
+const NAV_SETTLE_MS = 300;
+/**
+ * How long to keep watching after the last replayed action, for a bug whose
+ * trigger is asynchronous. See the poll in `run` — it exits the moment the
+ * fingerprint appears, so this is a ceiling, not a delay.
+ */
+const POST_REPLAY_WINDOW_MS = 1500;
 /** Replays a recorded action sequence against a page. Best-effort: a selector
  * that no longer resolves is skipped, not fatal. */
 export async function replayActions(page, actions) {
     for (const a of actions) {
         if (a.type === "navigate") {
             if (a.value) {
-                await page.goto(a.value, { waitUntil: "domcontentloaded", timeout: 10000 }).catch(() => { });
+                // Already there: a trace can carry the same URL twice, and re-loading
+                // the page it is already on costs a full load and resets its state.
+                if (page.url() !== a.value) {
+                    await page.goto(a.value, { waitUntil: "domcontentloaded", timeout: 10000 }).catch(() => { });
+                    await page.waitForTimeout(NAV_SETTLE_MS);
+                }
             }
             continue;
         }
@@ -111,7 +137,14 @@ export class ReplayEngine {
                 attachInterceptor(page, bus);
                 if (this.opts.attachGuard)
                     await this.opts.attachGuard(page);
-                await page.goto(url, { waitUntil: "load", timeout: 30000 }).catch(() => { });
+                // A rejected navigation (refused connection, DNS failure, timeout) and a
+                // non-2xx answer both leave a page that will never emit the telemetry we
+                // are looking for. Capture that here rather than letting the empty
+                // fingerprint set read as a passing verification.
+                const nav = await page
+                    .goto(url, { waitUntil: "load", timeout: 30000 })
+                    .catch(() => null);
+                const loaded = nav !== null && nav.ok();
                 // Settle for hydration before replaying — the detection pass waits on the
                 // `load` event plus a settle window, and a replay that clicks before React
                 // attaches its handlers won't reproduce the crash (false "unreliable").
@@ -119,11 +152,23 @@ export class ReplayEngine {
                 if (opts?.targetType)
                     collecting = true;
                 await replayActions(page, actions);
-                await page.waitForTimeout(300);
-                const reproduced = opts?.targetType
-                    ? types.has(opts.targetType)
-                    : fingerprints.has(targetFingerprint);
-                return { reproduced };
+                // An action can start work that throws later — a `fetch` behind a 300ms
+                // mock, a promise chain, a state update that re-renders into the bug —
+                // and the last action is not the last word. Waiting a fixed 300ms for
+                // that measured *exactly* on the boundary of a real app's own 300ms
+                // delay, so the same trace flipped between reproducing and not from one
+                // run to the next.
+                //
+                // Poll instead of sleeping: a bug that fires during the replay returns
+                // on the first check, so the window costs nothing where the verdict is
+                // already decided, and only a trace that is going to be called
+                // `unreliable` pays for the full wait — which is the case that must not
+                // be wrong.
+                const seen = () => opts?.targetType ? types.has(opts.targetType) : fingerprints.has(targetFingerprint);
+                const deadline = Date.now() + POST_REPLAY_WINDOW_MS;
+                while (!seen() && Date.now() < deadline)
+                    await page.waitForTimeout(50);
+                return { reproduced: seen(), loaded };
             }
             catch (e) {
                 lastError = e;

package/dist/core/report.d.ts

@@ -0,0 +1,8 @@
+import type { Finding } from "./types.js";
+/**
+ * F-report — standalone offline HTML report. Self-contained (inline CSS, no
+ * CDN), rendered in the shared "crash seismograph" identity: one red spike per
+ * crash, severity chips, and colored repro verdicts.
+ */
+export declare function renderReport(targetUrl: string, findings: Finding[], lang?: string): string;
+export declare function writeReport(repoRoot: string, targetUrl: string, findings: Finding[], lang?: string): string;

package/dist/core/resolver.d.ts

@@ -0,0 +1,64 @@
+import type { ServerFrame } from "./types.js";
+export type ResolvedFrom = "sourcemap" | "direct" | "unresolved";
+export interface MappedError {
+    message: string;
+    /** Repo-relative path to the source file, e.g. `apps/web/src/App.tsx`. */
+    sourceFile: string;
+    line: number;
+    column: number;
+    codeSnippet: string;
+    resolvedFrom: ResolvedFrom;
+}
+export interface RawFrame {
+    url: string;
+    line: number;
+    column: number;
+    message: string;
+}
+/**
+ * Pulls the first *user-code* frame out of a stack string. Iterates every line,
+ * skips framework internals (webpack runtime, node_modules, next/dist), and
+ * returns the first frame in the user's own code — so a Next.js dev stack like
+ * `webpack-internal:///(app-pages-browser)/./app/page.tsx:29:21` resolves to the
+ * user's file, not `intercept-console-error.js`.
+ */
+export declare function extractFrame(text: string): RawFrame | null;
+/**
+ * Pull the first server-side source frame out of a raw server stack (a 500 body,
+ * a Next.js dev error page, etc.). V8 emits one frame per line as
+ * `at <fn> (<path>:<line>:<col>)` or `at <path>:<line>:<col>`; we take the first
+ * frame whose path is not inside node_modules. Best-effort — returns null when
+ * the body carries no stack trace (e.g. an explicit
+ * `NextResponse.json(..., { status: 500 })`).
+ */
+export declare function extractServerFrame(stack: string): ServerFrame | null;
+export declare function resolveFrame(frame: RawFrame, repoRoot: string): Promise<MappedError>;
+/**
+ * Resolve a server-side source frame (a filesystem path) to a repo-relative
+ * source location + snippet. Mirrors `resolveFrame`'s containment rules: a path
+ * outside the repo — via `..` traversal or a symlink pointing out — is never
+ * read. Server frames carry no sourcemap; a directly-readable file maps
+ * `resolvedFrom: "direct"`.
+ */
+export declare function resolveServerFrame(frame: ServerFrame, repoRoot: string): MappedError;
+export declare function extractSnippet(filePath: string, targetLine: number, window?: number): string;
+/**
+ * Re-anchor a position that a transpiled frame reported wrongly.
+ *
+ * `webpack-internal://` frames carry a position in the module webpack
+ * *generated*, not in the `.tsx` on disk. Next dev reported
+ * `app/page.tsx:29:21` for a crash that is on line 15 — and because the URL
+ * path is the real source path, the file is found and a confidently wrong line
+ * is shown. Worse, `generateRulePatch` looks for the property on the mapped
+ * line, finds a `</div>` instead, and declines — so the free no-key fix never
+ * fires on Next.js.
+ *
+ * The error message is the signal. `Cannot read properties of undefined
+ * (reading 'agents')` can only be thrown by a line that reads `.agents`, so a
+ * mapped line that does not read it is provably not the throw site, and the
+ * real one is findable. Ambiguity is left alone rather than guessed at.
+ */
+export declare function reanchorPosition(content: string, line: number, column: number, message: string): {
+    line: number;
+    column: number;
+};

package/dist/core/resolver.js

@@ -1,5 +1,6 @@
 import * as fs from "fs";
 import * as path from "path";
+import { fileURLToPath } from "url";
 import { FlattenMap, originalPositionFor, } from "@jridgewell/trace-mapping";
 /** Framework-internal frames to skip when hunting the throw site. */
 const FRAMEWORK_FRAME = /node_modules|webpack-runtime|\.next[\\/]|next[\\/]dist[\\/]/;
@@ -56,20 +57,40 @@ export function extractServerFrame(stack) {
 function stripQuery(url) {
     return url.split("?")[0];
 }
-/** Normalize a stack-frame URL to a repo-relative source path. Handles the
- * dev-server schemes (`webpack-internal:///(ns)/./src/…`, `webpack://ns/src/…`),
- * `file://`, and plain `https://host/path` bundle URLs. */
+/** Normalize a stack-frame URL to a path to probe: repo-relative for the
+ * dev-server schemes (`webpack-internal:///(ns)/./src/…`, `webpack://ns/src/…`)
+ * and plain `https://host/path` bundle URLs, **absolute** for `file://`.
+ *
+ * The asymmetry is deliberate. `file://` carries a real filesystem path, and on
+ * POSIX the leading slash is the root; the `^\//` strip below exists for URL
+ * paths (`/@fs/src/main.tsx`) and would eat it, turning `/tmp/p/app/actions.ts`
+ * into the relative `tmp/p/app/actions.ts` — a path under the repo that never
+ * exists. Every `file://` frame therefore fell through to "unresolved" on Linux
+ * and macOS. `resolveWithin` accepts absolute segments, so callers are unchanged;
+ * only display has to convert back (see `reportPath`). */
 function normalizeFrameUrl(url) {
-    return stripQuery(url)
+    const raw = stripQuery(url);
+    if (/^file:\/\//i.test(raw)) {
+        try {
+            return fileURLToPath(raw); // handles drive-letter and UNC forms on Windows too
+        }
+        catch {
+            return raw; // malformed URL — let the containment check reject it
+        }
+    }
+    return raw
         .replace(/^webpack-internal:\/\/\/[^/]+\/\.\//, "")
         .replace(/^webpack:\/\/[^/]+\//, "")
         .replace(/^webpack:\/\//, "")
         .replace(/^\/@fs\//, "")
-        .replace(/^file:\/\/\/([A-Za-z]:)/, "$1") // file:///C:/x → C:/x
-        .replace(/^file:\/\//, "")
         .replace(/^https?:\/\/[^/]+\//, "")
         .replace(/^\//, "");
 }
+/** The repo-relative form of a normalized frame path, for anything user-facing.
+ * An absolute `file://` path is reported the same way every other frame is. */
+function reportPath(p, repoRoot) {
+    return path.isAbsolute(p) ? path.relative(repoRoot, p) : p;
+}
 /** True only for a real, readable regular file — directories and unreadable
  * paths return false so readers never hit `EISDIR` / permission errors. */
 function isFile(p) {
@@ -140,14 +161,30 @@ function resolveWithin(root, ...segments) {
 }
 /** Turns a sourcemap `source` value into candidate absolute paths to probe. */
 function sourceCandidates(source, repoRoot) {
-    const cleaned = source
+    const raw = source.split("?")[0];
+    // `file://` is an absolute *filesystem* path, not a URL path, and the two
+    // differ in exactly one place: on POSIX the leading slash is the root. The
+    // web-style stripping below exists for URL paths (`/@fs/src/main.tsx`) and
+    // would eat that slash, turning `/tmp/p/app/actions.ts` into the relative
+    // `tmp/p/app/actions.ts` — a path under the repo that never exists, so every
+    // Turbopack `file:///` source silently resolved to nothing on Linux and macOS.
+    // `fileURLToPath` also handles the drive-letter and UNC forms on Windows.
+    if (/^file:\/\//i.test(raw)) {
+        let abs;
+        try {
+            abs = fileURLToPath(raw);
+        }
+        catch {
+            return []; // malformed URL — nothing to probe
+        }
+        const inside = resolveWithin(repoRoot, abs);
+        return inside === null ? [] : [inside];
+    }
+    const cleaned = raw
         .replace(/^webpack:\/\/[^/]+\//, "") // webpack://namespace/src/...
         .replace(/^webpack:\/\//, "")
         .replace(/^\/@fs\//, "")
-        .replace(/^file:\/\/\/([A-Za-z]:)/, "$1") // file:///C:/x → C:/x
-        .replace(/^file:\/\//, "")
-        .replace(/^\//, "")
-        .split("?")[0];
+        .replace(/^\//, "");
     const prefixes = ["", "apps/web/", "src/", "app/"];
     return prefixes
         .map((p) => resolveWithin(repoRoot, p, cleaned))
@@ -181,22 +218,32 @@ export async function resolveFrame(frame, repoRoot) {
             directPath = withIndex;
     }
     if (!directPath) {
+        const shown = reportPath(relative, repoRoot);
         return {
             message: frame.message,
-            sourceFile: relative,
+            sourceFile: shown,
             line: frame.line,
             column: frame.column,
-            codeSnippet: `<file not accessible locally: ${relative}>`,
+            codeSnippet: `<file not accessible locally: ${shown}>`,
             resolvedFrom: "unresolved",
         };
     }
+    // The frame's line is only as good as the code it came from: for a
+    // `webpack-internal://` frame it indexes webpack's *generated* module, not the
+    // source on disk (see reanchorPosition), so re-anchor before showing it — and
+    // before `generateRulePatch` reads it, which is the difference between a free
+    // fix and a paid one.
+    const readable = isFile(directPath) && !isSensitive(directPath);
+    const at = readable
+        ? reanchorPosition(fs.readFileSync(directPath, "utf-8"), frame.line, frame.column, frame.message)
+        : { line: frame.line, column: frame.column };
     return {
         message: frame.message,
         sourceFile: path.relative(repoRoot, directPath),
-        line: frame.line,
-        column: frame.column,
-        codeSnippet: extractSnippet(directPath, frame.line),
-        resolvedFrom: isFile(directPath) && !isSensitive(directPath) ? "direct" : "unresolved",
+        line: at.line,
+        column: at.column,
+        codeSnippet: extractSnippet(directPath, at.line),
+        resolvedFrom: readable ? "direct" : "unresolved",
     };
 }
 /**
@@ -356,3 +403,74 @@ export function extractSnippet(filePath, targetLine, window = 4) {
     })
         .join("\n");
 }
+/** The property a null-deref message was reading:
+ * `Cannot read properties of undefined (reading 'agents')` → `agents`.
+ * Null for every other error, which is what keeps the correction below scoped
+ * to the one message shape that proves where the throw happened. */
+function readProperty(message) {
+    const m = message.match(/reading ['"]([^'"]+)['"]/);
+    return m ? m[1] : null;
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Drop a trailing `//` comment. The `:` guard keeps `https://` intact. */
+function stripComment(line) {
+    const i = line.indexOf("//");
+    if (i <= 0 || line[i - 1] === ":")
+        return line;
+    return line.slice(0, i);
+}
+/** Does this line read `.prop`? */
+function readsProperty(line, prop) {
+    return new RegExp(`\\.${escapeRe(prop)}\\b`).test(line);
+}
+/** True when every read of `.prop` on this line is optional-chained. A guarded
+ * read cannot throw, so such a line is never the crash site — which is what
+ * separates `d?.agents ?? []` from the `d.agents.map(…)` that actually threw. */
+function allReadsGuarded(line, prop) {
+    const re = new RegExp(`(\\?)?\\.${escapeRe(prop)}\\b`, "g");
+    let seen = false;
+    for (let m = re.exec(line); m; m = re.exec(line)) {
+        seen = true;
+        if (!m[1])
+            return false;
+    }
+    return seen;
+}
+/**
+ * Re-anchor a position that a transpiled frame reported wrongly.
+ *
+ * `webpack-internal://` frames carry a position in the module webpack
+ * *generated*, not in the `.tsx` on disk. Next dev reported
+ * `app/page.tsx:29:21` for a crash that is on line 15 — and because the URL
+ * path is the real source path, the file is found and a confidently wrong line
+ * is shown. Worse, `generateRulePatch` looks for the property on the mapped
+ * line, finds a `</div>` instead, and declines — so the free no-key fix never
+ * fires on Next.js.
+ *
+ * The error message is the signal. `Cannot read properties of undefined
+ * (reading 'agents')` can only be thrown by a line that reads `.agents`, so a
+ * mapped line that does not read it is provably not the throw site, and the
+ * real one is findable. Ambiguity is left alone rather than guessed at.
+ */
+export function reanchorPosition(content, line, column, message) {
+    const prop = readProperty(message);
+    if (!prop)
+        return { line, column };
+    const lines = content.split("\n");
+    const mapped = lines[line - 1];
+    if (mapped && readsProperty(stripComment(mapped), prop))
+        return { line, column };
+    const candidates = [];
+    for (let i = 0; i < lines.length; i++) {
+        const text = stripComment(lines[i]);
+        if (!readsProperty(text, prop) || allReadsGuarded(text, prop))
+            continue;
+        candidates.push(i + 1);
+    }
+    if (candidates.length !== 1)
+        return { line, column }; // ambiguous — don't guess
+    const found = lines[candidates[0] - 1];
+    // Point the column at the property too: the frame's column is as transpiled
+    // as its line was.
+    return { line: candidates[0], column: found.indexOf(`.${prop}`) + 1 };
+}

package/dist/core/rng.d.ts

@@ -0,0 +1,2 @@
+/** Deterministic seeded PRNG (mulberry32) so fuzz runs are reproducible. */
+export declare function mulberry32(seed: number): () => number;

package/dist/core/specCompiler.d.ts

@@ -0,0 +1,17 @@
+import type { Finding, RecordedAction } from "./types.js";
+/**
+ * F8 — spec compiler. Turns a minimal action sequence into an executable
+ * Playwright test that asserts the failure actually happens, so a human can
+ * run `npx playwright test` and see the bug with their own eyes — proof, not
+ * a log line.
+ */
+export declare function compileSpec(finding: Finding, actions: RecordedAction[], url: string): string;
+export declare function writeSpec(repoRoot: string, finding: Finding, actions: RecordedAction[], url: string): string;
+/**
+ * Install validated repro specs into the project's test directory so a fixed
+ * bug can't silently regress — the "immunity" step after find → prove → fix.
+ * Copies each deterministic/flaky repro into `<dir>/aztrx-<fingerprint>.spec.ts`
+ * and returns the written paths. `dir` defaults to an existing test dir, else a
+ * gitignored fallback.
+ */
+export declare function writeRegressionSpecs(repoRoot: string, findings: Finding[], dir?: string): string[];

package/dist/core/studio.d.ts

@@ -0,0 +1,6 @@
+import * as http from "http";
+export interface StudioOptions {
+    repoRoot: string;
+    port?: number;
+}
+export declare function startStudio(opts: StudioOptions): http.Server;

package/dist/core/studio.js

@@ -3,9 +3,6 @@ import * as http from "http";
 import * as path from "path";
 import pc from "picocolors";
 import { BASE_CSS, SEVERITY_COLOR, seismograph } from "./ui.js";
-function escapeHtml(s) {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
 function send(res, status, contentType, body) {
     res.writeHead(status, { "Content-Type": contentType });
     res.end(body);

package/dist/core/summarize.d.ts

@@ -0,0 +1,26 @@
+/**
+ * F13 — the "X-ray report": a plain-language summary of a run's findings,
+ * instead of a wall of stack traces. Two engines behind one entry point:
+ *
+ *   - LLM (Anthropic Messages API) when `ANTHROPIC_API_KEY` is set — friendly
+ *     prose in the requested language, mirroring the transport in `heal/llm.ts`.
+ *   - deterministic template when there is no key (or the call fails) — a
+ *     readable, structured list that needs no network.
+ *
+ * An empty run short-circuits to the template (no reason to pay for "all clear").
+ * The offer-to-apply line is emitted only when verified fixes are actually ready,
+ * so `--explain` (no healing) never promises a fix it doesn't have.
+ */
+import type { Finding } from "./types.js";
+export type Lang = "en" | "ru";
+/** Deterministic, offline summary. Used as the no-key fallback and for empty runs. */
+export declare function summarizeFindingsTemplate(findings: Finding[], lang?: Lang): string;
+export interface SummarizeOptions {
+    lang?: string;
+}
+/**
+ * Entry point. Empty run → template (no API cost). Otherwise LLM when a key is
+ * present; falls back to the deterministic template on any transport failure, so
+ * the report never crashes the run.
+ */
+export declare function summarizeFindings(findings: Finding[], opts?: SummarizeOptions): Promise<string>;

package/dist/core/summarize.js

@@ -125,12 +125,23 @@ function buildLlmPrompt(findings, lang, hasHealed) {
 const SYSTEM = "You are the plain-spoken explainer for a QA tool called Aztrx AI. You turn raw runtime-finding data into a concise Markdown summary for a developer (headings, bold, bullet lists, short code snippets). Never invent details absent from the data. Respond in the requested language only.";
 async function summarizeFindingsLlm(findings, lang) {
     const hasHealed = findings.some((f) => f.heal?.status === "healed");
-    const text = (await complete({
-        system: SYSTEM,
-        prompt: buildLlmPrompt(findings, lang, hasHealed),
-        maxTokens: 1024,
-        temperature: 0.2,
-    })).trim();
+    // The template is the floor, not a fallback for one case: an explanation is a
+    // nice-to-have, so a provider that errors, truncates or filters must not take
+    // the report down with it. `complete()` throws on an empty completion rather
+    // than returning "", so this catch is what keeps that contract from becoming a
+    // crash — the `||` then covers a reply that was whitespace.
+    let text = "";
+    try {
+        text = (await complete({
+            system: SYSTEM,
+            prompt: buildLlmPrompt(findings, lang, hasHealed),
+            maxTokens: 1024,
+            temperature: 0.2,
+        })).trim();
+    }
+    catch {
+        text = "";
+    }
     return text || summarizeFindingsTemplate(findings, lang);
 }
 /**

package/dist/core/swarm.d.ts

@@ -0,0 +1,97 @@
+/**
+ * F-swarm — parallel detection. Runs N workers at once, each with its own
+ * browser context, event bus, action recorder, and classifier, so the action
+ * history attached to a finding belongs to the worker that saw it (never
+ * interleaved). Workers attack different sides: a deterministic walk, several
+ * chaos-fuzz seeds, and — optionally — the server-side HTTP fuzzer.
+ *
+ * Findings are merged by fingerprint at the end (occurrences summed, the richest
+ * action history / source mapping kept); the caller then runs repro/heal on the
+ * merged set as usual.
+ */
+import type { Browser } from "playwright";
+import { EventBus } from "./eventBus.js";
+import type { Finding } from "./types.js";
+export type WorkerStrategy = {
+    kind: "walk";
+} | {
+    kind: "fuzz";
+    seed: number;
+};
+export interface DetectResult {
+    findings: Finding[];
+    actions: number;
+    /** New JS code ranges covered by this worker's fuzz pass (0 for walk). */
+    newCoverage: number;
+    /** Whether the walk encountered a login form (a password input). */
+    sawLoginForm: boolean;
+    /** Auth-state path saved by worker 0 (used to authenticate replays). */
+    replayStorageState?: string;
+}
+export interface DetectWorkerOptions {
+    url: string;
+    repoRoot: string;
+    allowHosts: Set<string>;
+    maxActions: number;
+    dryRun?: boolean;
+    guardOn: boolean;
+    storageState?: string;
+    login?: boolean;
+    loginEmail?: string;
+    loginPassword?: string;
+    loginUrl?: string;
+    crashTest?: boolean;
+    saveAuthState?: boolean;
+    httpFuzzMutations?: boolean;
+    /** Fold the HTTP fuzzer in as a post-pass on this worker's page. */
+    httpFuzz?: boolean;
+    /** Opt-in: include destructive controls/endpoints (delete/pay/logout/…). */
+    allowDestructive?: boolean;
+    baseline: string[];
+    log: (msg: string) => void;
+}
+/**
+ * Run one worker's detection pass and return its findings. All internal events
+ * flow through a local bus (isolation); only `action`/`route`/`noise` are
+ * forwarded to `forwardBus` so a live panel can aggregate, never per-worker
+ * findings (those are merged by the caller first).
+ */
+export declare function detectWorker(browser: Browser, opts: DetectWorkerOptions, strategy: WorkerStrategy, forwardBus?: EventBus): Promise<DetectResult>;
+/** Dedup findings across workers by fingerprint: sum occurrences, keep the richest. */
+export declare function mergeFindings(arrays: Finding[][]): Finding[];
+export interface SwarmOptions {
+    url: string;
+    repoRoot: string;
+    maxActions: number;
+    dryRun?: boolean;
+    fuzz?: boolean;
+    httpFuzz?: boolean;
+    httpFuzzMutations?: boolean;
+    seed: number;
+    workers: number;
+    allowHosts: Set<string>;
+    storageState?: string;
+    login?: boolean;
+    loginEmail?: string;
+    loginPassword?: string;
+    loginUrl?: string;
+    crashTest?: boolean;
+    /** Opt-in: include destructive controls/endpoints (delete/pay/logout/…). */
+    allowDestructive?: boolean;
+    baseline: string[];
+    guardOn: boolean;
+    log: (msg: string) => void;
+    /** Forwarded to the orchestrator's bus so a live panel can aggregate action/route counts. */
+    forwardBus?: EventBus;
+}
+export interface SwarmResult {
+    findings: Finding[];
+    replayStorageState?: string;
+    totalActions: number;
+    totalCoverage: number;
+    workerCount: number;
+    roles: string[];
+    sawLoginForm: boolean;
+}
+/** Launch one browser, run the worker roster concurrently, merge findings. */
+export declare function swarmDetect(opts: SwarmOptions): Promise<SwarmResult>;

package/dist/core/swarm.js

@@ -95,9 +95,32 @@ export async function detectWorker(browser, opts, strategy, forwardBus) {
             onBlock: (u) => opts.log(`[guard] blocked ${u}`),
         });
     }
+    // The last URL this listener recorded as a `navigate`, to drop the duplicate.
+    // Playwright fires `framenavigated` twice for a single `page.goto` — measured
+    // against Chromium, not assumed: one goto to `/agents` produced two events
+    // for the same URL. Recording both would put a redundant full page load in
+    // every trace, and the buffer is only 25 actions deep.
+    let lastNavUrl = "";
     page.on("framenavigated", (frame) => {
-        if (frame === page.mainFrame())
-            workerBus.emit("route", { url: frame.url(), ts: Date.now() });
+        if (frame !== page.mainFrame())
+            return; // an iframe's URL is not the page's
+        const url = frame.url();
+        workerBus.emit("route", { url, ts: Date.now() });
+        // A trace has to say which page it was on, and nothing recorded that. The
+        // walker reaches each crawled route with `page.goto`, which emits no action
+        // at all, so a finding on `/agents` produced a trace of clicks that only
+        // mean anything *there* — replayed from the start URL every one of them
+        // resolved to nothing, the crash was never reached, and a bug that fires
+        // every single time came back `unreliable` (0/3 replays). `navigate` is
+        // already understood by everything that consumes a trace: `replayActions`
+        // and the spec compiler act on it, heal rewrites its origin to the booted
+        // server, and the patrol GIF skips it. Only the producer was missing.
+        if (!/^https?:/i.test(url))
+            return; // about:blank, and the first empty frame
+        if (url === lastNavUrl)
+            return; // the second of the pair described above
+        lastNavUrl = url;
+        workerBus.emit("action", { type: "navigate", selectors: [], value: url, timestamp: Date.now() });
     });
     let loaded = true;
     await page.goto(opts.url, { waitUntil: "load", timeout: 30000 }).catch((e) => {

package/dist/core/telemetry/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * F11 — opt-in telemetry / data flywheel. Collects the anonymized
+ * `[crash_fingerprint, min_repro_spec, verified_patch, framework_metadata,
+ * model_tier_used]` tuple for each crash/error finding, appends it to a local
+ * JSONL dataset, and — only under `--share-data` — dispatches an envelope to the
+ * telemetry endpoint.
+ *
+ * Privacy: everything is opt-in. `--telemetry` collects and persists locally
+ * only; `--share-data` additionally uploads. The dispatch is fire-and-forget,
+ * bounded by a 2s abort, and can never change the CLI exit code.
+ */
+import type { Finding } from "../types.js";
+import type { TelemetryEnvelope } from "./types.js";
+export interface SubmitOptions {
+    repoRoot: string;
+    url: string;
+    telemetry: boolean;
+    shareData: boolean;
+    endpoint?: string;
+    /** API key presented as `x-api-key` (falls back to `AZTRX_CLOUD_API_KEY`).
+     *  Deliberately not `AZTRX_API_KEY` — that one is a model provider credential
+     *  (`llm.ts:29,35`) and must never travel as an upload auth header. */
+    apiKey?: string;
+}
+/** Fire-and-forget upload. Never rejects; bounded by a short abort. Failures are
+ * reported on stderr rather than discarded — silence here reads as success. */
+export declare function dispatchTelemetry(envelope: TelemetryEnvelope, endpoint: string, apiKey?: string): Promise<void>;
+/** Collect + sanitize + persist, and (under `--share-data`) dispatch. Sync on
+ * the local path; the upload is detached so the run never waits on the network. */
+export declare function submitTelemetry(findings: Finding[], opts: SubmitOptions): void;
+/** Await all in-flight uploads (each already bounded). Called right before the
+ * CLI exits so a pending upload isn't killed mid-flight; never affects exit code. */
+export declare function flushTelemetry(): Promise<void>;