aztrx-cli 0.3.0 → 0.4.1

package/dist/cli.js

@@ -12,11 +12,13 @@ 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 { promptYesNo } from "./core/prompt.js";
+import { openFixPr } from "./core/fixPr.js";
+import { promptYesNo, promptInput } from "./core/prompt.js";
 import { modernizeFile } from "./core/modernize.js";
 function collect(value, prev) {
     prev.push(value);
@@ -27,6 +29,35 @@ function autoWorkers() {
     const n = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
     return Math.max(1, Math.min(n, 8));
 }
+/** Auto-detect the running dev server URL: `aztrx.config.ts`, the dev script's
+ * `--port`, then a probe of common ports. Returns null when nothing responds. */
+async function detectUrl(repoRoot) {
+    const configPath = path.join(repoRoot, "aztrx.config.ts");
+    if (fs.existsSync(configPath)) {
+        const m = fs.readFileSync(configPath, "utf-8").match(/url\s*[=:]\s*["']([^"']+)["']/);
+        if (m)
+            return m[1];
+    }
+    const pkgPath = path.join(repoRoot, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        const dev = pkg.scripts?.dev || pkg.scripts?.start || "";
+        const pm = dev.match(/(?:--port|-p)\s*[= ]?\s*(\d+)/);
+        if (pm)
+            return `http://localhost:${pm[1]}`;
+    }
+    for (const port of [3000, 5173, 8080, 3001, 4000, 8000]) {
+        try {
+            const res = await fetch(`http://localhost:${port}`, { signal: AbortSignal.timeout(300) });
+            if (res.status < 500)
+                return `http://localhost:${port}`;
+        }
+        catch {
+            // not listening — try the next port
+        }
+    }
+    return undefined;
+}
 /** Print one low-key "next flag" hint after a run, so users learn the advanced
  * flags on demand instead of memorizing the whole surface. Fires only in the
  * plain-log path when there's a finding worth acting on. */
@@ -104,7 +135,7 @@ program
 program
     .command("run", { isDefault: true })
     .description("inspect a running app and prove its bugs with an executable repro")
-    .argument("<url>", "dev server to inspect, e.g. http://localhost:3000")
+    .argument("[url]", "dev server to inspect (auto-detected if omitted), e.g. http://localhost:3000")
     .configureHelp({ formatHelp })
     .addOption(opt("--repo <path>", "project root to inspect/watch (default: cwd)", "advanced"))
     .addOption(opt("--max-actions <n>", "max actions per pass", "advanced").default("100"))
@@ -130,9 +161,11 @@ program
     .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"))
@@ -151,6 +184,16 @@ program
     // `--fix` is the memorable verb; `--magic-fix` is a hidden alias.
     const magicFix = opts.magicFix || opts.fix;
     const repoRoot = path.resolve(opts.repo ?? program.opts().repo);
+    // Auto-detect the target when no URL is given — one less thing to type.
+    let targetUrl = url;
+    if (!targetUrl) {
+        targetUrl = await detectUrl(repoRoot);
+        if (!targetUrl) {
+            console.error(pc.red("No URL given and none auto-detected. Pass <url>, or run `aztrx-cli init` first."));
+            process.exit(1);
+        }
+        console.log(pc.dim(`Auto-detected ${targetUrl}`));
+    }
     const workers = opts.workers ? parseInt(opts.workers, 10) : opts.swarm ? autoWorkers() : undefined;
     const mode = (workers ?? 1) > 1 || opts.httpFuzz
         ? `swarm (${workers ?? 1} worker${(workers ?? 1) === 1 ? "" : "s"})`
@@ -161,8 +204,16 @@ program
                 : opts.repro
                     ? "repro"
                     : "deterministic walk";
+    // Interactive login: if --login was passed without credentials, ask for them
+    // so the user never has to remember the AZTRX_AUTH_* env vars.
+    let loginEmail = opts.loginEmail ?? process.env.AZTRX_AUTH_EMAIL;
+    let loginPassword = opts.loginPassword ?? process.env.AZTRX_AUTH_PASSWORD;
+    if (opts.login && !loginEmail && !loginPassword) {
+        loginEmail = await promptInput("Email:");
+        loginPassword = await promptInput("Password:");
+    }
     const runOpts = {
-        url,
+        url: targetUrl,
         repoRoot,
         maxActions: parseInt(opts.maxActions, 10),
         dryRun: opts.dryRun,
@@ -189,8 +240,8 @@ program
         cloudUrl: opts.cloudUrl,
         storageState: opts.storageState ?? opts.auth,
         login: opts.login,
-        loginEmail: opts.loginEmail ?? process.env.AZTRX_AUTH_EMAIL,
-        loginPassword: opts.loginPassword ?? process.env.AZTRX_AUTH_PASSWORD,
+        loginEmail,
+        loginPassword,
         loginUrl: opts.loginUrl,
     };
     const failOn = Boolean(opts.failOn);
@@ -202,7 +253,7 @@ program
         await renderTui({
             bus,
             done: runPromise,
-            targetUrl: url,
+            targetUrl,
             repoRoot,
             mode,
         });
@@ -221,7 +272,7 @@ program
         const prPath = typeof opts.prComment === "string"
             ? opts.prComment
             : path.join(repoRoot, ".aztrx", "pr-comment.md");
-        writePrComment(repoRoot, url, findings, prPath);
+        writePrComment(repoRoot, targetUrl, findings, prPath);
         console.log(pc.dim(`PR comment: ${path.relative(repoRoot, prPath)}`));
     }
     if (opts.badge) {
@@ -231,6 +282,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,6 +316,15 @@ program
             }
         }
     }
+    if (opts.pr) {
+        const prRes = await openFixPr(repoRoot, findings, targetUrl);
+        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);

package/dist/core/classifier.js

@@ -37,6 +37,7 @@ const HYDRATION_NOISE = [
 ];
 function normalize(message) {
     return message
+        .replace(/^(?:TypeError|ReferenceError|RangeError|SyntaxError|URIError|EvalError|Error):\s*/g, "")
         .replace(/\b\d+\b/g, "<N>")
         .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<UUID>")
         .replace(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/g, "<TS>")

package/dist/core/domWalker.js

@@ -13,29 +13,32 @@ export const SELECTOR = 'a, button, input, select, textarea, [role="button"], [o
 export async function walkDom(page, bus, opts = {}) {
     const max = opts.maxActions ?? 100;
     const startUrl = page.url();
+    const startOrigin = originOf(startUrl);
     let actions = 0;
-    const seen = new Set();
-    // Re-scan the DOM after every action (the page may have mutated or navigated)
-    // rather than walking a stale snapshot. Mirrors the fuzzer's recover-and-iterate
-    // loop, but deterministically (document order) and without re-clicking elements
-    // it has already acted on.
-    while (actions < max) {
-        if (page.url() !== startUrl) {
-            // A previous action navigated away — return to the starting page.
-            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+    let sawLoginForm = false;
+    const visited = new Set();
+    const queue = [startUrl];
+    // Breadth-first crawl: visit each internal page, walk its in-place controls
+    // (buttons/inputs/selects), and queue any internal links it reveals. This finds
+    // bugs on every route, not just the one you pointed at.
+    while (queue.length > 0 && actions < max) {
+        const url = queue.shift();
+        if (visited.has(url))
+            continue;
+        visited.add(url);
+        if (page.url() !== url) {
+            await page.goto(url, { waitUntil: "domcontentloaded" }).catch(() => { });
             await page.waitForTimeout(300);
         }
+        // Per-page "seen" set — the same button label on two pages is two targets.
+        const seen = new Set();
         let handles;
         try {
             handles = await page.$$(SELECTOR);
         }
         catch {
-            // A navigation raced the re-scan — reset to the start page and retry.
-            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
-            await page.waitForTimeout(300);
-            continue;
+            continue; // mid-navigation — the next queued URL is visited anyway
         }
-        let acted = false;
         for (const handle of handles) {
             if (actions >= max)
                 break;
@@ -67,12 +70,25 @@ export async function walkDom(page, bus, opts = {}) {
             if (DESTRUCTIVE.test(label))
                 continue;
             if (tag === "a") {
+                // Don't click links directly — queue internal ones for the crawl.
                 const href = (await handle.getAttribute("href")) ?? "";
-                if (/^https?:\/\//.test(href) && !href.startsWith(originOf(startUrl)))
-                    continue;
+                if (href && !/^(javascript:|mailto:|tel:|#)/.test(href)) {
+                    try {
+                        const target = new URL(href, url).href.split("#")[0];
+                        if (target.startsWith(startOrigin) && !visited.has(target) && queue.length < 20) {
+                            queue.push(target);
+                        }
+                    }
+                    catch {
+                        // unparseable href — ignore
+                    }
+                }
+                continue;
             }
             if (tag === "input") {
                 const type = (await handle.getAttribute("type")) ?? "";
+                if (type === "password")
+                    sawLoginForm = true;
                 if (!TEXT_INPUT_TYPES.has(type))
                     continue; // skip password/hidden/submit/checkbox/etc.
             }
@@ -94,14 +110,22 @@ export async function walkDom(page, bus, opts = {}) {
                     await handle.click({ timeout: 1500 }).catch(() => { });
             }
             actions++;
-            acted = true;
             await page.waitForTimeout(120);
-            break; // re-scan next iteration — the DOM may have changed
+            // A click may navigate (e.g. a submit) — queue the new URL and stop this
+            // page's walk; the queue visits it next.
+            if (page.url() !== url) {
+                const target = page.url().split("#")[0];
+                if (target.startsWith(startOrigin) && !visited.has(target) && queue.length < 20) {
+                    queue.push(target);
+                }
+                break;
+            }
         }
-        if (!acted)
-            break; // nothing left to act on
+        // Give in-flight async work (fetches, timers) a moment to reject before we
+        // navigate to the next crawled page — otherwise a 300ms-later throw is lost.
+        await page.waitForTimeout(500);
     }
-    return actions;
+    return { actions, sawLoginForm };
 }
 export function originOf(url) {
     return url.match(/^https?:\/\/[^/]+/)?.[0] ?? "";

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

@@ -19,7 +19,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { redact, unredact } from "./redact.js";
 import { auditPatch } from "./gates.js";
-import { generatePatch, modelTiers } from "./llm.js";
+import { generatePatch, generateRulePatch, modelTiers, RULE_TIER } from "./llm.js";
 import { hasLlmKey } from "../llm.js";
 import { applyHunks, createWorktree, diffWorktree, runTests, typecheckWorktree, writeWorktreeFile } from "./sandbox.js";
 import { bootServer, detectStartCommand } from "./boot.js";
@@ -120,20 +120,24 @@ export async function heal(finding, opts) {
     // 1. Redact — only the redacted copy is shown to the model.
     const red = redact(original);
     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 && !hasLlmKey()) {
+    // A free, no-key rule-based fix (null/undefined deref) — tried before any LLM.
+    const rulePatch = !opts.patchFn ? generateRulePatch(ctx) : null;
+    // No transport configured, and no rule fix applies → nothing to try.
+    if (!opts.patchFn && !hasLlmKey() && !rulePatch) {
         return {
             ...base,
             status: "no-llm",
-            error: "heal: no LLM API key is set (set ANTHROPIC_API_KEY, AZTRX_API_KEY, or AZTRX_API_BASE)",
+            error: "this crash needs a model — the free fixer only handles null/undefined derefs. Add a key: Anthropic → ANTHROPIC_API_KEY, or any provider → AZTRX_API_BASE + AZTRX_API_KEY + AZTRX_MODEL (no Aztrx account needed)",
         };
     }
-    // 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 ?? "default", label: "sonnet" }]
-        : modelTiers(opts.model, opts.fastModel);
+    // The Smart Cloud Router tier plan: the free rule fix first, then fast/cheap,
+    // then Sonnet. An injected patchFn collapses to a single tier.
+    const tiers = [
+        ...(rulePatch ? [{ model: RULE_TIER, label: "fast" }] : []),
+        ...(opts.patchFn
+            ? [{ 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;
@@ -141,6 +145,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).
@@ -269,8 +277,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) {