aztrx-cli 0.4.3 → 0.4.4

package/dist/core/httpFuzzer.js

@@ -90,7 +90,7 @@ function hostAllowed(url, allowHosts) {
     return false;
 }
 /** Harvest candidate endpoints the app actually uses — not blind probing. */
-async function collectEndpoints(page, origin) {
+async function collectEndpoints(page, origin, allowDestructive, seedUrls = []) {
     const seen = new Map();
     const push = (raw) => {
         let u;
@@ -104,11 +104,15 @@ async function collectEndpoints(page, origin) {
             return;
         if (STATIC_EXT.test(u.pathname))
             return;
-        if (DESTRUCTIVE_PATH.test(u.pathname))
+        if (!allowDestructive && DESTRUCTIVE_PATH.test(u.pathname))
             return;
         if (!seen.has(u.pathname))
             seen.set(u.pathname, u);
     };
+    // Endpoints observed live by the caller — e.g. a `fetch()` fired from a click
+    // handler that never appears in `performance` resources or the DOM.
+    for (const s of seedUrls)
+        push(s);
     // URLs the page already fetched (API calls, RSC/data endpoints).
     const resources = await page
         .evaluate(() => performance.getEntriesByType("resource").map((e) => e.name))
@@ -191,11 +195,11 @@ export async function httpFuzz(page, targetUrl, bus, opts = {}) {
     const allowHosts = opts.allowHosts ?? new Set();
     if (!hostAllowed(targetUrl, allowHosts))
         return 0;
-    if (!opts.dryRun) {
+    if (!opts.dryRun && opts.navigate !== false) {
         await page.goto(targetUrl, { waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => { });
         await page.waitForTimeout(500);
     }
-    const endpoints = await collectEndpoints(page, new URL(targetUrl).origin);
+    const endpoints = await collectEndpoints(page, new URL(targetUrl).origin, Boolean(opts.allowDestructive), opts.seedUrls ?? []);
     endpoints.sort((a, b) => a.pathname.localeCompare(b.pathname));
     let sent = 0;
     outer: for (const endpoint of endpoints) {

package/dist/core/orchestrator.js

@@ -3,6 +3,7 @@ import pc from "picocolors";
 import { VERSION } from "./version.js";
 import { EventBus } from "./eventBus.js";
 import { loadBaseline } from "./classifier.js";
+import { diagnoseFinding } from "./diagnose.js";
 import { attachNetworkGuard, allowHostsFrom } from "./networkGuard.js";
 import { swarmDetect } from "./swarm.js";
 import { ReplayEngine } from "./replay.js";
@@ -14,18 +15,23 @@ import { RunLog } from "./events.js";
 import { heal } from "./heal/index.js";
 import { submitTelemetry } from "./telemetry/index.js";
 import { submitRun } from "./cloud/index.js";
+import { formatDiff } from "./diff.js";
 const SEVERITY_MARK = {
     crash: pc.red("● crash "),
     error: pc.red("● error "),
     warning: pc.yellow("○ warning "),
     noise: pc.dim("○ noise "),
 };
-function printFinding(f, write) {
+function printFinding(f, write, lang) {
     write(SEVERITY_MARK[f.severity] + pc.bold(f.rawMessage));
     if (f.mappedLocation) {
         write(pc.dim(`   ${f.mappedLocation.filePath}:${f.mappedLocation.line}:${f.mappedLocation.column}`));
         write(pc.dim(f.mappedLocation.codeContext));
     }
+    // F14 — the one-line "why + fix" diagnosis, inline with every crash/error.
+    const dx = diagnoseFinding(f, lang);
+    if (dx)
+        write(pc.cyan(`   ↳ ${dx}`));
     if (f.serverError) {
         write(pc.dim(`   server: ${f.serverError.message}`));
     }
@@ -78,6 +84,10 @@ export async function run(options) {
         say(pc.dim(`Net:    deny-by-default → allow ${[...allowHosts].join(", ") || "origin"}`));
     if (options.storageState)
         say(pc.dim(`Auth:   ${options.storageState}`));
+    if (options.allowDestructive) {
+        say(pc.yellow(pc.bold("⚠ DESTRUCTIVE MODE — delete/pay/logout/checkout controls are ENABLED.")));
+        say(pc.yellow("  This can mutate real data. Run only against a disposable/dev instance you own."));
+    }
     say("");
     emitPhase("launch", url);
     const runLog = new RunLog(repoRoot);
@@ -85,10 +95,11 @@ export async function run(options) {
     runLog.append({ type: "run_start", url, ts: Date.now() });
     const baseline = await loadBaseline(repoRoot);
     const workers = options.workers ?? 1;
-    // F-swarm — parallel detection. One worker is the legacy pass; `--http-fuzz`
-    // or `workers > 1` fan out into a swarm. Findings come back merged by
+    // F-swarm — parallel detection. One worker is the legacy pass; `workers > 1`
+    // fans out into a swarm. `--http-fuzz` folds into the walk/fuzz pass as a
+    // post-pass on the same page (no extra worker). Findings come back merged by
     // fingerprint, with per-worker action history already attached.
-    if (workers > 1 || options.httpFuzz) {
+    if (workers > 1) {
         emitPhase("swarm", `${workers} worker(s)`);
     }
     else if (options.fuzz) {
@@ -105,6 +116,7 @@ export async function run(options) {
         fuzz: options.fuzz,
         httpFuzz: options.httpFuzz,
         httpFuzzMutations: options.httpFuzzMutations,
+        allowDestructive: options.allowDestructive,
         seed: options.seed ?? 42,
         workers,
         allowHosts,
@@ -125,7 +137,7 @@ export async function run(options) {
     for (const f of findings) {
         bus.emit("finding", f);
         runLog.append({ type: "finding", finding: f });
-        printFinding(f, say);
+        printFinding(f, say, options.lang);
     }
     if (workerCount > 1) {
         say(pc.dim(`\nSwarm: ${totalActions} action(s) across ${workerCount} worker(s) — ${roles.join(", ")}.\n`));
@@ -235,7 +247,9 @@ export async function run(options) {
             f.type !== "network_timeout" &&
             f.repro &&
             f.repro.verdict !== "unreliable");
-        const healTargets = reproducible.filter((f) => f.mappedLocation?.isOwnCode);
+        const skip = new Set(options.skipHealFingerprints ?? []);
+        const candidates = reproducible.filter((f) => !skip.has(f.fingerprint));
+        const healTargets = candidates.filter((f) => f.mappedLocation?.isOwnCode);
         if (healTargets.length) {
             say(pc.cyan("— Closed-loop healing (redact → generate → gate → sandbox → test → verify) —"));
             emitPhase("heal");
@@ -254,6 +268,7 @@ export async function run(options) {
                         testTimeoutMs: options.testTimeoutMs,
                         skipTest: options.skipTest,
                         startCommand: options.startCommand,
+                        budget: options.budget,
                     });
                     f.heal = result;
                     bus.emit("heal", {
@@ -273,8 +288,14 @@ export async function run(options) {
                         ? pc.green("  ✓ healed")
                         : result.status === "unfixed"
                             ? pc.yellow("  ◐ unfixed")
-                            : pc.red(`  ✗ ${result.status}`);
+                            : result.status === "budget-exhausted"
+                                ? pc.dim("  ⏹ budget exhausted")
+                                : pc.red(`  ✗ ${result.status}`);
                     say(`${mark}  ${pc.bold(f.rawMessage.split("\n")[0].slice(0, 60))}`);
+                    if (result.status === "healed" && result.hunks.length > 0) {
+                        say(pc.dim(`        ${result.filePath}`));
+                        say(formatDiff(result.hunks));
+                    }
                     if (result.patchPath)
                         say(pc.dim(`        patch: ${path.relative(repoRoot, result.patchPath)}`));
                     if (result.error)
@@ -295,13 +316,14 @@ export async function run(options) {
                 }
             }
         }
-        else if (reproducible.length > 0) {
+        else if (candidates.length > 0) {
             // Reproducible crashes, but none mapped to source (wrong --repo?) — tell the
-            // user rather than silently doing nothing.
-            say(pc.yellow(`Found ${reproducible.length} reproducible crash(es) but couldn't map them to source files. Run from your project root (or pass --repo <dir>) so --fix can read the code.`));
+            // user rather than silently doing nothing. Already-handled fingerprints are
+            // excluded above, so this only fires for genuinely new findings.
+            say(pc.yellow(`Found ${candidates.length} reproducible crash(es) but couldn't map them to source files. Run from your project root (or pass --repo <dir>) so --fix can read the code.`));
         }
     }
-    const reportPath = writeReport(repoRoot, url, findings);
+    const reportPath = writeReport(repoRoot, url, findings, options.lang);
     say(pc.dim(`Report: ${path.relative(repoRoot, reportPath)}`));
     const counts = {};
     for (const f of findings)

package/dist/core/patrol/loop.js

@@ -0,0 +1,218 @@
+/**
+ * `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.
+ */
+import pc from "picocolors";
+import { run } from "../orchestrator.js";
+import { applyVerifiedPatches } from "../heal/apply.js";
+import { PatrolState } from "./state.js";
+import { openPatrolPr, openPatrolBatchPr } from "./pr.js";
+import { recordFindingGif } from "./record.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Any HTTP response means the server is up; only a network failure is "down". */
+async function isAlive(url) {
+    try {
+        await fetch(url, { signal: AbortSignal.timeout(3000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function head(f) {
+    return f.rawMessage.split("\n")[0].slice(0, 50);
+}
+/** Best-effort GIF recording — a failed capture must never block a PR. */
+async function recordGif(repoRoot, url, f) {
+    try {
+        return await recordFindingGif(repoRoot, url, f);
+    }
+    catch (e) {
+        console.log(pc.dim(`  · recorded repro skipped: ${e.message}`));
+        return null;
+    }
+}
+export async function patrol(opts) {
+    const retryAfterMs = opts.retryAfterMs ?? 30 * 60 * 1000;
+    const state = new PatrolState(opts.repoRoot, opts.url, retryAfterMs);
+    const maxFixes = opts.maxFixes ?? 5;
+    let sessionFixes = 0;
+    let sessionPrs = 0;
+    const seenFp = new Set();
+    // One budget object is shared across every cycle so the cap spans the session,
+    // not just a single run.
+    const budget = opts.maxSpend && opts.maxSpend > 0 ? { remaining: opts.maxSpend } : undefined;
+    console.log(pc.cyan("Aztrx AI — patrol"));
+    console.log(pc.dim(`Target: ${opts.url}   interval: ${Math.round(opts.intervalMs / 1000)}s   max fixes/session: ${maxFixes}` +
+        `   retry unfixed after: ${Math.round(retryAfterMs / 1000)}s` +
+        (budget ? `   spend cap: ${budget.remaining} generations` : "")));
+    console.log("");
+    for (let cycle = 1;; cycle++) {
+        if (!(await isAlive(opts.url))) {
+            console.log(pc.dim(`[cycle ${cycle}] target not responding — skipping this pass.`));
+            if (opts.once)
+                break;
+            await sleep(opts.intervalMs);
+            continue;
+        }
+        console.log(pc.dim(`[cycle ${cycle}] scanning…`));
+        let findings;
+        try {
+            // `ui: true` silences the per-run console so patrol prints its own concise
+            // summary instead of the full pipeline log on every cycle.
+            findings = await run({
+                url: opts.url,
+                repoRoot: opts.repoRoot,
+                maxActions: opts.maxActions,
+                fuzz: opts.fuzz,
+                workers: opts.workers,
+                allowHosts: opts.allowHosts,
+                storageState: opts.storageState,
+                login: opts.login,
+                loginEmail: opts.loginEmail,
+                loginPassword: opts.loginPassword,
+                loginUrl: opts.loginUrl,
+                lang: opts.lang,
+                seed: opts.seed,
+                allowDestructive: opts.allowDestructive,
+                httpFuzz: opts.httpFuzz,
+                httpFuzzMutations: opts.httpFuzzMutations,
+                repro: true,
+                heal: true,
+                healModel: opts.healModel,
+                healFastModel: opts.healFastModel,
+                testCommand: opts.testCommand,
+                testTimeoutMs: opts.testTimeoutMs,
+                skipTest: opts.skipTest,
+                startCommand: opts.startCommand,
+                // Already-handled fingerprints from a prior cycle get skipped before heal,
+                // so a re-scan re-detects (to confirm they're still gone) without re-paying
+                // the LLM to re-fix them.
+                skipHealFingerprints: state.handled(),
+                budget,
+                ui: true,
+            });
+        }
+        catch (e) {
+            console.log(pc.red(`[cycle ${cycle}] run failed: ${e.message}`));
+            if (opts.once)
+                break;
+            await sleep(opts.intervalMs);
+            continue;
+        }
+        // "found" = distinct crash/error fingerprints ever seen this session.
+        for (const f of findings) {
+            if (f.severity === "crash" || f.severity === "error")
+                seenFp.add(f.fingerprint);
+        }
+        // Reproducible but not healed → mark unfixable so we don't re-burn the LLM on
+        // it every cycle; `PatrolState` backs off and retries it once the cooldown
+        // lapses. `budget-exhausted` / `no-llm` are NOT unfixable — they mean we never
+        // got a real attempt, so they must not be written into memory as "won't fix".
+        for (const f of findings) {
+            if ((f.severity === "crash" || f.severity === "error") &&
+                f.repro &&
+                f.heal &&
+                f.heal.status !== "healed" &&
+                f.heal.status !== "budget-exhausted" &&
+                f.heal.status !== "no-llm" &&
+                !state.isHandled(f.fingerprint)) {
+                state.markUnfixed(f.fingerprint);
+            }
+        }
+        const newHealed = findings.filter((f) => f.heal?.status === "healed" && !state.isHandled(f.fingerprint));
+        const toFix = newHealed.slice(0, Math.max(0, maxFixes - sessionFixes));
+        if (toFix.length === 0 && sessionFixes >= maxFixes && newHealed.length > 0) {
+            console.log(pc.yellow(`[cycle ${cycle}] reached max fixes (${maxFixes}) — no more this session.`));
+        }
+        if (opts.batch) {
+            // Batch: apply each patch, then open one PR carrying every fix that landed.
+            const landed = [];
+            const files = [];
+            for (const f of toFix) {
+                const applied = applyVerifiedPatches(opts.repoRoot, [f]);
+                if (applied.applied.length === 0) {
+                    state.markUnfixed(f.fingerprint);
+                    console.log(pc.yellow(`  ◐ ${head(f)} — apply conflict, marked unfixable.`));
+                    continue;
+                }
+                landed.push(f);
+                for (const a of applied.applied)
+                    files.push(a.filePath);
+            }
+            if (landed.length > 0) {
+                const mediaPaths = [];
+                for (const f of landed)
+                    mediaPaths.push(await recordGif(opts.repoRoot, opts.url, f));
+                const pr = await openPatrolBatchPr(opts.repoRoot, landed, opts.url, [...new Set(files)], mediaPaths);
+                if (pr.ok && pr.url) {
+                    sessionPrs++;
+                    sessionFixes += landed.length;
+                    for (const f of landed)
+                        state.markPr(f.fingerprint, pr.url, pr.branch ?? "");
+                    console.log(pc.green(`  ✓ batch PR opened ${pr.url} — ${landed.length} fix(es)`));
+                }
+                else if (pr.skipped) {
+                    for (const f of landed)
+                        state.markPr(f.fingerprint, "existing", pr.branch ?? "");
+                    console.log(pc.dim(`  — batch PR already exists (${pr.branch})`));
+                }
+                else {
+                    for (const f of landed)
+                        state.markUnfixed(f.fingerprint);
+                    console.log(pc.red(`  ✗ batch PR failed: ${pr.error}`));
+                }
+            }
+        }
+        else {
+            for (const f of toFix) {
+                const applied = applyVerifiedPatches(opts.repoRoot, [f]);
+                if (applied.applied.length === 0) {
+                    state.markUnfixed(f.fingerprint);
+                    console.log(pc.yellow(`  ◐ ${head(f)} — apply conflict, marked unfixable.`));
+                    continue;
+                }
+                const files = applied.applied.map((a) => a.filePath);
+                const mediaPath = await recordGif(opts.repoRoot, opts.url, f);
+                const pr = await openPatrolPr(opts.repoRoot, f, opts.url, files, mediaPath);
+                if (pr.ok && pr.url) {
+                    sessionPrs++;
+                    sessionFixes++;
+                    state.markPr(f.fingerprint, pr.url, pr.branch ?? "");
+                    console.log(pc.green(`  ✓ PR opened ${pr.url} — ${head(f)}`));
+                }
+                else if (pr.skipped) {
+                    state.markPr(f.fingerprint, "existing", pr.branch ?? "");
+                    console.log(pc.dim(`  — already has a PR (${pr.branch})`));
+                }
+                else {
+                    state.markUnfixed(f.fingerprint);
+                    console.log(pc.red(`  ✗ PR failed: ${pr.error}`));
+                }
+            }
+        }
+        // Rolling status — the "found / fixed / PRs" tally that makes the loop read
+        // as alive rather than a stream of isolated lines.
+        console.log(pc.dim(`[cycle ${cycle}] found ${seenFp.size} · fixed ${sessionFixes} · PRs ${sessionPrs}` +
+            (newHealed.length === 0 ? " · nothing new to fix" : "")));
+        // Once the session's paid budget is spent there's nothing left to fix — stop
+        // rather than silently re-detecting without healing.
+        if (budget && budget.remaining <= 0) {
+            console.log(pc.yellow(`\nSpend budget exhausted — ${sessionPrs} PR(s) opened this session.`));
+            break;
+        }
+        state.save();
+        if (opts.once)
+            break;
+        await sleep(opts.intervalMs);
+    }
+    console.log(pc.cyan(`patrol session done — found ${seenFp.size} bug(s) · fixed ${sessionFixes} · PRs ${sessionPrs}`));
+}

package/dist/core/patrol/pr.js

@@ -0,0 +1,233 @@
+/**
+ * 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 { execFile } from "child_process";
+import { promisify } from "util";
+import { createHash } from "crypto";
+import { diagnoseFinding } from "../diagnose.js";
+import { sanitizeSecrets } from "../heal/redact.js";
+const exec = promisify(execFile);
+export function branchFor(fp) {
+    return `aztrx/fix-${fp.slice(0, 8)}`;
+}
+/** 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 function branchForSet(fps) {
+    const h = createHash("sha1").update([...fps].sort().join("\n")).digest("hex").slice(0, 8);
+    return `aztrx/fix-batch-${h}`;
+}
+function headTitle(f) {
+    return f.rawMessage.split("\n")[0].slice(0, 60);
+}
+/** 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 function isLocalUrl(url) {
+    try {
+        const host = new URL(url).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+        if (host === "localhost" || host === "::1" || host === "::" || host === "0.0.0.0")
+            return true;
+        if (host.endsWith(".local") || host.endsWith(".internal") || host.endsWith(".localhost")) {
+            return true;
+        }
+        const octets = host.split(".");
+        if (octets.length === 4 && octets.every((o) => /^\d{1,3}$/.test(o) && Number(o) <= 255)) {
+            const [a, b] = octets.map(Number);
+            if (a === 10)
+                return true; // 10.0.0.0/8
+            if (a === 172 && b >= 16 && b <= 31)
+                return true; // 172.16.0.0/12
+            if (a === 192 && b === 168)
+                return true; // 192.168.0.0/16
+            if (a === 127)
+                return true; // 127.0.0.0/8
+            if (a === 169 && b === 254)
+                return true; // 169.254.0.0/16 link-local
+            return false;
+        }
+        return false;
+    }
+    catch {
+        return true; // unparseable target → assume local, don't scare-monger
+    }
+}
+/** Per-finding "before/after" narrative: the crash ("before"), a one-line *why*
+ * from the deterministic diagnosis, and the healed fix explanation ("after").
+ * Plain words rather than a stack trace, so a reviewer who never ran the scan
+ * still understands the PR at a glance. Untrusted text is secret-scrubbed. */
+function findingBlock(f, i) {
+    const head = sanitizeSecrets(f.rawMessage.split("\n")[0].trim());
+    const loc = f.mappedLocation
+        ? `\`${f.mappedLocation.filePath}:${f.mappedLocation.line}\``
+        : "unknown location";
+    const why = diagnoseFinding(f);
+    const fix = f.heal?.status === "healed" && f.heal.explanation
+        ? sanitizeSecrets(f.heal.explanation.trim())
+        : "";
+    const repro = f.repro?.verdict
+        ? `_repro: ${f.repro.verdict} ${f.repro.reproductions}/${f.repro.runs}_`
+        : "";
+    const lines = [`### ${i}. ${head.length > 96 ? head.slice(0, 93) + "…" : head}`];
+    lines.push(`- **Where:** ${loc}`);
+    if (why)
+        lines.push(`- **Why:** ${why}`);
+    if (fix)
+        lines.push(`- **The fix:** ${fix.length > 400 ? fix.slice(0, 397) + "…" : fix}`);
+    if (repro)
+        lines.push(`- ${repro}`);
+    return lines.join("\n");
+}
+const PROD_BANNER = "> ⚠️ **This crash is live in production right now** — the target isn't a local dev server.";
+const VERIFIED_NOTE = "Verified: AST-gated, compiled, run against the test suite, and replayed against the repro before this PR. Opened automatically by `aztrx patrol`.";
+async function hasOpenPr(repoRoot, branch) {
+    try {
+        const { stdout } = await exec("gh", ["pr", "list", "--head", branch, "--state", "open", "--json", "number"], { cwd: repoRoot });
+        const list = JSON.parse(stdout || "[]");
+        return Array.isArray(list) && list.length > 0;
+    }
+    catch {
+        // gh missing / unauthenticated — surface on the create step instead.
+        return false;
+    }
+}
+async function currentBranch(repoRoot) {
+    try {
+        const { stdout } = await exec("git", ["-C", repoRoot, "rev-parse", "--abbrev-ref", "HEAD"]);
+        return stdout.trim() || "main";
+    }
+    catch {
+        return "main";
+    }
+}
+async function safeCheckout(repoRoot, branch) {
+    await exec("git", ["-C", repoRoot, "checkout", branch]).catch(() => { });
+}
+/**
+ * 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 function githubRawUrl(remote, branch, repoPath) {
+    const m = /github\.com[:/]([^/]+)\/([^/\s]+?)(?:\.git)?$/.exec(remote.trim());
+    if (!m)
+        return "";
+    return `https://github.com/${m[1]}/${m[2]}/raw/${branch}/${repoPath}`;
+}
+/**
+ * Reads the `origin` remote and delegates to {@link githubRawUrl}. Returns "" when
+ * `git` is missing or the remote isn't GitHub — the media is still committed to
+ * the branch, just not inlined.
+ */
+async function rawUrlFor(repoRoot, branch, repoPath) {
+    try {
+        const { stdout } = await exec("git", ["-C", repoRoot, "remote", "get-url", "origin"]);
+        return githubRawUrl(stdout, branch, repoPath);
+    }
+    catch {
+        return "";
+    }
+}
+/** Shared git plumbing: (re)create the branch at HEAD, stage only the touched
+ * 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) {
+    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, "commit", "-m", title]);
+    }
+    catch (e) {
+        await safeCheckout(repoRoot, originalBranch);
+        return { ok: false, branch, error: `git failed: ${e.message}` };
+    }
+    try {
+        const { stdout } = await exec("gh", ["pr", "create", "--title", title, "--body", body], {
+            cwd: repoRoot,
+        });
+        await safeCheckout(repoRoot, originalBranch);
+        return { ok: true, branch, url: stdout.trim() };
+    }
+    catch (e) {
+        await safeCheckout(repoRoot, originalBranch);
+        return {
+            ok: false,
+            branch,
+            error: `gh pr create failed (is gh installed and authenticated?): ${e.message}`,
+        };
+    }
+}
+export async function openPatrolPr(repoRoot, finding, url, files, mediaPath) {
+    const branch = branchFor(finding.fingerprint);
+    if (await hasOpenPr(repoRoot, branch)) {
+        return { ok: false, skipped: true, branch, error: "PR already open for this finding" };
+    }
+    const mediaBody = mediaPath ? await rawUrlFor(repoRoot, branch, mediaPath) : "";
+    const block = findingBlock(finding, 1);
+    const body = [
+        "## Aztrx AI — autonomous fix",
+        "",
+        ...(isLocalUrl(url) ? [] : [PROD_BANNER, ""]),
+        `Found against ${url}:`,
+        "",
+        mediaBody ? `${block}\n\n![Recorded repro](${mediaBody})` : block,
+        "",
+        VERIFIED_NOTE,
+    ].join("\n");
+    return createPr(repoRoot, branch, `fix: ${headTitle(finding)}`, body, mediaPath ? [...files, mediaPath] : files);
+}
+/** 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 async function openPatrolBatchPr(repoRoot, findings, url, files, mediaPaths) {
+    const branch = branchForSet(findings.map((f) => f.fingerprint));
+    if (await hasOpenPr(repoRoot, branch)) {
+        return { ok: false, skipped: true, branch, error: "batch PR already open" };
+    }
+    const n = findings.length;
+    // Resolve each finding's media to a raw URL ("" when absent / non-GitHub), kept
+    // parallel to `findings` so each inline image lands under its own bug's block.
+    const mediaBodies = [];
+    for (let i = 0; i < findings.length; i++) {
+        const mp = mediaPaths?.[i];
+        mediaBodies.push(mp ? await rawUrlFor(repoRoot, branch, mp) : "");
+    }
+    const blocks = findings.map((f, i) => {
+        const block = findingBlock(f, i + 1);
+        return mediaBodies[i] ? `${block}\n\n![Recorded repro](${mediaBodies[i]})` : block;
+    });
+    const body = [
+        "## Aztrx AI — autonomous fix (batch)",
+        "",
+        ...(isLocalUrl(url) ? [] : [PROD_BANNER, ""]),
+        `Found ${n} bug${n === 1 ? "" : "s"} against ${url}:`,
+        "",
+        blocks.join("\n\n"),
+        "",
+        VERIFIED_NOTE,
+    ].join("\n");
+    const staged = mediaPaths
+        ? [...files, ...mediaPaths.filter((p) => !!p)]
+        : files;
+    const title = `fix: ${n} bug${n === 1 ? "" : "s"} (${headTitle(findings[0])})`;
+    return createPr(repoRoot, branch, title, body, staged);
+}