nightralph 0.0.52 → 0.0.54

package/dist/index.js

@@ -3,8 +3,9 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/index.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
-import { dirname as dirname4, join as join6 } from "node:path";
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
+import { dirname as dirname6, join as join9 } from "node:path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { select } from "@inquirer/prompts";
@@ -198,14 +199,15 @@ __name(setup, "setup");
 import { spawn as spawn2, execFile as execFile4 } from "node:child_process";
 import {
   createWriteStream,
-  mkdirSync as mkdirSync2,
-  readFileSync as readFileSync4,
-  writeFileSync as writeFileSync3,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync6,
+  writeFileSync as writeFileSync5,
   unlinkSync,
-  readdirSync as readdirSync2
+  readdirSync as readdirSync2,
+  statSync
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join4, dirname as dirname2, basename as basename2 } from "node:path";
+import { join as join6, dirname as dirname4, basename as basename5, relative as relative2 } from "node:path";
 import { createInterface } from "node:readline";
 import { promisify as promisify4 } from "node:util";
 
@@ -233,15 +235,138 @@ function getRepoName() {
   return basename(dirname(resolve(commonDir)));
 }
 __name(getRepoName, "getRepoName");
-function getCurrentBranch() {
+function getCurrentBranch(cwd) {
   const stdout = execFileSync(
     "git",
     ["rev-parse", "--abbrev-ref", "HEAD"],
-    { encoding: "utf8" }
+    { cwd, encoding: "utf8" }
   );
   return stdout.trim();
 }
 __name(getCurrentBranch, "getCurrentBranch");
+function localBranchExists(repoRoot, name) {
+  try {
+    execFileSync(
+      "git",
+      ["show-ref", "--verify", "--quiet", `refs/heads/${name}`],
+      { cwd: repoRoot, stdio: "ignore" }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(localBranchExists, "localBranchExists");
+function getDefaultBranch(repoRoot) {
+  try {
+    const ref = execFileSync(
+      "git",
+      [
+        "symbolic-ref",
+        "--quiet",
+        "--short",
+        "refs/remotes/origin/HEAD"
+      ],
+      {
+        cwd: repoRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }
+    ).trim();
+    if (ref) return ref.replace(/^origin\//, "");
+  } catch {
+  }
+  for (const name of ["main", "master"]) {
+    if (localBranchExists(repoRoot, name)) return name;
+  }
+  return null;
+}
+__name(getDefaultBranch, "getDefaultBranch");
+function integrationBranchName(features) {
+  const distinct = [...new Set(features.filter(Boolean))];
+  return distinct.length === 1 ? `nightralph--${distinct[0]}` : "nightralph--all";
+}
+__name(integrationBranchName, "integrationBranchName");
+function planIntegrationBranch(current, defaultBranch, features) {
+  if (!defaultBranch || current === "HEAD") return null;
+  if (current !== defaultBranch) return null;
+  return integrationBranchName(features);
+}
+__name(planIntegrationBranch, "planIntegrationBranch");
+function gitText(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+}
+__name(gitText, "gitText");
+function prepareIntegrationBranch(repoRoot, features) {
+  const current = getCurrentBranch(repoRoot);
+  const defaultBranch = getDefaultBranch(repoRoot);
+  const name = planIntegrationBranch(
+    current,
+    defaultBranch,
+    features
+  );
+  if (!name) {
+    const onIntegration = defaultBranch !== null && current === integrationBranchName(features);
+    return {
+      branch: current,
+      created: false,
+      resumed: false,
+      behind: 0,
+      fastForwarded: false,
+      launchBranch: current,
+      forkedFrom: onIntegration ? defaultBranch : null
+    };
+  }
+  if (isDirty(repoRoot)) {
+    throw new Error(
+      "Working tree is dirty; commit or stash changes before running"
+    );
+  }
+  if (localBranchExists(repoRoot, name)) {
+    const contained = isAncestor(repoRoot, name, current);
+    gitText(repoRoot, ["checkout", "--quiet", name]);
+    let behind = Number(gitText(
+      repoRoot,
+      ["rev-list", "--count", `${name}..${current}`]
+    ));
+    const fastForwarded = contained && behind > 0;
+    if (fastForwarded) {
+      gitText(repoRoot, ["merge", "--ff-only", "--quiet", current]);
+      behind = 0;
+    }
+    return {
+      branch: name,
+      created: false,
+      resumed: true,
+      behind,
+      fastForwarded,
+      launchBranch: current,
+      forkedFrom: defaultBranch
+    };
+  }
+  gitText(repoRoot, ["checkout", "--quiet", "-b", name]);
+  return {
+    branch: name,
+    created: true,
+    resumed: false,
+    behind: 0,
+    fastForwarded: false,
+    launchBranch: current,
+    forkedFrom: defaultBranch
+  };
+}
+__name(prepareIntegrationBranch, "prepareIntegrationBranch");
+function describeIntegrationBranch(repoRoot, features) {
+  const current = getCurrentBranch(repoRoot);
+  const name = planIntegrationBranch(
+    current,
+    getDefaultBranch(repoRoot),
+    features
+  );
+  if (!name) return `Branch:       merges into ${current}`;
+  return localBranchExists(repoRoot, name) ? `Branch:       would resume ${name}` : `Branch:       would create ${name} from ${current}`;
+}
+__name(describeIntegrationBranch, "describeIntegrationBranch");
 async function branchExists(repoRoot, branchName) {
   try {
     await execFileAsync(
@@ -261,16 +386,20 @@ function buildBranchName(repoName, ticket) {
   return `${repoName}--${prefix}${num}-${ticket.slug}`;
 }
 __name(buildBranchName, "buildBranchName");
-async function createWorktreeNow(opts) {
-  const { repoRoot, repoName, baseBranch, ticket } = opts;
-  const branchName = buildBranchName(repoName, ticket);
-  const num = String(ticket.num).padStart(2, "0");
-  const prefix = ticket.feature ? `${ticket.feature}-` : "";
-  const worktreePath = join2(
-    repoRoot,
-    "..",
-    `${repoName}.${prefix}${num}-${ticket.slug}`
-  );
+async function removeWorktreeNow(worktreePath, opts) {
+  const args = [
+    "-C",
+    worktreePath,
+    "worktree",
+    "remove"
+  ];
+  if (opts?.force) args.push("--force");
+  args.push(worktreePath);
+  await execFileAsync("git", args);
+}
+__name(removeWorktreeNow, "removeWorktreeNow");
+async function addWorktreeNow(opts) {
+  const { repoRoot, baseBranch, branchName, worktreePath } = opts;
   if (existsSync2(worktreePath)) {
     try {
       await execFileAsync(
@@ -310,36 +439,56 @@ async function createWorktreeNow(opts) {
   );
   return { worktreePath, branchName };
 }
-__name(createWorktreeNow, "createWorktreeNow");
+__name(addWorktreeNow, "addWorktreeNow");
 var worktreeQueue = Promise.resolve();
-function createWorktree(opts) {
-  const result = worktreeQueue.then(() => createWorktreeNow(opts));
+function enqueue(fn) {
+  const result = worktreeQueue.then(fn);
   worktreeQueue = result.catch(() => {
   });
   return result;
 }
+__name(enqueue, "enqueue");
+function createWorktree(opts) {
+  const { repoRoot, repoName, ticket } = opts;
+  const num = String(ticket.num).padStart(2, "0");
+  const prefix = ticket.feature ? `${ticket.feature}-` : "";
+  return enqueue(() => addWorktreeNow({
+    repoRoot,
+    baseBranch: opts.baseBranch,
+    branchName: buildBranchName(repoName, ticket),
+    worktreePath: join2(
+      repoRoot,
+      "..",
+      `${repoName}.${prefix}${num}-${ticket.slug}`
+    )
+  }));
+}
 __name(createWorktree, "createWorktree");
-async function removeWorktreeNow(worktreePath, opts) {
-  const args = [
-    "-C",
-    worktreePath,
-    "worktree",
-    "remove"
-  ];
-  if (opts?.force) args.push("--force");
-  args.push(worktreePath);
-  await execFileAsync("git", args);
+function createNamedWorktree(opts) {
+  const { repoRoot, repoName, name } = opts;
+  return enqueue(() => addWorktreeNow({
+    repoRoot,
+    baseBranch: opts.baseBranch,
+    branchName: `${repoName}--${name}`,
+    worktreePath: join2(repoRoot, "..", `${repoName}.${name}`)
+  }));
 }
-__name(removeWorktreeNow, "removeWorktreeNow");
+__name(createNamedWorktree, "createNamedWorktree");
 function removeWorktree(worktreePath, opts) {
-  const result = worktreeQueue.then(
-    () => removeWorktreeNow(worktreePath, opts)
-  );
-  worktreeQueue = result.catch(() => {
-  });
-  return result;
+  return enqueue(() => removeWorktreeNow(worktreePath, opts));
 }
 __name(removeWorktree, "removeWorktree");
+function deleteBranch(repoRoot, name) {
+  return enqueue(async () => {
+    if (!await branchExists(repoRoot, name)) return;
+    await execFileAsync(
+      "git",
+      ["branch", "-D", name],
+      { cwd: repoRoot }
+    );
+  });
+}
+__name(deleteBranch, "deleteBranch");
 function hasNewCommits(repoRoot, base, branch) {
   const stdout = execFileSync(
     "git",
@@ -349,6 +498,51 @@ function hasNewCommits(repoRoot, base, branch) {
   return Number(stdout.trim()) > 0;
 }
 __name(hasNewCommits, "hasNewCommits");
+function headCommit(cwd) {
+  return gitText(cwd, ["rev-parse", "HEAD"]);
+}
+__name(headCommit, "headCommit");
+function mergeBase(cwd, a, b) {
+  try {
+    return gitText(cwd, ["merge-base", a, b]) || null;
+  } catch {
+    return null;
+  }
+}
+__name(mergeBase, "mergeBase");
+function isAncestor(cwd, ancestor, of) {
+  try {
+    execFileSync(
+      "git",
+      ["merge-base", "--is-ancestor", ancestor, of],
+      { cwd, stdio: "ignore" }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isAncestor, "isAncestor");
+function hasChangesOutside(cwd, from, to, excludeDir) {
+  try {
+    execFileSync(
+      "git",
+      [
+        "diff",
+        "--quiet",
+        `${from}..${to}`,
+        "--",
+        ".",
+        `:(exclude)${excludeDir}`
+      ],
+      { cwd, stdio: "ignore" }
+    );
+    return false;
+  } catch {
+    return true;
+  }
+}
+__name(hasChangesOutside, "hasChangesOutside");
 function isDirty(cwd) {
   const stdout = execFileSync(
     "git",
@@ -555,16 +749,17 @@ function writeProgress(progressPath, data) {
   );
 }
 __name(writeProgress, "writeProgress");
-async function commitProgress(repoRoot, progressPath, message) {
+async function commitProgress(repoRoot, paths, message) {
+  const list = typeof paths === "string" ? [paths] : paths;
   await execFileAsync2(
     "git",
-    ["add", "--force", progressPath],
+    ["add", "--force", "--", ...list],
     { cwd: repoRoot }
   );
   try {
     await execFileAsync2(
       "git",
-      ["diff", "--cached", "--quiet", "--", progressPath],
+      ["diff", "--cached", "--quiet", "--", ...list],
       { cwd: repoRoot }
     );
     return false;
@@ -572,7 +767,7 @@ async function commitProgress(repoRoot, progressPath, message) {
   }
   await execFileAsync2(
     "git",
-    ["commit", "-m", message, "--", progressPath],
+    ["commit", "-m", message, "--", ...list],
     { cwd: repoRoot }
   );
   return true;
@@ -837,6 +1032,14 @@ var DEFAULT_COLUMNS = 80;
 var MIN_LOG_ROWS = 1;
 var MAX_MESSAGE_BUFFER = 200;
 var ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/g;
+function rowText(ticket) {
+  const label = ticketLabel(ticket);
+  if (ticket.status !== "blocked" || !ticket.blockedBy?.length) {
+    return label;
+  }
+  return `${label} (blocked by ${ticket.blockedBy.join(", ")})`;
+}
+__name(rowText, "rowText");
 function fitLine(line, width) {
   const visible = line.replace(ANSI_RE, "");
   if (visible.length <= width) return line;
@@ -860,13 +1063,16 @@ function renderDot(status) {
     case "in-progress":
       return color.yellow(FILLED_DOT);
     // The agent and its test gate are finished; the branch
-    // waits for the rest of the wave before it is merged.
+    // waits for the rest of the wave before it is merged. It
+    // stays cyan through the merge and any conflict respawn.
     case "awaiting-merge":
       return color.cyan(FILLED_DOT);
     case "done":
       return color.green(FILLED_DOT);
     case "failed":
       return color.red(FILLED_DOT);
+    case "blocked":
+      return color.dim(FILLED_DOT);
   }
 }
 __name(renderDot, "renderDot");
@@ -875,8 +1081,8 @@ var StatusDisplay = class {
     __name(this, "StatusDisplay");
   }
   wave = null;
-  progress = null;
-  remaining = [];
+  tickets = [];
+  hasRun = false;
   messages = [];
   renderedLines = 0;
   config;
@@ -893,20 +1099,28 @@ var StatusDisplay = class {
     const available = termHeight - overhead;
     return Math.max(1, available);
   }
-  startWave(waveNum, totalWaves, tickets, progress, remaining) {
-    this.wave = {
-      waveNum,
-      totalWaves,
-      tickets: tickets.map((t) => ({
-        ...t,
-        status: "pending"
-      }))
-    };
-    this.remaining = (remaining ?? []).map((t) => ({
+  findTicket(num, feature) {
+    const found = feature ? this.tickets.find(
+      (t) => t.num === num && t.feature === feature
+    ) : this.tickets.find((t) => t.num === num);
+    return found ?? null;
+  }
+  startRun(tickets) {
+    this.tickets = tickets.map((t) => ({
       ...t,
       status: "pending"
     }));
-    this.progress = progress ?? null;
+    this.hasRun = true;
+    this.viewportStart = 0;
+  }
+  startWave(waveNum, totalWaves, tickets, _progress) {
+    if (!this.hasRun) {
+      this.startRun(tickets);
+    }
+    this.wave = {
+      waveNum,
+      totalWaves
+    };
     this.messages = [];
     this.viewportStart = 0;
     this.config.stream.write(ansi.cursorHide());
@@ -926,28 +1140,31 @@ var StatusDisplay = class {
     this.render();
   }
   setTicketStatus(num, status, feature) {
-    if (!this.wave) return;
-    const ticket = feature ? this.wave.tickets.find(
-      (t) => t.num === num && t.feature === feature
-    ) : this.wave.tickets.find((t) => t.num === num);
-    if (ticket) {
-      ticket.status = status;
-      if (status === "in-progress") {
-        const ticketIndex = this.wave.tickets.indexOf(ticket);
-        const availableRows = this.getAvailableRows();
-        const totalTickets = this.wave.tickets.length;
-        if (ticketIndex < this.viewportStart) {
-          this.viewportStart = ticketIndex;
-        } else if (ticketIndex >= this.viewportStart + availableRows) {
-          this.viewportStart = ticketIndex - availableRows + 3;
-        }
-        this.viewportStart = Math.max(
-          0,
-          Math.min(this.viewportStart, totalTickets - 1)
-        );
+    const ticket = this.findTicket(num, feature);
+    if (!ticket) return;
+    ticket.status = status;
+    if (status === "in-progress") {
+      const ticketIndex = this.tickets.indexOf(ticket);
+      const availableRows = this.getAvailableRows();
+      const totalTickets = this.tickets.length;
+      if (ticketIndex < this.viewportStart) {
+        this.viewportStart = ticketIndex;
+      } else if (ticketIndex >= this.viewportStart + availableRows) {
+        this.viewportStart = ticketIndex - availableRows + 3;
       }
-      this.render();
+      this.viewportStart = Math.max(
+        0,
+        Math.min(this.viewportStart, totalTickets - 1)
+      );
     }
+    this.render();
+  }
+  setBlocked(num, feature, blockedBy) {
+    const ticket = this.findTicket(num, feature);
+    if (!ticket) return;
+    ticket.status = "blocked";
+    ticket.blockedBy = [...blockedBy];
+    this.render();
   }
   log(message) {
     if (!this.wave) {
@@ -974,59 +1191,52 @@ var StatusDisplay = class {
     if (this.renderedLines > 0) {
       output += ansi.eraseLines(this.renderedLines + 1);
     }
-    const doneInWave = this.wave.tickets.filter(
+    const done = this.tickets.filter(
       (t) => t.status === "done"
     ).length;
-    const completed = doneInWave + (this.progress?.completed ?? 0);
-    const total = this.progress?.total ?? this.wave.tickets.length;
-    const pct = total === 0 ? 0 : Math.round(completed / total * 100);
+    const total = this.tickets.length;
+    const pct = total === 0 ? 0 : Math.round(done / total * 100);
     const width = Math.max(
       1,
       (this.config.stream.columns ?? DEFAULT_COLUMNS) - 1
     );
-    output += `Wave ${this.wave.waveNum}/${this.wave.totalWaves} - ${pct}% complete
-`;
+    const header = `Wave ${this.wave.waveNum}/${this.wave.totalWaves} - ${done}/${total} done - ${pct}%`;
+    output += fitLine(header, width) + "\n";
     const availableRows = this.getAvailableRows();
-    const tickets = [
-      ...this.wave.tickets,
-      ...this.remaining
-    ];
     let renderedTicketCount = 0;
-    if (tickets.length <= availableRows) {
-      for (const ticket of tickets) {
+    if (this.tickets.length <= availableRows) {
+      for (const ticket of this.tickets) {
         const dot = renderDot(ticket.status);
-        const name = fitLine(
-          ticketLabel(ticket),
-          width - 2
-        );
+        const text = rowText(ticket);
+        const name = fitLine(text, width - 2);
         output += `${dot} ${name}
 `;
       }
-      renderedTicketCount = tickets.length;
+      renderedTicketCount = this.tickets.length;
     } else {
       this.viewportStart = Math.max(
         0,
         Math.min(
           this.viewportStart,
-          tickets.length - 1
+          this.tickets.length - 1
         )
       );
       let hasMoreAbove = this.viewportStart > 0;
       let tentativeCount = availableRows - (hasMoreAbove ? 1 : 0);
-      let hasMoreBelow = this.viewportStart + tentativeCount < tickets.length;
+      let hasMoreBelow = this.viewportStart + tentativeCount < this.tickets.length;
       let ticketsToShow = Math.max(
         0,
         tentativeCount - (hasMoreBelow ? 1 : 0)
       );
       const maxStart = Math.max(
         0,
-        tickets.length - Math.max(1, ticketsToShow)
+        this.tickets.length - Math.max(1, ticketsToShow)
       );
       if (this.viewportStart > maxStart) {
         this.viewportStart = maxStart;
         hasMoreAbove = this.viewportStart > 0;
         tentativeCount = availableRows - (hasMoreAbove ? 1 : 0);
-        hasMoreBelow = this.viewportStart + tentativeCount < tickets.length;
+        hasMoreBelow = this.viewportStart + tentativeCount < this.tickets.length;
         ticketsToShow = Math.max(
           0,
           tentativeCount - (hasMoreBelow ? 1 : 0)
@@ -1037,21 +1247,19 @@ var StatusDisplay = class {
         output += `  ... ${moreCount} more above
 `;
       }
-      const visibleTickets = tickets.slice(
+      const visibleTickets = this.tickets.slice(
         this.viewportStart,
         this.viewportStart + ticketsToShow
       );
       for (const ticket of visibleTickets) {
         const dot = renderDot(ticket.status);
-        const name = fitLine(
-          ticketLabel(ticket),
-          width - 2
-        );
+        const text = rowText(ticket);
+        const name = fitLine(text, width - 2);
         output += `${dot} ${name}
 `;
       }
       if (hasMoreBelow) {
-        const moreCount = tickets.length - (this.viewportStart + ticketsToShow);
+        const moreCount = this.tickets.length - (this.viewportStart + ticketsToShow);
         output += `  ... ${moreCount} more below
 `;
       }
@@ -1083,7 +1291,9 @@ var PlainDisplay = class {
   static {
     __name(this, "PlainDisplay");
   }
-  startWave(waveNum, _totalWaves, tickets, progress, _remaining) {
+  startRun(_tickets) {
+  }
+  startWave(waveNum, _totalWaves, tickets, progress) {
     const pct = progress && progress.total > 0 ? ` (${progress.completed}/${progress.total} done)` : "";
     console.log(
       `
@@ -1092,6 +1302,8 @@ Wave ${waveNum}${pct}: ` + tickets.map((t) => ticketLabel(t)).join(", ")
   }
   setTicketStatus(_num, _status, _feature) {
   }
+  setBlocked(_num, _feature, _blockedBy) {
+  }
   log(message) {
     console.log(message);
   }
@@ -1124,8 +1336,20 @@ function detectTestCmd(projectDir) {
   }
 }
 __name(detectTestCmd, "detectTestCmd");
+function detectInstallCmd(projectDir) {
+  const has = /* @__PURE__ */ __name((name) => existsSync3(join3(projectDir, name)), "has");
+  if (!has("package.json")) return null;
+  if (has("pnpm-lock.yaml")) {
+    return "pnpm install --prefer-offline --frozen-lockfile";
+  }
+  if (has("package-lock.json")) {
+    return "npm ci --prefer-offline --no-audit --no-fund";
+  }
+  return "npm install --prefer-offline --no-audit --no-fund --no-package-lock";
+}
+__name(detectInstallCmd, "detectInstallCmd");
 function runTestCmd(opts) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     let settled = false;
     const child = spawn("sh", ["-c", opts.cmd], {
       cwd: opts.cwd,
@@ -1157,7 +1381,7 @@ function runTestCmd(opts) {
         opts.registry.delete(child.pid);
       }
       chunks.push(String(err));
-      resolve2({
+      resolve3({
         exitCode: 1,
         output: chunks.join("")
       });
@@ -1169,7 +1393,7 @@ function runTestCmd(opts) {
       if (child.pid !== void 0 && opts.registry) {
         opts.registry.delete(child.pid);
       }
-      resolve2({
+      resolve3({
         exitCode: code ?? 1,
         output: chunks.join("")
       });
@@ -1178,6 +1402,1061 @@ function runTestCmd(opts) {
 }
 __name(runTestCmd, "runTestCmd");
 
+// src/learnings.ts
+import {
+  appendFileSync,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync4,
+  rmSync,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { basename as basename2, dirname as dirname2, join as join4 } from "node:path";
+var MAX_OWN_ENTRIES = 4;
+var MAX_ENTRY_CHARS = 4e3;
+var LOG_TAIL_LINES = 40;
+var NOTES_PATH = ".nightralph/notes.md";
+var SENTINEL_PREFIX = "<!-- nightralph:entry";
+var TRUNCATED_MARKER = "[truncated]";
+var LEARNING_OUTCOMES = [
+  "done",
+  "exit",
+  "tests",
+  "install",
+  "no-commits",
+  "error",
+  "merge"
+];
+function encodeKey(key) {
+  return key.replace(/%/g, "%25").replace(/\s/g, (c) => encodeURIComponent(c));
+}
+__name(encodeKey, "encodeKey");
+function fence(content) {
+  const longest = Math.max(
+    0,
+    ...[...content.matchAll(/`+/g)].map((m) => m[0].length)
+  );
+  const ticks = "`".repeat(Math.max(3, longest + 1));
+  return `${ticks}
+${content}
+${ticks}`;
+}
+__name(fence, "fence");
+function sanitize(text) {
+  if (!text) return "";
+  return text.replace(
+    new RegExp(SENTINEL_PREFIX, "g"),
+    "<!-- nightralph-entry"
+  );
+}
+__name(sanitize, "sanitize");
+function renderAgentSummary(run, effort) {
+  const effortLine = effort ? `Effort: ${effort}.` : "";
+  const exitLine = `Agent exit: ${run.exitCode}.`;
+  const itemsText = run.completedItems.length > 0 ? run.completedItems.map(
+    (item) => `"${sanitize(item)}"`
+  ).join(", ") + "." : "none.";
+  const itemsLine = `Checked items: ${itemsText}`;
+  return [
+    effortLine,
+    exitLine,
+    itemsLine
+  ].filter(Boolean).join(" ");
+}
+__name(renderAgentSummary, "renderAgentSummary");
+function renderNotesSection(notes) {
+  const notesSanitized = sanitize(notes);
+  return notesSanitized.trim() ? `### Agent notes
+${notesSanitized}` : "The agent left no notes.";
+}
+__name(renderNotesSection, "renderNotesSection");
+function formatDate(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}`;
+}
+__name(formatDate, "formatDate");
+function isLearningOutcome(value) {
+  return LEARNING_OUTCOMES.some((o) => o === value);
+}
+__name(isLearningOutcome, "isLearningOutcome");
+function renderEntry(input) {
+  const encodedKey = encodeKey(input.key);
+  const hasRun = "run" in input;
+  const timedOut = hasRun && input.run.timedOut;
+  const timedOutStr = timedOut ? " timedout=true" : "";
+  const sentinel = `<!-- nightralph:entry ticket=${encodedKey} attempt=${input.attempt} outcome=${input.outcome}${timedOutStr} -->`;
+  const timestamp = formatDate(input.now);
+  const attemptStr = input.outcome === "merge" ? "" : ` attempt ${input.attempt}`;
+  let description;
+  switch (input.outcome) {
+    case "done":
+      description = "done";
+      break;
+    case "exit":
+      description = `failed (exit ${input.run.exitCode})`;
+      break;
+    case "tests":
+      description = "failed (tests)";
+      break;
+    case "install":
+      description = "failed (install)";
+      break;
+    case "no-commits":
+      description = "no commits";
+      break;
+    case "error":
+      description = "error";
+      break;
+    case "merge":
+      description = "merge failed";
+      break;
+    default: {
+      const _exhaustive = input;
+      description = _exhaustive;
+    }
+  }
+  const timedOutPrefix = timedOut ? "timed out, then " : "";
+  const heading = `## ${timestamp} -- ${input.label}${attemptStr} -- ${timedOutPrefix}${description}`;
+  let body;
+  switch (input.outcome) {
+    case "done":
+    case "exit":
+    case "no-commits": {
+      const run = input.run;
+      const summary = renderAgentSummary(run, input.effort);
+      const notesSection = renderNotesSection(run.notes);
+      body = summary + "\n\n" + notesSection;
+      break;
+    }
+    case "tests": {
+      const logTail = sanitize(input.logTail);
+      const fenced = fence(logTail);
+      const summary = renderAgentSummary(
+        input.run,
+        input.effort
+      );
+      const notesSection = renderNotesSection(input.run.notes);
+      const lastNLines = `Last ${LOG_TAIL_LINES} lines of \`${sanitize(input.logName)}\`:`;
+      body = summary + `
+
+Test gate failed.
+${lastNLines}
+${fenced}
+
+` + notesSection;
+      break;
+    }
+    case "install": {
+      const logTail = sanitize(input.logTail);
+      const fenced = fence(logTail);
+      const lastNLines = `Last ${LOG_TAIL_LINES} lines of \`${sanitize(input.logName)}\`:`;
+      body = `Install failed.
+${lastNLines}
+` + fenced;
+      break;
+    }
+    case "error": {
+      const errorText = sanitize(input.error);
+      const fenced = fence(errorText);
+      body = fenced;
+      break;
+    }
+    case "merge": {
+      const stderrText = sanitize(input.stderr);
+      const fenced = fence(stderrText);
+      body = `Merge failed.
+${fenced}`;
+      break;
+    }
+    default: {
+      const unknown = input;
+      throw new Error(`Unknown outcome: ${JSON.stringify(unknown)}`);
+    }
+  }
+  return `${sentinel}
+${heading}
+
+${body}
+
+---
+`;
+}
+__name(renderEntry, "renderEntry");
+function parseEntries(text) {
+  const lines = text.split("\n").map((line) => {
+    return line.endsWith("\r") ? line.slice(0, -1) : line;
+  });
+  const entries = [];
+  let currentSentinel = null;
+  let currentBody = [];
+  const sentinelRegex = /^<!-- nightralph:entry (.*) -->$/;
+  for (const line of lines) {
+    const match = line.match(sentinelRegex);
+    if (match) {
+      if (currentSentinel !== null) {
+        const entry = parseSentinel(currentSentinel, currentBody);
+        if (entry) {
+          entries.push(entry);
+        }
+      }
+      currentSentinel = match[1];
+      currentBody = [];
+    } else if (currentSentinel !== null) {
+      currentBody.push(line);
+    }
+  }
+  if (currentSentinel !== null) {
+    const entry = parseSentinel(currentSentinel, currentBody);
+    if (entry) {
+      entries.push(entry);
+    }
+  }
+  return entries;
+}
+__name(parseEntries, "parseEntries");
+function parseSentinel(sentinel, bodyLines) {
+  const parts = sentinel.split(/\s+/).filter(Boolean);
+  const attrs = {};
+  for (const part of parts) {
+    const idx = part.indexOf("=");
+    if (idx > 0) {
+      const key2 = part.slice(0, idx);
+      const value = part.slice(idx + 1);
+      if (value) {
+        attrs[key2] = value;
+      }
+    }
+  }
+  let key = attrs.ticket;
+  if (!key) return null;
+  try {
+    key = decodeURIComponent(key);
+  } catch (_e) {
+    return null;
+  }
+  if (!key.trim()) return null;
+  const attemptStr = attrs.attempt;
+  if (!attemptStr) return null;
+  if (!/^\d+$/.test(attemptStr)) return null;
+  const attempt = Number(attemptStr);
+  const outcome = attrs.outcome;
+  if (!outcome || !isLearningOutcome(outcome)) return null;
+  const timedOut = attrs.timedout === "true";
+  let body = bodyLines.join("\n").trim();
+  const lines = body.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "---") {
+    body = lines.slice(0, -1).join("\n").trim();
+  }
+  return {
+    key,
+    attempt,
+    outcome,
+    timedOut,
+    body
+  };
+}
+__name(parseSentinel, "parseSentinel");
+function selectHistory(entries, opts) {
+  const own = entries.filter((e) => e.key === opts.key).slice(-MAX_OWN_ENTRIES);
+  const blockers = opts.blockerKeys.flatMap((k) => {
+    const done = entries.filter((e) => {
+      return e.key === k && e.outcome === "done";
+    });
+    const last = done[done.length - 1];
+    return last ? [last] : [];
+  });
+  return { own, blockers };
+}
+__name(selectHistory, "selectHistory");
+function renderHistory(selection) {
+  if (selection.own.length === 0 && selection.blockers.length === 0) {
+    return "";
+  }
+  const framing = "These are records of earlier runs. The ticket or spec may have changed since then; where they disagree, follow the ticket and spec. Do not repeat an approach these notes say failed unless you can see why it failed.";
+  const parts = [framing, ""];
+  if (selection.own.length > 0) {
+    parts.push("---- PREVIOUS ATTEMPTS AT THIS TICKET ----");
+    parts.push(selection.own.map((e) => capEntry(e)).join("\n\n"));
+    parts.push("");
+  }
+  if (selection.blockers.length > 0) {
+    parts.push("---- WHAT THE BLOCKING TICKETS DID ----");
+    parts.push(selection.blockers.map((e) => capEntry(e)).join("\n\n"));
+  }
+  return parts.join("\n");
+}
+__name(renderHistory, "renderHistory");
+function capEntry(entry) {
+  if (entry.body.length <= MAX_ENTRY_CHARS) {
+    return entry.body;
+  }
+  return entry.body.slice(0, MAX_ENTRY_CHARS) + "\n" + TRUNCATED_MARKER;
+}
+__name(capEntry, "capEntry");
+function tailLines(text, n) {
+  let lines = text.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines = lines.slice(0, -1);
+  }
+  if (lines.length > n) {
+    lines = lines.slice(-n);
+  }
+  return lines.join("\n");
+}
+__name(tailLines, "tailLines");
+function learningsPathFor(progressPath) {
+  return join4(dirname2(progressPath), "learnings.md");
+}
+__name(learningsPathFor, "learningsPathFor");
+function readEntries(path) {
+  if (!existsSync4(path)) return [];
+  return parseEntries(readFileSync4(path, "utf8"));
+}
+__name(readEntries, "readEntries");
+function appendEntry(path, text) {
+  mkdirSync2(dirname2(path), { recursive: true });
+  appendFileSync(path, text);
+}
+__name(appendEntry, "appendEntry");
+function collectNotes(worktreePath, file = basename2(NOTES_PATH)) {
+  const dir = join4(worktreePath, dirname2(NOTES_PATH));
+  const path = join4(dir, file);
+  const text = existsSync4(path) ? readFileSync4(path, "utf8").trim() : "";
+  rmSync(dir, { recursive: true, force: true });
+  return text || null;
+}
+__name(collectNotes, "collectNotes");
+function ensureNotesIgnored(worktreePath) {
+  const dir = join4(worktreePath, dirname2(NOTES_PATH));
+  mkdirSync2(dir, { recursive: true });
+  writeFileSync3(join4(dir, ".gitignore"), "*\n");
+}
+__name(ensureNotesIgnored, "ensureNotesIgnored");
+
+// src/rules.ts
+function readDocsRule(subject) {
+  return `- Read the files directly relevant to the ${subject} before writing code. Also read any AGENTS.md in or above the directories you will touch, plus CONTEXT.md and the relevant docs/adr/ entries if they exist. If they do not exist, proceed silently.`;
+}
+__name(readDocsRule, "readDocsRule");
+function installRule(installCmd) {
+  if (!installCmd) return [];
+  return [
+    `- Dependencies are already installed with \`${installCmd}\`. Do NOT reinstall them with any other command; to reinstall, run that same command. To add a dependency, use the package manager that command uses, so its lockfile stays in sync.`
+  ];
+}
+__name(installRule, "installRule");
+function testGateRule(testCmd, subject) {
+  if (testCmd === "") {
+    return `- Before each commit, run the tests relevant to what you changed. Do not commit with failing tests. The orchestrator runs no test command for this ${subject}.`;
+  }
+  return `- While iterating, run only the tests relevant to what you changed. Run \`${testCmd}\` in full once, as the final gate before your last commit. Do not commit with failing tests. The orchestrator runs the same command after you exit and rejects the ${subject} if it fails.`;
+}
+__name(testGateRule, "testGateRule");
+var LINT_RULE = "- If the project has a lint script, run it and fix what it reports.";
+function integrityRule(unit) {
+  return `- INTEGRITY: never delete, skip, weaken, or write tautological tests to force a green result. Only report a ${unit} done when its real tests genuinely pass. If an item cannot be completed honestly, leave it unchecked and record what blocked you in your notes file.`;
+}
+__name(integrityRule, "integrityRule");
+var CONFINEMENT_RULES = [
+  "- Do NOT read or modify files outside your current directory (the worktree).",
+  "- Do NOT run git push."
+];
+function commitRule(unit) {
+  return `- Commit after each ${unit}, and make sure everything is committed when finished, except your notes file.`;
+}
+__name(commitRule, "commitRule");
+function notesRule(unit, subject) {
+  return `- Keep notes for this attempt in \`${NOTES_PATH}\` (create the directory). Update it after each ${unit} and as soon as you hit a blocker, not only at the end. Record what you implemented, files changed, how you read any vague acceptance criteria, what blocked you, and anything the next attempt at this ${subject} should know. Never commit, git add, or delete this file; the orchestrator collects it.`;
+}
+__name(notesRule, "notesRule");
+function agentsMdRule(subject) {
+  return `- Before your final commit, record reusable learnings in the nearest AGENTS.md (in or above the directories you modified; prefer that over the repo root). Good additions: module conventions, gotchas, files that must change together, how to test that area, environment requirements. Do NOT add ${subject}-specific details or temporary debugging notes. Only write when you have knowledge that would help future work in that directory. Reusable patterns go in AGENTS.md; anything specific to this ${subject} goes in your notes file.`;
+}
+__name(agentsMdRule, "agentsMdRule");
+
+// src/review.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "node:fs";
+import { basename as basename4, dirname as dirname3, join as join5, relative } from "node:path";
+
+// src/retry.ts
+import { basename as basename3 } from "node:path";
+var EFFORT_LADDERS = {
+  pi: [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max"
+  ],
+  claude: [
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max"
+  ],
+  codex: ["low", "medium", "high"]
+};
+var ALL_EFFORT_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+];
+function escalateEffort(provider, level) {
+  if (!level) return "high";
+  const ladder = EFFORT_LADDERS[provider];
+  const i = ladder.indexOf(level);
+  if (i === -1) return level;
+  return ladder[Math.min(i + 1, ladder.length - 1)];
+}
+__name(escalateEffort, "escalateEffort");
+function retryDelayFor(base, attempt) {
+  return base * 2 ** (attempt - 2);
+}
+__name(retryDelayFor, "retryDelayFor");
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+__name(sleep, "sleep");
+async function runWithRetries(opts, run) {
+  const maxAttempts = Math.max(1, opts.maxAttempts);
+  const providerName = basename3(opts.agentCmd);
+  const isKnown = providerName in EFFORT_LADDERS;
+  const wait = opts.wait ?? sleep;
+  let effort = opts.effort;
+  for (let attempt = 1; ; attempt++) {
+    if (attempt === 1) {
+      opts.log(`  Starting ${opts.label}`);
+    } else {
+      if (isKnown) {
+        effort = escalateEffort(
+          providerName,
+          effort
+        );
+      }
+      const delay = retryDelayFor(opts.retryDelay, attempt);
+      opts.log(
+        `  ${opts.label}: retrying (attempt ${attempt}/${maxAttempts}` + (isKnown && effort ? `, effort ${effort}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
+      );
+      if (delay > 0) await wait(delay * 1e3);
+    }
+    const step = await run(attempt, effort);
+    if (step.stop || attempt >= maxAttempts) return step.result;
+  }
+}
+__name(runWithRetries, "runWithRetries");
+
+// src/review.ts
+var FINDINGS_FILE = "findings.md";
+var FINDINGS_PATH = `${dirname3(NOTES_PATH)}/${FINDINGS_FILE}`;
+var NO_FINDINGS = "No findings.";
+var REVIEW_EXCLUDE = ".scratch";
+var REVIEW_MARKER = "---- REVIEW INSTRUCTIONS ----";
+var FIX_MARKER = "---- REVIEW FINDINGS ----";
+function reviewExcludeFor(repoRoot, reviewPath) {
+  let dir = dirname3(reviewPath);
+  while (dirname3(dir) !== dir) {
+    if (basename4(dir) === ".scratch") {
+      const rel = relative(repoRoot, dir);
+      if (rel && !rel.startsWith("..")) return rel;
+      break;
+    }
+    dir = dirname3(dir);
+  }
+  return REVIEW_EXCLUDE;
+}
+__name(reviewExcludeFor, "reviewExcludeFor");
+function reviewDiffCommand(from, to, exclude = REVIEW_EXCLUDE) {
+  return `git diff ${from}..${to} -- . ':(exclude)${exclude}'`;
+}
+__name(reviewDiffCommand, "reviewDiffCommand");
+function renderReviewPrompt(opts) {
+  return [
+    "---- SPEC CONTEXT ----",
+    opts.specBody,
+    "",
+    REVIEW_MARKER,
+    "You are reviewing work that autonomous agents merged into this branch, one ticket at a time. Review the combined change as a whole.",
+    "",
+    "The change to review:",
+    "",
+    `    ${reviewDiffCommand(opts.from, opts.to, opts.exclude)}`,
+    "",
+    "Follow these rules:",
+    "- Read any AGENTS.md in or above the directories the change touches, plus CONTEXT.md and the relevant docs/adr/ entries if they exist. Treat their contracts and the spec above as the standard the code must meet.",
+    "- Look for correctness bugs, missing or weak tests, and code that breaks a documented contract. Ignore style preferences.",
+    "- You may run the tests or the type checker to confirm a suspicion.",
+    "- Do NOT edit, stage, or commit code. Anything you change here is discarded.",
+    ...CONFINEMENT_RULES,
+    "",
+    `Write your findings to \`${FINDINGS_PATH}\` (create the directory), most severe first, in exactly this form:`,
+    "",
+    "- [ ] <one-line summary of the finding>",
+    "    <file:line, and a concrete input or state that goes wrong>",
+    "",
+    "If you find nothing worth fixing, write the single line: " + NO_FINDINGS,
+    "Never git add or commit that file; the orchestrator collects it.",
+    ""
+  ].join("\n");
+}
+__name(renderReviewPrompt, "renderReviewPrompt");
+var FIX_FAILURE_TEXT = {
+  install: "dependency install failed",
+  exit: "the agent exited with an error",
+  "no-commits": "the agent made no commits",
+  tests: "the test command failed after the agent finished",
+  merge: "the fix branch did not merge cleanly"
+};
+function findingLines(findings) {
+  return findings.flatMap((f) => [
+    `- [ ] ${f.summary}`,
+    ...f.detail ? f.detail.split("\n").map((l) => `    ${l}`) : []
+  ]);
+}
+__name(findingLines, "findingLines");
+function previousBlock(previous) {
+  if (!previous) return [];
+  return [
+    "---- PREVIOUS FIX ATTEMPT ----",
+    `It failed: ${FIX_FAILURE_TEXT[previous.reason]}.`,
+    previous.notes ?? "It left no notes.",
+    ""
+  ];
+}
+__name(previousBlock, "previousBlock");
+function renderFixPrompt(opts) {
+  return [
+    "---- SPEC CONTEXT ----",
+    opts.specBody,
+    "",
+    FIX_MARKER,
+    ...findingLines(opts.findings),
+    "",
+    ...previousBlock(opts.previous),
+    "---- AGENT INSTRUCTIONS ----",
+    "You are an autonomous coding agent. Fix the review findings above using /tdd.",
+    "",
+    "Follow these rules:",
+    readDocsRule("findings"),
+    "- Fix ONLY the listed findings. Do not fix unrelated problems you notice.",
+    ...installRule(opts.installCmd),
+    "- Use /tdd for every finding: write a failing test that shows the problem, then write only enough code to make it pass, then refactor.",
+    testGateRule(opts.testCmd, "fix"),
+    LINT_RULE,
+    integrityRule("finding"),
+    ...CONFINEMENT_RULES,
+    commitRule("finding"),
+    notesRule("finding", "fix"),
+    "- After fixing each finding, print a line: [x] <finding summary> (matching the summary text exactly).",
+    "- If a finding is wrong or cannot be fixed honestly, leave it unchecked and explain why in your notes file.",
+    agentsMdRule("fix"),
+    ""
+  ].join("\n");
+}
+__name(renderFixPrompt, "renderFixPrompt");
+var SENTINEL_PREFIX2 = "<!-- nightralph:review";
+var SENTINEL_RE = /^<!-- nightralph:review (.*) -->$/;
+var SHA_RE = /^[0-9a-f]{4,64}$/;
+var FIX_HEADING = "### Fix";
+var FINDING_RE = /^ ?[-*+]\s+\[([ xX])\]\s+(.+)$/;
+var REVIEW_STATUSES = [
+  "clean",
+  "fixed",
+  "unresolved",
+  "review-failed"
+];
+function isReviewStatus(value) {
+  return REVIEW_STATUSES.includes(value);
+}
+__name(isReviewStatus, "isReviewStatus");
+function collapse(s) {
+  return s.replace(/\s+/g, " ").trim();
+}
+__name(collapse, "collapse");
+function normalize(s) {
+  return collapse(s).toLowerCase();
+}
+__name(normalize, "normalize");
+function sanitize2(text) {
+  return text.replace(
+    new RegExp(SENTINEL_PREFIX2, "g"),
+    "<!-- nightralph-review"
+  );
+}
+__name(sanitize2, "sanitize");
+function splitLines(text) {
+  return text.split("\n").map((line) => {
+    return line.endsWith("\r") ? line.slice(0, -1) : line;
+  });
+}
+__name(splitLines, "splitLines");
+function parseFindings(text) {
+  const findings = [];
+  const details = [];
+  for (const line of splitLines(text)) {
+    const m = line.match(FINDING_RE);
+    if (m) {
+      findings.push({
+        summary: collapse(m[2]),
+        detail: "",
+        checked: m[1] !== " "
+      });
+      details.push([]);
+    } else if (findings.length > 0 && line.trim()) {
+      details[details.length - 1].push(line.trim());
+    }
+  }
+  if (findings.length > 0) {
+    return findings.map((f, i) => {
+      return { ...f, detail: details[i].join("\n") };
+    });
+  }
+  const clean = splitLines(text).some((line) => {
+    return normalize(line) === NO_FINDINGS.toLowerCase();
+  });
+  return clean ? [] : null;
+}
+__name(parseFindings, "parseFindings");
+function markFixed(findings, completedItems) {
+  const done = new Set(completedItems.map(normalize));
+  return findings.map((f) => {
+    return { ...f, checked: done.has(normalize(f.summary)) };
+  });
+}
+__name(markFixed, "markFixed");
+function headline(input) {
+  const n = input.findings.length;
+  const fixed = input.findings.filter((f) => f.checked).length;
+  switch (input.status) {
+    case "clean":
+      return "no findings";
+    case "fixed":
+      return `${fixed} of ${n} fixed`;
+    case "unresolved":
+      return `${n} finding${n === 1 ? "" : "s"}, fix failed`;
+    case "review-failed":
+      return "review failed";
+    default: {
+      const _exhaustive = input.status;
+      return _exhaustive;
+    }
+  }
+}
+__name(headline, "headline");
+function renderFindings(input) {
+  if (input.status === "review-failed") {
+    return ["The reviewer left no usable findings file."];
+  }
+  if (input.findings.length === 0) return [NO_FINDINGS];
+  return input.findings.flatMap((f) => {
+    const box = f.checked ? "[x]" : "[ ]";
+    const detail = f.detail ? f.detail.split("\n").map((l) => `    ${sanitize2(l)}`) : [];
+    return [`- ${box} ${sanitize2(collapse(f.summary))}`, ...detail];
+  });
+}
+__name(renderFindings, "renderFindings");
+function renderFix(fix) {
+  if (!fix) return [];
+  return [
+    "",
+    FIX_HEADING,
+    `- attempts: ${fix.attempts} of ${fix.maxAttempts}`,
+    ...fix.effort ? [`- effort: ${fix.effort}`] : [],
+    `- agent exit code: ${fix.exitCode ?? "none"}`,
+    `- result: ${sanitize2(fix.result)}`,
+    "",
+    fix.notes ? sanitize2(fix.notes) : "The fixer left no notes."
+  ];
+}
+__name(renderFix, "renderFix");
+function renderReviewEntry(input) {
+  return [
+    `${SENTINEL_PREFIX2} from=${input.from} to=${input.to} status=${input.status} -->`,
+    `## ${formatDate(input.now)} -- review ${input.from.slice(0, 7)}..${input.to.slice(0, 7)} -- ${headline(input)}`,
+    ...renderFindings(input),
+    ...renderFix(input.fix),
+    "---",
+    ""
+  ].join("\n");
+}
+__name(renderReviewEntry, "renderReviewEntry");
+function parseEntry(sentinel, bodyLines) {
+  const attrs = {};
+  for (const part of sentinel.split(/\s+/).filter(Boolean)) {
+    const idx = part.indexOf("=");
+    if (idx > 0) attrs[part.slice(0, idx)] = part.slice(idx + 1);
+  }
+  const { from, to, status } = attrs;
+  if (!from || !SHA_RE.test(from)) return null;
+  if (!to || !SHA_RE.test(to)) return null;
+  if (!status || !isReviewStatus(status)) return null;
+  const lines = [...bodyLines];
+  while (lines.length > 0 && !lines[lines.length - 1].trim()) {
+    lines.pop();
+  }
+  if (lines[lines.length - 1] === "---") lines.pop();
+  const fixAt = lines.indexOf(FIX_HEADING);
+  const findingLines2 = fixAt === -1 ? lines : lines.slice(0, fixAt);
+  return {
+    from,
+    to,
+    status,
+    findings: parseFindings(findingLines2.join("\n")) ?? [],
+    body: lines.join("\n").trim()
+  };
+}
+__name(parseEntry, "parseEntry");
+function parseReviewEntries(text) {
+  const entries = [];
+  let sentinel = null;
+  let body = [];
+  const flush = /* @__PURE__ */ __name(() => {
+    if (sentinel === null) return;
+    const entry = parseEntry(sentinel, body);
+    if (entry) entries.push(entry);
+  }, "flush");
+  for (const line of splitLines(text)) {
+    const m = line.match(SENTINEL_RE);
+    if (m) {
+      flush();
+      sentinel = m[1];
+      body = [];
+    } else if (sentinel !== null) {
+      body.push(line);
+    }
+  }
+  flush();
+  return entries;
+}
+__name(parseReviewEntries, "parseReviewEntries");
+function selectReviewBase(entries, opts) {
+  const last = [...entries].reverse().find((e) => {
+    return e.status !== "review-failed";
+  });
+  if (last && opts.isAncestor(last.to)) return last.to;
+  return opts.forkPoint ?? opts.launchCommit;
+}
+__name(selectReviewBase, "selectReviewBase");
+function renderReviewSummary(outcome, reviewPath) {
+  const see = ` -- see ${reviewPath}`;
+  const plural = outcome.findings === 1 ? "" : "s";
+  switch (outcome.status) {
+    case "skipped":
+      return null;
+    case "clean":
+      return `Review: no findings${see}`;
+    case "fixed":
+      return `Review: ${outcome.findings} finding${plural}, ${outcome.fixed} fixed${see}`;
+    case "unresolved":
+      return `Review: ${outcome.findings} finding${plural}, fix failed${see}`;
+    case "review-failed":
+      return `Review: the reviewer failed${see}`;
+    default: {
+      const _exhaustive = outcome.status;
+      return _exhaustive;
+    }
+  }
+}
+__name(renderReviewSummary, "renderReviewSummary");
+function logPath(logsDir, stem, attempt, ext) {
+  const suffix = attempt > 1 ? `.attempt${attempt}` : "";
+  return join5(logsDir, `${stem}${suffix}${ext}`);
+}
+__name(logPath, "logPath");
+async function runStep(opts, deps, cmd, cwd, path) {
+  const result = await runTestCmd({
+    cmd,
+    cwd,
+    timeout: opts.timeout,
+    registry: deps.registry
+  });
+  writeFileSync4(path, result.output);
+  return result.exitCode === 0;
+}
+__name(runStep, "runStep");
+async function discardWorktree(opts, wt) {
+  try {
+    await removeWorktree(wt.worktreePath, { force: true });
+    await deleteBranch(opts.repoRoot, wt.branchName);
+  } catch (err) {
+    opts.log(
+      `  Failed to remove ${wt.worktreePath}: ` + (err instanceof Error ? err.message : String(err))
+    );
+  }
+}
+__name(discardWorktree, "discardWorktree");
+async function runReviewer(opts, deps, range) {
+  return runWithRetries({
+    maxAttempts: opts.retries + 1,
+    retryDelay: opts.retryDelay,
+    agentCmd: opts.agentCmd,
+    effort: opts.effort,
+    label: "review",
+    log: opts.log
+  }, async (attempt, effort) => {
+    const wt = await createNamedWorktree({
+      repoRoot: opts.repoRoot,
+      repoName: opts.repoName,
+      baseBranch: opts.baseBranch,
+      name: "review"
+    });
+    try {
+      if (opts.installCmd && !await runStep(
+        opts,
+        deps,
+        opts.installCmd,
+        wt.worktreePath,
+        logPath(opts.logsDir, "review", attempt, ".install.log")
+      )) {
+        opts.log("  review: install failed");
+        return { result: null, stop: false };
+      }
+      ensureNotesIgnored(wt.worktreePath);
+      await deps.spawnAgent({
+        prompt: renderReviewPrompt({
+          specBody: opts.specBody,
+          ...range,
+          exclude: reviewExcludeFor(
+            opts.repoRoot,
+            opts.reviewPath
+          )
+        }),
+        agentCmd: opts.agentCmd,
+        model: opts.model,
+        timeout: opts.timeout,
+        logPath: logPath(opts.logsDir, "review", attempt, ".log"),
+        cwd: wt.worktreePath,
+        label: "review",
+        maxTurns: opts.maxTurns,
+        effort,
+        onLine: opts.log
+      });
+      const text = collectNotes(wt.worktreePath, FINDINGS_FILE);
+      const findings = text === null ? null : parseFindings(text);
+      if (findings === null) {
+        opts.log("  review: no usable findings file");
+      }
+      return { result: findings, stop: findings !== null };
+    } finally {
+      await discardWorktree(opts, wt);
+    }
+  });
+}
+__name(runReviewer, "runReviewer");
+async function runFixer(opts, deps, findings) {
+  const unchecked = findings.map((f) => ({ ...f, checked: false }));
+  let previous;
+  return runWithRetries({
+    maxAttempts: opts.retries + 1,
+    retryDelay: opts.retryDelay,
+    agentCmd: opts.agentCmd,
+    effort: opts.effort,
+    label: "review fix",
+    log: opts.log
+  }, async (attempt, effort) => {
+    const fail = /* @__PURE__ */ __name((reason, exitCode, notes) => {
+      previous = { reason, notes };
+      opts.log(`  review fix: ${FIX_FAILURE_TEXT[reason]}`);
+      return {
+        result: {
+          merged: false,
+          findings: unchecked,
+          attempts: attempt,
+          effort,
+          exitCode,
+          result: FIX_FAILURE_TEXT[reason],
+          notes
+        },
+        stop: false
+      };
+    }, "fail");
+    const wt = await createNamedWorktree({
+      repoRoot: opts.repoRoot,
+      repoName: opts.repoName,
+      baseBranch: opts.baseBranch,
+      name: "review-fix"
+    });
+    try {
+      if (opts.installCmd && !await runStep(
+        opts,
+        deps,
+        opts.installCmd,
+        wt.worktreePath,
+        logPath(
+          opts.logsDir,
+          "review-fix",
+          attempt,
+          ".install.log"
+        )
+      )) {
+        return fail("install", null, null);
+      }
+      ensureNotesIgnored(wt.worktreePath);
+      const agent = await deps.spawnAgent({
+        prompt: renderFixPrompt({
+          specBody: opts.specBody,
+          findings,
+          testCmd: opts.testCmd,
+          installCmd: opts.installCmd,
+          previous
+        }),
+        agentCmd: opts.agentCmd,
+        model: opts.model,
+        timeout: opts.timeout,
+        logPath: logPath(
+          opts.logsDir,
+          "review-fix",
+          attempt,
+          ".log"
+        ),
+        cwd: wt.worktreePath,
+        label: "review-fix",
+        maxTurns: opts.maxTurns,
+        effort,
+        onLine: opts.log
+      });
+      const notes = collectNotes(wt.worktreePath);
+      if (!agent.timedOut && agent.exitCode !== 0) {
+        return fail("exit", agent.exitCode, notes);
+      }
+      if (isDirty(wt.worktreePath)) {
+        await commitDirty(
+          wt.worktreePath,
+          "nightralph: auto-commit review fix remaining changes"
+        );
+      }
+      if (!hasNewCommits(
+        opts.repoRoot,
+        opts.baseBranch,
+        wt.branchName
+      )) {
+        return fail("no-commits", agent.exitCode, notes);
+      }
+      if (opts.testCmd === "") {
+        opts.log("  review fix: no test gate");
+      } else if (!await runStep(
+        opts,
+        deps,
+        opts.testCmd,
+        wt.worktreePath,
+        logPath(
+          opts.logsDir,
+          "review-fix",
+          attempt,
+          ".test.log"
+        )
+      )) {
+        return fail("tests", agent.exitCode, notes);
+      }
+      const merged = await mergeBranch(
+        opts.repoRoot,
+        wt.branchName
+      );
+      if (!merged.success) {
+        return fail(
+          "merge",
+          agent.exitCode,
+          [notes, merged.stderr].filter(Boolean).join("\n\n") || null
+        );
+      }
+      opts.log("  review fix: merged");
+      return {
+        result: {
+          merged: true,
+          findings: markFixed(findings, agent.completedItems),
+          attempts: attempt,
+          effort,
+          exitCode: agent.exitCode,
+          result: "merged",
+          notes
+        },
+        stop: true
+      };
+    } finally {
+      await discardWorktree(opts, wt);
+    }
+  });
+}
+__name(runFixer, "runFixer");
+function readReviewEntries(path) {
+  if (!existsSync5(path)) return [];
+  return parseReviewEntries(readFileSync5(path, "utf8"));
+}
+__name(readReviewEntries, "readReviewEntries");
+async function runReviewPass(opts, deps) {
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  const to = headCommit(opts.repoRoot);
+  const forkPoint = opts.forkedFrom ? mergeBase(opts.repoRoot, opts.forkedFrom, to) : null;
+  const from = selectReviewBase(readReviewEntries(opts.reviewPath), {
+    isAncestor: /* @__PURE__ */ __name((sha) => isAncestor(opts.repoRoot, sha, to), "isAncestor"),
+    forkPoint,
+    launchCommit: opts.launchCommit
+  });
+  const exclude = reviewExcludeFor(opts.repoRoot, opts.reviewPath);
+  if (!hasChangesOutside(opts.repoRoot, from, to, exclude)) {
+    opts.log("\nReview: nothing new to review");
+    return { status: "skipped", findings: 0, fixed: 0 };
+  }
+  opts.log(`
+Reviewing ${from.slice(0, 7)}..${to.slice(0, 7)}`);
+  const findings = await runReviewer(opts, deps, { from, to });
+  let entry;
+  if (findings === null) {
+    entry = {
+      from,
+      to,
+      status: "review-failed",
+      now: now(),
+      findings: []
+    };
+  } else if (findings.length === 0) {
+    entry = { from, to, status: "clean", now: now(), findings: [] };
+  } else {
+    opts.log(
+      `Review: ${findings.length} finding${findings.length === 1 ? "" : "s"}`
+    );
+    const fix = await runFixer(opts, deps, findings);
+    entry = {
+      from,
+      // A merged fix counts as reviewed
+      to: fix.merged ? headCommit(opts.repoRoot) : to,
+      status: fix.merged ? "fixed" : "unresolved",
+      now: now(),
+      findings: fix.findings,
+      fix: {
+        attempts: fix.attempts,
+        maxAttempts: opts.retries + 1,
+        effort: fix.effort,
+        exitCode: fix.exitCode,
+        result: fix.result,
+        notes: fix.notes
+      }
+    };
+  }
+  appendEntry(opts.reviewPath, renderReviewEntry(entry));
+  await commitProgress(
+    opts.repoRoot,
+    opts.reviewPath,
+    "nightralph: record review"
+  );
+  return {
+    status: entry.status,
+    findings: entry.findings.length,
+    fixed: entry.findings.filter((f) => f.checked).length
+  };
+}
+__name(runReviewPass, "runReviewPass");
+
 // src/orchestrator.ts
 var execFileAsync4 = promisify4(execFile4);
 function formatErrorMessage(error) {
@@ -1270,8 +2549,8 @@ function scanTickets(dir, feature = "") {
   ));
   return files.map((filename) => {
     const parsed = parseTicketFilename(filename);
-    const filepath = join4(dir, filename);
-    const body = readFileSync4(filepath, "utf8");
+    const filepath = join6(dir, filename);
+    const body = readFileSync6(filepath, "utf8");
     return {
       num: parsed.num,
       slug: parsed.slug,
@@ -1301,6 +2580,37 @@ function findReadyTickets(tickets) {
   });
 }
 __name(findReadyTickets, "findReadyTickets");
+function findBlockedTickets(tickets, failedKeys) {
+  const byKey = new Map(
+    tickets.map((t) => [ticketKey(t.feature, t.num), t])
+  );
+  function collectDead(ticket, visited, found) {
+    for (const b of ticket.blockers) {
+      const key = ticketKey(ticket.feature, b);
+      if (visited.has(key)) continue;
+      visited.add(key);
+      const blocker = byKey.get(key);
+      if (!blocker || blocker.status === "done") continue;
+      if (failedKeys.has(key) || blocker.status !== "ready-for-agent") {
+        found.add(key);
+        continue;
+      }
+      collectDead(blocker, visited, found);
+    }
+  }
+  __name(collectDead, "collectDead");
+  const blocked = /* @__PURE__ */ new Map();
+  for (const t of tickets) {
+    const key = ticketKey(t.feature, t.num);
+    if (t.status !== "ready-for-agent") continue;
+    if (failedKeys.has(key)) continue;
+    const found = /* @__PURE__ */ new Set();
+    collectDead(t, /* @__PURE__ */ new Set([key]), found);
+    if (found.size > 0) blocked.set(key, [...found]);
+  }
+  return blocked;
+}
+__name(findBlockedTickets, "findBlockedTickets");
 var COMPLETED_RE = /^\s*[-*+]?\s*\[x\]\s+(.+)$/i;
 var TOOL_USE_RE = /^\[[\w.]+\]/;
 var CHECKBOX_RE = /^(\s*[-*+] )\[( |x|X)\]( .*)$/;
@@ -1351,7 +2661,7 @@ function checkItems(ticket, completedItems) {
   if (completedItems.length === 0) return;
   let body;
   try {
-    body = readFileSync4(ticket.filepath, "utf8");
+    body = readFileSync6(ticket.filepath, "utf8");
   } catch {
     body = ticket.body;
   }
@@ -1375,7 +2685,7 @@ function checkItems(ticket, completedItems) {
   }
   if (!changed) return;
   body = lines.join("\n");
-  writeFileSync3(ticket.filepath, body);
+  writeFileSync5(ticket.filepath, body);
   ticket.body = body;
 }
 __name(checkItems, "checkItems");
@@ -1399,7 +2709,7 @@ __name(checkAllItems, "checkAllItems");
 function markDone(ticket) {
   let body;
   try {
-    body = readFileSync4(ticket.filepath, "utf8");
+    body = readFileSync6(ticket.filepath, "utf8");
   } catch {
     body = ticket.body;
   }
@@ -1408,7 +2718,7 @@ function markDone(ticket) {
     /\*\*Status:\*\*\s*.+/i,
     "**Status:** done"
   );
-  writeFileSync3(ticket.filepath, updated);
+  writeFileSync5(ticket.filepath, updated);
   ticket.status = "done";
   ticket.body = updated;
 }
@@ -1441,11 +2751,23 @@ function stripSpecSection(specBody, heading) {
   return out.join("\n");
 }
 __name(stripSpecSection, "stripSpecSection");
+function reviewSpecBody(specBody, specBodies) {
+  if (!specBodies || specBodies.size <= 1) return specBody;
+  return [...specBodies].map(([name, body]) => `# Feature: ${name}
+
+${body}`).join("\n\n");
+}
+__name(reviewSpecBody, "reviewSpecBody");
 function lookupSpec(specBodies, fallback, feature) {
   if (!feature || !specBodies) return fallback;
   return specBodies.get(feature) ?? fallback;
 }
 __name(lookupSpec, "lookupSpec");
+function historyBlock(history) {
+  if (!history) return [];
+  return [history, ""];
+}
+__name(historyBlock, "historyBlock");
 function renderPrompt(specBody, ticket, opts) {
   return [
     "---- SPEC CONTEXT ----",
@@ -1455,27 +2777,29 @@ function renderPrompt(specBody, ticket, opts) {
     ticket.filename,
     ticket.body,
     "",
+    ...historyBlock(opts.history),
     "---- AGENT INSTRUCTIONS ----",
     "You are an autonomous coding agent. Implement the ticket using /tdd.",
     "",
     "Follow these rules:",
-    "- Read the files directly relevant to the ticket before writing code. Also read any AGENTS.md in or above the directories you will touch, plus CONTEXT.md and the relevant docs/adr/ entries if they exist. If they do not exist, proceed silently.",
+    readDocsRule("ticket"),
     "- Work ONLY on this ticket. Do not fix unrelated problems you notice.",
     "- Do NOT research external APIs or services via web search. Use the spec and ticket body as your sole reference for API shapes.",
-    "- Use /tdd for every checklist item. For each item, write a failing test at the seams named in the spec's Testing Decisions section, then write only enough code to make it pass, then refactor.",
-    `- While iterating, run only the tests relevant to what you changed. Run \`${opts.testCmd}\` in full once, as the final gate before your last commit. Do not commit with failing tests. The orchestrator runs the same command after you exit and rejects the ticket if it fails.`,
-    "- If the project has a lint script, run it and fix what it reports.",
-    "- INTEGRITY: never delete, skip, weaken, or write tautological tests to force a green result. Only report a checklist item done when its real tests genuinely pass. If an item cannot be completed honestly, leave it unchecked and say what blocked you.",
-    "- Do NOT read or modify files outside your current directory (the worktree).",
-    "- Do NOT run git push.",
-    "- Commit after each checklist item, and make sure everything is committed when finished.",
+    ...installRule(opts.installCmd),
+    "- Use /tdd for every checklist item. For each item, write a failing test at the seams named in the spec's Testing Decisions section, then write only enough code to make it pass, then refactor. For a checklist item that is pure scaffolding, config, or docs (where a test adds no value), skip test-first and record that decision in your notes file.",
+    testGateRule(opts.testCmd, "ticket"),
+    LINT_RULE,
+    integrityRule("checklist item"),
+    ...CONFINEMENT_RULES,
+    commitRule("checklist item"),
+    notesRule("checklist item", "ticket"),
     "- After completing each checklist item in the ticket, print a line: [x] <item text> (matching the checklist text exactly).",
-    "- Before your final commit, record reusable learnings in the nearest AGENTS.md (in or above the directories you modified; prefer that over the repo root). Good additions: module conventions, gotchas, files that must change together, how to test that area, environment requirements. Do NOT add ticket-specific details or temporary debugging notes. Only write when you have knowledge that would help future work in that directory.",
+    agentsMdRule("ticket"),
     ""
   ].join("\n");
 }
 __name(renderPrompt, "renderPrompt");
-function renderMergePrompt(specBody, ticket) {
+function renderMergePrompt(specBody, ticket, opts = {}) {
   return [
     "---- SPEC CONTEXT ----",
     specBody,
@@ -1496,6 +2820,7 @@ function renderMergePrompt(specBody, ticket) {
     "4. Commit the resolved files.",
     "",
     "Do NOT re-implement the ticket from scratch.",
+    ...installRule(opts.installCmd),
     "Do NOT read or modify files outside your current directory (the worktree).",
     "Do NOT run git push."
   ].join("\n");
@@ -1603,48 +2928,12 @@ var PROVIDER_ARGS = {
     "--mode",
     "json"
   ]
-};
-function getProviderArgs(cmd) {
-  const name = basename2(cmd);
-  return PROVIDER_ARGS[name] ?? [];
-}
-__name(getProviderArgs, "getProviderArgs");
-var EFFORT_LADDERS = {
-  pi: [
-    "off",
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max"
-  ],
-  claude: [
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max"
-  ],
-  codex: ["low", "medium", "high"]
-};
-var ALL_EFFORT_LEVELS = [
-  "off",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max"
-];
-function escalateEffort(provider, level) {
-  if (!level) return "high";
-  const ladder = EFFORT_LADDERS[provider];
-  const i = ladder.indexOf(level);
-  if (i === -1) return level;
-  return ladder[Math.min(i + 1, ladder.length - 1)];
+};
+function getProviderArgs(cmd) {
+  const name = basename5(cmd);
+  return PROVIDER_ARGS[name] ?? [];
 }
-__name(escalateEffort, "escalateEffort");
+__name(getProviderArgs, "getProviderArgs");
 function formatStreamLine(line) {
   let obj;
   try {
@@ -1745,8 +3034,8 @@ function createPiStreamFormatter() {
 __name(createPiStreamFormatter, "createPiStreamFormatter");
 function writePromptFile(prompt) {
   const name = `nightralph-${Date.now()}-${Math.random().toString(36).slice(2)}.md`;
-  const filePath = join4(tmpdir(), name);
-  writeFileSync3(filePath, prompt);
+  const filePath = join6(tmpdir(), name);
+  writeFileSync5(filePath, prompt);
   return filePath;
 }
 __name(writePromptFile, "writePromptFile");
@@ -1787,7 +3076,7 @@ function spawnAgent(opts) {
   if (opts.model) {
     args.push("--model", opts.model);
   }
-  const providerName = basename2(opts.agentCmd);
+  const providerName = basename5(opts.agentCmd);
   const isClaude = providerName === "claude";
   const isPi = providerName === "pi";
   if (opts.maxTurns) {
@@ -1837,7 +3126,7 @@ function spawnAgent(opts) {
     detached: true
   });
   if (proc.pid !== void 0) runningAgents.add(proc.pid);
-  proc.stdout.pipe(logStream);
+  proc.stdout.pipe(logStream, { end: false });
   const piFormatter = isPi ? createPiStreamFormatter() : null;
   const completedItems = [];
   const seenItems = /* @__PURE__ */ new Set();
@@ -1886,7 +3175,7 @@ function spawnAgent(opts) {
       }
     }
   });
-  proc.stderr.pipe(logStream);
+  proc.stderr.pipe(logStream, { end: false });
   const rlErr = createInterface({ input: proc.stderr });
   rlErr.on("line", (line) => {
     if (isClaude && !TOOL_USE_RE.test(line)) return;
@@ -1921,7 +3210,7 @@ function spawnAgent(opts) {
     proc.stdin.write(opts.prompt);
   }
   proc.stdin.end();
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     let settled = false;
     let graceTimer;
     function finish(exitCode) {
@@ -1947,7 +3236,7 @@ function spawnAgent(opts) {
       rlErr.close();
       logStream.end();
       if (promptFile) cleanupPromptFile(promptFile);
-      resolve2({ exitCode, completedItems, timedOut });
+      resolve3({ exitCode, completedItems, timedOut });
     }
     __name(finish, "finish");
     proc.on("exit", (code) => {
@@ -1971,16 +3260,21 @@ function spawnAgent(opts) {
       }
       rl.close();
       rlErr.close();
-      logStream.end();
+      const msg = "agent process error: " + formatErrorMessage(err);
+      logStream.write(`nightralph: ${msg}
+`);
       if (promptFile) cleanupPromptFile(promptFile);
-      console.error(
-        "Agent process error:",
-        formatErrorMessage(err)
-      );
-      resolve2({
-        exitCode: 1,
-        completedItems,
-        timedOut
+      if (opts.onLine) {
+        opts.onLine(`${prefix}${msg}`);
+      } else {
+        console.error(`${prefix}${msg}`);
+      }
+      logStream.end(() => {
+        resolve3({
+          exitCode: 1,
+          completedItems,
+          timedOut
+        });
       });
     });
   });
@@ -2000,6 +3294,8 @@ function dryRun(tickets, specBody, testCmd) {
       "\nDeadlocked tickets: " + stuck.map((t) => t.filename).join(", ")
     );
   }
+  console.log(`
+Test command: ${testCmd || "(none)"}`);
   const firstReady = findReadyTickets(tickets);
   if (firstReady.length > 0) {
     console.log(
@@ -2055,14 +3351,20 @@ Prompt for first ready ticket (${firstReady[0].filename}):
       renderPrompt(
         opts.specBody,
         firstReady[0],
-        { testCmd: opts.testCmd }
+        {
+          testCmd: opts.testCmd,
+          installCmd: opts.installCmd
+        }
       )
     );
   }
   const strategyDesc = opts.conflictStrategy === "respawn" ? "respawn (re-run agent on conflict)" : "stop (stop merging on conflict)";
   console.log(
     `
-Test command: ${opts.testCmd}`
+Test command: ${opts.testCmd || "(none)"}`
+  );
+  console.log(
+    `Install:      ${opts.installCmd || "(none)"}`
   );
   console.log(
     `Effort:       ${opts.effort ?? "(provider default)"}`
@@ -2083,7 +3385,34 @@ Merge strategy: ${strategyDesc}`
   console.log(`Progress file: ${opts.progressPath}`);
 }
 __name(dryRunIsolated, "dryRunIsolated");
+async function runInstall(opts) {
+  const result = await runTestCmd({
+    cmd: opts.installCmd,
+    cwd: opts.worktreePath,
+    timeout: opts.timeout,
+    registry: opts.registry
+  });
+  const installLogPath = attemptLogPath(
+    opts.logsDir,
+    opts.ticket,
+    opts.attempt ?? 1,
+    ".install.log"
+  );
+  writeFileSync5(installLogPath, result.output);
+  if (result.exitCode !== 0) {
+    opts.log(
+      `  ${opts.ticket.filename}: install failed (exit ${result.exitCode}); see ${installLogPath}`
+    );
+    return false;
+  }
+  return true;
+}
+__name(runInstall, "runInstall");
 async function runTestGate(opts) {
+  if (opts.testCmd === "") {
+    opts.log(`  ${opts.ticket.filename}: no test gate`);
+    return true;
+  }
   const result = await runTestCmd({
     cmd: opts.testCmd,
     cwd: opts.worktreePath,
@@ -2096,7 +3425,7 @@ async function runTestGate(opts) {
     opts.attempt ?? 1,
     ".test.log"
   );
-  writeFileSync3(testLogPath, result.output);
+  writeFileSync5(testLogPath, result.output);
   if (result.exitCode !== 0) {
     opts.log(
       `  ${opts.ticket.filename}: tests failed (exit ${result.exitCode}); see ${testLogPath}`
@@ -2125,11 +3454,24 @@ async function respawnAndRetryMerge(opts) {
   } else {
     console.log(msg1);
   }
+  if (opts.installCmd) {
+    const installed = await runInstall({
+      installCmd: opts.installCmd,
+      ticket: opts.ticket,
+      worktreePath: opts.worktreePath,
+      timeout: opts.timeout,
+      logsDir: opts.logsDir,
+      log,
+      registry: runningAgents
+    });
+    if (!installed) return false;
+  }
   const prompt = renderMergePrompt(
     opts.specBody,
-    opts.ticket
+    opts.ticket,
+    { installCmd: opts.installCmd }
   );
-  const logPath = join4(
+  const logPath2 = join6(
     opts.logsDir,
     opts.ticket.filename.replace(/\.md$/, ".respawn.log")
   );
@@ -2142,7 +3484,7 @@ async function respawnAndRetryMerge(opts) {
     agentCmd: opts.agentCmd,
     model: opts.model,
     timeout: opts.timeout,
-    logPath,
+    logPath: logPath2,
     cwd: opts.worktreePath,
     label,
     maxTurns: opts.maxTurns,
@@ -2226,20 +3568,31 @@ async function runPool(items, limit, fn) {
   return results;
 }
 __name(runPool, "runPool");
-function retryDelayFor(base, attempt) {
-  return base * 2 ** (attempt - 2);
-}
-__name(retryDelayFor, "retryDelayFor");
-function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
-}
-__name(sleep, "sleep");
 function attemptLogPath(logsDir, ticket, attempt, ext) {
   const stem = ticket.filename.replace(/\.md$/, "");
   const suffix = attempt > 1 ? `.attempt${attempt}` : "";
-  return join4(logsDir, `${stem}${suffix}${ext}`);
+  return join6(logsDir, `${stem}${suffix}${ext}`);
 }
 __name(attemptLogPath, "attemptLogPath");
+function buildHistory(learningsPath, ticket, d) {
+  try {
+    return renderHistory(selectHistory(
+      readEntries(learningsPath),
+      {
+        key: ticketKey(ticket.feature, ticket.num),
+        blockerKeys: ticket.blockers.map((b) => {
+          return ticketKey(ticket.feature, b);
+        })
+      }
+    ));
+  } catch (err) {
+    d.log(
+      `  ${ticket.filename}: could not read learnings: ${formatErrorMessage(err)}`
+    );
+    return "";
+  }
+}
+__name(buildHistory, "buildHistory");
 async function runTicketAttempt(opts) {
   const { ticket, d } = opts;
   let worktree;
@@ -2258,6 +3611,38 @@ async function runTicketAttempt(opts) {
     "in-progress",
     ticket.feature
   );
+  if (opts.installCmd) {
+    const installed = await runInstall({
+      installCmd: opts.installCmd,
+      ticket,
+      worktreePath: worktree.worktreePath,
+      timeout: opts.timeout,
+      logsDir: opts.logsDir,
+      attempt: opts.attempt,
+      log: /* @__PURE__ */ __name((msg) => d.log(msg), "log"),
+      registry: runningAgents
+    });
+    if (!installed) {
+      await removeWorktreeQuietly(
+        worktree.worktreePath,
+        d
+      );
+      return {
+        kind: "failed",
+        reason: "install",
+        branchName: worktree.branchName,
+        exitCode: 1,
+        completedItems: []
+      };
+    }
+  }
+  try {
+    ensureNotesIgnored(worktree.worktreePath);
+  } catch (err) {
+    d.log(
+      `  ${ticket.filename}: could not set up the notes directory: ${formatErrorMessage(err)}`
+    );
+  }
   const ticketSpec = lookupSpec(
     opts.specBodies,
     opts.specBody,
@@ -2267,7 +3652,17 @@ async function runTicketAttempt(opts) {
     prompt: renderPrompt(
       ticketSpec,
       ticket,
-      { testCmd: opts.testCmd }
+      {
+        testCmd: opts.testCmd,
+        installCmd: opts.installCmd,
+        // Rebuilt every attempt, so a retry sees the
+        // entry its previous attempt just wrote
+        history: buildHistory(
+          opts.learningsPath,
+          ticket,
+          d
+        )
+      }
     ),
     agentCmd: opts.agentCmd,
     model: opts.model,
@@ -2284,6 +3679,20 @@ async function runTicketAttempt(opts) {
     effort: opts.effort,
     onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
   });
+  let notes = null;
+  try {
+    notes = collectNotes(worktree.worktreePath);
+  } catch (err) {
+    d.log(
+      `  ${ticket.filename}: could not collect notes: ${formatErrorMessage(err)}`
+    );
+  }
+  const agentRun = {
+    exitCode: agentResult.exitCode,
+    completedItems: agentResult.completedItems,
+    timedOut: agentResult.timedOut,
+    notes
+  };
   if (agentResult.timedOut) {
     d.log(
       `  ${ticket.filename}: timed out; keeping the work it committed`
@@ -2298,7 +3707,8 @@ async function runTicketAttempt(opts) {
       reason: "exit",
       branchName: worktree.branchName,
       exitCode: agentResult.exitCode,
-      completedItems: agentResult.completedItems
+      completedItems: agentResult.completedItems,
+      agentRun
     };
   }
   if (isDirty(worktree.worktreePath)) {
@@ -2321,7 +3731,8 @@ async function runTicketAttempt(opts) {
     return {
       kind: "no-commits",
       worktreePath: worktree.worktreePath,
-      branchName: worktree.branchName
+      branchName: worktree.branchName,
+      agentRun
     };
   }
   const passed = await runTestGate({
@@ -2344,44 +3755,130 @@ async function runTicketAttempt(opts) {
       reason: "tests",
       branchName: worktree.branchName,
       exitCode: 1,
-      completedItems: agentResult.completedItems
+      completedItems: agentResult.completedItems,
+      agentRun
     };
   }
   return {
     kind: "ready",
     worktreePath: worktree.worktreePath,
     branchName: worktree.branchName,
-    completedItems: agentResult.completedItems
+    completedItems: agentResult.completedItems,
+    agentRun
   };
 }
 __name(runTicketAttempt, "runTicketAttempt");
-async function runTicketAttempts(opts) {
-  const { ticket, d } = opts;
-  const maxAttempts = opts.retries + 1;
-  const providerName = basename2(opts.agentCmd);
-  const isKnown = providerName in EFFORT_LADDERS;
-  let effort = opts.effort;
-  let outcome = {
-    kind: "no-commits",
-    worktreePath: "",
-    branchName: ""
+function readLogTail(path) {
+  try {
+    return tailLines(readFileSync6(path, "utf8"), LOG_TAIL_LINES);
+  } catch {
+    return "";
+  }
+}
+__name(readLogTail, "readLogTail");
+function attemptEntry(opts) {
+  const { logsDir, ticket, attempt, effort, outcome } = opts;
+  const base = {
+    key: ticketKey(ticket.feature, ticket.num),
+    label: ticketLabel(ticket),
+    attempt,
+    now: /* @__PURE__ */ new Date()
   };
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    if (attempt === 1) {
-      d.log(`  Starting ${ticket.filename}`);
-    } else {
-      if (isKnown) {
-        effort = escalateEffort(
-          providerName,
-          effort
-        );
+  const logFor = /* @__PURE__ */ __name((ext) => {
+    const path = attemptLogPath(logsDir, ticket, attempt, ext);
+    return { logName: basename5(path), logTail: readLogTail(path) };
+  }, "logFor");
+  switch (outcome.kind) {
+    case "ready":
+      return {
+        ...base,
+        outcome: "done",
+        run: outcome.agentRun,
+        effort
+      };
+    case "failed":
+      switch (outcome.reason) {
+        case "exit":
+          return {
+            ...base,
+            outcome: "exit",
+            run: outcome.agentRun,
+            effort
+          };
+        case "tests":
+          return {
+            ...base,
+            outcome: "tests",
+            run: outcome.agentRun,
+            effort,
+            ...logFor(".test.log")
+          };
+        case "install":
+          return {
+            ...base,
+            outcome: "install",
+            ...logFor(".install.log")
+          };
+        default: {
+          const _exhaustive = outcome;
+          return _exhaustive;
+        }
       }
-      const delay = retryDelayFor(opts.retryDelay, attempt);
-      d.log(
-        `  ${ticket.filename}: retrying (attempt ${attempt}/${maxAttempts}` + (isKnown && effort ? `, effort ${effort}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
-      );
-      if (delay > 0) await sleep(delay * 1e3);
+    case "no-commits":
+      return {
+        ...base,
+        outcome: "no-commits",
+        run: outcome.agentRun,
+        effort
+      };
+    case "error":
+    case "worktree-error":
+      return {
+        ...base,
+        outcome: "error",
+        error: formatErrorMessage(outcome.error)
+      };
+    default: {
+      const _exhaustive = outcome;
+      return _exhaustive;
     }
+  }
+}
+__name(attemptEntry, "attemptEntry");
+function recordAttempt(opts) {
+  try {
+    const entry = attemptEntry(opts);
+    if (!entry) return;
+    appendEntry(opts.learningsPath, renderEntry(entry));
+  } catch (err) {
+    opts.d.log(
+      `  ${opts.ticket.filename}: could not record learnings: ${formatErrorMessage(err)}`
+    );
+  }
+}
+__name(recordAttempt, "recordAttempt");
+async function runTicketAttempts(opts) {
+  const { ticket, d } = opts;
+  return runWithRetries({
+    maxAttempts: opts.retries + 1,
+    retryDelay: opts.retryDelay,
+    agentCmd: opts.agentCmd,
+    effort: opts.effort,
+    label: ticket.filename,
+    log: /* @__PURE__ */ __name((msg) => d.log(msg), "log")
+  }, async (attempt, effort) => {
+    const record = /* @__PURE__ */ __name((o) => {
+      recordAttempt({
+        learningsPath: opts.learningsPath,
+        logsDir: opts.logsDir,
+        ticket,
+        attempt,
+        effort,
+        outcome: o,
+        d
+      });
+    }, "record");
+    let outcome;
     try {
       outcome = await runTicketAttempt({
         ...opts,
@@ -2392,25 +3889,46 @@ async function runTicketAttempts(opts) {
       d.log(
         `  ${ticket.filename}: attempt ${attempt} threw: ${formatErrorMessage(error)}`
       );
-      return { kind: "error", error };
+      const errorOutcome = { kind: "error", error };
+      record(errorOutcome);
+      return { result: errorOutcome, stop: true };
     }
+    record(outcome);
     if (outcome.kind === "ready") {
       d.setTicketStatus(
         ticket.num,
         "awaiting-merge",
         ticket.feature
       );
-      return outcome;
+      return { result: outcome, stop: true };
     }
-    if (outcome.kind === "worktree-error") return outcome;
-  }
-  return outcome;
+    return {
+      result: outcome,
+      stop: outcome.kind === "worktree-error"
+    };
+  });
 }
 __name(runTicketAttempts, "runTicketAttempts");
+function failureNote(reason) {
+  if (reason === "tests") return "tests failed";
+  if (reason === "install") return "install failed";
+  return "failed";
+}
+__name(failureNote, "failureNote");
+function isRegularFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+__name(isRegularFile, "isRegularFile");
 async function saveProgress(repoRoot, progressPath, progress, message, d) {
   writeProgress(progressPath, progress);
+  const learningsPath = learningsPathFor(progressPath);
+  const paths = isRegularFile(learningsPath) ? [progressPath, learningsPath] : progressPath;
   try {
-    await commitProgress(repoRoot, progressPath, message);
+    await commitProgress(repoRoot, paths, message);
   } catch (err) {
     d.log(
       "  Failed to commit progress: " + formatErrorMessage(err)
@@ -2480,6 +3998,29 @@ function renderFinishSummary(tickets, totalCompleted, failedKeys) {
   return lines.join("\n");
 }
 __name(renderFinishSummary, "renderFinishSummary");
+function sessionTickets(tickets) {
+  return [...tickets].filter((t) => t.status === "ready-for-agent").sort((a, b) => a.feature.localeCompare(b.feature) || a.num - b.num);
+}
+__name(sessionTickets, "sessionTickets");
+function toRef(t) {
+  return { num: t.num, filename: t.filename, feature: t.feature };
+}
+__name(toRef, "toRef");
+function reportBlocked(d, tickets, failedKeys) {
+  const byKey = new Map(
+    tickets.map((t) => [ticketKey(t.feature, t.num), t])
+  );
+  for (const [key, dead] of findBlockedTickets(
+    tickets,
+    failedKeys
+  )) {
+    const ticket = byKey.get(key);
+    if (!ticket) continue;
+    const labels = dead.map((k) => byKey.get(k)).filter((t) => t !== void 0).map((t) => ticketLabel(toRef(t)));
+    d.setBlocked(ticket.num, ticket.feature, labels);
+  }
+}
+__name(reportBlocked, "reportBlocked");
 function runProgress(tickets) {
   return {
     completed: tickets.filter((t) => t.status === "done").length,
@@ -2488,19 +4029,21 @@ function runProgress(tickets) {
 }
 __name(runProgress, "runProgress");
 async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, testCmd, display, maxTurns, effort, retries, retryDelay, concurrency) {
-  mkdirSync2(logsDir, { recursive: true });
+  mkdirSync3(logsDir, { recursive: true });
   const d = display ?? createDisplay();
   const maxAttempts = (retries ?? DEFAULT_RETRIES) + 1;
   const delayBase = retryDelay ?? 0;
   const poolSize = concurrency ?? DEFAULT_CONCURRENCY;
-  const providerName = basename2(agentCmd);
+  const providerName = basename5(agentCmd);
   const isKnown = providerName in EFFORT_LADDERS;
   let totalWaves = 0;
   for (const _ of simulateWaves(tickets)) totalWaves++;
   let totalCompleted = 0;
   let waveNum = 0;
   const failedKeys = /* @__PURE__ */ new Set();
+  const session = sessionTickets(tickets);
   while (true) {
+    if (waveNum > 0) reportBlocked(d, tickets, failedKeys);
     const ready = findReadyTickets(tickets).filter(
       (t) => !failedKeys.has(
         ticketKey(t.feature, t.num)
@@ -2508,12 +4051,10 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
     );
     if (ready.length === 0) break;
     waveNum++;
-    const readyKeys = new Set(
-      ready.map((t) => ticketKey(t.feature, t.num))
-    );
-    const remaining2 = tickets.filter(
-      (t) => t.status === "ready-for-agent" && !readyKeys.has(ticketKey(t.feature, t.num))
-    );
+    if (waveNum === 1) {
+      d.startRun(session.map(toRef));
+      reportBlocked(d, tickets, failedKeys);
+    }
     d.startWave(
       waveNum,
       totalWaves,
@@ -2522,12 +4063,7 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
         filename: t.filename,
         feature: t.feature
       })),
-      runProgress(tickets),
-      remaining2.map((t) => ({
-        num: t.num,
-        filename: t.filename,
-        feature: t.feature
-      }))
+      runProgress(session)
     );
     const results = await runPool(
       ready,
@@ -2624,10 +4160,10 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
       );
     }
     if (waveCompleted === 0) {
-      const remaining3 = findReadyTickets(tickets).filter((t) => !failedKeys.has(
+      const remaining2 = findReadyTickets(tickets).filter((t) => !failedKeys.has(
         ticketKey(t.feature, t.num)
       ));
-      if (remaining3.length === 0) {
+      if (remaining2.length === 0) {
         d.log(
           "\nNo tickets completed this wave and no ready tickets remain. Stopping."
         );
@@ -2635,10 +4171,11 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
       }
       d.log(
         `
-No tickets completed this wave. ${remaining3.length} ready ticket${remaining3.length === 1 ? "" : "s"} remain; continuing.`
+No tickets completed this wave. ${remaining2.length} ready ticket${remaining2.length === 1 ? "" : "s"} remain; continuing.`
       );
     }
   }
+  if (waveNum > 0) reportBlocked(d, tickets, failedKeys);
   const remaining = tickets.filter(
     (t) => t.status === "ready-for-agent"
   );
@@ -2652,7 +4189,7 @@ No tickets completed this wave. ${remaining3.length} ready ticket${remaining3.le
 }
 __name(runWaves, "runWaves");
 async function runWavesIsolated(opts) {
-  mkdirSync2(opts.logsDir, { recursive: true });
+  mkdirSync3(opts.logsDir, { recursive: true });
   const d = opts.display ?? createDisplay();
   const retries = opts.retries ?? DEFAULT_RETRIES;
   const retryDelay = opts.retryDelay ?? 0;
@@ -2667,12 +4204,13 @@ async function runWavesIsolated(opts) {
       "Working tree is dirty; commit or stash changes before running"
     );
   }
+  const launchCommit = headCommit(repoRoot);
   const features = new Set(
     opts.tickets.map((t) => t.feature).filter(Boolean)
   );
   const multiFeature = features.size > 1 && opts.progressPaths !== void 0;
-  const fallbackProgressPath = join4(
-    dirname2(opts.logsDir),
+  const fallbackProgressPath = join6(
+    dirname4(opts.logsDir),
     "progress.md"
   );
   let tracker;
@@ -2731,7 +4269,9 @@ async function runWavesIsolated(opts) {
   let totalCompleted = 0;
   let waveNum = 0;
   const failedKeys = /* @__PURE__ */ new Set();
+  const session = sessionTickets(opts.tickets);
   while (true) {
+    if (waveNum > 0) reportBlocked(d, opts.tickets, failedKeys);
     const ready = findReadyTickets(opts.tickets).filter(
       (t) => !failedKeys.has(
         ticketKey(t.feature, t.num)
@@ -2739,12 +4279,10 @@ async function runWavesIsolated(opts) {
     );
     if (ready.length === 0) break;
     waveNum++;
-    const readyKeys = new Set(
-      ready.map((t) => ticketKey(t.feature, t.num))
-    );
-    const remaining2 = opts.tickets.filter(
-      (t) => t.status === "ready-for-agent" && !readyKeys.has(ticketKey(t.feature, t.num))
-    );
+    if (waveNum === 1) {
+      d.startRun(session.map(toRef));
+      reportBlocked(d, opts.tickets, failedKeys);
+    }
     d.startWave(
       waveNum,
       totalWaves,
@@ -2753,12 +4291,7 @@ async function runWavesIsolated(opts) {
         filename: t.filename,
         feature: t.feature
       })),
-      runProgress(opts.tickets),
-      remaining2.map((t) => ({
-        num: t.num,
-        filename: t.filename,
-        feature: t.feature
-      }))
+      runProgress(session)
     );
     const settled = await runPool(
       ready,
@@ -2775,13 +4308,34 @@ async function runWavesIsolated(opts) {
         timeout: opts.timeout,
         logsDir: opts.logsDir,
         testCmd: opts.testCmd,
+        installCmd: opts.installCmd,
         maxTurns: opts.maxTurns,
         effort: opts.effort,
+        learningsPath: learningsPathFor(
+          tracker.pathFor(t.feature)
+        ),
         retries,
         retryDelay,
         d
       })
     );
+    const touched = new Set(ready.map((t) => {
+      return learningsPathFor(tracker.pathFor(t.feature));
+    }));
+    for (const path of touched) {
+      if (!isRegularFile(path)) continue;
+      try {
+        await commitProgress(
+          repoRoot,
+          path,
+          "nightralph: record attempt learnings"
+        );
+      } catch (err) {
+        d.log(
+          "  Failed to commit learnings: " + formatErrorMessage(err)
+        );
+      }
+    }
     const outcomes = settled.map(
       (r) => r.status === "fulfilled" ? r.value : { kind: "error", error: r.reason }
     );
@@ -2885,7 +4439,7 @@ async function runWavesIsolated(opts) {
           repoRoot,
           tracker.pathFor(ticket.feature),
           tracker.dataFor(ticket.feature),
-          `nightralph: ${ticket.filename} ` + (outcome.reason === "tests" ? "tests failed" : "failed"),
+          `nightralph: ${ticket.filename} ` + failureNote(outcome.reason),
           d
         );
         continue;
@@ -2921,6 +4475,7 @@ async function runWavesIsolated(opts) {
         branches: successfulBranches,
         strategy: opts.conflictStrategy
       });
+      const doneThisWave = [];
       for (const branchResult of mergeResult.merged) {
         const bk = branchToKey.get(
           branchResult.branch
@@ -2929,6 +4484,7 @@ async function runWavesIsolated(opts) {
         if (!ticket) continue;
         if (branchResult.merged) {
           markDone(ticket);
+          doneThisWave.push(ticket);
           waveCompleted++;
           totalCompleted++;
           d.setTicketStatus(
@@ -2978,11 +4534,13 @@ async function runWavesIsolated(opts) {
             timeout: opts.timeout,
             logsDir: opts.logsDir,
             testCmd: opts.testCmd,
+            installCmd: opts.installCmd,
             maxTurns: opts.maxTurns,
             onLine: /* @__PURE__ */ __name((msg) => d.log(msg), "onLine")
           }) : false;
           if (recovered) {
             markDone(ticket);
+            doneThisWave.push(ticket);
             waveCompleted++;
             totalCompleted++;
             d.setTicketStatus(
@@ -3020,6 +4578,11 @@ async function runWavesIsolated(opts) {
             failedKeys.add(
               ticketKey(ticket.feature, ticket.num)
             );
+            d.setTicketStatus(
+              ticket.num,
+              "failed",
+              ticket.feature
+            );
             d.log(
               `  ${ticket.filename}: merge failed, staying ready-for-agent`
             );
@@ -3033,6 +4596,28 @@ async function runWavesIsolated(opts) {
               exitCode: 0,
               done: false
             });
+            try {
+              appendEntry(
+                learningsPathFor(
+                  tracker.pathFor(ticket.feature)
+                ),
+                renderEntry({
+                  outcome: "merge",
+                  key: ticketKey(
+                    ticket.feature,
+                    ticket.num
+                  ),
+                  label: ticketLabel(ticket),
+                  attempt: 0,
+                  now: /* @__PURE__ */ new Date(),
+                  stderr: branchResult.stderr ?? ""
+                })
+              );
+            } catch (err) {
+              d.log(
+                `  ${ticket.filename}: could not record learnings: ` + formatErrorMessage(err)
+              );
+            }
             await saveProgress(
               repoRoot,
               tracker.pathFor(ticket.feature),
@@ -3043,6 +4628,7 @@ async function runWavesIsolated(opts) {
           }
         }
       }
+      await commitTicketFiles(repoRoot, doneThisWave, d);
       if (mergeResult.stoppedAt) {
         d.log(
           `
@@ -3067,12 +4653,12 @@ Merge stopped at ${mergeResult.stoppedAt.branch}`
       }
     }
     if (waveCompleted === 0) {
-      const remaining3 = findReadyTickets(
+      const remaining2 = findReadyTickets(
         opts.tickets
       ).filter((t) => !failedKeys.has(
         ticketKey(t.feature, t.num)
       ));
-      if (remaining3.length === 0) {
+      if (remaining2.length === 0) {
         d.log(
           "\nNo tickets completed this wave and no ready tickets remain. Stopping."
         );
@@ -3080,8 +4666,44 @@ Merge stopped at ${mergeResult.stoppedAt.branch}`
       }
       d.log(
         `
-No tickets completed this wave. ${remaining3.length} ready ticket${remaining3.length === 1 ? "" : "s"} remain; continuing.`
+No tickets completed this wave. ${remaining2.length} ready ticket${remaining2.length === 1 ? "" : "s"} remain; continuing.`
+      );
+    }
+  }
+  if (waveNum > 0) reportBlocked(d, opts.tickets, failedKeys);
+  let reviewLine = null;
+  if (opts.review) {
+    try {
+      const outcome = await runReviewPass({
+        repoRoot,
+        repoName,
+        baseBranch,
+        reviewPath: opts.review.reviewPath,
+        forkedFrom: opts.review.forkedFrom,
+        launchCommit,
+        specBody: reviewSpecBody(
+          opts.specBody,
+          opts.specBodies
+        ),
+        agentCmd: opts.agentCmd,
+        model: opts.model,
+        timeout: opts.timeout,
+        logsDir: opts.logsDir,
+        testCmd: opts.testCmd,
+        installCmd: opts.installCmd,
+        maxTurns: opts.maxTurns,
+        effort: opts.effort,
+        retries,
+        retryDelay,
+        log: /* @__PURE__ */ __name((msg) => d.log(msg), "log")
+      }, { spawnAgent, registry: runningAgents });
+      reviewLine = renderReviewSummary(
+        outcome,
+        relative2(repoRoot, opts.review.reviewPath)
       );
+    } catch (err) {
+      d.log(`
+Review failed: ${formatErrorMessage(err)}`);
     }
   }
   const remaining = opts.tickets.filter(
@@ -3092,23 +4714,55 @@ No tickets completed this wave. ${remaining3.length} ready ticket${remaining3.le
     totalCompleted,
     failedKeys
   ));
+  if (reviewLine) d.log(reviewLine);
+  d.log(`Work is on ${baseBranch}`);
   d.cleanup();
-  return { allDone: remaining.length === 0 };
+  return { allDone: remaining.length === 0, branch: baseBranch };
 }
 __name(runWavesIsolated, "runWavesIsolated");
 
+// src/preflight.ts
+import { accessSync, constants, statSync as statSync2 } from "node:fs";
+import { delimiter, join as join7, resolve as resolve2 } from "node:path";
+function isExecutableFile(file) {
+  try {
+    if (!statSync2(file).isFile()) return false;
+    accessSync(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isExecutableFile, "isExecutableFile");
+function resolveExecutable(cmd, opts = {}) {
+  if (cmd === "") return null;
+  const cwd = opts.cwd ?? process.cwd();
+  if (cmd.includes("/")) {
+    const full = resolve2(cwd, cmd);
+    return isExecutableFile(full) ? full : null;
+  }
+  const path = opts.path ?? process.env.PATH ?? "";
+  for (const dir of path.split(delimiter)) {
+    if (dir === "") continue;
+    const candidate = join7(dir, cmd);
+    if (isExecutableFile(candidate)) return candidate;
+  }
+  return null;
+}
+__name(resolveExecutable, "resolveExecutable");
+
 // src/resolve.ts
-import { existsSync as existsSync4, readdirSync as readdirSync3 } from "node:fs";
-import { dirname as dirname3, join as join5 } from "node:path";
+import { existsSync as existsSync6, readdirSync as readdirSync3 } from "node:fs";
+import { dirname as dirname5, join as join8 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { checkbox, Separator } from "@inquirer/prompts";
 function getScriptDir(metaUrl) {
-  return dirname3(fileURLToPath(metaUrl));
+  return dirname5(fileURLToPath(metaUrl));
 }
 __name(getScriptDir, "getScriptDir");
 function findFeatureDirs(cwd) {
-  const scratchDir = join5(cwd, ".scratch");
-  if (!existsSync4(scratchDir)) return [];
+  const scratchDir = join8(cwd, ".scratch");
+  if (!existsSync6(scratchDir)) return [];
   const entries = readdirSync3(
     scratchDir,
     { withFileTypes: true }
@@ -3116,18 +4770,18 @@ function findFeatureDirs(cwd) {
   const results = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const issuesDir = join5(
+    const issuesDir = join8(
       scratchDir,
       entry.name,
       "issues"
     );
-    const specFile = join5(
+    const specFile = join8(
       scratchDir,
       entry.name,
       "spec.md"
     );
-    if (!existsSync4(issuesDir)) continue;
-    const progressFile = join5(
+    if (!existsSync6(issuesDir)) continue;
+    const progressFile = join8(
       scratchDir,
       entry.name,
       "progress.md"
@@ -3146,10 +4800,10 @@ __name(findFeatureDirs, "findFeatureDirs");
 var ALL_VALUE = "__all__";
 async function resolveIssuesDir(specName, cwd = process.cwd()) {
   if (specName) {
-    const featureDir = join5(cwd, ".scratch", specName);
+    const featureDir = join8(cwd, ".scratch", specName);
     return [{
-      dir: join5(featureDir, "issues"),
-      spec: join5(featureDir, "spec.md"),
+      dir: join8(featureDir, "issues"),
+      spec: join8(featureDir, "spec.md"),
       name: specName
     }];
   }
@@ -3228,8 +4882,8 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
       }
     }
     setup({
-      bundledSkillsDir: join6(scriptDir, "skills"),
-      docsTemplatesDir: join6(
+      bundledSkillsDir: join9(scriptDir, "skills"),
+      docsTemplatesDir: join9(
         scriptDir,
         "docs-templates"
       ),
@@ -3264,7 +4918,10 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
     default: 3600
   }).option("test-cmd", {
     type: "string",
-    describe: 'Command run in each worktree after the agent exits; non-zero exit rejects the ticket. Defaults to "npm test".'
+    describe: 'Command run in each worktree after the agent exits; non-zero exit rejects the ticket. Defaults to "npm test" when package.json has a test script; otherwise the run has no test gate. "" disables it.'
+  }).option("install-cmd", {
+    type: "string",
+    describe: `Command run in each fresh worktree before the agent starts. Defaults to the install command for the project's lockfile (npm ci or pnpm install); "" disables it.`
   }).option("X", {
     type: "boolean",
     describe: "Stop on merge conflict instead of re-spawning",
@@ -3288,6 +4945,10 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
     type: "number",
     default: DEFAULT_CONCURRENCY,
     describe: "Max agents running at once within a wave."
+  }).option("review", {
+    type: "boolean",
+    default: true,
+    describe: "Review the merged work and run one fix pass at the end. --no-review skips it."
   }),
   async (argv) => {
     await runExecute({
@@ -3297,15 +4958,26 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
       dryRun: argv.dryRun,
       timeout: argv.timeout,
       testCmd: argv.testCmd,
+      installCmd: argv.installCmd,
       stopOnConflict: argv.X,
       maxTurns: argv.maxTurns ?? argv.turns,
       effort: argv.effort,
       retries: argv.retries,
       retryDelay: argv.retryDelay,
-      concurrency: argv.concurrency
+      concurrency: argv.concurrency,
+      review: argv.review
     });
   }
-).strict().demandCommand(1, "Specify a command or provider").help().parse();
+).strict().demandCommand(1, "Specify a command or provider").help().fail((msg, err, y) => {
+  if (err && !msg) {
+    console.error(formatErrorMessage(err));
+    process.exit(2);
+  }
+  y.showHelp();
+  console.error(`
+${msg}`);
+  process.exit(1);
+}).parse();
 function isGitRepo() {
   try {
     getRepoRoot();
@@ -3326,41 +4998,36 @@ function extractFeatureName(spec) {
   return parts[parts.length - 2] ?? parts[parts.length - 1] ?? "feature";
 }
 __name(extractFeatureName, "extractFeatureName");
-async function runExecute(argv) {
-  const selections = await resolveIssuesDir(
-    argv.spec
-  );
+function loadTickets(selections, log) {
   const allTickets = [];
   const specBodies = /* @__PURE__ */ new Map();
   const progressPaths = /* @__PURE__ */ new Map();
+  const issuesDirs = [];
   let firstFeatureName = "";
   let firstLogsDir = "";
+  const missing = [];
   for (const selection of selections) {
     const { dir, spec, name } = selection;
-    if (!existsSync5(dir)) {
-      console.error(
-        `Directory not found: ${dir}`
-      );
-      process.exit(2);
+    if (!existsSync7(dir)) {
+      missing.push(`Directory not found: ${dir}`);
+      continue;
     }
-    if (!existsSync5(spec)) {
-      console.error(
-        `Spec file not found: ${spec}`
-      );
-      process.exit(2);
+    if (!existsSync7(spec)) {
+      missing.push(`Spec file not found: ${spec}`);
+      continue;
     }
     const specBody = stripSpecSection(
-      readFileSync5(spec, "utf8"),
+      readFileSync7(spec, "utf8"),
       "User Stories"
     );
     const tickets = scanTickets(dir, name);
     if (tickets.length === 0) {
-      console.log(
+      log(
         `No ticket files found for ${name}. Skipping.`
       );
       continue;
     }
-    console.log(
+    log(
       `[${name}] Found ${tickets.length} tickets`
     );
     const knownNums = new Set(
@@ -3371,7 +5038,7 @@ async function runExecute(argv) {
         (b) => !knownNums.has(b)
       );
       if (unknown.length > 0) {
-        console.warn(
+        log(
           `${t.filename}: blockers [${unknown.join(", ")}] not found in directory`
         );
       }
@@ -3382,24 +5049,128 @@ async function runExecute(argv) {
     specBodies.set(name, specBody);
     progressPaths.set(
       name,
-      join6(dirname4(dir), "progress.md")
+      join9(dirname6(dir), "progress.md")
     );
+    issuesDirs.push(dir);
     allTickets.push(...tickets);
     if (!firstFeatureName) {
       firstFeatureName = extractFeatureName(spec);
-      firstLogsDir = join6(dirname4(dir), "logs");
+      firstLogsDir = join9(dirname6(dir), "logs");
+    }
+  }
+  return {
+    allTickets,
+    specBodies,
+    progressPaths,
+    issuesDirs,
+    firstFeatureName,
+    firstLogsDir,
+    missing
+  };
+}
+__name(loadTickets, "loadTickets");
+function loadTicketsOrExit(selections) {
+  const loaded = loadTickets(selections, console.log);
+  if (loaded.missing.length > 0) {
+    for (const msg of loaded.missing) console.error(msg);
+    process.exit(2);
+  }
+  return loaded;
+}
+__name(loadTicketsOrExit, "loadTicketsOrExit");
+function failStaleResume(plan, problems) {
+  try {
+    execFileSync2(
+      "git",
+      ["checkout", "--quiet", plan.launchBranch],
+      { cwd: getRepoRoot(), stdio: "ignore" }
+    );
+  } catch {
+  }
+  const n = plan.behind;
+  console.error(
+    `Cannot resume ${plan.branch}: ${problems.join("; ")}. It is ${n} commit${n === 1 ? "" : "s"} behind ${plan.launchBranch}. Merge ${plan.launchBranch} into it, or delete it with \`git branch -D ${plan.branch}\`. Back on ${plan.launchBranch}.`
+  );
+  process.exit(2);
+}
+__name(failStaleResume, "failStaleResume");
+function reviewPathFor(issuesDirs) {
+  const featureDir = dirname6(issuesDirs[0]);
+  return issuesDirs.length === 1 ? join9(featureDir, "review.md") : join9(dirname6(featureDir), "review.md");
+}
+__name(reviewPathFor, "reviewPathFor");
+async function runExecute(argv) {
+  const selections = await resolveIssuesDir(
+    argv.spec
+  );
+  let loaded = loadTicketsOrExit(selections);
+  if (loaded.allTickets.length === 0) return;
+  const providerPath = resolveExecutable(argv.provider);
+  const providerIsPath = argv.provider.includes("/");
+  const providerMissing = providerIsPath ? "not found or not executable" : "not found on PATH";
+  if (providerPath === null && !argv.dryRun) {
+    console.error(
+      `Provider '${argv.provider}' ${providerMissing}`
+    );
+    process.exit(2);
+  }
+  const agentCmd = providerIsPath ? providerPath ?? argv.provider : argv.provider;
+  const isolated = isGitRepo();
+  const featureNames = [...loaded.specBodies.keys()];
+  let plan = null;
+  if (isolated && !argv.dryRun) {
+    try {
+      plan = prepareIntegrationBranch(
+        getRepoRoot(),
+        featureNames
+      );
+    } catch (err) {
+      console.error(formatErrorMessage(err));
+      process.exit(2);
+    }
+    if (plan.created) {
+      console.log(
+        `Created branch ${plan.branch} from ${plan.launchBranch}`
+      );
+    } else if (plan.resumed) {
+      console.log(
+        `Resumed ${plan.branch}` + (plan.fastForwarded ? ` (fast-forwarded to ${plan.launchBranch})` : "") + (plan.behind > 0 ? ` (${plan.launchBranch} is ${plan.behind} commit${plan.behind === 1 ? "" : "s"} ahead)` : "")
+      );
+      loaded = loadTickets(selections, () => {
+      });
+      if (loaded.missing.length > 0) {
+        failStaleResume(plan, loaded.missing);
+      }
+      if (loaded.allTickets.length === 0) {
+        failStaleResume(plan, ["no tickets"]);
+      }
     }
   }
-  if (allTickets.length === 0) return;
+  const {
+    allTickets,
+    specBodies,
+    progressPaths,
+    firstFeatureName,
+    firstLogsDir
+  } = loaded;
   const timeout = argv.timeout ?? 900;
-  const testCmd = argv.testCmd || detectTestCmd(
-    isGitRepo() ? getRepoRoot() : process.cwd()
-  ) || "npm test";
+  const testCmd = argv.testCmd ?? detectTestCmd(
+    isolated ? getRepoRoot() : process.cwd()
+  ) ?? "";
+  if (argv.testCmd === void 0 && testCmd === "") {
+    console.log(
+      "No test command detected; running without a test gate. Pass --test-cmd to add one."
+    );
+  }
+  const installCmd = argv.installCmd ?? (isolated ? detectInstallCmd(getRepoRoot()) ?? void 0 : void 0);
   const conflictStrategy = argv.stopOnConflict ? "stop" : "respawn";
   const logsDir = firstLogsDir;
   const fallbackSpec = specBodies.values().next().value;
   if (argv.dryRun) {
-    if (isGitRepo()) {
+    console.log(
+      `Provider:     ${providerPath ?? providerMissing}`
+    );
+    if (isolated) {
       const repoName = getRepoName();
       dryRunIsolated({
         tickets: allTickets,
@@ -3408,11 +5179,20 @@ async function runExecute(argv) {
         conflictStrategy,
         progressPath: progressPaths.values().next().value,
         testCmd,
+        installCmd,
         effort: argv.effort,
         retries: argv.retries,
         retryDelay: argv.retryDelay,
         concurrency: argv.concurrency
       });
+      console.log(
+        describeIntegrationBranch(
+          getRepoRoot(),
+          featureNames
+        )
+      );
+      const reviewState = argv.review === false ? "off" : "on";
+      console.log(`Review:       ${reviewState}`);
     } else {
       dryRun(allTickets, fallbackSpec, testCmd);
     }
@@ -3428,12 +5208,12 @@ async function runExecute(argv) {
   process.on("SIGINT", () => onSignal(130));
   process.on("SIGTERM", () => onSignal(143));
   let result;
-  if (isGitRepo()) {
+  if (isolated) {
     result = await runWavesIsolated({
       tickets: allTickets,
       specBody: fallbackSpec,
       specBodies,
-      agentCmd: argv.provider,
+      agentCmd,
       model: argv.model ?? null,
       timeout,
       logsDir,
@@ -3441,18 +5221,23 @@ async function runExecute(argv) {
       conflictStrategy,
       display,
       testCmd,
+      installCmd,
       maxTurns: argv.maxTurns,
       effort: argv.effort,
       retries: argv.retries,
       retryDelay: argv.retryDelay,
       concurrency: argv.concurrency,
-      progressPaths
+      progressPaths,
+      review: argv.review === false ? void 0 : {
+        reviewPath: reviewPathFor(loaded.issuesDirs),
+        forkedFrom: plan?.forkedFrom ?? void 0
+      }
     });
   } else {
     result = await runWaves(
       allTickets,
       fallbackSpec,
-      argv.provider,
+      agentCmd,
       argv.model ?? null,
       timeout,
       logsDir,