aztrx-cli 0.4.5 → 0.5.2

package/dist/core/eventBus.d.ts

@@ -0,0 +1,59 @@
+import type { Finding, RecordedAction, ReproVerdict, TelemetryErrorPayload } from "./types.js";
+import type { HealStatus } from "./heal/types.js";
+export type RunPhase = "launch" | "swarm" | "walk" | "fuzz" | "http-fuzz" | "repro" | "heal" | "done";
+export interface PhaseEvent {
+    phase: RunPhase;
+    detail?: string;
+    ts: number;
+}
+export interface RouteEvent {
+    url: string;
+    ts: number;
+}
+export interface ReproEvent {
+    finding: Finding;
+    verdict: ReproVerdict;
+    runs: number;
+    reproductions: number;
+    steps: number;
+    totalSteps: number;
+    /** Repo-relative path to the compiled Playwright spec. */
+    specPath: string;
+}
+export interface HealEvent {
+    finding: Finding;
+    status: HealStatus;
+    patchPath?: string;
+    error?: string;
+}
+export type NoticeLevel = "hint" | "warning" | "danger";
+export interface NoticeEvent {
+    message: string;
+    level: NoticeLevel;
+    ts: number;
+}
+export interface AztrxEvents {
+    telemetry: TelemetryErrorPayload;
+    action: RecordedAction;
+    finding: Finding;
+    repro: ReproEvent;
+    heal: HealEvent;
+    phase: PhaseEvent;
+    route: RouteEvent;
+    noise: {
+        ts: number;
+    };
+    notice: NoticeEvent;
+}
+type Handler<T> = (payload: T) => void;
+/**
+ * Minimal typed event bus — the single backbone the modules communicate over,
+ * so the Orchestrator can be swapped for a cloud sink later without touching
+ * any module (hexagonal, per PRD §2.2).
+ */
+export declare class EventBus {
+    private handlers;
+    on<K extends keyof AztrxEvents>(event: K, handler: Handler<AztrxEvents[K]>): () => void;
+    emit<K extends keyof AztrxEvents>(event: K, payload: AztrxEvents[K]): void;
+}
+export {};

package/dist/core/events.d.ts

@@ -0,0 +1,42 @@
+import type { Finding, ReproVerdict } from "./types.js";
+import type { HealStatus } from "./heal/types.js";
+export type RunEvent = {
+    type: "run_start";
+    url: string;
+    ts: number;
+} | {
+    type: "finding";
+    finding: Finding;
+} | {
+    type: "repro";
+    fingerprint: string;
+    verdict: ReproVerdict;
+    runs: number;
+    reproductions: number;
+    steps: number;
+    totalSteps: number;
+    specPath: string;
+} | {
+    type: "heal";
+    fingerprint: string;
+    status: HealStatus;
+    patchPath?: string;
+    error?: string;
+} | {
+    type: "run_end";
+    counts: Record<string, number>;
+    ts: number;
+};
+/**
+ * Append-only JSON-lines run log. Every run writes its lifecycle + findings
+ * here so a live surface (Local Studio, later the cloud sink) can tail it
+ * without coupling to the orchestrator's console output.
+ */
+export declare class RunLog {
+    private readonly file;
+    constructor(repoRoot: string);
+    append(event: RunEvent): void;
+    /** Truncate so the log represents the latest run only (live-tail semantics). */
+    reset(): void;
+    get path(): string;
+}

package/dist/core/fixPr.d.ts

@@ -0,0 +1,16 @@
+import type { Finding } from "./types.js";
+export interface FixPrResult {
+    ok: boolean;
+    url?: string;
+    error?: string;
+}
+/**
+ * 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.
+ *
+ * Only the files the patches touched are staged. `git add -A` would commit the
+ * user's unrelated uncommitted work into an auto-generated commit and push it —
+ * the one thing an automated fixer must never do to someone's repo.
+ */
+export declare function openFixPr(repoRoot: string, findings: Finding[], url: string): Promise<FixPrResult>;

package/dist/core/fixPr.js

@@ -5,6 +5,10 @@ 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.
+ *
+ * Only the files the patches touched are staged. `git add -A` would commit the
+ * user's unrelated uncommitted work into an auto-generated commit and push it —
+ * the one thing an automated fixer must never do to someone's repo.
  */
 export async function openFixPr(repoRoot, findings, url) {
     const healed = findings.filter((f) => f.heal?.status === "healed");
@@ -30,9 +34,15 @@ export async function openFixPr(repoRoot, findings, url) {
         "",
         "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");
+    // The authoritative path of what was written is `heal.filePath` — the same
+    // field `applyVerifiedPatches` resolves and writes through.
+    const files = [...new Set(healed.map((f) => f.heal?.filePath).filter((p) => !!p))];
+    if (files.length === 0) {
+        return { ok: false, error: "no staged files recorded for the verified fixes" };
+    }
     try {
         await exec("git", ["-C", repoRoot, "checkout", "-b", branch]);
-        await exec("git", ["-C", repoRoot, "add", "-A"]);
+        await exec("git", ["-C", repoRoot, "add", "--", ...files]);
         await exec("git", ["-C", repoRoot, "commit", "-m", title]);
     }
     catch (e) {

package/dist/core/fuzzer.d.ts

@@ -0,0 +1,24 @@
+import type { Page } from "playwright";
+import type { EventBus } from "./eventBus.js";
+export interface FuzzOptions {
+    seed?: number;
+    maxActions?: number;
+    dryRun?: boolean;
+    /** Opt-in: include controls the deny-list skips (delete/pay/logout/checkout…).
+     * Off by default — these can mutate real state. */
+    allowDestructive?: boolean;
+}
+export interface FuzzResult {
+    actions: number;
+    /** JS code ranges executed for the first time during this run — a coverage
+     * signal that this pass explored new code, not just re-clicked known paths. */
+    newCoverage: number;
+}
+/**
+ * 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 declare function fuzz(page: Page, bus: EventBus, opts?: FuzzOptions): Promise<FuzzResult>;

package/dist/core/fuzzer.js

@@ -145,7 +145,7 @@ export async function fuzz(page, bus, opts = {}) {
         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 selectors = await selectorCascade(handle);
         const roll = rnd();
         let didAct = true;
         if (tag === "input" || tag === "textarea") {

package/dist/core/heal/apply.d.ts

@@ -0,0 +1,28 @@
+/**
+ * F13 — the only place Aztrx writes a verified patch into the user's *working
+ * tree*. Healing itself stays sandboxed (see `index.ts`); this module is the
+ * explicit, opt-in "apply" step behind `--fix`, so the recipe's promised
+ * `git diff` shows real changes.
+ *
+ * Rules that keep this safe:
+ *   - Only findings whose heal result is `healed` (verified: bug gone) are applied.
+ *   - The file is re-read *per finding* (several findings can touch one file),
+ *     and each patch is applied with exact-match hunks. A mismatch is a conflict
+ *     and is skipped — its `.patch` artifact stays for manual review.
+ *   - Paths are confined to `repoRoot`; anything escaping it is refused.
+ *   - Aztrx never commits. This writes working-tree files only.
+ */
+import type { Finding } from "../types.js";
+export interface AppliedPatch {
+    filePath: string;
+    hunkCount: number;
+}
+export interface ApplyConflict {
+    filePath: string;
+    error: string;
+}
+export interface ApplySummary {
+    applied: AppliedPatch[];
+    conflicts: ApplyConflict[];
+}
+export declare function applyVerifiedPatches(repoRoot: string, findings: Finding[]): ApplySummary;

package/dist/core/heal/boot.d.ts

@@ -0,0 +1,74 @@
+/**
+ * F10 gate #4 — boot the *patched* app for server-side verification. A server
+ * finding (e.g. `HTTP 500 /api/cart`) can't be verified by statically serving
+ * the worktree — the 500 only reappears when the route actually runs. So before
+ * the replay, this boots the patched server inside the worktree on a free port,
+ * waits for an HTTP readiness signal, and returns a `close` hook that tree-kills
+ * the process (and its children) so nothing is left holding the port.
+ *
+ * The same machinery serves zero-config runs (`aztrx` with no URL — see
+ * `src/core/devServer.ts`), which boot the user's own app instead of patched
+ * worktree code. The two callers differ only in environment isolation and port
+ * choice, which is what the `env` and `port` options below select.
+ */
+/** Auto-detect how the app starts, mirroring `runTests`'s `npm test` convention:
+ * prefer `scripts.dev` (no build step), then `scripts.start`. Null when neither
+ * exists — the caller then requires an explicit `--start-command`. */
+export declare function detectStartCommand(repoRoot: string): string | null;
+/** Is anything listening on this loopback port?
+ *
+ * Connect-based rather than bind-based on purpose: on Windows `SO_REUSEADDR`
+ * lets a socket bind a port another process already holds, so a successful
+ * `listen()` proves nothing there. A refused connection is the only reliable
+ * "nobody home" signal across platforms. */
+export declare function isPortFree(port: number): Promise<boolean>;
+/** Signal a process and everything below it to stop.
+ *
+ * The process we spawned is rarely the only one that matters: `shell: true`
+ * puts a cmd.exe/sh in between, and a dev server or a browser launch leaves
+ * grandchildren of its own. Killing only the direct child orphans them, which
+ * shows up later as a taken port or a stray Chromium.
+ *
+ * Callers must spawn with `detached: process.platform !== "win32"` so that
+ * POSIX can signal the whole process group; Windows has no group signalling and
+ * uses `taskkill /T` instead. */
+export declare function killTreeSync(pid: number): void;
+/** The awaiting form, for callers with an async shutdown path. The plugins use
+ * `killTreeSync` directly because their cleanup also runs from
+ * `process.on("exit")`, where promises never settle.
+ *
+ * This one does not return until the group is actually gone. `killTreeSync` only
+ * *sends* the signal, and the two platforms differ in what that guarantees:
+ * `taskkill /F` blocks until the process is dead, but POSIX SIGTERM is delivered
+ * asynchronously, so a synchronous kill leaves the server holding its listening
+ * socket for a few more milliseconds. Callers treat `close()` as "the port is
+ * free now" — the plugins and `patrol` re-bind the same port on restart — so
+ * returning early hands them a port that is still taken.
+ *
+ * Liveness is checked on the group (`-pid`) rather than the pid, because the
+ * process we spawned is a shell: `shell: true` means the socket is usually held
+ * by a grandchild, and only the group covers it. */
+export declare function killTree(pid: number): Promise<void>;
+export interface BootedServer {
+    url: string;
+    close: () => Promise<void>;
+    /** Tail of the server's stdout/stderr, for timeout/error reporting. */
+    logs: () => string;
+}
+export declare function bootServer(opts: {
+    worktreeDir: string;
+    repoRoot: string;
+    startCommand: string;
+    timeoutMs?: number;
+    /** Preferred port. Honoured only when it is genuinely free — otherwise a free
+     * one is allocated. A dev server on its framework's usual port is more
+     * faithful (absolute URLs, redirects, CORS origins), so the zero-config path
+     * asks for it; heal wants isolation and leaves it unset. */
+    port?: number;
+    /** `isolated` (default) strips the environment to a minimal allow-list so the
+     * booted process — untrusted PR code in the heal sandbox — never sees the
+     * caller's secrets. `inherit` passes this process's environment through,
+     * which is what booting the user's *own* app on their *own* machine needs:
+     * a stripped env breaks anything reading `DATABASE_URL` and friends. */
+    env?: "isolated" | "inherit";
+}): Promise<BootedServer>;

package/dist/core/heal/boot.js

@@ -5,8 +5,13 @@
  * the replay, this boots the patched server inside the worktree on a free port,
  * waits for an HTTP readiness signal, and returns a `close` hook that tree-kills
  * the process (and its children) so nothing is left holding the port.
+ *
+ * The same machinery serves zero-config runs (`aztrx` with no URL — see
+ * `src/core/devServer.ts`), which boot the user's own app instead of patched
+ * worktree code. The two callers differ only in environment isolation and port
+ * choice, which is what the `env` and `port` options below select.
  */
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import * as fs from "fs";
 import * as net from "net";
 import * as path from "path";
@@ -41,9 +46,121 @@ function freePort() {
         });
     });
 }
+/** Is anything listening on this loopback port?
+ *
+ * Connect-based rather than bind-based on purpose: on Windows `SO_REUSEADDR`
+ * lets a socket bind a port another process already holds, so a successful
+ * `listen()` proves nothing there. A refused connection is the only reliable
+ * "nobody home" signal across platforms. */
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const sock = net.connect({ port, host: "127.0.0.1" });
+        const finish = (free) => {
+            sock.destroy();
+            resolve(free);
+        };
+        sock.setTimeout(1000);
+        sock.once("connect", () => finish(false));
+        // A listener that accepts but never speaks is still a listener — treat a
+        // timeout as taken, so the caller allocates a different port rather than
+        // colliding with whatever is there.
+        sock.once("timeout", () => finish(false));
+        sock.once("error", () => finish(true));
+    });
+}
+/** Signal a process and everything below it to stop.
+ *
+ * The process we spawned is rarely the only one that matters: `shell: true`
+ * puts a cmd.exe/sh in between, and a dev server or a browser launch leaves
+ * grandchildren of its own. Killing only the direct child orphans them, which
+ * shows up later as a taken port or a stray Chromium.
+ *
+ * Callers must spawn with `detached: process.platform !== "win32"` so that
+ * POSIX can signal the whole process group; Windows has no group signalling and
+ * uses `taskkill /T` instead. */
+export function killTreeSync(pid) {
+    if (process.platform === "win32") {
+        try {
+            spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+        }
+        catch {
+            // already exited, or no such process
+        }
+    }
+    else {
+        try {
+            process.kill(-pid, "SIGTERM");
+        }
+        catch {
+            // already exited
+        }
+    }
+}
+/** How long to let a signalled process group exit before escalating, and how
+ * long to wait after SIGKILL — which cannot be caught, so this is a backstop. */
+const TERM_GRACE_MS = 3000;
+const KILL_GRACE_MS = 2000;
+const POLL_MS = 25;
+/** Is this pid — or, given a negative pid, this whole process group — alive?
+ * Signal 0 delivers nothing; it only asks the kernel whether the target exists. */
+function isAlive(target) {
+    try {
+        process.kill(target, 0);
+        return true;
+    }
+    catch (e) {
+        // Only ESRCH means "no such process". EPERM means it exists but is not ours
+        // to signal — still alive, and treating it as gone would cut the wait short.
+        return e.code !== "ESRCH";
+    }
+}
+async function waitUntilGone(target, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (isAlive(target)) {
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((r) => setTimeout(r, POLL_MS));
+    }
+    return true;
+}
+/** The awaiting form, for callers with an async shutdown path. The plugins use
+ * `killTreeSync` directly because their cleanup also runs from
+ * `process.on("exit")`, where promises never settle.
+ *
+ * This one does not return until the group is actually gone. `killTreeSync` only
+ * *sends* the signal, and the two platforms differ in what that guarantees:
+ * `taskkill /F` blocks until the process is dead, but POSIX SIGTERM is delivered
+ * asynchronously, so a synchronous kill leaves the server holding its listening
+ * socket for a few more milliseconds. Callers treat `close()` as "the port is
+ * free now" — the plugins and `patrol` re-bind the same port on restart — so
+ * returning early hands them a port that is still taken.
+ *
+ * Liveness is checked on the group (`-pid`) rather than the pid, because the
+ * process we spawned is a shell: `shell: true` means the socket is usually held
+ * by a grandchild, and only the group covers it. */
+export async function killTree(pid) {
+    killTreeSync(pid);
+    // Windows has no group signalling and `killTreeSync` already blocked on the
+    // forced kill, so there is nothing left to wait for.
+    if (process.platform === "win32")
+        return;
+    const group = -pid;
+    if (await waitUntilGone(group, TERM_GRACE_MS))
+        return;
+    // Still alive after the grace period: a child that ignores SIGTERM. SIGKILL
+    // cannot be caught or blocked, so this is the end of the line.
+    try {
+        process.kill(group, "SIGKILL");
+    }
+    catch {
+        // exited between the check and the signal
+    }
+    await waitUntilGone(group, KILL_GRACE_MS);
+}
 export async function bootServer(opts) {
     const { worktreeDir, repoRoot, startCommand } = opts;
     const timeoutMs = opts.timeoutMs ?? 60_000;
+    const envMode = opts.env ?? "isolated";
     // A fresh worktree has no node_modules — symlink the root's so the booted
     // server resolves its dependencies (the same junction trick sandbox.ts uses).
     const rootNodeModules = path.join(repoRoot, "node_modules");
@@ -56,7 +173,7 @@ export async function bootServer(opts) {
             /* resolution errors surface in the readiness timeout below */
         }
     }
-    const port = await freePort();
+    const port = opts.port !== undefined && (await isPortFree(opts.port)) ? opts.port : await freePort();
     // Support scripts that hardcode a port via `-p {port}`; `PORT` is also set in
     // the environment for the (more common) scripts that read `process.env.PORT`.
     const command = startCommand.replace(/\{port\}/g, String(port));
@@ -76,8 +193,12 @@ export async function bootServer(opts) {
         shell: true,
         cwd: worktreeDir,
         // Minimal allow-list — the booted app is patched PR code; it must not see
-        // the caller's ANTHROPIC_API_KEY or other CI secrets.
-        env: buildChildEnv({ PORT: String(port), CI: "true" }),
+        // the caller's ANTHROPIC_API_KEY or other CI secrets. `inherit` (the
+        // zero-config path) boots the user's own app, so it gets the real env —
+        // minus the forced `CI`, which changes how dev servers behave.
+        env: envMode === "isolated"
+            ? buildChildEnv({ PORT: String(port), CI: "true" })
+            : { ...process.env, PORT: String(port) },
         // On POSIX, detach so the server + its children form their own process
         // group — close() can then signal the whole group. Windows can't do group
         // signaling; it relies on `taskkill /T` below instead.
@@ -91,25 +212,7 @@ export async function bootServer(opts) {
         if (closed || !child.pid)
             return;
         closed = true;
-        if (process.platform === "win32") {
-            // `shell: true` spawns cmd.exe which spawns the real server as a child —
-            // a plain child.kill() would orphan that child and leave the port taken.
-            await new Promise((resolve) => {
-                const killer = spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], {
-                    stdio: "ignore",
-                });
-                killer.on("exit", () => resolve());
-                killer.on("error", () => resolve());
-            });
-        }
-        else {
-            try {
-                process.kill(-child.pid, "SIGTERM");
-            }
-            catch {
-                // already exited
-            }
-        }
+        await killTree(child.pid);
     };
     // Readiness: poll until the server answers with *any* HTTP response (2xx/4xx/
     // 5xx all mean "the listener is up"). A still-compiling dev server (Next) may

package/dist/core/heal/childEnv.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Child-process environment isolation. The heal sandbox runs the project's own
+ * test suite, `tsc`, and dev server — which means it executes untrusted PR code.
+ * Handing that code the full `process.env` would leak the caller's secrets
+ * (ANTHROPIC_API_KEY, GH_TOKEN, NPM_TOKEN, AWS_*, …) into a process the PR author
+ * controls. Children therefore get only a minimal allow-list of harmless,
+ * platform-essential variables.
+ *
+ * Escape hatch: a caller whose dev server legitimately needs app config (e.g.
+ * `DATABASE_URL`) can pass it through by naming it in `AZTRX_ENV_ALLOW`
+ * (comma-separated) — without re-opening the leak for every secret in the env.
+ */
+/** Build a minimal child environment: harmless platform vars, anything named in
+ * `AZTRX_ENV_ALLOW`, and any caller-supplied `extra` (e.g. `{ PORT: "4317" }`). */
+export declare function buildChildEnv(extra?: Record<string, string>): Record<string, string>;

package/dist/core/heal/gates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * F10 gate #2 — AST safety gates. A model-generated patch is never applied
+ * blindly: the patched file is re-parsed and rejected if it smuggles in a new
+ * import, dynamic code execution, child-process access, or an empty catch that
+ * would swallow the very error we're trying to surface. JavaScript/TypeScript
+ * use the TypeScript compiler's AST; HTML/Vue/Svelte are audited by extracting
+ * inline <script> blocks and running the same checks on each.
+ */
+import type { GateResult } from "./types.js";
+/** Audit a patch by parsing the resulting file. `filePath` selects the parser. */
+export declare function auditPatch(original: string, patched: string, filePath: string): GateResult;

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

@@ -0,0 +1,19 @@
+/**
+ * F10 — closed-loop healing. Orchestrates the full loop, in order:
+ *
+ *   1. redact   — strip secrets from anything that will leave the machine
+ *   2. generate — ask an LLM for a Search & Replace diff (against the redacted
+ *                 file, unredacted before it touches the raw bytes)
+ *   3. gate     — re-parse the patched file; reject new imports / eval /
+ *                 child_process / empty catch
+ *   4. sandbox  — apply the patch in a detached git worktree, never the tree
+ *   5. test     — run the repo's own test suite; reject the patch if it goes red
+ *   6. verify   — replay the repro against the patched app; the bug must be gone
+ *   7. hand off — write a unified-diff `.patch` for a human to review and commit
+ *
+ * Aztrx never commits. A patch that fails any gate, does not apply exactly, or
+ * still reproduces the bug is rejected and reported, not silently kept.
+ */
+import type { Finding } from "../types.js";
+import type { HealOptions, HealResult } from "./types.js";
+export declare function heal(finding: Finding, opts: HealOptions): Promise<HealResult>;

package/dist/core/heal/index.js

@@ -36,9 +36,17 @@ const MIME = {
     ".jpg": "image/jpeg",
     ".ico": "image/x-icon",
 };
+/** Can this file be verification-served as-is? Only a self-contained HTML
+ * document. Static serving hands back raw bytes with no build step, so a `.tsx`
+ * arrives as text the browser will not execute — the code under test never runs
+ * and the crash cannot reproduce. Fixtures qualify; app sources never do. */
+function isStaticEntry(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return ext === ".html" || ext === ".htm";
+}
 /** Default verification server: serve the worktree's repo root statically and
- * address the mapped file directly. Works for static fixtures; real apps inject
- * their own dev-server `serve` fn. */
+ * address the mapped file directly. Works for static fixtures; real apps boot
+ * the patched worktree instead (see the serve selection in `heal`). */
 function staticServe(worktreeDir, filePath) {
     const entry = filePath.split(path.sep).join("/");
     return new Promise((resolve, reject) => {
@@ -97,18 +105,29 @@ export async function heal(finding, opts) {
     if (!finding.repro || finding.repro.verdict === "unreliable") {
         return { ...base, error: "no deterministic repro to verify against" };
     }
-    // Server findings (network_5xx) verify by *booting* the patched app, not static
-    // serving. That needs a start command — resolve it before paying the LLM so a
-    // missing one skips cleanly rather than after an expensive generation.
+    // Verification has to run the *patched* code, and there are only two ways to
+    // do that. Booting the worktree runs the real app, but needs a start command.
+    // Static serving runs anything, but with no build step and no bundler — so a
+    // `.tsx` comes back as text the browser will not execute, the patched code
+    // never runs, and the crash "not reproducing" means nothing. Only a
+    // self-contained HTML document is honest to static-serve (the fixture path).
+    //
+    // So: an injected serve hook wins, then booting, then static — and when none
+    // applies we refuse. Both checks run before paying the LLM, so an unverifiable
+    // finding skips cleanly instead of after an expensive generation.
     const isNetwork = finding.type === "network_5xx";
     const startCommand = opts.startCommand ?? detectStartCommand(opts.repoRoot);
-    if (isNetwork && !startCommand) {
-        return {
-            ...base,
-            error: "no start command for server heal (set --start-command, or add scripts.dev / scripts.start)",
-        };
-    }
     const filePath = loc.filePath;
+    if (!opts.serve && !startCommand) {
+        if (isNetwork || !isStaticEntry(filePath)) {
+            return {
+                ...base,
+                error: isNetwork
+                    ? "no start command for server heal (set --start-command, or add scripts.dev / scripts.start)"
+                    : `cannot verify a patch to ${filePath} without running it — a statically served source file never executes, so "fixed" would be unprovable. Set --start-command, or add scripts.dev / scripts.start to package.json`,
+            };
+        }
+    }
     const absPath = path.resolve(opts.repoRoot, filePath);
     let original;
     try {
@@ -131,12 +150,18 @@ export async function heal(finding, opts) {
         };
     }
     // The Smart Cloud Router tier plan: the free rule fix first, then fast/cheap,
-    // then Sonnet. An injected patchFn collapses to a single tier.
+    // then Sonnet. An injected patchFn collapses to a single tier. Paid tiers are
+    // enqueued only when a key is actually configured — otherwise the last tier
+    // throws "…_API_KEY is not set" and overwrites the specific failure the free
+    // rule tier already reported (test-failed, compile-failed, …), telling the
+    // user to add a key when the real problem was something else entirely.
     const tiers = [
         ...(rulePatch ? [{ model: RULE_TIER, label: "fast" }] : []),
         ...(opts.patchFn
             ? [{ model: opts.model ?? "default", label: "sonnet" }]
-            : modelTiers(opts.model, opts.fastModel)),
+            : hasLlmKey()
+                ? 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.
@@ -158,10 +183,14 @@ export async function heal(finding, opts) {
             }
             catch (e) {
                 // A spent session budget stops everything paid; a transport/config failure
-                // won't be fixed by a pricier tier either, so both break out here.
-                last = e instanceof BudgetExhaustedError
-                    ? { ...base, status: "budget-exhausted", error: e.message, model: tier.model }
-                    : { ...base, status: "no-llm", error: e.message, model: tier.model };
+                // won't be fixed by a pricier tier either, so both break out here. Keep an
+                // earlier tier's gate failure (test-failed, unfixed, …) — it names a real
+                // problem the user can act on, where "no key" would mask it.
+                if (e instanceof BudgetExhaustedError || last.status === base.status) {
+                    last = e instanceof BudgetExhaustedError
+                        ? { ...base, status: "budget-exhausted", error: e.message, model: tier.model }
+                        : { ...base, status: "no-llm", error: e.message, model: tier.model };
+                }
                 break;
             }
             if (patch.hunks.length === 0) {
@@ -253,12 +282,13 @@ export async function heal(finding, opts) {
                 };
                 continue;
             }
-            // 4. Verify — the bug must stop reproducing. Server findings boot the
-            // patched app in the worktree (static serving can't run a server); client
-            // findings keep the static server.
-            const serve = isNetwork
-                ? (dir) => bootServer({ worktreeDir: dir, repoRoot: opts.repoRoot, startCommand: startCommand })
-                : opts.serve ?? ((dir, fp) => staticServe(dir, fp));
+            // 4. Verify — the bug must stop reproducing, against the *patched* code.
+            // Mirror the selection made before generation: an injected hook wins, then
+            // booting the worktree, then static serving for a real HTML entry.
+            const serve = opts.serve ??
+                (startCommand
+                    ? (dir) => bootServer({ worktreeDir: dir, repoRoot: opts.repoRoot, startCommand })
+                    : (dir, fp) => staticServe(dir, fp));
             const v = await verifyFix({
                 url: opts.url,
                 actions: opts.actions,