aztrx-cli 0.1.0 → 0.1.1

package/README.md

@@ -1,21 +1,21 @@
-# ⚡ Aztrx
+# <img src="media/logo.svg" width="28" height="32" alt="Aztrx logo" align="absmiddle" /> Aztrx AI
 
 > **Autonomous runtime stress-tester, deterministic bug minimizer, and self-healing engine for web applications.**
 
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg?style=flat-square)](https://nodejs.org)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
 
-Aztrx drives your web app like a hostile user — clicking, entering boundary data, and racing asynchronous UI states. When a runtime crash occurs (even one swallowed by a React Error Boundary), Aztrx intercepts it via the Chrome DevTools Protocol, maps it back to the exact source line, shrinks the interaction trace to the bare minimum with **ddmin**, and emits an executable, standalone **Playwright test** that proves the bug — not a log line.
+Aztrx AI drives your web app like a hostile user — clicking, entering boundary data, and racing asynchronous UI states. When a runtime crash occurs (even one swallowed by a React Error Boundary), Aztrx AI intercepts it via the Chrome DevTools Protocol, maps it back to the exact source line, shrinks the interaction trace to the bare minimum with **ddmin**, and emits an executable, standalone **Playwright test** that proves the bug — not a log line.
 
 ![aztrx demo](media/demo.gif)
 
 ---
 
-## Why Aztrx
+## Why Aztrx AI
 
-- **Sees swallowed errors.** Error Boundaries and `window.onerror` miss the errors your app *catches*. Aztrx reads the real throw-site stack off the `Error` object, so a crash you've never seen in your logs becomes a finding you can't ignore.
+- **Sees swallowed errors.** Error Boundaries and `window.onerror` miss the errors your app *catches*. Aztrx AI reads the real throw-site stack off the `Error` object, so a crash you've never seen in your logs becomes a finding you can't ignore.
 - **Proves, not reports.** Every crash/error finding ships with an executable `.spec.ts` and a flake-rate verdict — `[deterministic 5/5]`, `[flaky 3/5]`, or `[unreliable]`.
-- **Heals, not just finds.** `--heal` generates a patch through an LLM, gates it (redaction + AST safety), compiles it, and replays it against the repro inside an isolated git worktree — the patch is verified before a human ever sees it.
+- **Heals, not just finds.** `--heal` generates a patch through an LLM, gates it (redaction + AST safety), compiles it, runs your test suite, and replays it against the repro inside an isolated git worktree — the patch is verified before a human ever sees it.
 - **Safe by default.** A deny-by-default network guard blocks off-origin calls, and a destructive-action deny-list refuses to click "delete", "pay", or "logout".
 
 ---
@@ -28,25 +28,27 @@ Run against any running local dev server — no install, no repo clone:
 npx aztrx-cli run http://localhost:3000              # deterministic walk
 npx aztrx-cli run http://localhost:3000 --fuzz       # seeded chaos (replayable)
 npx aztrx-cli run http://localhost:3000 --fuzz --repro   # + minimize → compile → validate
+npx aztrx-cli run http://localhost:3000 --http-fuzz --repro   # server-side 5xx hunt → proof
 ```
 
-Install it globally once it's published:
+Install it globally:
 
 ```bash
 npm i -g aztrx-cli
 aztrx-cli run http://localhost:3000 --repro
 ```
 
-> **Not on npm yet?** Install from source (contributors):
-> ```bash
-> git clone https://github.com/DanisChaparov/aztrx
-> cd aztrx
-> npm install
-> npm run build
-> npm link        # puts `aztrx-cli` on your PATH
-> ```
+Or install from source (contributors):
 
-Aztrx drives Chromium through Playwright — the first run downloads the browser
+```bash
+git clone https://github.com/DanisChaparov/aztrx
+cd aztrx
+npm install
+npm run build
+npm link        # puts `aztrx-cli` on your PATH
+```
+
+Aztrx AI drives Chromium through Playwright — the first run downloads the browser
 automatically (`npx playwright install chromium` to force it).
 
 ---
@@ -91,6 +93,14 @@ npx aztrx-cli run http://localhost:3000 --upload --api-key <YOUR_API_KEY> --clou
 
 Ship a runtime gate on every PR — see [Continuous Integration](#continuous-integration-github-action) below.
 
+### 6. HTTP mutation fuzzing (`--http-fuzz`)
+
+The DOM fuzzer (`--fuzz`) breaks the *client*. `--http-fuzz` attacks the *server*: it harvests the endpoints your app actually calls, then throws hostile requests at them — query overflow, JSON type-confusion, header injection, method confusion — and turns every `5xx` into an executable repro.
+
+Every `5xx` finding also captures the server's *own* error response — its message and body — and, when the body leaks a stack trace, the server-side source line. So a finding reads "`HTTP 500 /api/cart` … `server: Cannot read properties of undefined` at `app/api/cart/route.ts:14`", not just "something 500'd".
+
+When the 500 body leaks that server stack, `--heal` can also *fix* it: it boots the patched app inside the worktree (via `--start-command`, or auto-detected `scripts.dev`/`scripts.start`), waits for an HTTP readiness signal, and replays the repro against the booted server — so a server patch is verified against a *running* app, not a static file. Server findings whose body does not leak a stack are still reported and repro'd but not healed (there is no file to patch).
+
 ---
 
 ## CLI reference
@@ -98,6 +108,7 @@ Ship a runtime gate on every PR — see [Continuous Integration](#continuous-int
 | Flag | Description | Default |
 | --- | --- | --- |
 | `--fuzz` | Seeded chaos fuzzing instead of the deterministic walk | — |
+| `--http-fuzz` | Server-side mutation fuzzing — hostile requests against the target origin | — |
 | `--repro` | Minimize (ddmin) → emit Playwright spec → validate flake rate | — |
 | `--heal` | Generate + verify an LLM patch (implies `--repro`) | — |
 | `--upload` | Stream run findings to the cloud ingest backend | — |
@@ -108,7 +119,12 @@ Ship a runtime gate on every PR — see [Continuous Integration](#continuous-int
 | `--repro-runs <n>` | Flake-rate replay iterations | `3` |
 | `--heal-model <model>` | Fallback LLM tier | `claude-sonnet-5` |
 | `--heal-fast-model <model>` | Fast/cheap first tier | `claude-haiku-4-5` |
+| `--test-command <cmd>` | Test command run against a healed patch | `npm test` (auto-detected) |
+| `--test-timeout <ms>` | Timeout for the heal test gate | `300000` |
+| `--no-test` | Skip the test gate during healing | — |
+| `--start-command <cmd>` | Command to boot the app for server healing | `scripts.dev` → `scripts.start` (auto-detected) |
 | `--pr-comment [path]` | Write a GitHub PR markdown comment | `.aztrx/pr-comment.md` |
+| `--badge [path]` | Write a self-contained SVG status badge | `.aztrx/badge.svg` |
 | `--telemetry` | Collect anonymized tuples locally (opt-in) | — |
 | `--share-data` | Also upload the sanitized tuples (opt-in) | — |
 | `--repo <path>` | Root path for sourcemap → source resolution | cwd |
@@ -132,16 +148,17 @@ Every run writes self-contained artifacts inside `.aztrx/` (gitignored):
 │   └── 458f6bf71977.spec.ts     # minimal, executable Playwright repro
 ├── heal/
 │   └── fix.patch                # gated, compiler-checked fix
-├── events.jsonl                 # run log, streamed by `aztrx studio`
+├── events.jsonl                 # run log, streamed by `aztrx-cli studio`
 ├── telemetry/dataset.jsonl      # opt-in anonymized tuple dataset
-└── pr-comment.md                # GitHub PR markdown (with --pr-comment)
+├── pr-comment.md                # GitHub PR markdown (with --pr-comment)
+└── badge.svg                    # status badge (with --badge)
 ```
 
 ---
 
 ## Architecture
 
-Aztrx is a decoupled, event-driven pipeline — modules talk only through an
+Aztrx AI is a decoupled, event-driven pipeline — modules talk only through an
 `EventBus`; the orchestrator wires them together.
 
 ```
@@ -184,7 +201,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: DanisChaparov/aztrx@main
+      - uses: DanisChaparov/aztrx@e5b89247cb0fba7f5c0febe8fa27f5e1c74cd898
         with:
           url: http://localhost:3000
           start-command: npm run dev          # optional — boot the app in the background
@@ -198,7 +215,7 @@ Or as a reusable workflow:
 on: pull_request
 jobs:
   aztrx:
-    uses: DanisChaparov/aztrx/.github/workflows/aztrx-pr.yml@main
+    uses: DanisChaparov/aztrx/.github/workflows/aztrx-pr.yml@e5b89247cb0fba7f5c0febe8fa27f5e1c74cd898
     with:
       url: http://localhost:3000
       start-command: npm run dev
@@ -208,6 +225,63 @@ jobs:
 
 ---
 
+## Status badge
+
+Hang a live badge in your README that reflects your *actual* crash/error state —
+not a static "protected" sticker.
+
+```bash
+npx aztrx-cli run http://localhost:3000 --badge badge.svg
+```
+
+```markdown
+[![aztrx](badge.svg)](https://github.com/DanisChaparov/aztrx)
+```
+
+The badge is a self-contained SVG generated from the run's findings — green
+`crash-free` or red `N findings`. It's honest because it's *earned*: regenerate it
+in CI on every push to `main` and commit it back.
+
+```yaml
+# .github/workflows/badge.yml — keep the badge honest on every push to main
+on:
+  push:
+    branches: [main]
+jobs:
+  badge:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - name: Boot dev server
+        run: |
+          nohup npm run dev > /tmp/dev.log 2>&1 &
+          for i in $(seq 1 60); do
+            curl -sS -o /dev/null http://localhost:3000 && break
+            sleep 2
+          done
+      - name: Generate badge
+        run: npx --yes aztrx-cli@0.1.1 run http://localhost:3000 --badge badge.svg
+      - name: Commit badge
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add badge.svg
+          git commit -m "chore: update aztrx badge" || echo "no change"
+          git push
+```
+
+No `--fail-on` here on purpose: the badge reflects the findings whatever they
+are, and the run still exits 0 so the commit step always runs. Swap `push` for a
+`schedule` cron if you'd rather regenerate daily than on every push.
+
+---
+
 ## Smart Cloud Router
 
 `--heal` is backed by a two-tier router. The fast/cheap model
@@ -227,11 +301,42 @@ strips secrets, anonymizes URLs to `<host>`, and scrubs repo paths to `<repo>`.
 Uploads are fire-and-forget, bounded by a 2s timeout, and never affect the exit
 code.
 
-## Security invariants
+## Security & data flow
 
-- **Deny-by-default network** — only the target origin (plus explicit `--allow-host`) is reachable.
-- **Destructive-action deny-list** — never clicks delete / pay / logout.
-- **`.aztrx/` is gitignored** on `init` — repro specs and reports stay out of history.
+**Local-first by default.** A run never phones home unless you pass an opt-in
+flag. By default nothing leaves your machine — no telemetry, no cloud sync, no
+LLM call.
+
+| What | Leaves your machine | When |
+| --- | --- | --- |
+| `run` (default) | nothing | — |
+| `--heal` | redacted file + redacted error/stack, to the LLM API | only with `--heal` + `ANTHROPIC_API_KEY` |
+| `--share-data` | a sanitized crash→repro→patch tuple | explicit opt-in |
+| `--upload` | sanitized findings + counts | explicit opt-in |
+
+### Invariants
+
+- **Sourcemap containment.** A hostile sourcemap or stack URL can't read outside
+  your repo: every path is resolved against the repo root and rejected if it
+  escapes it — including through symlinks. Secret-bearing files (`.env`, `.npmrc`,
+  private keys) are never read into a report or PR comment.
+- **Redaction before the model.** `--heal` redacts common secret patterns (keys,
+  tokens, credentials) from the file, error, and stack before they're sent; only
+  the repo-relative path and line/column are visible. Redaction is heuristic — it
+  is not a substitute for not committing secrets.
+- **Isolated sandbox, no commits.** Patches land in a detached `git worktree` in
+  the OS temp dir — never your working tree. Aztrx AI never commits. A patch must
+  parse, add no new imports / `eval` / `child_process`, typecheck, *and* pass your
+  own test suite before it's offered as a `.patch` for you to review.
+- **Deny-by-default network.** Only the target origin (plus explicit
+  `--allow-host`) is reachable; off-origin calls are blocked.
+- **Destructive-action deny-list.** Never clicks delete / pay / logout.
+- **Studio is localhost-only.** The dashboard binds `127.0.0.1` with no wildcard
+  CORS.
+- **`.aztrx/` is gitignored** on `init` — repro specs, reports, and patches stay
+  out of history.
+- **Pinned supply chain.** The GitHub Action pins `aztrx-cli@0.1.1` (never
+  `@latest`).
 
 ---
 
@@ -271,6 +376,7 @@ Full per-case table and scoring notes live in
 - [x] B2B ($29/mo) — Smart Cloud Router (haiku fast-tier → verify → Sonnet fallback)
 - [x] B2B ($29/mo) — Cloud dashboard (api.aztrx.app)
 - [x] Data flywheel — opt-in anonymized patch-tuple collection (F11)
+- [x] Server-side healing — heal server `5xx` findings (verify a patch by booting the patched server; requires a leaked server stack + a resolvable start command)
 
 ## Contributing
 

package/dist/cli.js

@@ -8,6 +8,7 @@ import { renderTui } from "./ui/app.js";
 import { initProject } from "./core/init.js";
 import { startStudio } from "./core/studio.js";
 import { writePrComment } from "./core/pr.js";
+import { writeBadge } from "./core/badge.js";
 import { flushTelemetry } from "./core/telemetry/index.js";
 import { flushCloud } from "./core/cloud/index.js";
 function collect(value, prev) {
@@ -15,7 +16,7 @@ function collect(value, prev) {
     return prev;
 }
 program
-    .name("aztrx")
+    .name("aztrx-cli")
     .description("Runtime stress-testing for web apps — detect bugs, prove them with a repro")
     .option("--repo <path>", "project root to inspect/watch (default: cwd)", process.cwd());
 program
@@ -33,7 +34,7 @@ program
     if (res.gitignoreUpdated)
         console.log(pc.green("✓") + " .aztrx/ added to .gitignore");
     console.log("");
-    console.log(pc.dim(`Next:  npx aztrx run ${res.url} --repo .`));
+    console.log(pc.dim(`Next:  npx aztrx-cli run ${res.url} --repo .`));
 });
 program
     .command("studio")
@@ -52,16 +53,23 @@ program
     .option("--crash-test", "throw a deliberate error to verify capture")
     .option("--fail-on", "exit 1 if any crash/error finding is present")
     .option("--fuzz", "chaos fuzzing instead of the deterministic walk (F5)")
+    .option("--http-fuzz", "HTTP-layer mutation fuzzing — hostile requests against the target origin (F5-http)")
+    .option("--http-fuzz-mutations", "with --http-fuzz: also send POST/PUT body mutations (default: GET-only)")
     .option("--seed <n>", "RNG seed for fuzz", "42")
     .option("--repro", "minimize + compile + validate each finding (F7-F9)")
     .option("--repro-runs <n>", "replay iterations for the flake-rate gate", "3")
     .option("--heal", "closed-loop healing for crash/error findings (implies --repro)")
     .option("--heal-model <model>", "LLM model for healing — the fallback tier (default claude-sonnet-5)")
     .option("--heal-fast-model <model>", "fast/cheap first tier for the smart router (default claude-haiku-4-5)")
+    .option("--test-command <cmd>", "test command run against a healed patch (default: npm test, auto-detected)")
+    .option("--test-timeout <ms>", "timeout for the heal test gate, ms", "300000")
+    .option("--no-test", "skip the test gate during healing")
+    .option("--start-command <cmd>", "command to boot the app for server healing (default: auto-detect scripts.dev/scripts.start)")
     .option("--pr-comment [path]", "write a GitHub PR markdown comment (default .aztrx/pr-comment.md)")
+    .option("--badge [path]", "write a self-contained SVG badge (default .aztrx/badge.svg)")
     .option("--telemetry", "opt-in: collect anonymized crash→repro→patch tuples locally (.aztrx/telemetry)")
     .option("--share-data", "opt-in: also upload the sanitized tuples to the telemetry endpoint")
-    .option("--upload", "opt-in: stream run results to the Aztrx cloud dashboard (needs --api-key)")
+    .option("--upload", "opt-in: stream run results to the Aztrx AI cloud dashboard (needs --api-key)")
     .option("--api-key <key>", "API key for --upload / --share-data (defaults to $AZTRX_API_KEY)")
     .option("--cloud-url <url>", "override the cloud ingest base URL (default https://api.aztrx.app)")
     .option("--allow-host <host>", "add a host to the network allow-list (repeatable)", collect, [])
@@ -78,6 +86,8 @@ program
         dryRun: opts.dryRun,
         crashTest: opts.crashTest,
         fuzz: opts.fuzz,
+        httpFuzz: opts.httpFuzz,
+        httpFuzzMutations: opts.httpFuzzMutations,
         repro: opts.repro || opts.heal,
         seed: parseInt(opts.seed, 10),
         allowHosts: opts.allowHost ?? [],
@@ -85,6 +95,10 @@ program
         heal: opts.heal,
         healModel: opts.healModel,
         healFastModel: opts.healFastModel,
+        testCommand: opts.testCommand,
+        testTimeoutMs: opts.testTimeoutMs ? parseInt(opts.testTimeoutMs, 10) : undefined,
+        skipTest: opts.test === false,
+        startCommand: opts.startCommand,
         telemetry: opts.telemetry,
         shareData: opts.shareData,
         upload: opts.upload,
@@ -103,13 +117,13 @@ program
             done: runPromise,
             targetUrl: url,
             repoRoot,
-            mode: opts.fuzz ? `fuzz (seed ${opts.seed})` : opts.heal ? "repro → heal" : opts.repro ? "repro" : "deterministic walk",
+            mode: opts.fuzz ? `fuzz (seed ${opts.seed})` : opts.httpFuzz ? "http fuzz" : opts.heal ? "repro → heal" : opts.repro ? "repro" : "deterministic walk",
         });
         try {
             findings = await runPromise;
         }
         catch (e) {
-            console.error(pc.red("Aztrx run failed:"), e.message);
+            console.error(pc.red("Aztrx AI run failed:"), e.message);
             process.exit(1);
         }
     }
@@ -123,6 +137,13 @@ program
         writePrComment(repoRoot, url, findings, prPath);
         console.log(pc.dim(`PR comment: ${path.relative(repoRoot, prPath)}`));
     }
+    if (opts.badge) {
+        const badgePath = typeof opts.badge === "string"
+            ? opts.badge
+            : path.join(repoRoot, ".aztrx", "badge.svg");
+        writeBadge(repoRoot, findings, badgePath);
+        console.log(pc.dim(`Badge: ${path.relative(repoRoot, badgePath)}`));
+    }
     // Drain any in-flight telemetry uploads (each bounded) before exit, so a
     // pending `--share-data` dispatch isn't killed mid-flight. Never affects
     // the exit code.

package/dist/core/badge.js

@@ -0,0 +1,50 @@
+/**
+ * Self-contained SVG status badge generated from a real run's findings. Unlike a
+ * static "Protected by …" sticker, this badge is *earned*: it reflects the
+ * crash/error count of the run that produced it, so a stale badge is a
+ * regeneration problem — not a lie baked into the image.
+ */
+import * as fs from "fs";
+import * as path from "path";
+const CHAR_W = 7.1; // Verdana 11px approximate advance width
+const PAD_X = 11; // horizontal padding per text block
+const LABEL = "#27272a"; // zinc-800 — brand monochrome
+const GREEN = "#16a34a";
+const RED = "#dc2626";
+function criticalCount(findings) {
+    return findings.filter((f) => f.severity === "crash" || f.severity === "error").length;
+}
+function blockWidth(text) {
+    return Math.round(text.length * CHAR_W + 2 * PAD_X);
+}
+export function renderBadge(findings, label = "aztrx") {
+    const n = criticalCount(findings);
+    const message = n === 0 ? "crash-free" : `${n} finding${n === 1 ? "" : "s"}`;
+    const color = n === 0 ? GREEN : RED;
+    const labelW = blockWidth(label);
+    const msgW = blockWidth(message);
+    const totalW = labelW + msgW;
+    const labelX = labelW / 2;
+    const msgX = labelW + msgW / 2;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${totalW}" height="20" role="img" aria-label="${label}: ${message}">`,
+        `  <linearGradient id="g" x2="0" y2="100%"><stop offset="0" stop-color="#ffffff" stop-opacity="0.14"/><stop offset="1" stop-opacity="0"/></linearGradient>`,
+        `  <clipPath id="r"><rect width="${totalW}" height="20" rx="3" fill="#fff"/></clipPath>`,
+        `  <g clip-path="url(#r)">`,
+        `    <rect width="${labelW}" height="20" fill="${LABEL}"/>`,
+        `    <rect x="${labelW}" width="${msgW}" height="20" fill="${color}"/>`,
+        `    <rect width="${totalW}" height="20" fill="url(#g)"/>`,
+        `  </g>`,
+        `  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11" font-weight="600">`,
+        `    <text x="${labelX}" y="14">${label}</text>`,
+        `    <text x="${msgX}" y="14">${message}</text>`,
+        `  </g>`,
+        `</svg>`,
+    ].join("\n") + "\n";
+}
+export function writeBadge(repoRoot, findings, filePath) {
+    const file = filePath ?? path.join(repoRoot, ".aztrx", "badge.svg");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, renderBadge(findings), "utf-8");
+    return file;
+}

package/dist/core/fuzzer.js

@@ -5,7 +5,7 @@ const GARBAGE = [
     "<script>alert(1)</script>",
     "'; DROP TABLE users;--",
     "a".repeat(4096),
-    "😀".repeat(64),
+    "字".repeat(64),
     String.fromCharCode(0) + "null-byte",
     "NaN",
     "-1",

package/dist/core/heal/boot.js

@@ -0,0 +1,136 @@
+/**
+ * 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.
+ */
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as net from "net";
+import * as path from "path";
+import { buildChildEnv } from "./childEnv.js";
+/** 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 function detectStartCommand(repoRoot) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf-8"));
+        const s = pkg.scripts;
+        if (s && typeof s.dev === "string")
+            return "npm run dev";
+        if (s && typeof s.start === "string")
+            return "npm run start";
+    }
+    catch {
+        // no package.json, or unparseable — fall through to null
+    }
+    return null;
+}
+/** Allocate a free loopback port. Best-effort: there is a small window between
+ * closing the probe and the app binding, so a collision is surfaced as a boot
+ * timeout rather than silently mis-directed. */
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            srv.close(() => resolve(addr.port));
+        });
+    });
+}
+export async function bootServer(opts) {
+    const { worktreeDir, repoRoot, startCommand } = opts;
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    // 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");
+    const wtNodeModules = path.join(worktreeDir, "node_modules");
+    if (!fs.existsSync(wtNodeModules) && fs.existsSync(rootNodeModules)) {
+        try {
+            fs.symlinkSync(rootNodeModules, wtNodeModules, process.platform === "win32" ? "junction" : "dir");
+        }
+        catch {
+            /* resolution errors surface in the readiness timeout below */
+        }
+    }
+    const 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));
+    // Ring buffer of the last ~40 log lines, so a boot timeout can tell the user
+    // *why* the server didn't come up rather than just "timeout".
+    const lines = [];
+    const push = (chunk) => {
+        for (const line of chunk.toString().split(/\r?\n/)) {
+            if (line) {
+                lines.push(line);
+                if (lines.length > 40)
+                    lines.shift();
+            }
+        }
+    };
+    const child = spawn(command, {
+        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" }),
+        // 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.
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    child.stdout?.on("data", push);
+    child.stderr?.on("data", push);
+    let closed = false;
+    const close = async () => {
+        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
+            }
+        }
+    };
+    // 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
+    // take a while on its first request — the loop keeps retrying until it's hot.
+    const url = `http://127.0.0.1:${port}`;
+    const deadline = Date.now() + timeoutMs;
+    let ready = false;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(1000) });
+            await res.arrayBuffer().catch(() => { });
+            ready = true;
+            break;
+        }
+        catch {
+            await new Promise((r) => setTimeout(r, 400));
+        }
+    }
+    if (!ready) {
+        await close();
+        throw new Error(`server did not become ready in ${timeoutMs}ms: ${startCommand}\n${lines.join("\n").slice(-2000)}`);
+    }
+    return { url, close, logs: () => lines.join("\n") };
+}

package/dist/core/heal/childEnv.js

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+const ALLOWED = new Set([
+    "PATH",
+    "HOME",
+    "USER",
+    "USERNAME",
+    "LOGNAME",
+    "SHELL",
+    "TMP",
+    "TEMP",
+    "TMPDIR",
+    "SystemRoot",
+    "SystemDrive",
+    "windir",
+    "COMSPEC",
+    "PATHEXT",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "NODE_ENV",
+    "CI",
+    "PORT",
+]);
+/** Build a minimal child environment: harmless platform vars, anything named in
+ * `AZTRX_ENV_ALLOW`, and any caller-supplied `extra` (e.g. `{ PORT: "4317" }`). */
+export function buildChildEnv(extra) {
+    const env = {};
+    for (const key of ALLOWED) {
+        const v = process.env[key];
+        if (v !== undefined)
+            env[key] = v;
+    }
+    const allow = process.env.AZTRX_ENV_ALLOW;
+    if (allow) {
+        for (const raw of allow.split(",")) {
+            const name = raw.trim();
+            if (!name)
+                continue;
+            const v = process.env[name];
+            if (v !== undefined)
+                env[name] = v;
+        }
+    }
+    if (extra)
+        for (const [k, v] of Object.entries(extra))
+            env[k] = v;
+    return env;
+}