aztrx-cli 0.4.4 → 0.5.1

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

@@ -0,0 +1,54 @@
+/**
+ * F10 gate #3 — isolated Git worktree sandbox. A patch is never applied to the
+ * user's working tree: it lands in a detached `git worktree`, is verified there,
+ * and the only artifact that escapes is a `.patch` file for a human to review
+ * and apply. Aztrx never commits — humans do.
+ */
+import type { PatchHunk, TestGateResult } from "./types.js";
+export interface Worktree {
+    dir: string;
+    cleanup: () => Promise<void>;
+}
+export interface ApplyResult {
+    ok: boolean;
+    patched: string;
+    applied: number;
+    errors: string[];
+}
+/** Create a detached worktree at HEAD in a temp dir (outside the repo). */
+export declare function createWorktree(repoRoot: string, label: string): Promise<Worktree>;
+/** Apply Search & Replace hunks to an in-memory file. Each `search` must match
+ * exactly once; ambiguous or missing matches fail the whole apply (no partial
+ * writes). Pure — the caller decides where the result lands. */
+export declare function applyHunks(content: string, hunks: PatchHunk[]): ApplyResult;
+/** Write the patched file into the worktree, refusing to escape it. */
+export declare function writeWorktreeFile(worktreeDir: string, repoRelativePath: string, content: string): string | null;
+/** Produce a unified diff of the patched file against HEAD in the worktree. */
+export declare function diffWorktree(worktreeDir: string, repoRelativePath: string): Promise<string>;
+/** Run `tsc --noEmit` against the patched worktree — the full type check that
+ * follows the AST syntax gate. Best-effort: passes (skips) when the repo has no
+ * TypeScript or the worktree has no tsconfig, so non-TS projects aren't blocked.
+ * The worktree has no node_modules; a symlink to the root's is created first and
+ * removed with the worktree on cleanup.
+ *
+ * Unlike every other gate here, this one is whole-project work: `tsc` type-checks
+ * the entire repository, so its cost scales with the repo, and on a very large
+ * one it is minutes. It therefore carries a ceiling — and a timeout is reported
+ * as *skipped*, not failed. "The compiler never reached a verdict" is a different
+ * sentence from "the patch is broken", and conflating them would silently discard
+ * good fixes on exactly the large repos this ceiling exists to protect. */
+export declare function typecheckWorktree(worktreeDir: string, repoRoot: string, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    ran: boolean;
+    output: string;
+}>;
+/** Run the repo's own test suite inside the patched worktree. Best-effort: skips
+ * (passes by omission) when there is no `test` script to run, so untested or
+ * non-JS projects are never blocked. `CI=true` is set so watch-mode runners exit
+ * instead of hanging until the timeout. */
+export declare function runTests(worktreeDir: string, repoRoot: string, opts?: {
+    command?: string;
+    timeoutMs?: number;
+}): Promise<TestGateResult>;

package/dist/core/heal/sandbox.js

@@ -76,8 +76,15 @@ export async function diffWorktree(worktreeDir, repoRelativePath) {
  * follows the AST syntax gate. Best-effort: passes (skips) when the repo has no
  * TypeScript or the worktree has no tsconfig, so non-TS projects aren't blocked.
  * The worktree has no node_modules; a symlink to the root's is created first and
- * removed with the worktree on cleanup. */
-export async function typecheckWorktree(worktreeDir, repoRoot) {
+ * removed with the worktree on cleanup.
+ *
+ * Unlike every other gate here, this one is whole-project work: `tsc` type-checks
+ * the entire repository, so its cost scales with the repo, and on a very large
+ * one it is minutes. It therefore carries a ceiling — and a timeout is reported
+ * as *skipped*, not failed. "The compiler never reached a verdict" is a different
+ * sentence from "the patch is broken", and conflating them would silently discard
+ * good fixes on exactly the large repos this ceiling exists to protect. */
+export async function typecheckWorktree(worktreeDir, repoRoot, opts = {}) {
     const tscBin = path.join(repoRoot, "node_modules", "typescript", "bin", "tsc");
     const hasTsconfig = fs.existsSync(path.join(worktreeDir, "tsconfig.json"));
     if (!fs.existsSync(tscBin) || !hasTsconfig) {
@@ -93,12 +100,22 @@ export async function typecheckWorktree(worktreeDir, repoRoot) {
             /* symlink failed — tsc reports its own resolution errors below */
         }
     }
+    const timeoutMs = opts.timeoutMs ?? 300000;
     try {
-        const { stdout } = await execFileP(process.execPath, [tscBin, "--noEmit", "-p", worktreeDir], { cwd: worktreeDir, maxBuffer: 10 * 1024 * 1024, env: buildChildEnv() });
+        const { stdout } = await execFileP(process.execPath, [tscBin, "--noEmit", "-p", worktreeDir], { cwd: worktreeDir, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, env: buildChildEnv() });
         return { ok: true, ran: true, output: stdout.trim() };
     }
     catch (e) {
         const err = e;
+        // A timeout kills the child; that is not a compile error. Skip the gate and
+        // say why, rather than reporting a verdict the compiler never gave.
+        if (err.killed || err.signal) {
+            return {
+                ok: true,
+                ran: false,
+                output: `tsc did not finish within ${timeoutMs}ms — type check skipped`,
+            };
+        }
         return { ok: false, ran: true, output: ((err.stdout ?? "") + (err.stderr ?? "")).trim() };
     }
 }

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

@@ -0,0 +1,102 @@
+import type { Finding, RecordedAction } from "../types.js";
+export type HealStatus = "healed" | "unfixed" | "rejected" | "compile-failed" | "apply-failed" | "test-failed" | "skipped" | "no-llm" | "budget-exhausted";
+/** One Search & Replace edit. `search` is an exact, unique substring of the
+ * source file; `replace` is its replacement. */
+export interface PatchHunk {
+    search: string;
+    replace: string;
+}
+export interface Patch {
+    explanation: string;
+    hunks: PatchHunk[];
+}
+export interface GateViolation {
+    rule: string;
+    detail: string;
+}
+export interface GateResult {
+    ok: boolean;
+    violations: GateViolation[];
+}
+/** Context handed to the patch generator. `redactedContent` is what may leave
+ * the machine; `fileContent` is the raw bytes used for applying the edit. */
+export interface HealContext {
+    finding: Finding;
+    filePath: string;
+    fileContent: string;
+    redactedContent: string;
+}
+/** Shared, mutable cap on paid LLM generations across a whole patrol session.
+ * `generatePatch` decrements `remaining` each time it pays for a completion; once
+ * it hits 0 generation stops and heal reports `budget-exhausted`. The free
+ * rule-based fixer never touches it. One object is threaded through every
+ * `run()`/`heal()` of a session so the cap spans cycles, not just one run. */
+export interface SpendBudget {
+    remaining: number;
+}
+export interface VerifyResult {
+    runs: number;
+    reproductions: number;
+    /** Of `runs`, how many actually loaded the app. `fixed` requires this to be
+     * non-zero: a run whose page never loaded proves nothing, and counting it as a
+     * non-reproduction is how a patch gets declared verified without being tried. */
+    loaded: number;
+    fixed: boolean;
+}
+export interface TestGateResult {
+    /** False when there was no test script to run — the gate passes by omission. */
+    ran: boolean;
+    ok: boolean;
+    command: string;
+    /** Tail of the test output, already truncated. */
+    output: string;
+}
+export interface HealOptions {
+    repoRoot: string;
+    url: string;
+    /** Minimized repro actions (F7 output). */
+    actions: RecordedAction[];
+    fingerprint: string;
+    allowHosts: string[];
+    /** Fallback model (the last tier tried). Defaults to `claude-sonnet-5`. */
+    model?: string;
+    /** Fast/cheap first tier. Defaults to `claude-haiku-4-5` (`AZTRX_FAST_MODEL`). */
+    fastModel?: string;
+    /** Inject a patch generator for testing/demo (bypasses the network LLM). */
+    patchFn?: (ctx: HealContext) => Promise<Patch>;
+    /** Shared session budget for paid generations (see `SpendBudget`). */
+    budget?: SpendBudget;
+    /** Inject an app server for the patched code. Default: static file server. */
+    serve?: (worktreeDir: string, filePath: string) => Promise<{
+        url: string;
+        close: () => Promise<void>;
+    }>;
+    /** How to boot the patched app for server (network_5xx) findings. Auto-detected
+     * from package.json `scripts.dev` / `scripts.start` when omitted. */
+    startCommand?: string;
+    verifyRuns?: number;
+    /** Override the test command run against a healed patch (default: `npm test`,
+     * auto-detected from package.json). */
+    testCommand?: string;
+    /** Timeout for the test gate, ms (default 300000). */
+    testTimeoutMs?: number;
+    /** Skip the test gate entirely. */
+    skipTest?: boolean;
+}
+export interface HealResult {
+    status: HealStatus;
+    findingId: string;
+    filePath: string;
+    explanation?: string;
+    hunks: PatchHunk[];
+    violations: GateViolation[];
+    verification?: VerifyResult;
+    test?: TestGateResult;
+    /** Path to the saved unified-diff patch artifact (.aztrx/heal/…, gitignored). */
+    patchPath?: string;
+    error?: string;
+    /** Model that produced the returned patch (the winning tier). */
+    model?: string;
+    /** All tiers attempted, in order, for observability in the PR bot. */
+    tiers?: string[];
+}

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

@@ -0,0 +1,37 @@
+/**
+ * F10 — automated verification. Reuses the repro engine (F9) but inverts the
+ * question: the bug must *stop* reproducing against the patched code. If the
+ * fingerprint is still seen after the fix, the loop rejects the patch rather
+ * than handing the human a lie.
+ */
+import type { ReplayResult } from "../replay.js";
+import type { FindingType, RecordedAction } from "../types.js";
+import type { VerifyResult } from "./types.js";
+/** The slice of the replay engine verification depends on. Production passes a
+ * real browser-backed `ReplayEngine`; tests inject a stub so the pass/fail logic
+ * is exercised without launching Chromium. */
+export interface Verifier {
+    run(url: string, actions: RecordedAction[], targetFingerprint: string, opts?: {
+        targetType?: FindingType;
+    }): Promise<ReplayResult>;
+    close(): Promise<void>;
+}
+export interface VerifyOptions {
+    /** The URL the finding was recorded against. Retained for callers/reporting;
+     * replays run against the served URL, never this origin. */
+    url: string;
+    actions: RecordedAction[];
+    fingerprint: string;
+    runs?: number;
+    /** Start the patched app and return its URL + a close hook. */
+    serve: () => Promise<{
+        url: string;
+        close: () => Promise<void>;
+    }>;
+    /** For network findings: verify by signal type (origin-agnostic) instead of the
+     * exact fingerprint. */
+    targetType?: FindingType;
+    /** Replay engine override — tests only. Defaults to a real browser-backed one. */
+    engine?: Verifier;
+}
+export declare function verifyFix(opts: VerifyOptions): Promise<VerifyResult>;

package/dist/core/heal/verify.js

@@ -23,29 +23,43 @@ function rewriteOrigin(raw, serveUrl) {
 }
 export async function verifyFix(opts) {
     const { url: serveUrl, close } = await opts.serve();
-    const engine = new ReplayEngine();
+    const engine = opts.engine ?? new ReplayEngine();
     try {
-        const runs = opts.runs ?? 3;
+        // Never zero. `fixed` is derived from the reproduction count, so a caller that
+        // asks for 0 runs would otherwise get "fixed: true" out of *no attempts at
+        // all* — a patch declared verified on the strength of never having been run.
+        const runs = Math.max(1, Math.trunc(opts.runs ?? 3));
         let reproductions = 0;
-        const actions = opts.targetType
-            ? opts.actions.map((a) => {
-                if (a.type === "request" && a.request) {
-                    return { ...a, request: { ...a.request, url: rewriteOrigin(a.request.url, serveUrl) } };
-                }
-                if (a.type === "navigate" && a.value) {
-                    return { ...a, value: rewriteOrigin(a.value, serveUrl) };
-                }
-                return a;
-            })
-            : opts.actions;
+        let loaded = 0;
+        // Every recorded URL is rewritten to the served origin — for client findings
+        // too, not just network ones. The repro was recorded against the original
+        // app, so a `navigate` action left as-is would send the replay straight back
+        // to the *unpatched* server, where the bug reproduces no matter what the
+        // patch says. That reads as "unfixed" at best; when the fingerprint happens
+        // to be absent there, it reads as a verified fix that was never exercised.
+        const actions = opts.actions.map((a) => {
+            if (a.type === "request" && a.request) {
+                return { ...a, request: { ...a.request, url: rewriteOrigin(a.request.url, serveUrl) } };
+            }
+            if (a.type === "navigate" && a.value) {
+                return { ...a, value: rewriteOrigin(a.value, serveUrl) };
+            }
+            return a;
+        });
         for (let i = 0; i < runs; i++) {
             const res = opts.targetType
                 ? await engine.run(serveUrl, actions, opts.fingerprint, { targetType: opts.targetType })
                 : await engine.run(serveUrl, actions, opts.fingerprint);
+            if (res.loaded)
+                loaded += 1;
             if (res.reproduced)
                 reproductions += 1;
         }
-        return { runs, reproductions, fixed: reproductions === 0 };
+        // "Did not reproduce" only means "fixed" if the app was actually there to
+        // reproduce against. If no run loaded, this verification proved nothing about
+        // the patch — so it must not report success, or the caller writes an
+        // unverified patch into the user's working tree on the strength of it.
+        return { runs, reproductions, loaded, fixed: loaded > 0 && reproductions === 0 };
     }
     finally {
         await engine.close();

package/dist/core/httpFuzzer.d.ts

@@ -0,0 +1,33 @@
+import type { Page } from "playwright";
+import type { EventBus } from "./eventBus.js";
+export interface HttpFuzzOptions {
+    maxRequests?: number;
+    dryRun?: boolean;
+    /** Hostnames the fuzzer may target — the Node-side self-enforcement of the
+     * deny-by-default policy (the browser `networkGuard` only wraps the `Page`). */
+    allowHosts?: Set<string>;
+    /** Opt-in for POST/PUT body mutations. Default false: the fuzzer sends only
+     * GET requests (query mutations + hostile GET headers), which can't mutate
+     * server state. Set this to also probe JSON-body type-confusion and method
+     * confusion — only on endpoints you own and trust to be non-destructive. */
+    mutations?: boolean;
+    /** Opt-in: also probe endpoints the deny-list skips (delete/pay/logout/…).
+     * Off by default — these can mutate real state. */
+    allowDestructive?: boolean;
+    /** Endpoints observed live during a walk/fuzz pass (e.g. a `fetch()` fired
+     * from a click handler) that `collectEndpoints` can't see on a fresh page.
+     * Each is pushed through the same origin/static/destructive filters. */
+    seedUrls?: string[];
+    /** When false, skip the `page.goto` — the page is already loaded and
+     * positioned by the caller (folded post-walk pass). Default true. */
+    navigate?: boolean;
+}
+/**
+ * F5-http — server-side mutation fuzzer. Harvests the endpoints the app really
+ * uses, then throws seeded hostile requests at them (query overflow, JSON type
+ * confusion, header injection, method confusion). A response `status >= 500`
+ * becomes a `network_5xx` finding — same type and message format the interceptor
+ * emits for in-browser requests — so it flows through the existing
+ * ddmin → spec → validate → heal pipeline unchanged.
+ */
+export declare function httpFuzz(page: Page, targetUrl: string, bus: EventBus, opts?: HttpFuzzOptions): Promise<number>;

package/dist/core/init.d.ts

@@ -0,0 +1,21 @@
+export interface InitOptions {
+    repoRoot: string;
+    url?: string;
+    framework?: string;
+}
+export interface InitResult {
+    framework: string;
+    url: string;
+    configPath: string;
+    gitignoreUpdated: boolean;
+}
+export interface FrameworkMeta {
+    framework: string;
+    version?: string;
+}
+/** Detect the framework name plus its installed version range. */
+export declare function detectFrameworkMeta(repoRoot: string): FrameworkMeta;
+/** The port a framework's dev server listens on by default. */
+export declare function defaultPort(framework: string): number;
+/** `aztrx-cli init` — detect framework + port, scaffold aztrx.config.ts, seed .gitignore. */
+export declare function initProject(opts: InitOptions): Promise<InitResult>;

package/dist/core/init.js

@@ -31,7 +31,8 @@ export function detectFrameworkMeta(repoRoot) {
 function detectFramework(repoRoot) {
     return detectFrameworkMeta(repoRoot).framework;
 }
-function defaultPort(framework) {
+/** The port a framework's dev server listens on by default. */
+export function defaultPort(framework) {
     if (["Vite", "Svelte", "SvelteKit", "Vue", "Astro"].includes(framework))
         return 5173;
     return 3000;
@@ -44,13 +45,11 @@ export default {
   // Dev server Aztrx should attack.
   url: ${JSON.stringify(url)},
 
-  // Repo root for sourcemap → source resolution (defaults to this directory).
-  repo: ".",
-
-  // Max interactions per pass.
+  // Max interactions per pass (default: 100). --max-actions overrides this.
   maxActions: 100,
 
-  // Deny-by-default network allow-list for fuzz runs — add your API host here.
+  // Deny-by-default network allow-list — add your API host here, or every
+  // cross-origin request the app makes is refused. --allow-host adds to this.
   allowHosts: [],
 };
 `;

package/dist/core/interceptor.d.ts

@@ -0,0 +1,21 @@
+import type { Page } from "playwright";
+import type { EventBus } from "./eventBus.js";
+/**
+ * Canonical 5xx finding message. Shared by the interceptor (passive in-browser
+ * capture) and the HTTP mutation fuzzer (active Node-side capture) so the two
+ * produce byte-identical `rawMessage`s — otherwise a finding's fingerprint and
+ * its replay fingerprint would diverge and repro would never match.
+ */
+export declare function network5xxMessage(status: number, url: string): string;
+/**
+ * F1 — CDP interceptor. Attaches capture to a page and emits typed
+ * `telemetry` events on the bus. No framework hooks: works on React
+ * (17/18/19), Next.js, Vite, Svelte, Remix, and Vue alike.
+ *
+ * The subtle part: `console.error` is the ONLY runtime-level way to see
+ * errors a React Error Boundary swallows, because the boundary logs them
+ * there instead of rethrowing — so `window.onerror` / `pageerror` never fire
+ * for them. We pull the real throw-site stack off the Error *object* via
+ * `msg.args()`, not `msg.text()` (which is just the message, no stack).
+ */
+export declare function attachInterceptor(page: Page, bus: EventBus): void;

package/dist/core/llm.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Provider-agnostic LLM client. Two transports behind one `complete()`:
+ *
+ *   - Anthropic Messages API (default) — key from `ANTHROPIC_API_KEY` (or
+ *     `AZTRX_API_KEY`), primary model defaults to `claude-sonnet-5`.
+ *   - Any OpenAI-compatible `/chat/completions` endpoint — selected by setting
+ *     `AZTRX_API_BASE`. That single flag unlocks OpenAI, Grok, DeepSeek, Gemini,
+ *     Kimi, Mistral, OpenRouter, and local models (Ollama / vLLM / LM Studio)
+ *     with their existing keys.
+ *
+ * `AZTRX_MODEL` / `AZTRX_FAST_MODEL` pick the model(s); they default sensibly
+ * for Anthropic and must be set explicitly when a custom base URL is used.
+ */
+export type Provider = "anthropic" | "openai";
+export interface LlmSettings {
+    provider: Provider;
+    apiKey?: string;
+    baseUrl?: string;
+}
+/** Resolve the active provider from the environment. */
+export declare function resolveSettings(): LlmSettings;
+/** Is any provider configured? Used to decide whether to attempt an LLM call. */
+export declare function hasLlmKey(): boolean;
+/** The primary model for the active provider. */
+export declare function primaryModel(): string;
+/** The cheap/fast first tier, or undefined when the provider has none. */
+export declare function fastModel(): string | undefined;
+export interface CompleteOptions {
+    system: string;
+    prompt: string;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+/** Run one completion against the active provider and return the text. */
+export declare function complete(opts: CompleteOptions): Promise<string>;

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).

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[]>;