aztrx-cli 0.4.5 → 0.5.2

package/dist/core/llm.js

@@ -44,14 +44,6 @@ export function fastModel() {
         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).
@@ -81,6 +73,31 @@ export async function complete(opts) {
         ? anthropicComplete(s, model, opts)
         : openaiComplete(s, model, opts);
 }
+/**
+ * Turn an empty completion into a diagnosable error.
+ *
+ * Returning `""` here is what makes a provider-side failure reach the caller as
+ * `Unexpected end of JSON input` — a message that points at *our* parser rather
+ * than at the model, and which the heal path then degrades to a bland "no-llm".
+ * The stop reason is the entire diagnosis, so it is carried into the message.
+ *
+ * Real cases this covers: a free/contended endpoint failing mid-flight
+ * (`finish_reason: "error"` on OpenRouter), a reasoning model spending the whole
+ * budget before emitting any text (`length`), and provider-side filters.
+ */
+function emptyCompletion(provider, model, reason) {
+    const why = reason === "length" || reason === "max_tokens"
+        ? "the token limit was reached before any text was emitted — the model is most likely spending its whole budget on reasoning; pick a different one with --heal-model / AZTRX_MODEL"
+        : reason === "error"
+            ? "the provider failed mid-response"
+            : reason === "content_filter"
+                ? "the provider blocked the response"
+                : reason === "refusal"
+                    ? "the model refused the request"
+                    : "the provider returned no text";
+    const seen = reason ? `finish_reason: ${reason}` : "no finish_reason given";
+    return new Error(`${provider} returned no content (${seen}) — ${why}. Model: ${model}`);
+}
 async function anthropicComplete(s, model, opts) {
     const headers = {
         "content-type": "application/json",
@@ -107,10 +124,13 @@ async function anthropicComplete(s, model, opts) {
         throw new Error(`LLM request failed (${res.status}): ${body.slice(0, 300)}`);
     }
     const data = (await res.json());
-    return (data.content ?? [])
+    const text = (data.content ?? [])
         .filter((c) => c.type === "text")
         .map((c) => c.text ?? "")
         .join("\n");
+    if (!text.trim())
+        throw emptyCompletion("Anthropic", model, data.stop_reason);
+    return text;
 }
 async function openaiComplete(s, model, opts) {
     const res = await fetch(`${s.baseUrl}/chat/completions`, {
@@ -134,14 +154,21 @@ async function openaiComplete(s, model, opts) {
         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")
+    // OpenRouter reports upstream failures in the body with HTTP 200, so `res.ok`
+    // alone does not mean the model answered.
+    if (data.error)
+        throw new Error(`LLM request failed: ${data.error.message ?? "unknown error"}`);
+    const choice = data.choices?.[0];
+    const content = choice?.message?.content;
+    if (typeof content === "string" && content.trim())
         return content;
     if (Array.isArray(content)) {
-        return content
+        const text = content
             .filter((c) => typeof c === "object" && c !== null && c.type === "text")
             .map((c) => c.text ?? "")
             .join("\n");
+        if (text.trim())
+            return text;
     }
-    return "";
+    throw emptyCompletion("OpenAI-compatible endpoint", model, choice?.finish_reason);
 }

package/dist/core/minimizer.d.ts

@@ -0,0 +1,13 @@
+import type { RecordedAction } from "./types.js";
+import type { ReplayEngine } from "./replay.js";
+export interface MinimizeOptions {
+    url: string;
+    fingerprint: string;
+    maxReplays?: number;
+}
+/**
+ * F7 — ddmin (delta debugging). Shrinks the failing action sequence to a
+ * minimal subset that still reproduces `fingerprint`. Best-effort under a
+ * replay budget; a sequence shorter than 2 actions is returned as-is.
+ */
+export declare function minimize(engine: ReplayEngine, actions: RecordedAction[], opts: MinimizeOptions): Promise<RecordedAction[]>;

package/dist/core/modernize.d.ts

@@ -0,0 +1,28 @@
+/**
+ * F-modernize — the "code translator". Rewrites a legacy JS/TS file into modern
+ * idiomatic form (const/let over var, async/await over callbacks and promise
+ * chains, arrow functions, optional chaining) while preserving behavior. This is
+ * a *static* transform, unlike the rest of Aztrx's runtime detection, so it's its
+ * own command rather than a `run` flag.
+ *
+ * Safety model: the model's output is gated by a re-parse (`ts.transpileModule`
+ * reports syntax errors without running a full tsc), and the caller applies it to
+ * the working tree only after the user confirms — never automatically.
+ */
+export type Lang = "ts" | "js";
+export declare function detectLang(filePath: string): Lang | null;
+export interface ParseGateResult {
+    ok: boolean;
+    errors: string[];
+}
+/** Syntax gate: does the output still parse? In-process (no tsc subprocess). */
+export declare function parseGate(source: string): ParseGateResult;
+export interface ModernizeResult {
+    ok: boolean;
+    original: string;
+    modernized?: string;
+    changes: string[];
+    lang?: Lang;
+    error?: string;
+}
+export declare function modernizeFile(repoRoot: string, filePath: string): Promise<ModernizeResult>;

package/dist/core/modernize.js

@@ -22,7 +22,7 @@ export function detectLang(filePath) {
     return null;
 }
 /** Syntax gate: does the output still parse? In-process (no tsc subprocess). */
-export function parseGate(source, lang) {
+export function parseGate(source) {
     const result = ts.transpileModule(source, {
         compilerOptions: {
             target: ts.ScriptTarget.ES2022,
@@ -110,7 +110,7 @@ export async function modernizeFile(repoRoot, filePath) {
     if (!parsed.modernized.trim()) {
         return { ok: false, original, changes: [], lang, error: "model returned an empty file" };
     }
-    const gate = parseGate(parsed.modernized, lang);
+    const gate = parseGate(parsed.modernized);
     if (!gate.ok) {
         return {
             ok: false,

package/dist/core/networkGuard.d.ts

@@ -0,0 +1,13 @@
+import type { Page } from "playwright";
+export interface NetworkGuardOptions {
+    allowHosts: Set<string>;
+    onBlock?: (url: string) => void;
+}
+/**
+ * F6 — deny-by-default network guard (PRD §6.2). Aborts every request whose
+ * host isn't allow-listed, so a fuzz/replay pass can't reach payment, delete,
+ * or analytics endpoints. Loopback is always allowed (this is a local tool).
+ */
+export declare function attachNetworkGuard(page: Page, opts: NetworkGuardOptions): Promise<void>;
+/** Builds the allow-list: target origin + each `--allow-host`. */
+export declare function allowHostsFrom(url: string, extra: string[]): Set<string>;

package/dist/core/orchestrator.d.ts

@@ -0,0 +1,86 @@
+import { EventBus } from "./eventBus.js";
+import type { Finding } from "./types.js";
+import type { SpendBudget } from "./heal/types.js";
+export interface RunOptions {
+    url: string;
+    repoRoot: string;
+    maxActions?: number;
+    dryRun?: boolean;
+    crashTest?: boolean;
+    fuzz?: boolean;
+    /** F5-http: mutate the target origin with hostile HTTP requests (server-side
+     * attack surface). Runs after the walk/fuzz pass, before repro/heal. */
+    httpFuzz?: boolean;
+    /** With `httpFuzz`, also send POST/PUT body mutations (default: GET-only). */
+    httpFuzzMutations?: boolean;
+    /** Opt-in: include destructive controls/endpoints (delete/pay/logout/checkout…).
+     * Off by default — these can mutate real state, so they're refused unless the
+     * caller explicitly accepts the risk (loudly warned). */
+    allowDestructive?: boolean;
+    /** Language for the per-finding diagnosis headline (en/ru). Default: en. */
+    lang?: string;
+    repro?: boolean;
+    seed?: number;
+    /** F-swarm: number of parallel detection workers (default 1). `--swarm` = auto. */
+    workers?: number;
+    allowHosts?: string[];
+    reproRuns?: number;
+    /** Path to a Playwright storage-state JSON (cookies + localStorage) so the
+     * session starts authenticated. Produced by `playwright codegen --save-storage`. */
+    storageState?: string;
+    /** F-auth: auto-login before the pass. Needs `loginEmail` + `loginPassword`. */
+    login?: boolean;
+    loginEmail?: string;
+    loginPassword?: string;
+    /** Explicit login page URL (default: the current page, after any auth-wall redirect). */
+    loginUrl?: string;
+    /** F10: attempt closed-loop healing for crash/error findings. Needs
+     * `ANTHROPIC_API_KEY` (or an injected patchFn) and `repro: true`. */
+    heal?: boolean;
+    /** Fingerprints already handled (PR opened / marked unfixable) by an
+     * autonomous supervisor — skip healing them so a re-scan doesn't re-burn the
+     * LLM on a bug we've already acted on. */
+    skipHealFingerprints?: string[];
+    /** Shared, mutable session cap on paid LLM generations (see `SpendBudget`).
+     * Passed through to every heal call; a patrol session creates one budget and
+     * reuses it across cycles. */
+    budget?: SpendBudget;
+    /** LLM model override for healing (the fallback tier). */
+    healModel?: string;
+    /** Fast/cheap first tier for the Smart Cloud Router (`AZTRX_FAST_MODEL`). */
+    healFastModel?: string;
+    /** Override the test command run against a healed patch (default: `npm test`). */
+    testCommand?: string;
+    /** Timeout for the heal test gate, ms. */
+    testTimeoutMs?: number;
+    /** Skip the heal test gate. */
+    skipTest?: boolean;
+    /** How to boot the app for server-side healing (network_5xx findings).
+     * Auto-detected from package.json `scripts.dev` / `scripts.start` when omitted. */
+    startCommand?: string;
+    /** F11: collect + persist anonymized telemetry locally (opt-in). */
+    telemetry?: boolean;
+    /** F11: additionally upload the sanitized tuple to the telemetry endpoint. */
+    shareData?: boolean;
+    /** Override the telemetry endpoint (`AZTRX_TELEMETRY_URL`). */
+    telemetryUrl?: string;
+    /** F12: upload the run's findings to the Aztrx AI cloud dashboard (opt-in). */
+    upload?: boolean;
+    /** API key for cloud + telemetry uploads (`AZTRX_CLOUD_API_KEY`). */
+    apiKey?: string;
+    /** Override the cloud ingest base URL (`AZTRX_CLOUD_URL`). */
+    cloudUrl?: string;
+    /** Inject an external bus (the TUI subscribes to it). */
+    bus?: EventBus;
+    /** When true, suppress console output — the caller renders from bus events. */
+    ui?: boolean;
+}
+/**
+ * The run's finite state machine: launch → (guard) → intercept → act (walk or
+ * fuzz) → classify → map → report → repro (minimize/compile/validate). Modules
+ * communicate only through the EventBus; the orchestrator is the single place
+ * that wires them together. In `ui` mode it emits structured events (phase,
+ * action, finding, repro, route, noise) and stays silent on stdout, so a
+ * terminal renderer (Ink) can draw the live panel instead of log lines.
+ */
+export declare function run(options: RunOptions): Promise<Finding[]>;

package/dist/core/orchestrator.js

@@ -355,7 +355,10 @@ export async function run(options) {
     // F12 — opt-in cloud sync. Streams the sanitized run results to the ingest
     // API for the team dashboard; dedup happens server-side by fingerprint.
     if (options.upload) {
-        if (options.apiKey || process.env.AZTRX_API_KEY) {
+        // `AZTRX_CLOUD_API_KEY`, not `AZTRX_API_KEY`: the latter is a model provider
+        // credential, and treating its presence as consent to upload would put that
+        // key on the wire as the ingest auth header.
+        if (options.apiKey || process.env.AZTRX_CLOUD_API_KEY) {
             submitRun(findings, {
                 repoRoot,
                 url,
@@ -366,7 +369,7 @@ export async function run(options) {
             });
         }
         else {
-            say(pc.yellow("Upload skipped: no API key. Set --api-key or AZTRX_API_KEY to stream findings to the dashboard."));
+            say(pc.yellow("Upload skipped: no API key. Set --api-key or AZTRX_CLOUD_API_KEY to stream findings to the dashboard."));
         }
     }
     runLog.append({ type: "run_end", counts, ts: Date.now() });

package/dist/core/patrol/loop.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `aztrx patrol` — the autonomous bug-patrol loop. It wraps the existing
+ * `run()` detect → repro → heal pipeline in a supervisor loop with memory, so
+ * instead of "run it and read the output" the tool re-scans on an interval,
+ * fixes anything new, and opens a PR per bug — no human in the middle.
+ *
+ * Guardrails that keep an autonomous run from going off the rails:
+ *   - memory (PatrolState) — a handled fingerprint is never re-fixed/re-PR'd;
+ *   - per-session fix cap (`maxFixes`) — bounds LLM spend + PR spam;
+ *   - scoped staging — PRs carry only the files the patch touched;
+ *   - a liveness check — a dead target skips the cycle instead of burning a crawl.
+ */
+export interface PatrolOptions {
+    url: string;
+    repoRoot: string;
+    intervalMs: number;
+    maxFixes?: number;
+    maxActions?: number;
+    /** Hard cap on paid LLM generations across the whole session (0/undefined = unlimited). */
+    maxSpend?: number;
+    /** Cooldown before an `unfixed` fingerprint is retried, ms. Default 30 min. */
+    retryAfterMs?: number;
+    /** Group all of a cycle's fixes into one PR instead of one PR per bug. */
+    batch?: boolean;
+    once?: boolean;
+    fuzz?: boolean;
+    workers?: number;
+    allowHosts?: string[];
+    storageState?: string;
+    login?: boolean;
+    loginEmail?: string;
+    loginPassword?: string;
+    loginUrl?: string;
+    healModel?: string;
+    healFastModel?: string;
+    testCommand?: string;
+    testTimeoutMs?: number;
+    skipTest?: boolean;
+    startCommand?: string;
+    lang?: string;
+    seed?: number;
+    allowDestructive?: boolean;
+    httpFuzz?: boolean;
+    httpFuzzMutations?: boolean;
+}
+export declare function patrol(opts: PatrolOptions): Promise<void>;

package/dist/core/patrol/pr.d.ts

@@ -0,0 +1,42 @@
+/**
+ * PR opener for `aztrx patrol`. Like `fixPr.openFixPr`, but built for an
+ * autonomous loop, so it adds two things a human-driven flow doesn't need:
+ *
+ *   - **Dedup**: a fingerprint-stable branch name (`aztrx/fix-<fp8>`) plus a
+ *     `gh pr list --head` check, so a re-scan never opens a second PR for a bug
+ *     that already has one open.
+ *   - **Scoped staging**: stages only the files the patch touched (`git add --
+ *     <files>`), never `git add -A` — an autonomous run must not sweep up the
+ *     user's unrelated uncommitted work into a PR.
+ *
+ * The caller is responsible for applying patches first (`applyVerifiedPatches`).
+ */
+import type { Finding } from "../types.js";
+export interface PatrolPrResult {
+    ok: boolean;
+    skipped?: boolean;
+    url?: string;
+    branch?: string;
+    error?: string;
+}
+export declare function branchFor(fp: string): string;
+/** Stable branch name for a *set* of fingerprints — the same set always maps to
+ * the same branch, so a re-scan of an unchanged batch doesn't open a duplicate PR. */
+export declare function branchForSet(fps: string[]): string;
+/** A local/loopback/private target is a dev box; only a publicly-routable host is
+ * a deployed app, so a crash there is "live in production" and worth flagging.
+ * Covers loopback, RFC1918 private ranges (10/8, 172.16/12, 192.168/16),
+ * link-local (169.254/16), and mDNS/internal suffixes (.local, .internal). */
+export declare function isLocalUrl(url: string): boolean;
+/**
+ * Pure URL builder: turns a `git remote` origin URL into a raw-content URL for a
+ * repo-relative path, so the PR body can inline an image
+ * (`![…](https://github.com/<owner>/<repo>/raw/<branch>/<path>)`). Handles the
+ * three common remote shapes (`https://`, `git@github.com:`, `ssh://git@…`) and a
+ * trailing `.git`. Returns "" when the remote isn't GitHub.
+ */
+export declare function githubRawUrl(remote: string, branch: string, repoPath: string): string;
+export declare function openPatrolPr(repoRoot: string, finding: Finding, url: string, files: string[], mediaPath?: string | null): Promise<PatrolPrResult>;
+/** One PR carrying a whole batch of fixes. Branch is stable across the *set*, so
+ * an unchanged batch re-scan dedups to the same PR. */
+export declare function openPatrolBatchPr(repoRoot: string, findings: Finding[], url: string, files: string[], mediaPaths?: (string | null)[]): Promise<PatrolPrResult>;

package/dist/core/patrol/pr.js

@@ -144,17 +144,20 @@ async function rawUrlFor(repoRoot, branch, repoPath) {
  * files, commit, open the PR, and return to the original branch. The caller has
  * already done its own dedup + title/body. */
 async function createPr(repoRoot, branch, title, body, files) {
+    // Nothing to stage means no patch landed, so there is no fix to open a PR for.
+    // This used to fall back to `git add -A`, which would have swept the user's
+    // unrelated uncommitted work into an auto-generated commit under a "fix: …"
+    // title and pushed it. Refuse instead — and refuse before touching git, so a
+    // branch is never created for an empty fix set.
+    if (files.length === 0) {
+        return { ok: false, branch, error: "no files to stage — refusing to commit an empty fix set" };
+    }
     const originalBranch = await currentBranch(repoRoot);
     try {
         // `-B` (re)creates the branch at HEAD — idempotent against a stale local
         // branch left over from a previously failed PR attempt.
         await exec("git", ["-C", repoRoot, "checkout", "-B", branch]);
-        if (files.length) {
-            await exec("git", ["-C", repoRoot, "add", "--", ...files]);
-        }
-        else {
-            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/patrol/record.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Recorded repro (Phase 3) — turns a reproducible bug into a shareable
+ * "before/after" proof: an animated GIF and a static crash screenshot, both
+ * destined for the patrol PR body.
+ *
+ * The capture is deliberately OFF the hot path. Verification replays a bug many
+ * times (ddmin + validator), but the recording runs once, only when a PR is about
+ * to open — so it launches its own browser instead of reusing ReplayEngine's.
+ *
+ * GIF encoding is pure-JS (`gifenc` + `pngjs`), no ffmpeg, so it works for every
+ * `npm install aztrx-cli` user rather than only machines with ffmpeg on PATH.
+ */
+import type { Finding, RecordedAction } from "../types.js";
+export interface CaptureOptions {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Settle time after page load, before the first frame. */
+    settleMs?: number;
+    /** Settle time after each replayed action, before its screenshot. */
+    stepMs?: number;
+}
+/**
+ * Captures one PNG screenshot before the replay and one after each action, so
+ * the crash (or its absence) is visible in the sequence. Replays `replayActions`
+ * one action at a time — reusing the exact detection semantics, not a parallel
+ * reimplementation that could drift.
+ */
+export declare function captureReproFrames(url: string, actions: RecordedAction[], opts?: CaptureOptions): Promise<Buffer[]>;
+export interface GifOptions {
+    /** Frame delay in ms (default 400). */
+    delay?: number;
+    /** Quantized palette size, ≤ 256 (default 256). */
+    maxColors?: number;
+}
+/** Encodes a sequence of PNG frames into an animated GIF (pure JS, no ffmpeg). */
+export declare function encodeGif(frames: Buffer[], opts?: GifOptions): Buffer;
+/** The static "crash shot": the final frame, when the crash has fully rendered. */
+export declare function crashFrame(frames: Buffer[]): Buffer;
+/**
+ * Produces the recorded-repro GIF for a finding and writes it to
+ * `aztrx-media/<fp8>.gif`. That dir is deliberate: `media/` is in the npm
+ * `files` allowlist (so demo.gif/logo ship), but patrol GIFs must not publish —
+ * they're per-run artifacts. The path is committed to the PR branch so the PR
+ * body can inline it via a raw URL.
+ *
+ * Returns the repo-relative path, or null when there is nothing to record (no
+ * repro, or capture/encode failed) — the caller opens the PR regardless.
+ */
+export declare function recordFindingGif(repoRoot: string, url: string, finding: Finding): Promise<string | null>;

package/dist/core/patrol/state.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cross-run memory for `aztrx patrol`. Where `RunLog` is append-only and reset
+ * every run, this is a small index of "have I seen this fingerprint before, and
+ * what happened to it?" — the thing that stops an autonomous loop from re-fixing
+ * the same bug and re-opening the same PR on every cycle.
+ *
+ * Lives at `.aztrx/patrol.json` (already gitignored via `.aztrx/`). A fingerprint
+ * absent from the map is implicitly "new".
+ */
+export type FingerprintStatus = "pr-opened" | "unfixed";
+export interface FingerprintEntry {
+    status: FingerprintStatus;
+    firstSeen: string;
+    lastSeen: string;
+    prUrl?: string;
+    branch?: string;
+    attempts: number;
+}
+export declare class PatrolState {
+    private readonly file;
+    private readonly cooldownMs;
+    private data;
+    constructor(repoRoot: string, url: string, cooldownMs?: number);
+    private read;
+    /**
+     * A fingerprint is "handled" while its PR is open, or while an `unfixed` mark
+     * is still within its cooldown. Once the cooldown lapses, an `unfixed` bug
+     * becomes retry-eligible again — it stops being "handled" and `run()` heals it
+     * afresh rather than skipping it forever.
+     */
+    isHandled(fp: string, now?: number): boolean;
+    /** Every currently-handled fingerprint, so the supervisor can tell `run()` to skip healing them. */
+    handled(now?: number): string[];
+    markPr(fp: string, prUrl: string, branch: string): void;
+    markUnfixed(fp: string): void;
+    private firstSeen;
+    private attempts;
+    save(): void;
+}

package/dist/core/pr.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from "./types.js";
+export declare function renderPrComment(targetUrl: string, findings: Finding[]): string;
+export declare function writePrComment(repoRoot: string, targetUrl: string, findings: Finding[], filePath?: string): string;

package/dist/core/pr.js

@@ -9,12 +9,6 @@ import { sanitizeSecrets } from "./heal/redact.js";
  * shields.io badges, which GitHub renders natively.
  */
 const SEV_ORDER = ["crash", "error", "warning", "noise"];
-const SEV_BADGE = {
-    crash: "ff5a5f",
-    error: "ff5a5f",
-    warning: "f5a623",
-    noise: "5b6573",
-};
 /** Shields.io badge-path escaping: literal `-` → `--`, `/` → `%2F`, space → `_`. */
 function shield(s) {
     return s.replace(/-/g, "--").replace(/\//g, "%2F").replace(/ /g, "_");
@@ -44,6 +38,17 @@ function inlineCode(s) {
 function cleanInline(s) {
     return sanitizeSecrets(s).replace(/`/g, "").replace(/[\r\n]/g, " ");
 }
+/** Prose that lands in the comment body — a model-written explanation, an error
+ * string. Escaping the HTML keeps it inside the surrounding `<details>`;
+ * defusing the link/image syntax stops a crafted PR from having the bot render
+ * a tracking pixel or a phishing link under the consumer's token. Secrets are
+ * scrubbed for the same reason every other inlined string is: the model read
+ * the app's own source to write this, so it can quote a key back out. */
+function cleanProse(s) {
+    return escapeHtml(sanitizeSecrets(s))
+        .replace(/!\[/g, "!\\[")
+        .replace(/\]\(/g, "\\]\\(");
+}
 /** Hard cap on the server body inlined into a PR comment — a 500 page can be
  * huge, and only the first line or two are ever diagnostic. */
 const SERVER_BODY_CAP = 2000;
@@ -84,13 +89,13 @@ function healBlock(f) {
         body.push(fence(diff, "diff"));
     }
     else if (h.explanation) {
-        body.push(`> ${h.explanation}`);
+        body.push(`> ${cleanProse(h.explanation)}`);
     }
     if (h.test?.ran) {
         body.push(`**tests** ${inlineCode(h.test.command)} — ${h.test.ok ? "passed" : "failed"}`);
     }
     if (h.error)
-        body.push(`\n_${escapeHtml(h.error)}_`);
+        body.push(`\n_${cleanProse(h.error)}_`);
     return `\n<details>\n<summary>${badge("heal", meta.text, meta.color)} proposed patch${via}${tiers}</summary>\n\n${body.join("\n")}\n</details>`;
 }
 function reproBlock(f) {
@@ -122,8 +127,7 @@ function findingBlock(f) {
         : "";
     return `<details open>\n<summary><code>${escapeHtml(sev)}</code> — ${escapeHtml(first)}</summary>\n${loc}${snippet}${serverErr}${reproBlock(f)}${healBlock(f)}\n</details>`;
 }
-export function renderPrComment(targetUrl, findings, opts = {}) {
-    void opts;
+export function renderPrComment(targetUrl, findings) {
     const sorted = [...findings].sort((a, b) => SEV_ORDER.indexOf(a.severity) - SEV_ORDER.indexOf(b.severity));
     const counts = { crash: 0, error: 0, warning: 0, noise: 0 };
     for (const f of sorted)
@@ -160,6 +164,6 @@ ${body}
 export function writePrComment(repoRoot, targetUrl, findings, filePath) {
     const file = filePath ?? path.join(repoRoot, ".aztrx", "pr-comment.md");
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, renderPrComment(targetUrl, findings, { repoRoot }), "utf-8");
+    fs.writeFileSync(file, renderPrComment(targetUrl, findings), "utf-8");
     return file;
 }

package/dist/core/prompt.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A single yes/no confirmation for `--fix`. Kept tiny and side-effect free:
+ *
+ *   - `--yes` short-circuits to `true` (scripts/CI).
+ *   - a non-TTY stdout without `--yes` short-circuits to `false` — an unattended
+ *     run never mutates the working tree, it just leaves the `.patch` files.
+ *   - otherwise prompts on stdin, defaulting to "no".
+ */
+export interface PromptOptions {
+    yes?: boolean;
+}
+export declare function promptYesNo(question: string, opts?: PromptOptions): Promise<boolean>;
+/** A single-line text prompt. Returns "" when stdout isn't a TTY (unattended run). */
+export declare function promptInput(question: string): Promise<string>;

package/dist/core/recorder.d.ts

@@ -0,0 +1,23 @@
+import type { ElementHandle } from "playwright";
+import type { RecordedAction } from "./types.js";
+type AnyElement = SVGElement | HTMLElement;
+/**
+ * F2 — ring buffer of the last 25 actions. The Repro Minimizer (F7) later
+ * shrinks this history; for now it's the action context attached to findings.
+ */
+export declare class ActionRecorder {
+    private buffer;
+    readonly capacity = 25;
+    record(action: RecordedAction): void;
+    snapshot(): RecordedAction[];
+}
+/**
+ * Selector cascade, most-reliable first: data-testid → text → css path.
+ *
+ * Each `evaluate` is wrapped defensively: selector resolution is best-effort
+ * and must never take down a whole run if the page tears the node down
+ * mid-query or the browser rejects a serialized function. A failed probe just
+ * degrades to the next (weaker) selector in the cascade.
+ */
+export declare function selectorCascade(handle: ElementHandle<AnyElement>): Promise<string[]>;
+export {};

package/dist/core/recorder.js

@@ -22,7 +22,7 @@ export class ActionRecorder {
  * mid-query or the browser rejects a serialized function. A failed probe just
  * degrades to the next (weaker) selector in the cascade.
  */
-export async function selectorCascade(page, handle) {
+export async function selectorCascade(handle) {
     const out = [];
     try {
         const testId = await handle.evaluate((el) => {

package/dist/core/renderMarkdown.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Minimal Markdown → ANSI renderer for the `--explain` / `--fix` human-language
+ * summary. Handles the small dialect Aztrx emits: headings, bold/`code` inline,
+ * bullet and numbered lists, and fenced code blocks with a light JS/TS syntax
+ * highlight. Plain prose without markdown passes through unchanged.
+ */
+export declare function renderMarkdown(md: string): string;

package/dist/core/replay.d.ts

@@ -0,0 +1,33 @@
+import type { Page } from "playwright";
+import type { FindingType, RecordedAction } from "./types.js";
+export interface ReplayEngineOptions {
+    attachGuard?: (page: Page) => Promise<void>;
+    /** Playwright storage-state JSON (path or object) for authenticated replays. */
+    storageState?: string;
+}
+export interface ReplayResult {
+    reproduced: boolean;
+    /** Did the target page actually load? A navigation that was refused, timed out,
+     * or answered non-2xx produces no telemetry — which is indistinguishable from
+     * "the bug is gone" unless the caller can tell the two apart. Verification
+     * depends on this: an unreachable page must never count as a passing run. */
+    loaded: boolean;
+}
+/** Replays a recorded action sequence against a page. Best-effort: a selector
+ * that no longer resolves is skipped, not fatal. */
+export declare function replayActions(page: Page, actions: RecordedAction[]): Promise<void>;
+/**
+ * Reuses one browser across replays (ddmin + validator each run many). Each
+ * `run` gets a fresh page; the interceptor collects telemetry fingerprints and
+ * reports whether `targetFingerprint` was seen.
+ */
+export declare class ReplayEngine {
+    private opts;
+    private browser;
+    constructor(opts?: ReplayEngineOptions);
+    private getBrowser;
+    run(url: string, actions: RecordedAction[], targetFingerprint: string, opts?: {
+        targetType?: FindingType;
+    }): Promise<ReplayResult>;
+    close(): Promise<void>;
+}