aztrx-cli 0.2.4 → 0.4.0

package/README.md

@@ -1,14 +1,30 @@
 # <img src="media/logo.svg" width="28" height="32" alt="Aztrx logo" align="absmiddle" /> Aztrx AI
 
-> **Autonomous runtime stress-tester, deterministic bug minimizer, human-language explainer, and self-healing engine for web applications.**
+> **Catch the runtime crash your Error Boundary hid — and prove it with a test, not a log line.**
 
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg?style=flat-square)](https://nodejs.org)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
 
-Aztrx AI drives your web app like a hostile user — clicking, entering boundary data, and racing asynchronous UI states. When a runtime crash occurs (even one swallowed by a React Error Boundary), Aztrx AI intercepts it via the Chrome DevTools Protocol, maps it back to the exact source line, shrinks the interaction trace to the bare minimum with **ddmin**, and emits an executable, standalone **Playwright test** that proves the bug — not a log line.
+Aztrx AI finds **runtime** bugs — not security holes. It drives your web app like a
+hostile user (clicking, entering boundary data, racing async state) and catches the
+crashes that ship to real users, *including ones a React Error Boundary swallows* —
+the errors `window.onerror` never sees. Every crash comes back as an exact source line
+plus an executable **Playwright repro** that fails `3/3` times. Then it fixes it.
+
+This is the reliability layer — the bug that crashed a real user, not the vuln a hacker
+could exploit.
 
 ![aztrx demo](media/demo.gif)
 
+```bash
+npx aztrx-cli run http://localhost:3000          # find the crashes — zero setup
+npx aztrx-cli run http://localhost:3000 --fix    # …and fix them (needs a key)
+```
+
+| Find | Prove | Fix |
+| --- | --- | --- |
+| deterministic walk · coverage-guided fuzz · HTTP fuzz · swarm | ddmin → executable `.spec.ts` → `[deterministic 3/3]` | gated LLM patch → compile → test → replay → apply / `--pr` |
+
 ---
 
 ## Run it
@@ -47,7 +63,7 @@ aztrx-cli run http://localhost:3000
 ## Fix it, not just find it
 
 The only feature that needs a key. `--fix` hands the crash to an LLM and applies a
-verified patch to your working tree. Set `ANTHROPIC_API_KEY` and run:
+verified patch to your working tree. Anthropic by default — set `ANTHROPIC_API_KEY`:
 
 ```bash
 export ANTHROPIC_API_KEY="your-api-key"
@@ -55,6 +71,16 @@ npx aztrx-cli run http://localhost:3000 --fix          # find → explain → he
 npx aztrx-cli run http://localhost:3000 --fix --yes    # non-interactive (CI)
 ```
 
+Or use **any model** — Grok, DeepSeek, Gemini, GPT, Kimi, Mistral, OpenRouter, or a
+local Ollama/vLLM. Point it at any OpenAI-compatible `/v1` endpoint:
+
+```bash
+export AZTRX_API_BASE="https://openrouter.ai/api/v1"   # or api.openai.com/v1, api.x.ai/v1, ...
+export AZTRX_API_KEY="your-key"
+export AZTRX_MODEL="anthropic/claude-sonnet-5"         # any model the provider serves
+npx aztrx-cli run http://localhost:3000 --fix
+```
+
 `--fix` chains find → explain → heal, then asks *"Apply the fix?"* (`y/N`). On yes, the
 verified patch lands in your working tree — `git diff` shows the result. Aztrx AI never
 commits.
@@ -72,10 +98,12 @@ on your own test suite before you ever see it.
 Everything else is optional. One line each — the full table is in the [CLI reference](#cli-reference).
 
 ### Fuzz harder
-`--fuzz` breaks the *client*; `--http-fuzz` attacks the *server* — it harvests your app's
-real endpoints and throws hostile requests at them (query overflow, JSON type-confusion,
-header injection), turning every `5xx` into an executable repro. When a 500 body leaks a
-server stack, `--heal` can even fix it by booting the patched app and replaying the repro.
+`--fuzz` breaks the *client* — a seeded chaos walk that also reads **V8 JS coverage** and
+steers toward code it hasn't reached yet, so it explores rather than re-clicks. `--http-fuzz`
+attacks the *server* — it harvests your app's real endpoints and throws hostile requests at
+them (query overflow, JSON type-confusion, header injection), turning every `5xx` into an
+executable repro. When a 500 body leaks a server stack, `--heal` can even fix it by booting
+the patched app and replaying the repro.
 
 ### Parallel swarm
 `--workers 4` fans detection into parallel workers (walk + several fuzz seeds + http-fuzz),
@@ -129,6 +157,7 @@ and niche tuning knobs).
 | `--magic-fix` | Deprecated alias for `--fix` (hidden) | — |
 | `--explain` | Print a human-language summary of the findings | — |
 | `--yes` / `-y` | Auto-apply verified fixes without prompting (with `--fix`) | — |
+| `--pr` | Open a merge-ready PR with the verified fixes (with `--fix`) | — |
 | `--lang <code>` | Language for the human-language summary (`en`, `ru`) | `en` |
 | `--upload` | Stream run findings to the cloud ingest backend | — |
 | `--api-key <key>` | Auth key for `--upload` / `--share-data` | `$AZTRX_API_KEY` |
@@ -138,14 +167,15 @@ and niche tuning knobs).
 | `--workers <n>` | Number of parallel detection workers | `1` |
 | `--swarm` | Hidden alias for `--workers auto` | — |
 | `--repro-runs <n>` | Flake-rate replay iterations | `3` |
-| `--heal-model <model>` | Fallback LLM tier | `claude-sonnet-5` |
-| `--heal-fast-model <model>` | Fast/cheap first tier | `claude-haiku-4-5` |
+| `--heal-model <model>` | Fallback LLM tier | `claude-sonnet-5` / `$AZTRX_MODEL` |
+| `--heal-fast-model <model>` | Fast/cheap first tier | `claude-haiku-4-5` / `$AZTRX_FAST_MODEL` |
 | `--test-command <cmd>` | Test command run against a healed patch | `npm test` (auto-detected) |
 | `--test-timeout <ms>` | Timeout for the heal test gate | `300000` |
 | `--no-test` | Skip the test gate during healing | — |
 | `--start-command <cmd>` | Command to boot the app for server healing | `scripts.dev` → `scripts.start` (auto-detected) |
 | `--pr-comment [path]` | Write a GitHub PR markdown comment | `.aztrx/pr-comment.md` |
 | `--badge [path]` | Write a self-contained SVG status badge | `.aztrx/badge.svg` |
+| `--regression-test [dir]` | Copy validated repro specs into the project test dir | `e2e/` or `tests/` |
 | `--telemetry` | Collect anonymized tuples locally (opt-in) | — |
 | `--share-data` | Also upload the sanitized tuples (opt-in) | — |
 | `--repo <path>` | Root path for sourcemap → source resolution | cwd |
@@ -196,7 +226,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: DanisChaparov/aztrx@40570783592a768b5e012a984eee1ff334850a5d
+      - uses: Aztrx-AI/aztrx@dc90680bca73343863da6e98c46e64be0223c6ee
         with:
           url: http://localhost:3000
           start-command: npm run dev          # optional — boot the app in the background
@@ -210,7 +240,7 @@ Or as a reusable workflow:
 on: pull_request
 jobs:
   aztrx:
-    uses: DanisChaparov/aztrx/.github/workflows/aztrx-pr.yml@40570783592a768b5e012a984eee1ff334850a5d
+    uses: Aztrx-AI/aztrx/.github/workflows/aztrx-pr.yml@dc90680bca73343863da6e98c46e64be0223c6ee
     with:
       url: http://localhost:3000
       start-command: npm run dev
@@ -230,7 +260,7 @@ npx aztrx-cli run http://localhost:3000 --badge badge.svg
 ```
 
 ```markdown
-[![aztrx](badge.svg)](https://github.com/DanisChaparov/aztrx)
+[![aztrx](badge.svg)](https://github.com/Aztrx-AI/aztrx)
 ```
 
 The badge is a self-contained SVG generated from the run's findings — green
@@ -261,7 +291,7 @@ jobs:
             sleep 2
           done
       - name: Generate badge
-        run: npx --yes aztrx-cli@0.2.4 run http://localhost:3000 --badge badge.svg
+        run: npx --yes aztrx-cli@0.4.0 run http://localhost:3000 --badge badge.svg
       - name: Commit badge
         run: |
           git config user.name "github-actions[bot]"
@@ -279,12 +309,13 @@ are, and the run still exits 0 so the commit step always runs. Swap `push` for a
 
 ## Smart Cloud Router
 
-`--heal` is backed by a two-tier router. The fast/cheap model
-(`claude-haiku-4-5`) generates first; its patch is gated, compiled, and replayed
-against the repro. If the bug still reproduces — or the patch fails a gate —
-aztrx falls back to `claude-sonnet-5` and tries again. Most one-line fixes never
-pay for the big model. Tiers are configurable via `AZTRX_FAST_MODEL` /
-`AZTRX_MODEL` or `--heal-fast-model` / `--heal-model`.
+`--heal` is backed by a two-tier router: a fast/cheap model generates first, its patch
+is gated, compiled, and replayed against the repro, and if the bug still reproduces (or
+the patch fails a gate) aztrx falls back to the stronger model and tries again. Most
+one-line fixes never pay for the big model. With Anthropic the defaults are
+`claude-haiku-4-5` → `claude-sonnet-5`; with any other provider you pick both via
+`AZTRX_FAST_MODEL` / `AZTRX_MODEL` (or `--heal-fast-model` / `--heal-model`). When only
+one model is set, the router collapses to a single tier.
 
 ## Security & data flow
 
@@ -320,7 +351,7 @@ LLM call.
   CORS.
 - **`.aztrx/` is gitignored** on `init` — repro specs, reports, and patches stay
   out of history.
-- **Pinned supply chain.** The GitHub Action pins `aztrx-cli@0.2.4` (never
+- **Pinned supply chain.** The GitHub Action pins `aztrx-cli@0.4.0` (never
   `@latest`).
 
 ## Telemetry & privacy
@@ -412,7 +443,7 @@ Aztrx AI is a decoupled, event-driven pipeline — modules talk only through an
 ## Contributing
 
 ```bash
-git clone https://github.com/DanisChaparov/aztrx
+git clone https://github.com/Aztrx-AI/aztrx
 cd aztrx
 npm install
 npx playwright install chromium

package/dist/cli.js

@@ -12,10 +12,12 @@ import { initProject } from "./core/init.js";
 import { startStudio } from "./core/studio.js";
 import { writePrComment } from "./core/pr.js";
 import { writeBadge } from "./core/badge.js";
+import { writeRegressionSpecs } from "./core/specCompiler.js";
 import { flushTelemetry } from "./core/telemetry/index.js";
 import { flushCloud } from "./core/cloud/index.js";
 import { summarizeFindings } from "./core/summarize.js";
 import { applyVerifiedPatches } from "./core/heal/apply.js";
+import { openFixPr } from "./core/fixPr.js";
 import { promptYesNo } from "./core/prompt.js";
 import { modernizeFile } from "./core/modernize.js";
 function collect(value, prev) {
@@ -122,17 +124,19 @@ program
     .addOption(opt("--fix", "find → explain → heal → apply: one-command fix", "fix"))
     .addOption(opt("--heal", "closed-loop healing for crash/error findings (implies --repro)", "fix"))
     .addOption(opt("--magic-fix", "alias for --fix (deprecated)").hideHelp())
-    .addOption(opt("--heal-model <model>", "LLM model for healing — the fallback tier (default claude-sonnet-5)", "advanced"))
-    .addOption(opt("--heal-fast-model <model>", "fast/cheap first tier for the smart router (default claude-haiku-4-5)", "advanced"))
+    .addOption(opt("--heal-model <model>", "LLM model for healing (default: claude-sonnet-5 or $AZTRX_MODEL)", "advanced"))
+    .addOption(opt("--heal-fast-model <model>", "fast/cheap first tier (default: claude-haiku-4-5 or $AZTRX_FAST_MODEL)", "advanced"))
     .addOption(opt("--test-command <cmd>", "test command run against a healed patch (default: npm test, auto-detected)", "advanced"))
     .addOption(opt("--test-timeout <ms>", "timeout for the heal test gate, ms", "advanced").default("300000"))
     .addOption(opt("--no-test", "skip the test gate during healing", "advanced"))
     .addOption(opt("--start-command <cmd>", "command to boot the app for server healing (default: auto-detect scripts.dev/scripts.start)", "advanced"))
     .addOption(opt("--explain", "print a human-language summary of the findings (no healing)", "fix"))
     .addOption(opt("-y, --yes", "auto-apply verified fixes without prompting (with --fix)", "fix"))
+    .addOption(opt("--pr", "open a PR with the verified fixes (with --fix)", "fix"))
     .addOption(opt("--lang <en|ru>", "language for the human-language summary", "advanced").default("en"))
     .addOption(opt("--pr-comment [path]", "write a GitHub PR markdown comment (default .aztrx/pr-comment.md)", "ship"))
     .addOption(opt("--badge [path]", "write a self-contained SVG badge (default .aztrx/badge.svg)", "ship"))
+    .addOption(opt("--regression-test [dir]", "copy validated repro specs into the project test dir (default: e2e/ or tests/)", "ship"))
     .addOption(opt("--telemetry", "opt-in: collect anonymized crash→repro→patch tuples locally (.aztrx/telemetry)", "advanced"))
     .addOption(opt("--share-data", "opt-in: also upload the sanitized tuples to the telemetry endpoint", "advanced"))
     .addOption(opt("--upload", "opt-in: stream run results to the Aztrx AI cloud dashboard (needs --api-key)", "advanced"))
@@ -231,6 +235,13 @@ program
         writeBadge(repoRoot, findings, badgePath);
         console.log(pc.dim(`Badge: ${path.relative(repoRoot, badgePath)}`));
     }
+    if (opts.regressionTest) {
+        const regDir = typeof opts.regressionTest === "string" ? opts.regressionTest : undefined;
+        const written = writeRegressionSpecs(repoRoot, findings, regDir);
+        for (const w of written) {
+            console.log(pc.green("  ✓ regression test") + ` ${path.relative(repoRoot, w)}`);
+        }
+    }
     // F13 — human-language summary + opt-in apply (the "Senior Rescuer" flow).
     // The run already printed its structured output; this layer explains it and,
     // under `--fix`, offers to apply the verified patches so `git diff`
@@ -258,9 +269,18 @@ program
             }
         }
     }
-    if (!useUi) {
-        suggestNext(findings, opts);
+    if (opts.pr) {
+        const prRes = await openFixPr(repoRoot, findings, url);
+        if (prRes.ok) {
+            console.log(pc.green("  ✓ PR opened") + ` ${prRes.url}`);
+        }
+        else {
+            console.log(pc.yellow("  ◐ PR skipped") + `: ${prRes.error}`);
+        }
     }
+    // Suggest the next flag (e.g. --fix) after the run, in both the live TUI
+    // and plain paths. In the TUI this prints after the panel has finished.
+    suggestNext(findings, opts);
     // Drain any in-flight telemetry uploads (each bounded) before exit, so a
     // pending `--share-data` dispatch isn't killed mid-flight. Never affects
     // the exit code.

package/dist/core/fixPr.js

@@ -0,0 +1,50 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+const exec = promisify(execFile);
+/**
+ * Turn applied, verified fixes into a merge-ready PR: create a branch, commit,
+ * and open a PR via the `gh` CLI with the repro evidence in the body. Mirrors
+ * the "merge-ready PR" flow but for runtime crashes, not security vulns.
+ */
+export async function openFixPr(repoRoot, findings, url) {
+    const healed = findings.filter((f) => f.heal?.status === "healed");
+    if (healed.length === 0)
+        return { ok: false, error: "no verified fixes to open a PR for" };
+    const branch = `aztrx/fix-${Date.now().toString(36)}`;
+    const title = `fix: ${healed.length} runtime bug${healed.length === 1 ? "" : "s"} found by Aztrx`;
+    const bullets = healed.map((f) => {
+        const loc = f.mappedLocation
+            ? `${f.mappedLocation.filePath}:${f.mappedLocation.line}`
+            : "unknown location";
+        const repro = f.repro?.verdict
+            ? `repro: ${f.repro.verdict} ${f.repro.reproductions}/${f.repro.runs}`
+            : "";
+        return `- **${f.rawMessage.split("\n")[0].slice(0, 120)}** — \`${loc}\` ${repro}`.trim();
+    });
+    const body = [
+        "## Aztrx AI — verified fixes",
+        "",
+        `Found ${healed.length} runtime bug${healed.length === 1 ? "" : "s"} against ${url}:`,
+        "",
+        ...bullets,
+        "",
+        "Each fix was gated (AST safety), compiled, run against the test suite, and replayed against the repro in an isolated worktree before this PR.",
+    ].join("\n");
+    try {
+        await exec("git", ["-C", repoRoot, "checkout", "-b", branch]);
+        await exec("git", ["-C", repoRoot, "add", "-A"]);
+        await exec("git", ["-C", repoRoot, "commit", "-m", title]);
+    }
+    catch (e) {
+        return { ok: false, error: `git failed: ${e.message}` };
+    }
+    try {
+        const { stdout } = await exec("gh", ["pr", "create", "--title", title, "--body", body], {
+            cwd: repoRoot,
+        });
+        return { ok: true, url: stdout.trim() };
+    }
+    catch (e) {
+        return { ok: false, error: `gh pr create failed (is gh installed and authenticated?): ${e.message}` };
+    }
+}

package/dist/core/fuzzer.js

@@ -22,17 +22,63 @@ function pick(rnd, arr) {
     return arr[Math.floor(rnd() * arr.length)];
 }
 /**
- * F5 — chaos fuzzer. Seeded random walk with a richer vocabulary than the
- * deterministic walk: clicks (occasionally doubled), hover, keypresses, select
- * option changes, scrolls, and garbage-filled text inputs — tripping runtime
- * errors for the interceptor. Skips anything the destructive deny-list flags,
- * and never follows off-origin links.
+ * F5 — chaos fuzzer with coverage guidance. A seeded random walk (click/hover/
+ * keypress/select/garbage input) that also reads V8 JS coverage and biases its
+ * picks toward elements whose action previously uncovered new code — the same
+ * "prefer the input that reaches new code" idea behind libFuzzer/AFL, applied to
+ * the DOM. Returns how many brand-new JS ranges this pass executed.
  */
 export async function fuzz(page, bus, opts = {}) {
     const max = opts.maxActions ?? 100;
     const rnd = mulberry32(opts.seed ?? 42);
     const startUrl = page.url();
     let acted = 0;
+    let newCoverage = 0;
+    const seenRanges = new Set();
+    const interesting = new Set(); // labels whose action uncovered new code
+    try {
+        await page.coverage.startJSCoverage();
+    }
+    catch {
+        // coverage unsupported in this context — the fuzz still runs, just blind.
+    }
+    // Snapshot current JS coverage; returns the count of newly-seen ranges.
+    const snapshot = async () => {
+        let fresh = 0;
+        try {
+            const entries = await page.coverage.stopJSCoverage();
+            for (const e of entries) {
+                const id = e.scriptId || e.url;
+                for (const fn of e.functions) {
+                    for (const r of fn.ranges) {
+                        const key = `${id}:${r.startOffset}:${r.endOffset}`;
+                        if (!seenRanges.has(key)) {
+                            seenRanges.add(key);
+                            fresh++;
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            await page.coverage.startJSCoverage();
+        }
+        catch {
+            // ignore
+        }
+        return fresh;
+    };
+    const recordCoverage = async (label) => {
+        const fresh = await snapshot();
+        if (fresh > 0) {
+            newCoverage += fresh;
+            if (label)
+                interesting.add(label);
+        }
+    };
     for (let i = 0; i < max; i++) {
         if (page.url() !== startUrl) {
             await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
@@ -46,54 +92,63 @@ export async function fuzz(page, bus, opts = {}) {
                 await page.mouse.wheel(0, dir === "up" ? -600 : 600).catch(() => { });
             acted++;
             await page.waitForTimeout(40);
+            await recordCoverage("");
             continue;
         }
+        // Build the actionable list up front (skip destructive/external/non-text),
+        // so coverage guidance can bias the pick before we act.
         const handles = await page.$$(SELECTOR);
-        const visible = [];
+        const actionable = [];
         for (const h of handles) {
             const v = await h.isVisible().catch(() => false);
             const e = await h.isEnabled().catch(() => false);
-            if (v && e)
-                visible.push(h);
-        }
-        if (visible.length === 0)
-            break;
-        const handle = pick(rnd, visible);
-        let tag;
-        try {
-            tag = await handle.evaluate((el) => el.tagName.toLowerCase());
-        }
-        catch {
-            continue; // element detached/unreadable mid-query — skip
-        }
-        let label = "";
-        try {
-            label = await handle.evaluate((el) => {
-                const t = el.innerText ||
-                    el.getAttribute("aria-label") ||
-                    el.getAttribute("value") ||
-                    el.getAttribute("placeholder") ||
-                    "";
-                return t.trim();
-            });
-        }
-        catch {
-            label = ""; // degraded — no label to filter on
-        }
-        if (DESTRUCTIVE.test(label))
-            continue;
-        if (tag === "a") {
-            const href = (await handle.getAttribute("href")) ?? "";
-            if (/^https?:\/\//.test(href) && !href.startsWith(originOf(startUrl)))
+            if (!v || !e)
+                continue;
+            let tag;
+            try {
+                tag = await h.evaluate((el) => el.tagName.toLowerCase());
+            }
+            catch {
+                continue; // element detached/unreadable mid-query — skip
+            }
+            let label = "";
+            try {
+                label = await h.evaluate((el) => {
+                    const t = el.innerText ||
+                        el.getAttribute("aria-label") ||
+                        el.getAttribute("value") ||
+                        el.getAttribute("placeholder") ||
+                        "";
+                    return t.trim();
+                });
+            }
+            catch {
+                label = ""; // degraded — no label to filter on
+            }
+            if (DESTRUCTIVE.test(label))
                 continue;
+            if (tag === "a") {
+                const href = (await h.getAttribute("href")) ?? "";
+                if (/^https?:\/\//.test(href) && !href.startsWith(originOf(startUrl)))
+                    continue;
+            }
+            if (tag === "input") {
+                const type = (await h.getAttribute("type")) ?? "";
+                if (!TEXT_INPUT_TYPES.has(type))
+                    continue; // skip password/hidden/submit/checkbox/etc.
+            }
+            actionable.push({ handle: h, tag, label });
         }
-        // Text inputs — mostly pour garbage in, sometimes hit keys or hover.
+        if (actionable.length === 0)
+            break;
+        // Coverage guidance: prefer elements that previously uncovered new code.
+        const known = actionable.filter((a) => a.label && interesting.has(a.label));
+        const chosen = known.length > 0 && rnd() < 0.5 ? pick(rnd, known) : pick(rnd, actionable);
+        const { handle, tag, label } = chosen;
+        const selectors = await selectorCascade(page, handle);
+        const roll = rnd();
+        let didAct = true;
         if (tag === "input" || tag === "textarea") {
-            const type = (await handle.getAttribute("type")) ?? "";
-            if (!TEXT_INPUT_TYPES.has(type))
-                continue;
-            const selectors = await selectorCascade(page, handle);
-            const roll = rnd();
             if (roll < 0.6) {
                 const value = pick(rnd, GARBAGE);
                 const action = { type: "input", selectors, value, timestamp: Date.now() };
@@ -116,35 +171,27 @@ export async function fuzz(page, bus, opts = {}) {
                 if (!opts.dryRun)
                     await handle.hover().catch(() => { });
             }
-            acted++;
-            await page.waitForTimeout(60);
-            continue;
         }
-        // Select — actually change the option, a common source of state bugs.
-        if (tag === "select") {
+        else if (tag === "select") {
             let options = [];
             try {
                 options = await handle.evaluate((el) => Array.from(el.options).map((o) => o.value || o.textContent?.trim() || ""));
             }
             catch {
-                continue; // options unreadable — skip this select
+                didAct = false; // options unreadable — skip this select
             }
-            if (options.length > 0) {
+            if (didAct && options.length > 0) {
                 const value = pick(rnd, options);
-                const selectors = await selectorCascade(page, handle);
                 const action = { type: "select", selectors, value, timestamp: Date.now() };
                 bus.emit("action", action);
                 if (!opts.dryRun)
                     await handle.selectOption(value).catch(() => { });
-                acted++;
-                await page.waitForTimeout(60);
             }
-            continue;
+            else {
+                didAct = false;
+            }
         }
-        // Clickable — mostly click, otherwise hover or keyboard-navigate.
-        const selectors = await selectorCascade(page, handle);
-        const roll = rnd();
-        if (roll < 0.55) {
+        else if (roll < 0.55) {
             const action = { type: "click", selectors, timestamp: Date.now() };
             bus.emit("action", action);
             if (!opts.dryRun) {
@@ -168,8 +215,11 @@ export async function fuzz(page, bus, opts = {}) {
                 await page.keyboard.press(key).catch(() => { });
             }
         }
-        acted++;
-        await page.waitForTimeout(60);
+        if (didAct) {
+            acted++;
+            await page.waitForTimeout(60);
+            await recordCoverage(label);
+        }
     }
-    return acted;
+    return { actions: acted, newCoverage };
 }

package/dist/core/heal/index.js

@@ -20,6 +20,7 @@ import * as path from "path";
 import { redact, unredact } from "./redact.js";
 import { auditPatch } from "./gates.js";
 import { generatePatch, modelTiers } from "./llm.js";
+import { hasLlmKey } from "../llm.js";
 import { applyHunks, createWorktree, diffWorktree, runTests, typecheckWorktree, writeWorktreeFile } from "./sandbox.js";
 import { bootServer, detectStartCommand } from "./boot.js";
 import { verifyFix } from "./verify.js";
@@ -121,18 +122,18 @@ export async function heal(finding, opts) {
     const ctx = { finding, filePath, fileContent: original, redactedContent: red.text };
     // No transport configured (and no injected generator) → nothing to try. A
     // higher model tier can't fix a missing key, so bail before paying anything.
-    if (!opts.patchFn && !process.env.ANTHROPIC_API_KEY) {
+    if (!opts.patchFn && !hasLlmKey()) {
         return {
             ...base,
             status: "no-llm",
-            error: "heal: ANTHROPIC_API_KEY is not set (and no patchFn was injected)",
+            error: "heal: no LLM API key is set (set ANTHROPIC_API_KEY, AZTRX_API_KEY, or AZTRX_API_BASE)",
         };
     }
     // The Smart Cloud Router tier plan: fast/cheap first, Sonnet as the fallback.
     // An injected patchFn collapses to a single tier (there is no model to route).
     const tiers = opts.patchFn
-        ? [{ model: opts.model ?? "claude-sonnet-5", label: "sonnet" }]
-        : modelTiers(opts.model);
+        ? [{ model: opts.model ?? "default", label: "sonnet" }]
+        : modelTiers(opts.model, opts.fastModel);
     const wt = await createWorktree(opts.repoRoot, finding.id);
     // The winning (or last) patch + verification, held back for the final save.
     let savedPatch = null;
@@ -140,6 +141,10 @@ export async function heal(finding, opts) {
     let savedTest = null;
     let savedGateOk = false;
     let last = base;
+    // Multi-model consensus: with AZTRX_CONSENSUS, try every tier and keep the
+    // smallest-diff fix that actually heals, instead of the first one that works.
+    const consensus = Boolean(process.env.AZTRX_CONSENSUS);
+    let best = null;
     try {
         for (const tier of tiers) {
             // 2. Generate (this tier).
@@ -268,8 +273,20 @@ export async function heal(finding, opts) {
                 verification: v,
                 model: tier.model,
             };
-            if (v.fixed)
-                break;
+            if (v.fixed) {
+                const diffSize = hunks.reduce((s, h) => s + h.replace.length, 0);
+                if (!best || diffSize < best.diffSize) {
+                    best = { result: last, patch, verification: v, gateOk: gate.ok, diffSize };
+                }
+                if (!consensus)
+                    break;
+            }
+        }
+        if (best) {
+            last = best.result;
+            savedPatch = best.patch;
+            savedVerification = best.verification;
+            savedGateOk = best.gateOk;
         }
         // 5. Hand off a reviewable patch (the winning — or last — attempt only).
         if (savedPatch && savedVerification) {

package/dist/core/heal/llm.js

@@ -7,26 +7,31 @@
  * module's callers.
  */
 import { redact } from "./redact.js";
-const DEFAULT_MODEL = process.env.AZTRX_MODEL || "claude-sonnet-5";
-/** Cheap/fast first tier for the Smart Cloud Router. The idea: most one-line
- * fixes are trivial, so try the small model before paying for the big one. */
-const FAST_MODEL = process.env.AZTRX_FAST_MODEL || "claude-haiku-4-5-20251001";
-const API_URL = "https://api.anthropic.com/v1/messages";
+import { complete, primaryModel, fastModel } from "../llm.js";
 /**
  * The Smart Cloud Router's tier plan: fast/cheap first, then the capable model
  * as the fallback. Collapses to a single tier when the two resolve to the same
  * model (e.g. `AZTRX_FAST_MODEL=claude-sonnet-5`). Consumers loop over this in
  * order and stop at the first `healed` result.
  */
-export function modelTiers(fallbackModel) {
-    const fast = process.env.AZTRX_FAST_MODEL || FAST_MODEL;
-    const sonnet = fallbackModel || DEFAULT_MODEL;
-    if (fast === sonnet)
-        return [{ model: sonnet, label: "sonnet" }];
-    return [
-        { model: fast, label: "fast" },
-        { model: sonnet, label: "sonnet" },
-    ];
+export function modelTiers(fallbackModel, fastFallback) {
+    const fast = fastFallback || fastModel();
+    const primary = fallbackModel || primaryModel();
+    if (!primary)
+        return []; // no model configured — the caller reports no-llm
+    const tiers = [];
+    if (fast && fast !== primary)
+        tiers.push({ model: fast, label: "fast" });
+    tiers.push({ model: primary, label: "sonnet" });
+    // Extra models for multi-model consensus (`AZTRX_CONSENSUS_MODELS`), deduped.
+    for (const m of (process.env.AZTRX_CONSENSUS_MODELS || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)) {
+        if (!tiers.some((t) => t.model === m))
+            tiers.push({ model: m, label: "sonnet" });
+    }
+    return tiers;
 }
 const SYSTEM = `You are a meticulous bug-fixing engineer. You are given a single source file and a runtime error that occurs in it. Produce a MINIMAL fix as a Search & Replace diff.
 
@@ -76,33 +81,12 @@ export function parsePatch(raw) {
 export async function generatePatch(ctx, opts = {}) {
     if (opts.patchFn)
         return opts.patchFn(ctx);
-    const key = process.env.ANTHROPIC_API_KEY;
-    if (!key) {
-        throw new Error("heal: ANTHROPIC_API_KEY is not set (and no patchFn was injected)");
-    }
-    const res = await fetch(API_URL, {
-        method: "POST",
-        headers: {
-            "content-type": "application/json",
-            "x-api-key": key,
-            "anthropic-version": "2023-06-01",
-        },
-        body: JSON.stringify({
-            model: opts.model ?? DEFAULT_MODEL,
-            max_tokens: 2048,
-            temperature: 0,
-            system: SYSTEM,
-            messages: [{ role: "user", content: buildPrompt(ctx) }],
-        }),
+    const text = await complete({
+        system: SYSTEM,
+        prompt: buildPrompt(ctx),
+        model: opts.model,
+        maxTokens: 2048,
+        temperature: 0,
     });
-    if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new Error(`heal: LLM request failed (${res.status}): ${body.slice(0, 300)}`);
-    }
-    const data = (await res.json());
-    const text = (data.content ?? [])
-        .filter((c) => c.type === "text")
-        .map((c) => c.text ?? "")
-        .join("\n");
     return parsePatch(text);
 }

package/dist/core/llm.js

@@ -0,0 +1,142 @@
+/**
+ * Provider-agnostic LLM client. Two transports behind one `complete()`:
+ *
+ *   - Anthropic Messages API (default) — key from `ANTHROPIC_API_KEY` (or
+ *     `AZTRX_API_KEY`), primary model defaults to `claude-sonnet-5`.
+ *   - Any OpenAI-compatible `/chat/completions` endpoint — selected by setting
+ *     `AZTRX_API_BASE`. That single flag unlocks OpenAI, Grok, DeepSeek, Gemini,
+ *     Kimi, Mistral, OpenRouter, and local models (Ollama / vLLM / LM Studio)
+ *     with their existing keys.
+ *
+ * `AZTRX_MODEL` / `AZTRX_FAST_MODEL` pick the model(s); they default sensibly
+ * for Anthropic and must be set explicitly when a custom base URL is used.
+ */
+/** Resolve the active provider from the environment. */
+export function resolveSettings() {
+    const base = process.env.AZTRX_API_BASE?.trim();
+    if (base) {
+        return {
+            provider: "openai",
+            apiKey: process.env.AZTRX_API_KEY || process.env.OPENAI_API_KEY,
+            baseUrl: base.replace(/\/+$/, ""),
+        };
+    }
+    return {
+        provider: "anthropic",
+        apiKey: process.env.ANTHROPIC_API_KEY || process.env.AZTRX_API_KEY,
+    };
+}
+/** Is any provider configured? Used to decide whether to attempt an LLM call. */
+export function hasLlmKey() {
+    return Boolean(resolveSettings().apiKey);
+}
+/** The primary model for the active provider. */
+export function primaryModel() {
+    const s = resolveSettings();
+    if (s.provider === "anthropic")
+        return process.env.AZTRX_MODEL || "claude-sonnet-5";
+    return process.env.AZTRX_MODEL || "";
+}
+/** The cheap/fast first tier, or undefined when the provider has none. */
+export function fastModel() {
+    const s = resolveSettings();
+    if (s.provider === "anthropic")
+        return process.env.AZTRX_FAST_MODEL || "claude-haiku-4-5-20251001";
+    return process.env.AZTRX_FAST_MODEL || undefined;
+}
+/** Human-readable description of the active provider + model, e.g. `grok-2 via https://api.x.ai/v1`. */
+export function describeLlm(model) {
+    const s = resolveSettings();
+    const m = model || primaryModel();
+    if (s.provider === "anthropic")
+        return `${m} (Anthropic)`;
+    return `${m} via ${s.baseUrl}`;
+}
+// Announce the resolved model once per distinct (provider, model), so the two-tier
+// router shows each tier as it's tried without spamming. Written to stderr so it never
+// corrupts the Ink TUI (which renders on stdout).
+const announced = new Set();
+function announce(model, provider, baseUrl) {
+    const key = `${provider}:${model}`;
+    if (announced.has(key))
+        return;
+    announced.add(key);
+    const label = provider === "anthropic" ? `${model} (Anthropic)` : `${model} via ${baseUrl}`;
+    process.stderr.write(`LLM: ${label}\n`);
+}
+/** Run one completion against the active provider and return the text. */
+export async function complete(opts) {
+    const s = resolveSettings();
+    const model = opts.model || primaryModel();
+    if (!model) {
+        throw new Error("no model configured — set AZTRX_MODEL (e.g. AZTRX_MODEL=gpt-4o)");
+    }
+    if (!s.apiKey) {
+        throw new Error(s.provider === "anthropic"
+            ? "ANTHROPIC_API_KEY is not set"
+            : "AZTRX_API_KEY (or OPENAI_API_KEY) is not set");
+    }
+    announce(model, s.provider, s.baseUrl);
+    return s.provider === "anthropic"
+        ? anthropicComplete(s, model, opts)
+        : openaiComplete(s, model, opts);
+}
+async function anthropicComplete(s, model, opts) {
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-api-key": s.apiKey,
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({
+            model,
+            max_tokens: opts.maxTokens ?? 2048,
+            temperature: opts.temperature ?? 0,
+            system: opts.system,
+            messages: [{ role: "user", content: opts.prompt }],
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`LLM request failed (${res.status}): ${body.slice(0, 300)}`);
+    }
+    const data = (await res.json());
+    return (data.content ?? [])
+        .filter((c) => c.type === "text")
+        .map((c) => c.text ?? "")
+        .join("\n");
+}
+async function openaiComplete(s, model, opts) {
+    const res = await fetch(`${s.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${s.apiKey}`,
+        },
+        body: JSON.stringify({
+            model,
+            max_tokens: opts.maxTokens ?? 2048,
+            temperature: opts.temperature ?? 0,
+            messages: [
+                { role: "system", content: opts.system },
+                { role: "user", content: opts.prompt },
+            ],
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`LLM request failed (${res.status}): ${body.slice(0, 300)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices?.[0]?.message?.content;
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((c) => typeof c === "object" && c !== null && c.type === "text")
+            .map((c) => c.text ?? "")
+            .join("\n");
+    }
+    return "";
+}

package/dist/core/modernize.js

@@ -12,8 +12,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as ts from "typescript";
-const MODEL = process.env.AZTRX_MODEL || "claude-sonnet-5";
-const API_URL = "https://api.anthropic.com/v1/messages";
+import { complete, hasLlmKey } from "./llm.js";
 export function detectLang(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     if ([".ts", ".tsx", ".mts", ".cts"].includes(ext))
@@ -86,39 +85,20 @@ export async function modernizeFile(repoRoot, filePath) {
     catch (e) {
         return { ok: false, original: "", changes: [], error: `cannot read ${filePath}: ${e.message}` };
     }
-    const key = process.env.ANTHROPIC_API_KEY;
-    if (!key) {
-        return { ok: false, original, changes: [], lang, error: "ANTHROPIC_API_KEY is not set" };
+    if (!hasLlmKey()) {
+        return { ok: false, original, changes: [], lang, error: "no LLM API key is set (set ANTHROPIC_API_KEY, AZTRX_API_KEY, or AZTRX_API_BASE)" };
     }
     let reply;
     try {
-        const res = await fetch(API_URL, {
-            method: "POST",
-            headers: {
-                "content-type": "application/json",
-                "x-api-key": key,
-                "anthropic-version": "2023-06-01",
-            },
-            body: JSON.stringify({
-                model: MODEL,
-                max_tokens: 8192,
-                temperature: 0,
-                system: SYSTEM,
-                messages: [{ role: "user", content: buildPrompt(original, lang) }],
-            }),
+        reply = await complete({
+            system: SYSTEM,
+            prompt: buildPrompt(original, lang),
+            maxTokens: 8192,
+            temperature: 0,
         });
-        if (!res.ok) {
-            const body = await res.text().catch(() => "");
-            return { ok: false, original, changes: [], lang, error: `LLM request failed (${res.status}): ${body.slice(0, 300)}` };
-        }
-        const data = (await res.json());
-        reply = (data.content ?? [])
-            .filter((c) => c.type === "text")
-            .map((c) => c.text ?? "")
-            .join("\n");
     }
     catch (e) {
-        return { ok: false, original, changes: [], lang, error: `LLM request failed: ${e.message}` };
+        return { ok: false, original, changes: [], lang, error: e.message };
     }
     let parsed;
     try {

package/dist/core/orchestrator.js

@@ -97,7 +97,7 @@ export async function run(options) {
     else {
         emitPhase("walk");
     }
-    const { findings, replayStorageState: swarmAuthState, totalActions, workerCount, } = await swarmDetect({
+    const { findings, replayStorageState: swarmAuthState, totalActions, totalCoverage, workerCount, } = await swarmDetect({
         url,
         repoRoot,
         maxActions,
@@ -130,8 +130,11 @@ export async function run(options) {
     if (workerCount > 1) {
         say(pc.dim(`\nSwarm: ${totalActions} action(s) across ${workerCount} worker(s).\n`));
     }
+    else if (options.fuzz) {
+        say(pc.dim(`\nFuzzed ${totalActions} action(s) — covered ${totalCoverage} new code range(s).\n`));
+    }
     else {
-        say(pc.dim(`\n${options.fuzz ? "Fuzzed" : "Walked"} ${totalActions} action(s).\n`));
+        say(pc.dim(`\nWalked ${totalActions} action(s).\n`));
     }
     // F7 → F8 → F9: minimize each finding, compile an executable spec, validate
     // the flake rate. Only crash/error findings with a recorded action history.

package/dist/core/specCompiler.js

@@ -82,3 +82,34 @@ export function writeSpec(repoRoot, finding, actions, url) {
     fs.writeFileSync(file, compileSpec(finding, actions, url), "utf-8");
     return file;
 }
+/**
+ * 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 function writeRegressionSpecs(repoRoot, findings, dir) {
+    const target = path.resolve(repoRoot, dir || detectTestDir(repoRoot));
+    fs.mkdirSync(target, { recursive: true });
+    const written = [];
+    for (const f of findings) {
+        if (!f.repro?.specPath || f.repro.verdict === "unreliable")
+            continue;
+        const src = path.resolve(repoRoot, f.repro.specPath);
+        if (!fs.existsSync(src))
+            continue;
+        const dest = path.join(target, `aztrx-${f.fingerprint.slice(0, 8)}.spec.ts`);
+        fs.copyFileSync(src, dest);
+        written.push(dest);
+    }
+    return written;
+}
+/** Prefer an existing test dir, else a gitignored fallback. */
+function detectTestDir(repoRoot) {
+    for (const d of ["e2e", "tests", "test", "__tests__"]) {
+        if (fs.existsSync(path.join(repoRoot, d)))
+            return d;
+    }
+    return ".aztrx/regression";
+}

package/dist/core/summarize.js

@@ -11,8 +11,7 @@
  * 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.
  */
-const MODEL = process.env.AZTRX_MODEL || "claude-sonnet-5";
-const API_URL = "https://api.anthropic.com/v1/messages";
+import { complete, hasLlmKey } from "./llm.js";
 function normalizeLang(lang) {
     return lang === "ru" ? "ru" : "en";
 }
@@ -126,31 +125,12 @@ 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, human-language summary for a developer. 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 res = await fetch(API_URL, {
-        method: "POST",
-        headers: {
-            "content-type": "application/json",
-            "x-api-key": process.env.ANTHROPIC_API_KEY,
-            "anthropic-version": "2023-06-01",
-        },
-        body: JSON.stringify({
-            model: MODEL,
-            max_tokens: 1024,
-            temperature: 0.2,
-            system: SYSTEM,
-            messages: [{ role: "user", content: buildLlmPrompt(findings, lang, hasHealed) }],
-        }),
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new Error(`summarize: LLM request failed (${res.status}): ${body.slice(0, 300)}`);
-    }
-    const data = (await res.json());
-    const text = (data.content ?? [])
-        .filter((c) => c.type === "text")
-        .map((c) => c.text ?? "")
-        .join("\n")
-        .trim();
+    const text = (await complete({
+        system: SYSTEM,
+        prompt: buildLlmPrompt(findings, lang, hasHealed),
+        maxTokens: 1024,
+        temperature: 0.2,
+    })).trim();
     return text || summarizeFindingsTemplate(findings, lang);
 }
 /**
@@ -162,7 +142,7 @@ export async function summarizeFindings(findings, opts = {}) {
     const lang = normalizeLang(opts.lang);
     if (findings.length === 0)
         return summarizeFindingsTemplate(findings, lang);
-    if (!process.env.ANTHROPIC_API_KEY)
+    if (!hasLlmKey())
         return summarizeFindingsTemplate(findings, lang);
     try {
         return await summarizeFindingsLlm(findings, lang);

package/dist/core/swarm.js

@@ -130,12 +130,15 @@ export async function detectWorker(browser, opts, strategy, forwardBus) {
         await page.waitForTimeout(800);
     }
     let actions = 0;
+    let newCoverage = 0;
     if (loaded) {
         if (strategy.kind === "walk") {
             actions = await walkDom(page, workerBus, { maxActions: opts.maxActions, dryRun: opts.dryRun });
         }
         else if (strategy.kind === "fuzz") {
-            actions = await fuzz(page, workerBus, { seed: strategy.seed, maxActions: opts.maxActions, dryRun: opts.dryRun });
+            const fr = await fuzz(page, workerBus, { seed: strategy.seed, maxActions: opts.maxActions, dryRun: opts.dryRun });
+            actions = fr.actions;
+            newCoverage = fr.newCoverage;
         }
         else {
             actions = await httpFuzz(page, opts.url, workerBus, {
@@ -148,7 +151,7 @@ export async function detectWorker(browser, opts, strategy, forwardBus) {
     }
     await page.waitForTimeout(500);
     await context.close();
-    return { findings: classifier.findings(), actions, replayStorageState };
+    return { findings: classifier.findings(), actions, newCoverage, replayStorageState };
 }
 /** Dedup findings across workers by fingerprint: sum occurrences, keep the richest. */
 export function mergeFindings(arrays) {
@@ -227,7 +230,8 @@ export async function swarmDetect(opts) {
                 replayStorageState = r.replayStorageState;
         const findings = mergeFindings(results.map((r) => r.findings));
         const totalActions = results.reduce((sum, r) => sum + r.actions, 0);
-        return { findings, replayStorageState, totalActions, workerCount: strategies.length };
+        const totalCoverage = results.reduce((sum, r) => sum + r.newCoverage, 0);
+        return { findings, replayStorageState, totalActions, totalCoverage, workerCount: strategies.length };
     }
     finally {
         await browser.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aztrx-cli",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "private": false,
   "description": "Aztrx AI — runtime stress-tester for web apps. Detect bugs, then prove them with an executable repro.",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/DanisChaparov/aztrx.git"
+    "url": "https://github.com/Aztrx-AI/aztrx.git"
   },
   "scripts": {
     "build": "tsc",