nightralph 0.0.53 → 0.0.56

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 { basename as basename6, 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;
@@ -778,6 +973,106 @@ async function mergeWave(opts) {
 }
 __name(mergeWave, "mergeWave");
 
+// src/stats.ts
+var SUBAGENT_TOOLS = /* @__PURE__ */ new Set(["Agent", "Task"]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(isRecord, "isRecord");
+function emptyStreamStats() {
+  return { stats: { subagents: 0 }, seenToolIds: /* @__PURE__ */ new Set() };
+}
+__name(emptyStreamStats, "emptyStreamStats");
+function nextStreamStats(state, obj) {
+  if (!isRecord(obj)) return state;
+  if (obj.type === "assistant") return countSubagents(state, obj);
+  if (obj.type === "result") return applyResult(state, obj);
+  return state;
+}
+__name(nextStreamStats, "nextStreamStats");
+function countSubagents(state, obj) {
+  if (obj.parent_tool_use_id != null) return state;
+  const message = obj.message;
+  if (!isRecord(message) || !Array.isArray(message.content)) {
+    return state;
+  }
+  const ids = [];
+  for (const block of message.content) {
+    if (!isRecord(block) || block.type !== "tool_use") continue;
+    if (typeof block.name !== "string" || !SUBAGENT_TOOLS.has(block.name)) continue;
+    if (typeof block.id !== "string") continue;
+    if (state.seenToolIds.has(block.id)) continue;
+    if (ids.includes(block.id)) continue;
+    ids.push(block.id);
+  }
+  if (ids.length === 0) return state;
+  return {
+    stats: {
+      ...state.stats,
+      subagents: state.stats.subagents + ids.length
+    },
+    seenToolIds: /* @__PURE__ */ new Set([...state.seenToolIds, ...ids])
+  };
+}
+__name(countSubagents, "countSubagents");
+function applyResult(state, obj) {
+  const cost = obj.total_cost_usd;
+  const hasCost = typeof cost === "number" && Number.isFinite(cost);
+  const subagentStats = obj.subagent_stats;
+  const spawned = isRecord(subagentStats) ? subagentStats.spawned : void 0;
+  const hasSpawned = typeof spawned === "number" && Number.isInteger(spawned) && spawned >= 0;
+  if (!hasCost && !hasSpawned) return state;
+  const subagents = hasSpawned ? spawned : state.stats.subagents;
+  const costUsd = hasCost ? cost : state.stats.costUsd;
+  if (subagents === state.stats.subagents && costUsd === state.stats.costUsd) return state;
+  return {
+    stats: costUsd === void 0 ? { subagents } : { subagents, costUsd },
+    seenToolIds: state.seenToolIds
+  };
+}
+__name(applyResult, "applyResult");
+function addStats(total, run) {
+  const subagents = total.subagents + (run.subagents ?? 0);
+  if (total.costUsd === void 0 && run.costUsd === void 0) {
+    return { subagents };
+  }
+  return {
+    subagents,
+    costUsd: (total.costUsd ?? 0) + (run.costUsd ?? 0)
+  };
+}
+__name(addStats, "addStats");
+function formatStats(stats) {
+  if (!stats) return null;
+  if (stats.subagents === 0 && stats.costUsd === void 0) {
+    return null;
+  }
+  const count = `${stats.subagents} ` + (stats.subagents === 1 ? "subagent" : "subagents");
+  return stats.costUsd === void 0 ? count : `${count}, $${stats.costUsd.toFixed(2)}`;
+}
+__name(formatStats, "formatStats");
+function emptyRunStats() {
+  return { agentRuns: 0, withCost: 0, subagents: 0, costUsd: 0 };
+}
+__name(emptyRunStats, "emptyRunStats");
+function addRun(run, result) {
+  return {
+    agentRuns: run.agentRuns + 1,
+    withCost: run.withCost + (result.costUsd === void 0 ? 0 : 1),
+    subagents: run.subagents + (result.subagents ?? 0),
+    costUsd: run.costUsd + (result.costUsd ?? 0)
+  };
+}
+__name(addRun, "addRun");
+function renderRunStats(run) {
+  if (run.agentRuns === 0) return null;
+  if (run.withCost === 0 && run.subagents === 0) return null;
+  const runs = `${run.agentRuns} agent ` + (run.agentRuns === 1 ? "run" : "runs");
+  const partial = run.withCost < run.agentRuns ? ` (cost from ${run.withCost} of ${run.agentRuns} runs)` : "";
+  return `Subagents: ${run.subagents} started across ${runs}, cost $${run.costUsd.toFixed(2)}${partial}`;
+}
+__name(renderRunStats, "renderRunStats");
+
 // src/display.ts
 var ESC = "\x1B[";
 var ansi = {
@@ -839,10 +1134,9 @@ 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(", ")})`;
+  const base = ticket.status === "blocked" && ticket.blockedBy?.length ? `${label} (blocked by ${ticket.blockedBy.join(", ")})` : label;
+  const suffix = formatStats(ticket.stats);
+  return suffix === null ? base : `${base} - ${suffix}`;
 }
 __name(rowText, "rowText");
 function fitLine(line, width) {
@@ -971,6 +1265,12 @@ var StatusDisplay = class {
     ticket.blockedBy = [...blockedBy];
     this.render();
   }
+  setTicketStats(num, feature, stats) {
+    const ticket = this.findTicket(num, feature);
+    if (!ticket) return;
+    ticket.stats = { ...stats };
+    this.render();
+  }
   log(message) {
     if (!this.wave) {
       this.config.stream.write(message + "\n");
@@ -1105,95 +1405,1329 @@ var PlainDisplay = class {
 Wave ${waveNum}${pct}: ` + tickets.map((t) => ticketLabel(t)).join(", ")
     );
   }
-  setTicketStatus(_num, _status, _feature) {
-  }
-  setBlocked(_num, _feature, _blockedBy) {
-  }
-  log(message) {
-    console.log(message);
-  }
-  cleanup() {
-  }
-};
-function createDisplay(stream) {
-  const s = stream ?? process.stdout;
-  if (s.isTTY) {
-    return new StatusDisplay({ stream: s });
-  }
-  return new PlainDisplay();
+  setTicketStatus(_num, _status, _feature) {
+  }
+  setBlocked(_num, _feature, _blockedBy) {
+  }
+  setTicketStats(_num, _feature, _stats) {
+  }
+  log(message) {
+    console.log(message);
+  }
+  cleanup() {
+  }
+};
+function createDisplay(stream) {
+  const s = stream ?? process.stdout;
+  if (s.isTTY) {
+    return new StatusDisplay({ stream: s });
+  }
+  return new PlainDisplay();
+}
+__name(createDisplay, "createDisplay");
+
+// src/testcmd.ts
+import { spawn } from "node:child_process";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+function detectTestCmd(projectDir) {
+  const pkgPath = join3(projectDir, "package.json");
+  if (!existsSync3(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(
+      readFileSync3(pkgPath, "utf8")
+    );
+    return pkg.scripts?.test ? "npm test" : null;
+  } catch {
+    return null;
+  }
+}
+__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((resolve3) => {
+    let settled = false;
+    const child = spawn("sh", ["-c", opts.cmd], {
+      cwd: opts.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: true
+    });
+    if (child.pid !== void 0 && opts.registry) {
+      opts.registry.add(child.pid);
+    }
+    const chunks = [];
+    child.stdout.on("data", (d) => chunks.push(String(d)));
+    child.stderr.on("data", (d) => chunks.push(String(d)));
+    const timer = setTimeout(() => {
+      if (child.pid) {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+          child.kill("SIGKILL");
+        }
+      } else {
+        child.kill("SIGKILL");
+      }
+    }, opts.timeout * 1e3);
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (child.pid !== void 0 && opts.registry) {
+        opts.registry.delete(child.pid);
+      }
+      chunks.push(String(err));
+      resolve3({
+        exitCode: 1,
+        output: chunks.join("")
+      });
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (child.pid !== void 0 && opts.registry) {
+        opts.registry.delete(child.pid);
+      }
+      resolve3({
+        exitCode: code ?? 1,
+        output: chunks.join("")
+      });
+    });
+  });
+}
+__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 subagentsLine = run.subagents === void 0 ? "" : `Subagents: ${run.subagents}.`;
+  const costLine = run.costUsd === void 0 ? "" : `Cost: $${run.costUsd.toFixed(2)}.`;
+  const itemsText = run.completedItems.length > 0 ? run.completedItems.map(
+    (item) => `"${sanitize(item)}"`
+  ).join(", ") + "." : "none.";
+  const itemsLine = `Checked items: ${itemsText}`;
+  return [
+    effortLine,
+    exitLine,
+    subagentsLine,
+    costLine,
+    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 subagentRule(preferSubagent, readOnly = false) {
+  if (!preferSubagent) return [];
+  return [
+    `- Hand read-only work to subagents: exploring the codebase, searching code, and experiments or test runs whose output would flood your context. Subagents default to the ${preferSubagent} model.`,
+    "- A subagent starts with no context. Brief each one with the objective, what you already know, its boundaries, and the reply you expect (file:line references, or pass/fail with the relevant output).",
+    ...readOnly ? [] : [
+      "- Subagents never edit files or run git commands that write. You make every edit and every commit."
+    ],
+    "- Do not delegate a lookup that takes a single tool call."
+  ];
+}
+__name(subagentRule, "subagentRule");
+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.",
+    ...subagentRule(opts.preferSubagent, true),
+    "- 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),
+    ...subagentRule(opts.preferSubagent),
+    "- 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
+          ),
+          preferSubagent: opts.preferSubagent
+        }),
+        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,
+        preferSubagent: opts.preferSubagent,
+        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,
+          preferSubagent: opts.preferSubagent
+        }),
+        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,
+        preferSubagent: opts.preferSubagent,
+        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(createDisplay, "createDisplay");
+__name(runReviewPass, "runReviewPass");
 
-// src/testcmd.ts
-import { spawn } from "node:child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
-import { join as join3 } from "node:path";
-function detectTestCmd(projectDir) {
-  const pkgPath = join3(projectDir, "package.json");
-  if (!existsSync3(pkgPath)) return null;
-  try {
-    const pkg = JSON.parse(
-      readFileSync3(pkgPath, "utf8")
-    );
-    return pkg.scripts?.test ? "npm test" : null;
-  } catch {
-    return null;
-  }
+// src/blockers.ts
+var FIELD_RE = /\*\*Blocked by:\*\*/i;
+var NEXT_FIELD_RE = /^\s*(?:[-*]\s+)?\*\*[^*\n]+:\*\*/;
+var HEADING_RE = /^\s*#{1,6}\s/;
+var CHECKLIST_RE = /^\s*[-*+]\s+\[[ xX]\]/;
+var TOKEN_RE = /[A-Za-z0-9_-]+/g;
+function endsField(line) {
+  return line.trim() === "" || NEXT_FIELD_RE.test(line) || HEADING_RE.test(line) || CHECKLIST_RE.test(line);
 }
-__name(detectTestCmd, "detectTestCmd");
-function runTestCmd(opts) {
-  return new Promise((resolve2) => {
-    let settled = false;
-    const child = spawn("sh", ["-c", opts.cmd], {
-      cwd: opts.cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-      detached: true
-    });
-    if (child.pid !== void 0 && opts.registry) {
-      opts.registry.add(child.pid);
+__name(endsField, "endsField");
+function fieldText(body) {
+  const lines = body.split(/\r?\n/);
+  const start = lines.findIndex((l) => FIELD_RE.test(l));
+  if (start === -1) return null;
+  const first = lines[start];
+  const m = FIELD_RE.exec(first);
+  const parts = [first.slice(m.index + m[0].length)];
+  for (const line of lines.slice(start + 1)) {
+    if (endsField(line)) break;
+    parts.push(line);
+  }
+  return parts.join("\n");
+}
+__name(fieldText, "fieldText");
+function stripNotes(text) {
+  const chars = [...text];
+  const drop = new Array(chars.length).fill(false);
+  const ticks = [];
+  chars.forEach((ch, i) => {
+    if (ch === "`") ticks.push(i);
+  });
+  for (let i = 0; i + 1 < ticks.length; i += 2) {
+    for (let j = ticks[i]; j <= ticks[i + 1]; j++) {
+      drop[j] = true;
     }
-    const chunks = [];
-    child.stdout.on("data", (d) => chunks.push(String(d)));
-    child.stderr.on("data", (d) => chunks.push(String(d)));
-    const timer = setTimeout(() => {
-      if (child.pid) {
-        try {
-          process.kill(-child.pid, "SIGKILL");
-        } catch {
-          child.kill("SIGKILL");
-        }
-      } else {
-        child.kill("SIGKILL");
-      }
-    }, opts.timeout * 1e3);
-    child.on("error", (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (child.pid !== void 0 && opts.registry) {
-        opts.registry.delete(child.pid);
+  }
+  const open = [];
+  chars.forEach((ch, i) => {
+    if (drop[i]) return;
+    if (ch === "(") {
+      open.push(i);
+    } else if (ch === ")" && open.length > 0) {
+      const from = open.pop();
+      for (let j = from; j <= i; j++) drop[j] = true;
+    }
+  });
+  return chars.map((ch, i) => drop[i] ? " " : ch).join("");
+}
+__name(stripNotes, "stripNotes");
+function looksLikeFeature(word) {
+  const segments = word.split("/");
+  return (segments.length > 1 || word.includes("-")) && /[a-z]/.test(word) && segments.every((s) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s));
+}
+__name(looksLikeFeature, "looksLikeFeature");
+function wordBefore(text, start) {
+  let i = start;
+  while (i > 0 && /\s/.test(text[i - 1])) i--;
+  if (i === start) return null;
+  const end = i;
+  while (i > 0 && /[A-Za-z0-9_/-]/.test(text[i - 1])) i--;
+  return i === end ? null : text.slice(i, end);
+}
+__name(wordBefore, "wordBefore");
+function parseBlockerField(body, knownFeatures) {
+  const text = fieldText(body);
+  if (text === null) return { refs: [], typos: [] };
+  const clean = stripNotes(text);
+  if (/^\s*none\b/i.test(clean)) return { refs: [], typos: [] };
+  const refs = [];
+  const typos = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = /* @__PURE__ */ __name((num, feature) => {
+    const id = `${feature ?? ""}:${num}`;
+    if (seen.has(id)) return;
+    seen.add(id);
+    refs.push(feature === void 0 ? { num } : { feature, num });
+  }, "add");
+  for (const m of clean.matchAll(TOKEN_RE)) {
+    const word = m[0];
+    if (/^\d+(?:-\d+)*$/.test(word)) {
+      const before = wordBefore(clean, m.index ?? 0);
+      let feature;
+      if (before !== null && knownFeatures.has(before)) {
+        feature = before;
+      } else if (before !== null && looksLikeFeature(before) && !typos.includes(before)) {
+        typos.push(before);
       }
-      chunks.push(String(err));
-      resolve2({
-        exitCode: 1,
-        output: chunks.join("")
+      for (const n of word.split("-").map(Number)) add(n, feature);
+    }
+  }
+  return { refs, typos };
+}
+__name(parseBlockerField, "parseBlockerField");
+function refId(feature, num) {
+  return `${feature}:${num}`;
+}
+__name(refId, "refId");
+function resolveBlockers(raw, ownFeature, selected, lookup) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of raw) {
+    const feature = r.feature ?? ownFeature;
+    const id = refId(feature, r.num);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const nums = selected.get(feature);
+    if (nums) {
+      out.push({
+        feature,
+        num: r.num,
+        where: nums.has(r.num) ? "run" : "missing"
       });
-    });
-    child.on("close", (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (child.pid !== void 0 && opts.registry) {
-        opts.registry.delete(child.pid);
-      }
-      resolve2({
-        exitCode: code ?? 1,
-        output: chunks.join("")
+      continue;
+    }
+    const status = lookup(feature, r.num);
+    if (status === void 0) {
+      out.push({ feature, num: r.num, where: "missing" });
+    } else {
+      out.push({
+        feature,
+        num: r.num,
+        where: status === "done" ? "done" : "pending",
+        status
       });
-    });
-  });
+    }
+  }
+  return out;
 }
-__name(runTestCmd, "runTestCmd");
+__name(resolveBlockers, "resolveBlockers");
+function provisionalRefs(raw, ownFeature) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of raw) {
+    const feature = r.feature ?? ownFeature;
+    const id = refId(feature, r.num);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({ feature, num: r.num, where: "run" });
+  }
+  return out;
+}
+__name(provisionalRefs, "provisionalRefs");
 
 // src/orchestrator.ts
 var execFileAsync4 = promisify4(execFile4);
@@ -1265,21 +2799,7 @@ function parseStatus(body) {
   return m ? m[1].trim().toLowerCase() : "";
 }
 __name(parseStatus, "parseStatus");
-function parseBlockers(body) {
-  const m = body.match(/\*\*Blocked by:\*\*\s*(.+)/i);
-  if (!m) return [];
-  const text = m[1];
-  if (/none/i.test(text)) return [];
-  const nums = [];
-  const re = /(\d+)/g;
-  let match;
-  while (match = re.exec(text)) {
-    nums.push(Number(match[1]));
-  }
-  return nums;
-}
-__name(parseBlockers, "parseBlockers");
-function scanTickets(dir, feature = "") {
+function scanTickets(dir, feature = "", knownFeatures = /* @__PURE__ */ new Set()) {
   const files = readdirSync2(dir).filter((f) => TICKET_RE.test(f)).sort((a, b) => a.localeCompare(
     b,
     void 0,
@@ -1287,8 +2807,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,
@@ -1296,7 +2816,10 @@ function scanTickets(dir, feature = "") {
       filepath,
       body,
       status: parseStatus(body),
-      blockers: parseBlockers(body),
+      blockers: provisionalRefs(
+        parseBlockerField(body, knownFeatures).refs,
+        feature
+      ),
       feature
     };
   });
@@ -1306,15 +2829,35 @@ function ticketKey(feature, num) {
   return `${feature}:${num}`;
 }
 __name(ticketKey, "ticketKey");
+function blockerSatisfied(ref, doneKeys) {
+  switch (ref.where) {
+    case "run":
+      return doneKeys.has(ticketKey(ref.feature, ref.num));
+    case "done":
+      return true;
+    case "pending":
+    case "missing":
+      return false;
+  }
+}
+__name(blockerSatisfied, "blockerSatisfied");
+function blockerLabel(ref) {
+  const nn = String(ref.num).padStart(2, "0");
+  const base = ref.feature ? `${ref.feature}/${nn}` : nn;
+  if (ref.where === "pending") {
+    return `${base} (${ref.status ?? "not done"}, not in run)`;
+  }
+  if (ref.where === "missing") return `${base} (not found)`;
+  return base;
+}
+__name(blockerLabel, "blockerLabel");
 function findReadyTickets(tickets) {
   const doneKeys = new Set(
     tickets.filter((t) => t.status === "done").map((t) => ticketKey(t.feature, t.num))
   );
   return tickets.filter((t) => {
     if (t.status !== "ready-for-agent") return false;
-    return t.blockers.every(
-      (b) => doneKeys.has(ticketKey(t.feature, b))
-    );
+    return t.blockers.every((r) => blockerSatisfied(r, doneKeys));
   });
 }
 __name(findReadyTickets, "findReadyTickets");
@@ -1323,14 +2866,19 @@ function findBlockedTickets(tickets, failedKeys) {
     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);
+    for (const ref of ticket.blockers) {
+      const key = ticketKey(ref.feature, ref.num);
       if (visited.has(key)) continue;
       visited.add(key);
+      if (ref.where === "done") continue;
+      if (ref.where === "pending" || ref.where === "missing") {
+        found.set(key, ref);
+        continue;
+      }
       const blocker = byKey.get(key);
       if (!blocker || blocker.status === "done") continue;
       if (failedKeys.has(key) || blocker.status !== "ready-for-agent") {
-        found.add(key);
+        found.set(key, ref);
         continue;
       }
       collectDead(blocker, visited, found);
@@ -1342,9 +2890,9 @@ function findBlockedTickets(tickets, failedKeys) {
     const key = ticketKey(t.feature, t.num);
     if (t.status !== "ready-for-agent") continue;
     if (failedKeys.has(key)) continue;
-    const found = /* @__PURE__ */ new Set();
+    const found = /* @__PURE__ */ new Map();
     collectDead(t, /* @__PURE__ */ new Set([key]), found);
-    if (found.size > 0) blocked.set(key, [...found]);
+    if (found.size > 0) blocked.set(key, [...found.values()]);
   }
   return blocked;
 }
@@ -1399,7 +2947,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;
   }
@@ -1423,7 +2971,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");
@@ -1447,7 +2995,7 @@ __name(checkAllItems, "checkAllItems");
 function markDone(ticket) {
   let body;
   try {
-    body = readFileSync4(ticket.filepath, "utf8");
+    body = readFileSync6(ticket.filepath, "utf8");
   } catch {
     body = ticket.body;
   }
@@ -1456,7 +3004,7 @@ function markDone(ticket) {
     /\*\*Status:\*\*\s*.+/i,
     "**Status:** done"
   );
-  writeFileSync3(ticket.filepath, updated);
+  writeFileSync5(ticket.filepath, updated);
   ticket.status = "done";
   ticket.body = updated;
 }
@@ -1489,11 +3037,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 ----",
@@ -1503,27 +3063,30 @@ 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),
+    ...subagentRule(opts.preferSubagent),
+    "- 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,
@@ -1544,6 +3107,8 @@ function renderMergePrompt(specBody, ticket) {
     "4. Commit the resolved files.",
     "",
     "Do NOT re-implement the ticket from scratch.",
+    ...installRule(opts.installCmd),
+    ...subagentRule(opts.preferSubagent),
     "Do NOT read or modify files outside your current directory (the worktree).",
     "Do NOT run git push."
   ].join("\n");
@@ -1552,7 +3117,7 @@ __name(renderMergePrompt, "renderMergePrompt");
 function listTickets(tickets) {
   console.log("\nTickets:");
   for (const t of tickets) {
-    const blockerStr = t.blockers.length > 0 ? `blocked by [${t.blockers.join(", ")}]` : "no blockers";
+    const blockerStr = t.blockers.length > 0 ? `blocked by [${t.blockers.map(blockerLabel).join(", ")}]` : "no blockers";
     console.log(
       `  ${t.filename} (${t.status}) ${blockerStr}`
     );
@@ -1576,11 +3141,7 @@ function* simulateWaves(tickets) {
       if (sim.get(key) !== "ready-for-agent") {
         return false;
       }
-      return t.blockers.every(
-        (b) => doneKeys.has(
-          ticketKey(t.feature, b)
-        )
-      );
+      return t.blockers.every((r) => blockerSatisfied(r, doneKeys));
     });
     if (ready.length === 0) break;
     yield { wave, ready };
@@ -1613,9 +3174,7 @@ function detectDeadlocks(tickets) {
         (t) => ticketKey(t.feature, t.num) === key
       );
       if (ticket.blockers.every(
-        (b) => doneKeys.has(
-          ticketKey(ticket.feature, b)
-        )
+        (r) => blockerSatisfied(r, doneKeys)
       )) {
         doneKeys.add(key);
         readyKeys.delete(key);
@@ -1653,80 +3212,41 @@ var PROVIDER_ARGS = {
   ]
 };
 function getProviderArgs(cmd) {
-  const name = basename2(cmd);
+  const name = basename5(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)];
-}
-__name(escalateEffort, "escalateEffort");
-function formatStreamLine(line) {
-  let obj;
-  try {
-    obj = JSON.parse(line);
-  } catch {
-    return line;
-  }
+function formatStreamObject(value) {
+  if (!isRecord(value)) return null;
+  const obj = value;
   if (obj.type === "assistant") {
-    const msg = obj.message;
-    const content = msg?.content;
+    if (obj.parent_tool_use_id != null) return null;
+    const msg = isRecord(obj.message) ? obj.message : void 0;
+    const content = Array.isArray(msg?.content) ? msg.content : void 0;
     if (!content) return null;
     for (const block of content) {
-      if (block.type === "text") {
-        return String(block.text);
-      }
+      if (!isRecord(block)) continue;
+      if (block.type !== "text") continue;
+      if (typeof block.text === "string") return block.text;
     }
     return null;
   }
   if (obj.type === "result") {
-    const sub = obj.subtype ?? "done";
-    const cost = obj.total_cost_usd;
-    const costStr = cost != null ? ` ($${cost.toFixed(2)})` : "";
+    const sub = typeof obj.subtype === "string" ? obj.subtype : "done";
+    const cost = typeof obj.total_cost_usd === "number" ? obj.total_cost_usd : void 0;
+    const costStr = cost !== void 0 ? ` ($${cost.toFixed(2)})` : "";
     return `${sub}${costStr}`;
   }
   if (obj.type === "system") {
-    const sub = obj.subtype;
+    const sub = typeof obj.subtype === "string" ? obj.subtype : void 0;
     if (sub === "api_retry") {
-      const error = obj.error;
-      return `retry: ${error ?? "unknown"}`;
+      const error = typeof obj.error === "string" ? obj.error : "unknown";
+      return `retry: ${error}`;
     }
   }
   return null;
 }
-__name(formatStreamLine, "formatStreamLine");
+__name(formatStreamObject, "formatStreamObject");
 function createPiStreamFormatter() {
   const calls = /* @__PURE__ */ new Map();
   let textBuf = "";
@@ -1793,8 +3313,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");
@@ -1835,7 +3355,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) {
@@ -1879,10 +3399,15 @@ function spawnAgent(opts) {
     opts.logPath,
     { flags: "w" }
   );
+  const env = isClaude && opts.preferSubagent ? {
+    ...process.env,
+    CLAUDE_CODE_SUBAGENT_MODEL: opts.preferSubagent
+  } : void 0;
   const proc = spawn2(opts.agentCmd, args, {
     stdio: ["pipe", "pipe", "pipe"],
     cwd: opts.cwd,
-    detached: true
+    detached: true,
+    ...env ? { env } : {}
   });
   if (proc.pid !== void 0) runningAgents.add(proc.pid);
   proc.stdout.pipe(logStream, { end: false });
@@ -1900,10 +3425,26 @@ function spawnAgent(opts) {
     }
   }
   __name(collectCompleted, "collectCompleted");
+  let streamStats = emptyStreamStats();
+  function formatClaudeLine(line) {
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      return line;
+    }
+    const next = nextStreamStats(streamStats, obj);
+    if (next !== streamStats) {
+      streamStats = next;
+      opts.onStats?.(next.stats);
+    }
+    return formatStreamObject(obj);
+  }
+  __name(formatClaudeLine, "formatClaudeLine");
   const rl = createInterface({ input: proc.stdout });
   rl.on("line", (line) => {
     if (isClaude) {
-      const formatted = formatStreamLine(line);
+      const formatted = formatClaudeLine(line);
       if (formatted !== null) {
         collectCompleted(formatted);
         const output = `${prefix}${formatted}`;
@@ -1969,7 +3510,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) {
@@ -1995,7 +3536,12 @@ function spawnAgent(opts) {
       rlErr.close();
       logStream.end();
       if (promptFile) cleanupPromptFile(promptFile);
-      resolve2({ exitCode, completedItems, timedOut });
+      resolve3({
+        exitCode,
+        completedItems,
+        timedOut,
+        ...isClaude ? streamStats.stats : {}
+      });
     }
     __name(finish, "finish");
     proc.on("exit", (code) => {
@@ -2019,22 +3565,27 @@ 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
+        });
       });
     });
   });
 }
 __name(spawnAgent, "spawnAgent");
-function dryRun(tickets, specBody, testCmd) {
+function dryRun(tickets, specBody, testCmd, preferSubagent) {
   listTickets(tickets);
   console.log("\nSimulated wave order:");
   for (const { wave, ready } of simulateWaves(tickets)) {
@@ -2048,6 +3599,9 @@ function dryRun(tickets, specBody, testCmd) {
       "\nDeadlocked tickets: " + stuck.map((t) => t.filename).join(", ")
     );
   }
+  console.log(`
+Test command: ${testCmd || "(none)"}`);
+  console.log(`Prefer subagent: ${preferSubagent || "(none)"}`);
   const firstReady = findReadyTickets(tickets);
   if (firstReady.length > 0) {
     console.log(
@@ -2059,7 +3613,7 @@ Prompt for first ready ticket (${firstReady[0].filename}):
       renderPrompt(
         specBody,
         firstReady[0],
-        { testCmd }
+        { testCmd, preferSubagent }
       )
     );
   }
@@ -2103,18 +3657,28 @@ Prompt for first ready ticket (${firstReady[0].filename}):
       renderPrompt(
         opts.specBody,
         firstReady[0],
-        { testCmd: opts.testCmd }
+        {
+          testCmd: opts.testCmd,
+          installCmd: opts.installCmd,
+          preferSubagent: opts.preferSubagent
+        }
       )
     );
   }
   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)"}`
   );
+  console.log(
+    `Prefer subagent: ${opts.preferSubagent || "(none)"}`
+  );
   console.log(
     `Retries:      ${opts.retries ?? DEFAULT_RETRIES}`
   );
@@ -2131,7 +3695,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,
@@ -2144,7 +3735,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}`
@@ -2173,11 +3764,27 @@ 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,
+      preferSubagent: opts.preferSubagent
+    }
   );
-  const logPath = join4(
+  const logPath2 = join6(
     opts.logsDir,
     opts.ticket.filename.replace(/\.md$/, ".respawn.log")
   );
@@ -2190,12 +3797,14 @@ async function respawnAndRetryMerge(opts) {
     agentCmd: opts.agentCmd,
     model: opts.model,
     timeout: opts.timeout,
-    logPath,
+    logPath: logPath2,
     cwd: opts.worktreePath,
     label,
     maxTurns: opts.maxTurns,
+    preferSubagent: opts.preferSubagent,
     onLine: opts.onLine
   });
+  opts.onAgentRun?.(result);
   if (result.exitCode !== 0) {
     const msg2 = `  ${opts.ticket.filename}: respawned agent exited ${result.exitCode}`;
     if (opts.onLine) {
@@ -2274,20 +3883,43 @@ 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 historyFor(learningsPath, ticket) {
+  const featureDir = dirname4(dirname4(ticket.filepath));
+  const scratchDir = ticket.feature ? join6(featureDir, ...ticket.feature.split("/").map(() => "..")) : dirname4(featureDir);
+  const others = new Set(
+    ticket.blockers.map((r) => r.feature).filter((f) => f !== ticket.feature)
+  );
+  const entries = [
+    ...readEntries(learningsPath),
+    ...[...others].flatMap((f) => readEntries(
+      join6(scratchDir, f, "learnings.md")
+    ))
+  ];
+  return renderHistory(selectHistory(entries, {
+    key: ticketKey(ticket.feature, ticket.num),
+    blockerKeys: ticket.blockers.map((r) => {
+      return ticketKey(r.feature, r.num);
+    })
+  }));
+}
+__name(historyFor, "historyFor");
+function buildHistory(learningsPath, ticket, d) {
+  try {
+    return historyFor(learningsPath, ticket);
+  } 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;
@@ -2301,11 +3933,43 @@ async function runTicketAttempt(opts) {
   } catch (error) {
     return { kind: "worktree-error", error };
   }
-  d.setTicketStatus(
-    ticket.num,
-    "in-progress",
-    ticket.feature
-  );
+  d.setTicketStatus(
+    ticket.num,
+    "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,
@@ -2315,7 +3979,18 @@ 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
+        ),
+        preferSubagent: opts.preferSubagent
+      }
     ),
     agentCmd: opts.agentCmd,
     model: opts.model,
@@ -2330,8 +4005,27 @@ async function runTicketAttempt(opts) {
     label: ticket.filename.replace(/\.md$/, ""),
     maxTurns: opts.maxTurns,
     effort: opts.effort,
+    preferSubagent: opts.preferSubagent,
+    onStats: opts.onStats,
     onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
   });
+  opts.onAgentRun?.(agentResult);
+  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,
+    ...agentResult.subagents === void 0 ? {} : { subagents: agentResult.subagents },
+    ...agentResult.costUsd === void 0 ? {} : { costUsd: agentResult.costUsd }
+  };
   if (agentResult.timedOut) {
     d.log(
       `  ${ticket.filename}: timed out; keeping the work it committed`
@@ -2346,7 +4040,8 @@ async function runTicketAttempt(opts) {
       reason: "exit",
       branchName: worktree.branchName,
       exitCode: agentResult.exitCode,
-      completedItems: agentResult.completedItems
+      completedItems: agentResult.completedItems,
+      agentRun
     };
   }
   if (isDirty(worktree.worktreePath)) {
@@ -2369,7 +4064,8 @@ async function runTicketAttempt(opts) {
     return {
       kind: "no-commits",
       worktreePath: worktree.worktreePath,
-      branchName: worktree.branchName
+      branchName: worktree.branchName,
+      agentRun
     };
   }
   const passed = await runTestGate({
@@ -2392,73 +4088,189 @@ 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;
+  let prior = { subagents: 0 };
+  const showStats = /* @__PURE__ */ __name((stats) => {
+    d.setTicketStats(ticket.num, ticket.feature, stats);
+  }, "showStats");
+  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,
         attempt,
-        effort
+        effort,
+        onStats: /* @__PURE__ */ __name((stats) => showStats(addStats(prior, stats)), "onStats"),
+        onAgentRun: /* @__PURE__ */ __name((result) => {
+          prior = addStats(prior, result);
+          opts.onAgentRun?.(result);
+        }, "onAgentRun")
       });
     } catch (error) {
       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)
@@ -2471,15 +4283,77 @@ function indentFilenames(tickets) {
   return tickets.map((t) => `  ${t.filename}`).join("\n");
 }
 __name(indentFilenames, "indentFilenames");
-function renderFinishSummary(tickets, totalCompleted, failedKeys) {
+function explainOpen(tickets, failedKeys, warnings) {
   const remaining = tickets.filter(
     (t) => t.status === "ready-for-agent"
   );
+  const open = remaining.filter(
+    (t) => !failedKeys.has(ticketKey(t.feature, t.num))
+  );
+  const dead = findBlockedTickets(tickets, failedKeys);
+  const deadRefs = /* @__PURE__ */ __name((t) => dead.get(ticketKey(t.feature, t.num)) ?? [], "deadRefs");
+  const lines = [];
   const human = tickets.filter((t) => t.status === HUMAN_STATUS);
-  const humanNums = new Set(human.map((t) => t.num));
-  const blockedByHuman = remaining.filter(
-    (t) => !failedKeys.has(ticketKey(t.feature, t.num)) && t.blockers.some((b) => humanNums.has(b))
+  if (human.length > 0) {
+    const humanKeys = new Set(
+      human.map((t) => ticketKey(t.feature, t.num))
+    );
+    const blockedByHuman = open.filter((t) => deadRefs(t).some(
+      (r) => humanKeys.has(ticketKey(r.feature, r.num))
+    ));
+    const noun = human.length === 1 ? "ticket is" : "tickets are";
+    lines.push(
+      "",
+      (remaining.length === 0 && failedKeys.size === 0 ? `All remaining ${noun} marked ${HUMAN_STATUS}. ` : `${human.length} ${noun} marked ${HUMAN_STATUS}. `) + "nightralph only runs ready-for-agent tickets, so an agent cannot finish these:",
+      indentFilenames(human)
+    );
+    if (blockedByHuman.length > 0) {
+      const n = blockedByHuman.length;
+      lines.push(
+        `${n} ready-for-agent ticket${n === 1 ? " is" : "s are"} blocked until they are done:`,
+        indentFilenames(blockedByHuman)
+      );
+    }
+    lines.push(
+      "Do that work by hand, then set each ticket's **Status:** to done" + (blockedByHuman.length > 0 ? " and run nightralph again." : ".")
+    );
+  }
+  const blockers = [];
+  const outside = open.filter(
+    (t) => deadRefs(t).some((r) => r.where === "pending")
+  );
+  if (outside.length > 0) {
+    const n = outside.length;
+    blockers.push(
+      `${n} ready-for-agent ticket${n === 1 ? " waits" : "s wait"} on tickets outside this run. Select those features too, or finish them first:`,
+      ...outside.map((t) => `  ${ticketLabel(toRef(t))} waits on ` + deadRefs(t).filter((r) => r.where === "pending").map(blockerLabel).join(", "))
+    );
+  }
+  const missing = open.flatMap((t) => t.blockers.filter((r) => r.where === "missing").map((r) => `  ${ticketLabel(toRef(t))}: ${blockerLabel(r)}`));
+  if (missing.length > 0) {
+    const n = missing.length;
+    blockers.push(
+      `${n} blocker reference${n === 1 ? "" : "s"} match no ticket. Fix the **Blocked by:** line:`,
+      ...missing
+    );
+  }
+  const typos = warnings.filter((w) => w.kind === "typo");
+  if (typos.length > 0) {
+    const n = typos.length;
+    blockers.push(
+      `${n} word${n === 1 ? "" : "s"} in a **Blocked by:** line look${n === 1 ? "s" : ""} like a feature name but match no .scratch/<name>/issues directory:`,
+      ...typos.map((w) => `  ${w.ticket}: ${w.text}`)
+    );
+  }
+  if (blockers.length > 0) lines.push("", ...blockers);
+  return lines;
+}
+__name(explainOpen, "explainOpen");
+function renderFinishSummary(tickets, totalCompleted, failedKeys, warnings = []) {
+  const remaining = tickets.filter(
+    (t) => t.status === "ready-for-agent"
   );
+  const human = tickets.filter((t) => t.status === HUMAN_STATUS);
   const counts = `Finished: ${totalCompleted} completed` + (remaining.length > 0 ? `, ${remaining.length} remaining` : "") + (failedKeys.size > 0 ? `, ${failedKeys.size} failed` : "") + (human.length > 0 ? `, ${human.length} need a human` : "");
   const lines = [counts];
   const features = new Set(
@@ -2508,26 +4382,54 @@ function renderFinishSummary(tickets, totalCompleted, failedKeys) {
       lines.push(detail);
     }
   }
-  if (human.length === 0) return lines.join("\n");
-  const noun = human.length === 1 ? "ticket is" : "tickets are";
-  lines.push(
-    "",
-    (remaining.length === 0 && failedKeys.size === 0 ? `All remaining ${noun} marked ${HUMAN_STATUS}. ` : `${human.length} ${noun} marked ${HUMAN_STATUS}. `) + "nightralph only runs ready-for-agent tickets, so an agent cannot finish these:",
-    indentFilenames(human)
+  lines.push(...explainOpen(tickets, failedKeys, warnings));
+  return lines.join("\n");
+}
+__name(renderFinishSummary, "renderFinishSummary");
+function nothingReady(tickets) {
+  return findReadyTickets(tickets).length === 0 && tickets.some((t) => t.status === "ready-for-agent");
+}
+__name(nothingReady, "nothingReady");
+function renderNothingReady(tickets, warnings) {
+  const lines = [
+    "Nothing to run: every ready-for-agent ticket is waiting on a blocker.",
+    ...explainOpen(tickets, /* @__PURE__ */ new Set(), warnings)
+  ];
+  const dead = findBlockedTickets(tickets, /* @__PURE__ */ new Set());
+  const byKey = new Map(
+    tickets.map((t) => [ticketKey(t.feature, t.num), t])
   );
-  if (blockedByHuman.length > 0) {
-    const n = blockedByHuman.length;
+  const other = [];
+  for (const [key, refs] of dead) {
+    const stuck = refs.flatMap((r) => {
+      const b = byKey.get(ticketKey(r.feature, r.num));
+      return b && b.status !== HUMAN_STATUS ? [`${ticketLabel(toRef(b))} (${b.status})`] : [];
+    });
+    const t = byKey.get(key);
+    if (t && stuck.length > 0) {
+      other.push(
+        `  ${ticketLabel(toRef(t))} waits on ` + stuck.join(", ")
+      );
+    }
+  }
+  if (other.length > 0) {
     lines.push(
-      `${n} ready-for-agent ticket${n === 1 ? " is" : "s are"} blocked until they are done:`,
-      indentFilenames(blockedByHuman)
+      "",
+      "These tickets wait on tickets that are not ready-for-agent:",
+      ...other,
+      "Set those tickets to ready-for-agent or done, or fix the **Blocked by:** lines."
+    );
+  }
+  const cycle = detectDeadlocks(tickets).filter((t) => !dead.has(ticketKey(t.feature, t.num)));
+  if (cycle.length > 0) {
+    lines.push(
+      "",
+      "Deadlocked tickets (waiting on each other): " + cycle.map((t) => ticketLabel(toRef(t))).join(", ") + ". Fix their **Blocked by:** lines."
     );
   }
-  lines.push(
-    "Do that work by hand, then set each ticket's **Status:** to done" + (blockedByHuman.length > 0 ? " and run nightralph again." : ".")
-  );
   return lines.join("\n");
 }
-__name(renderFinishSummary, "renderFinishSummary");
+__name(renderNothingReady, "renderNothingReady");
 function sessionTickets(tickets) {
   return [...tickets].filter((t) => t.status === "ready-for-agent").sort((a, b) => a.feature.localeCompare(b.feature) || a.num - b.num);
 }
@@ -2546,7 +4448,10 @@ function reportBlocked(d, 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)));
+    const labels = dead.map((ref) => {
+      const t = byKey.get(ticketKey(ref.feature, ref.num));
+      return t ? ticketLabel(toRef(t)) : blockerLabel(ref);
+    });
     d.setBlocked(ticket.num, ticket.feature, labels);
   }
 }
@@ -2558,13 +4463,13 @@ 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 });
+async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, testCmd, display, maxTurns, effort, retries, retryDelay, concurrency, warnings = [], preferSubagent) {
+  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++;
@@ -2572,6 +4477,7 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
   let waveNum = 0;
   const failedKeys = /* @__PURE__ */ new Set();
   const session = sessionTickets(tickets);
+  let runStats = emptyRunStats();
   while (true) {
     if (waveNum > 0) reportBlocked(d, tickets, failedKeys);
     const ready = findReadyTickets(tickets).filter(
@@ -2602,7 +4508,7 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
         const prompt = renderPrompt(
           specBody,
           t,
-          { testCmd }
+          { testCmd, preferSubagent }
         );
         const label = t.filename.replace(
           /\.md$/,
@@ -2614,6 +4520,18 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
           t.feature
         );
         d.log(`  Starting ${t.filename}`);
+        let prior = { subagents: 0 };
+        const onStats = /* @__PURE__ */ __name((stats) => {
+          d.setTicketStats(
+            t.num,
+            t.feature,
+            addStats(prior, stats)
+          );
+        }, "onStats");
+        const tally = /* @__PURE__ */ __name((r) => {
+          prior = addStats(prior, r);
+          runStats = addRun(runStats, r);
+        }, "tally");
         let level = effort;
         let result = await spawnAgent({
           prompt,
@@ -2624,8 +4542,11 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
           label,
           maxTurns,
           effort: level,
+          preferSubagent,
+          onStats,
           onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
         });
+        tally(result);
         for (let attempt = 2; result.exitCode !== 0 && !result.timedOut && attempt <= maxAttempts; attempt++) {
           if (isKnown) {
             level = escalateEffort(
@@ -2652,8 +4573,11 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
             label,
             maxTurns,
             effort: level,
+            preferSubagent,
+            onStats,
             onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
           });
+          tally(result);
         }
         return { ticket: t, result };
       }
@@ -2712,14 +4636,17 @@ No tickets completed this wave. ${remaining2.length} ready ticket${remaining2.le
   d.log("\n" + renderFinishSummary(
     tickets,
     totalCompleted,
-    failedKeys
+    failedKeys,
+    warnings
   ));
+  const statsLine = renderRunStats(runStats);
+  if (statsLine) d.log(statsLine);
   d.cleanup();
   return { allDone: remaining.length === 0 };
 }
 __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;
@@ -2734,12 +4661,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;
@@ -2799,6 +4727,10 @@ async function runWavesIsolated(opts) {
   let waveNum = 0;
   const failedKeys = /* @__PURE__ */ new Set();
   const session = sessionTickets(opts.tickets);
+  let runStats = emptyRunStats();
+  const onAgentRun = /* @__PURE__ */ __name((result) => {
+    runStats = addRun(runStats, result);
+  }, "onAgentRun");
   while (true) {
     if (waveNum > 0) reportBlocked(d, opts.tickets, failedKeys);
     const ready = findReadyTickets(opts.tickets).filter(
@@ -2837,13 +4769,36 @@ async function runWavesIsolated(opts) {
         timeout: opts.timeout,
         logsDir: opts.logsDir,
         testCmd: opts.testCmd,
+        installCmd: opts.installCmd,
         maxTurns: opts.maxTurns,
         effort: opts.effort,
+        preferSubagent: opts.preferSubagent,
+        learningsPath: learningsPathFor(
+          tracker.pathFor(t.feature)
+        ),
         retries,
         retryDelay,
-        d
+        d,
+        onAgentRun
       })
     );
+    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 }
     );
@@ -2947,7 +4902,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;
@@ -2983,6 +4938,7 @@ async function runWavesIsolated(opts) {
         branches: successfulBranches,
         strategy: opts.conflictStrategy
       });
+      const doneThisWave = [];
       for (const branchResult of mergeResult.merged) {
         const bk = branchToKey.get(
           branchResult.branch
@@ -2991,6 +4947,7 @@ async function runWavesIsolated(opts) {
         if (!ticket) continue;
         if (branchResult.merged) {
           markDone(ticket);
+          doneThisWave.push(ticket);
           waveCompleted++;
           totalCompleted++;
           d.setTicketStatus(
@@ -3040,11 +4997,15 @@ 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")
+            preferSubagent: opts.preferSubagent,
+            onLine: /* @__PURE__ */ __name((msg) => d.log(msg), "onLine"),
+            onAgentRun
           }) : false;
           if (recovered) {
             markDone(ticket);
+            doneThisWave.push(ticket);
             waveCompleted++;
             totalCompleted++;
             d.setTicketStatus(
@@ -3100,6 +5061,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),
@@ -3110,6 +5093,7 @@ async function runWavesIsolated(opts) {
           }
         }
       }
+      await commitTicketFiles(repoRoot, doneThisWave, d);
       if (mergeResult.stoppedAt) {
         d.log(
           `
@@ -3152,31 +5136,109 @@ No tickets completed this wave. ${remaining2.length} ready ticket${remaining2.le
     }
   }
   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,
+        preferSubagent: opts.preferSubagent,
+        retries,
+        retryDelay,
+        log: /* @__PURE__ */ __name((msg) => d.log(msg), "log")
+      }, {
+        spawnAgent: /* @__PURE__ */ __name(async (spawnOpts) => {
+          const result = await spawnAgent(spawnOpts);
+          onAgentRun(result);
+          return result;
+        }, "spawnAgent"),
+        registry: runningAgents
+      });
+      reviewLine = renderReviewSummary(
+        outcome,
+        relative2(repoRoot, opts.review.reviewPath)
+      );
+    } catch (err) {
+      d.log(`
+Review failed: ${formatErrorMessage(err)}`);
+    }
+  }
   const remaining = opts.tickets.filter(
     (t) => t.status === "ready-for-agent"
   );
   d.log("\n" + renderFinishSummary(
     opts.tickets,
     totalCompleted,
-    failedKeys
+    failedKeys,
+    opts.warnings ?? []
   ));
+  const statsLine = renderRunStats(runStats);
+  if (statsLine) d.log(statsLine);
+  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 }
@@ -3184,18 +5246,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"
@@ -3211,13 +5273,93 @@ function findFeatureDirs(cwd) {
   return results;
 }
 __name(findFeatureDirs, "findFeatureDirs");
+function knownFeatureNames(scratchDir) {
+  const names = /* @__PURE__ */ new Set();
+  const walk = /* @__PURE__ */ __name((rel) => {
+    const dir = rel === "" ? scratchDir : join8(scratchDir, rel);
+    for (const e of readdirSync3(dir, { withFileTypes: true })) {
+      if (!e.isDirectory() || e.name === "issues") continue;
+      const name = rel === "" ? e.name : `${rel}/${e.name}`;
+      if (existsSync6(join8(scratchDir, name, "issues"))) {
+        names.add(name);
+      }
+      walk(name);
+    }
+  }, "walk");
+  if (existsSync6(scratchDir)) walk("");
+  return names;
+}
+__name(knownFeatureNames, "knownFeatureNames");
+function loadSelection(scratchDir, names) {
+  const known = knownFeatureNames(scratchDir);
+  const issuesDir = /* @__PURE__ */ __name((name) => join8(scratchDir, name, "issues"), "issuesDir");
+  const tickets = [];
+  const selected = /* @__PURE__ */ new Map();
+  for (const name of new Set(names)) {
+    const dir = issuesDir(name);
+    const found = existsSync6(dir) ? scanTickets(dir, name, known) : [];
+    selected.set(name, new Set(found.map((t) => t.num)));
+    tickets.push(...found);
+  }
+  const outside = /* @__PURE__ */ new Map();
+  const lookup = /* @__PURE__ */ __name((feature, num) => {
+    if (!known.has(feature)) return void 0;
+    let statuses = outside.get(feature);
+    if (!statuses) {
+      statuses = new Map(
+        scanTickets(issuesDir(feature), feature).map((t) => [t.num, t.status])
+      );
+      outside.set(feature, statuses);
+    }
+    return statuses.get(num);
+  }, "lookup");
+  const warnings = [];
+  for (const t of tickets) {
+    const parsed = parseBlockerField(t.body, known);
+    t.blockers = resolveBlockers(
+      parsed.refs,
+      t.feature,
+      selected,
+      lookup
+    );
+    const ticket = ticketLabel(t);
+    for (const word of parsed.typos) {
+      warnings.push({ ticket, kind: "typo", text: word });
+    }
+    for (const ref of t.blockers) {
+      if (ref.where !== "missing") continue;
+      warnings.push({
+        ticket,
+        kind: "missing",
+        text: blockerLabel(ref)
+      });
+    }
+  }
+  return { tickets, warnings };
+}
+__name(loadSelection, "loadSelection");
+function featureCounts(scratchDir, name) {
+  const { tickets, warnings } = loadSelection(scratchDir, [name]);
+  return {
+    ready: findReadyTickets(tickets).length,
+    total: tickets.length,
+    badBlockers: warnings.filter((w) => w.kind === "missing").length
+  };
+}
+__name(featureCounts, "featureCounts");
+function featureChoiceLabel(scratchDir, name) {
+  const c = featureCounts(scratchDir, name);
+  const bad = c.badBlockers === 0 ? "" : `, ${c.badBlockers} bad blocker` + (c.badBlockers === 1 ? "" : "s");
+  return `${name} (${c.ready}/${c.total} ready${bad})`;
+}
+__name(featureChoiceLabel, "featureChoiceLabel");
 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
     }];
   }
@@ -3233,14 +5375,11 @@ async function resolveIssuesDir(specName, cwd = process.cwd()) {
     console.log(`Using feature: ${f.name}`);
     return [{ dir: f.dir, spec: f.spec, name: f.name }];
   }
-  const featureChoices = features.map((f) => {
-    const tickets = scanTickets(f.dir);
-    const ready = findReadyTickets(tickets).length;
-    return {
-      name: `${f.name} (${ready}/${tickets.length} ready)`,
-      value: f.name
-    };
-  });
+  const scratchDir = join8(cwd, ".scratch");
+  const featureChoices = features.map((f) => ({
+    name: featureChoiceLabel(scratchDir, f.name),
+    value: f.name
+  }));
   while (true) {
     const selected = await checkbox({
       message: "Which features?",
@@ -3296,8 +5435,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"
       ),
@@ -3332,7 +5471,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",
@@ -3344,6 +5486,9 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
     type: "string",
     choices: ALL_EFFORT_LEVELS,
     describe: "Starting effort level. Omitted = provider default. Retries step up from here."
+  }).option("prefer-subagent", {
+    type: "string",
+    describe: 'claude only: model that subagents default to (CLAUDE_CODE_SUBAGENT_MODEL), plus a prompt rule to hand read-only work to them. "" disables it.'
   }).option("retries", {
     type: "number",
     default: DEFAULT_RETRIES,
@@ -3356,6 +5501,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({
@@ -3365,15 +5514,27 @@ 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,
+      preferSubagent: argv.preferSubagent,
       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();
@@ -3394,80 +5555,215 @@ 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 = [];
+  const valid = [];
+  const specs = /* @__PURE__ */ new Map();
   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"),
+    specs.set(name, stripSpecSection(
+      readFileSync7(spec, "utf8"),
       "User Stories"
-    );
-    const tickets = scanTickets(dir, name);
+    ));
+    valid.push(selection);
+  }
+  const loaded = valid.length > 0 ? loadSelection(
+    join9(process.cwd(), ".scratch"),
+    valid.map((s) => s.name)
+  ) : { tickets: [], warnings: [] };
+  for (const { dir, spec, name } of valid) {
+    const tickets = loaded.tickets.filter((t) => t.feature === 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(
-      tickets.map((t) => t.num)
-    );
-    for (const t of tickets) {
-      const unknown = t.blockers.filter(
-        (b) => !knownNums.has(b)
-      );
-      if (unknown.length > 0) {
-        console.warn(
-          `${t.filename}: blockers [${unknown.join(", ")}] not found in directory`
-        );
-      }
-      t.blockers = t.blockers.filter(
-        (b) => knownNums.has(b)
-      );
-    }
-    specBodies.set(name, specBody);
+    specBodies.set(name, specs.get(name));
     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,
+    warnings: loaded.warnings
+  };
+}
+__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 checkoutLaunchBranch(plan) {
+  try {
+    execFileSync2(
+      "git",
+      ["checkout", "--quiet", plan.launchBranch],
+      { cwd: getRepoRoot(), stdio: "ignore" }
+    );
+  } catch {
+  }
+}
+__name(checkoutLaunchBranch, "checkoutLaunchBranch");
+function failStaleResume(plan, problems) {
+  checkoutLaunchBranch(plan);
+  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 stopNothingReady(plan, loaded) {
+  checkoutLaunchBranch(plan);
+  console.log(
+    `Nothing to run on ${plan.branch}. Back on ${plan.launchBranch}.
+` + renderNothingReady(loaded.allTickets, loaded.warnings)
+  );
+  process.exit(0);
+}
+__name(stopNothingReady, "stopNothingReady");
+function willResume(features) {
+  const root = getRepoRoot();
+  const name = planIntegrationBranch(
+    getCurrentBranch(root),
+    getDefaultBranch(root),
+    features
+  );
+  return name !== null && localBranchExists(root, name);
+}
+__name(willResume, "willResume");
+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 resuming = /* @__PURE__ */ __name(() => !argv.dryRun && isGitRepo() && willResume([...loaded.specBodies.keys()]), "resuming");
+  if (nothingReady(loaded.allTickets) && !resuming()) {
+    console.log(renderNothingReady(
+      loaded.allTickets,
+      loaded.warnings
+    ));
+    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;
+  let preferSubagent = argv.preferSubagent || void 0;
+  const providerName = basename6(argv.provider);
+  if (preferSubagent && providerName !== "claude") {
+    console.warn(
+      `--prefer-subagent not supported by ${providerName}, skipping`
+    );
+    preferSubagent = void 0;
+  }
+  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 (nothingReady(loaded.allTickets)) {
+        stopNothingReady(plan, loaded);
+      }
     }
   }
-  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,
@@ -3476,13 +5772,28 @@ async function runExecute(argv) {
         conflictStrategy,
         progressPath: progressPaths.values().next().value,
         testCmd,
+        installCmd,
         effort: argv.effort,
         retries: argv.retries,
         retryDelay: argv.retryDelay,
-        concurrency: argv.concurrency
+        concurrency: argv.concurrency,
+        preferSubagent
       });
+      console.log(
+        describeIntegrationBranch(
+          getRepoRoot(),
+          featureNames
+        )
+      );
+      const reviewState = argv.review === false ? "off" : "on";
+      console.log(`Review:       ${reviewState}`);
     } else {
-      dryRun(allTickets, fallbackSpec, testCmd);
+      dryRun(
+        allTickets,
+        fallbackSpec,
+        testCmd,
+        preferSubagent
+      );
     }
     return;
   }
@@ -3496,12 +5807,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,
@@ -3509,18 +5820,25 @@ async function runExecute(argv) {
       conflictStrategy,
       display,
       testCmd,
+      installCmd,
       maxTurns: argv.maxTurns,
       effort: argv.effort,
       retries: argv.retries,
       retryDelay: argv.retryDelay,
       concurrency: argv.concurrency,
-      progressPaths
+      preferSubagent,
+      progressPaths,
+      warnings: loaded.warnings,
+      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,
@@ -3530,7 +5848,9 @@ async function runExecute(argv) {
       argv.effort,
       argv.retries,
       argv.retryDelay,
-      argv.concurrency
+      argv.concurrency,
+      loaded.warnings,
+      preferSubagent
     );
   }
   if (!result.allDone) {