nightralph 0.0.52 → 0.0.54

package/dist/orchestrator.js

@@ -7,10 +7,11 @@ import {
   readFileSync,
   writeFileSync,
   unlinkSync,
-  readdirSync
+  readdirSync,
+  statSync
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, dirname, basename } from "node:path";
+import { join, dirname, basename, relative } from "node:path";
 import { createInterface } from "node:readline";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
@@ -23,7 +24,8 @@ import {
   buildBranchName,
   hasNewCommits,
   isDirty,
-  commitDirty
+  commitDirty,
+  headCommit
 } from "./worktree.js";
 import {
   generateProgress,
@@ -41,9 +43,47 @@ import {
   updateWorktreeFromBase
 } from "./merge.js";
 import {
-  createDisplay
+  createDisplay,
+  ticketLabel
 } from "./display.js";
 import { runTestCmd } from "./testcmd.js";
+import {
+  readDocsRule,
+  installRule,
+  testGateRule,
+  LINT_RULE,
+  integrityRule,
+  CONFINEMENT_RULES,
+  commitRule,
+  notesRule,
+  agentsMdRule
+} from "./rules.js";
+import { runReviewPass, renderReviewSummary } from "./review.js";
+import {
+  EFFORT_LADDERS,
+  escalateEffort,
+  retryDelayFor,
+  runWithRetries,
+  sleep
+} from "./retry.js";
+import {
+  EFFORT_LADDERS as EFFORT_LADDERS2,
+  ALL_EFFORT_LEVELS,
+  escalateEffort as escalateEffort2,
+  retryDelayFor as retryDelayFor2
+} from "./retry.js";
+import {
+  LOG_TAIL_LINES,
+  appendEntry,
+  collectNotes,
+  ensureNotesIgnored,
+  learningsPathFor,
+  readEntries,
+  renderEntry,
+  renderHistory,
+  selectHistory,
+  tailLines
+} from "./learnings.js";
 function formatErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -165,6 +205,37 @@ function findReadyTickets(tickets) {
   });
 }
 __name(findReadyTickets, "findReadyTickets");
+function findBlockedTickets(tickets, failedKeys) {
+  const byKey = new Map(
+    tickets.map((t) => [ticketKey(t.feature, t.num), t])
+  );
+  function collectDead(ticket, visited, found) {
+    for (const b of ticket.blockers) {
+      const key = ticketKey(ticket.feature, b);
+      if (visited.has(key)) continue;
+      visited.add(key);
+      const blocker = byKey.get(key);
+      if (!blocker || blocker.status === "done") continue;
+      if (failedKeys.has(key) || blocker.status !== "ready-for-agent") {
+        found.add(key);
+        continue;
+      }
+      collectDead(blocker, visited, found);
+    }
+  }
+  __name(collectDead, "collectDead");
+  const blocked = /* @__PURE__ */ new Map();
+  for (const t of tickets) {
+    const key = ticketKey(t.feature, t.num);
+    if (t.status !== "ready-for-agent") continue;
+    if (failedKeys.has(key)) continue;
+    const found = /* @__PURE__ */ new Set();
+    collectDead(t, /* @__PURE__ */ new Set([key]), found);
+    if (found.size > 0) blocked.set(key, [...found]);
+  }
+  return blocked;
+}
+__name(findBlockedTickets, "findBlockedTickets");
 const COMPLETED_RE = /^\s*[-*+]?\s*\[x\]\s+(.+)$/i;
 const TOOL_USE_RE = /^\[[\w.]+\]/;
 const CHECKBOX_RE = /^(\s*[-*+] )\[( |x|X)\]( .*)$/;
@@ -305,11 +376,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 ----",
@@ -319,27 +402,29 @@ function renderPrompt(specBody, ticket, opts) {
     ticket.filename,
     ticket.body,
     "",
+    ...historyBlock(opts.history),
     "---- AGENT INSTRUCTIONS ----",
     "You are an autonomous coding agent. Implement the ticket using /tdd.",
     "",
     "Follow these rules:",
-    "- Read the files directly relevant to the ticket before writing code. Also read any AGENTS.md in or above the directories you will touch, plus CONTEXT.md and the relevant docs/adr/ entries if they exist. If they do not exist, proceed silently.",
+    readDocsRule("ticket"),
     "- Work ONLY on this ticket. Do not fix unrelated problems you notice.",
     "- Do NOT research external APIs or services via web search. Use the spec and ticket body as your sole reference for API shapes.",
-    "- Use /tdd for every checklist item. For each item, write a failing test at the seams named in the spec's Testing Decisions section, then write only enough code to make it pass, then refactor.",
-    `- While iterating, run only the tests relevant to what you changed. Run \`${opts.testCmd}\` in full once, as the final gate before your last commit. Do not commit with failing tests. The orchestrator runs the same command after you exit and rejects the ticket if it fails.`,
-    "- If the project has a lint script, run it and fix what it reports.",
-    "- INTEGRITY: never delete, skip, weaken, or write tautological tests to force a green result. Only report a checklist item done when its real tests genuinely pass. If an item cannot be completed honestly, leave it unchecked and say what blocked you.",
-    "- Do NOT read or modify files outside your current directory (the worktree).",
-    "- Do NOT run git push.",
-    "- Commit after each checklist item, and make sure everything is committed when finished.",
+    ...installRule(opts.installCmd),
+    "- Use /tdd for every checklist item. For each item, write a failing test at the seams named in the spec's Testing Decisions section, then write only enough code to make it pass, then refactor. For a checklist item that is pure scaffolding, config, or docs (where a test adds no value), skip test-first and record that decision in your notes file.",
+    testGateRule(opts.testCmd, "ticket"),
+    LINT_RULE,
+    integrityRule("checklist item"),
+    ...CONFINEMENT_RULES,
+    commitRule("checklist item"),
+    notesRule("checklist item", "ticket"),
     "- After completing each checklist item in the ticket, print a line: [x] <item text> (matching the checklist text exactly).",
-    "- Before your final commit, record reusable learnings in the nearest AGENTS.md (in or above the directories you modified; prefer that over the repo root). Good additions: module conventions, gotchas, files that must change together, how to test that area, environment requirements. Do NOT add ticket-specific details or temporary debugging notes. Only write when you have knowledge that would help future work in that directory.",
+    agentsMdRule("ticket"),
     ""
   ].join("\n");
 }
 __name(renderPrompt, "renderPrompt");
-function renderMergePrompt(specBody, ticket) {
+function renderMergePrompt(specBody, ticket, opts = {}) {
   return [
     "---- SPEC CONTEXT ----",
     specBody,
@@ -360,6 +445,7 @@ function renderMergePrompt(specBody, ticket) {
     "4. Commit the resolved files.",
     "",
     "Do NOT re-implement the ticket from scratch.",
+    ...installRule(opts.installCmd),
     "Do NOT read or modify files outside your current directory (the worktree).",
     "Do NOT run git push."
   ].join("\n");
@@ -473,42 +559,6 @@ function getProviderArgs(cmd) {
   return PROVIDER_ARGS[name] ?? [];
 }
 __name(getProviderArgs, "getProviderArgs");
-const EFFORT_LADDERS = {
-  pi: [
-    "off",
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max"
-  ],
-  claude: [
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max"
-  ],
-  codex: ["low", "medium", "high"]
-};
-const 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 {
@@ -701,7 +751,7 @@ function spawnAgent(opts) {
     detached: true
   });
   if (proc.pid !== void 0) runningAgents.add(proc.pid);
-  proc.stdout.pipe(logStream);
+  proc.stdout.pipe(logStream, { end: false });
   const piFormatter = isPi ? createPiStreamFormatter() : null;
   const completedItems = [];
   const seenItems = /* @__PURE__ */ new Set();
@@ -750,7 +800,7 @@ function spawnAgent(opts) {
       }
     }
   });
-  proc.stderr.pipe(logStream);
+  proc.stderr.pipe(logStream, { end: false });
   const rlErr = createInterface({ input: proc.stderr });
   rlErr.on("line", (line) => {
     if (isClaude && !TOOL_USE_RE.test(line)) return;
@@ -835,16 +885,21 @@ function spawnAgent(opts) {
       }
       rl.close();
       rlErr.close();
-      logStream.end();
+      const msg = "agent process error: " + formatErrorMessage(err);
+      logStream.write(`nightralph: ${msg}
+`);
       if (promptFile) cleanupPromptFile(promptFile);
-      console.error(
-        "Agent process error:",
-        formatErrorMessage(err)
-      );
-      resolve({
-        exitCode: 1,
-        completedItems,
-        timedOut
+      if (opts.onLine) {
+        opts.onLine(`${prefix}${msg}`);
+      } else {
+        console.error(`${prefix}${msg}`);
+      }
+      logStream.end(() => {
+        resolve({
+          exitCode: 1,
+          completedItems,
+          timedOut
+        });
       });
     });
   });
@@ -864,6 +919,8 @@ function dryRun(tickets, specBody, testCmd) {
       "\nDeadlocked tickets: " + stuck.map((t) => t.filename).join(", ")
     );
   }
+  console.log(`
+Test command: ${testCmd || "(none)"}`);
   const firstReady = findReadyTickets(tickets);
   if (firstReady.length > 0) {
     console.log(
@@ -919,14 +976,20 @@ Prompt for first ready ticket (${firstReady[0].filename}):
       renderPrompt(
         opts.specBody,
         firstReady[0],
-        { testCmd: opts.testCmd }
+        {
+          testCmd: opts.testCmd,
+          installCmd: opts.installCmd
+        }
       )
     );
   }
   const strategyDesc = opts.conflictStrategy === "respawn" ? "respawn (re-run agent on conflict)" : "stop (stop merging on conflict)";
   console.log(
     `
-Test command: ${opts.testCmd}`
+Test command: ${opts.testCmd || "(none)"}`
+  );
+  console.log(
+    `Install:      ${opts.installCmd || "(none)"}`
   );
   console.log(
     `Effort:       ${opts.effort ?? "(provider default)"}`
@@ -947,7 +1010,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"
+  );
+  writeFileSync(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,
@@ -989,9 +1079,22 @@ async function respawnAndRetryMerge(opts) {
   } else {
     console.log(msg1);
   }
+  if (opts.installCmd) {
+    const installed = await runInstall({
+      installCmd: opts.installCmd,
+      ticket: opts.ticket,
+      worktreePath: opts.worktreePath,
+      timeout: opts.timeout,
+      logsDir: opts.logsDir,
+      log,
+      registry: runningAgents
+    });
+    if (!installed) return false;
+  }
   const prompt = renderMergePrompt(
     opts.specBody,
-    opts.ticket
+    opts.ticket,
+    { installCmd: opts.installCmd }
   );
   const logPath = join(
     opts.logsDir,
@@ -1090,20 +1193,31 @@ async function runPool(items, limit, fn) {
   return results;
 }
 __name(runPool, "runPool");
-function retryDelayFor(base, attempt) {
-  return base * 2 ** (attempt - 2);
-}
-__name(retryDelayFor, "retryDelayFor");
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-__name(sleep, "sleep");
 function attemptLogPath(logsDir, ticket, attempt, ext) {
   const stem = ticket.filename.replace(/\.md$/, "");
   const suffix = attempt > 1 ? `.attempt${attempt}` : "";
   return join(logsDir, `${stem}${suffix}${ext}`);
 }
 __name(attemptLogPath, "attemptLogPath");
+function buildHistory(learningsPath, ticket, d) {
+  try {
+    return renderHistory(selectHistory(
+      readEntries(learningsPath),
+      {
+        key: ticketKey(ticket.feature, ticket.num),
+        blockerKeys: ticket.blockers.map((b) => {
+          return ticketKey(ticket.feature, b);
+        })
+      }
+    ));
+  } catch (err) {
+    d.log(
+      `  ${ticket.filename}: could not read learnings: ${formatErrorMessage(err)}`
+    );
+    return "";
+  }
+}
+__name(buildHistory, "buildHistory");
 async function runTicketAttempt(opts) {
   const { ticket, d } = opts;
   let worktree;
@@ -1122,6 +1236,38 @@ async function runTicketAttempt(opts) {
     "in-progress",
     ticket.feature
   );
+  if (opts.installCmd) {
+    const installed = await runInstall({
+      installCmd: opts.installCmd,
+      ticket,
+      worktreePath: worktree.worktreePath,
+      timeout: opts.timeout,
+      logsDir: opts.logsDir,
+      attempt: opts.attempt,
+      log: /* @__PURE__ */ __name((msg) => d.log(msg), "log"),
+      registry: runningAgents
+    });
+    if (!installed) {
+      await removeWorktreeQuietly(
+        worktree.worktreePath,
+        d
+      );
+      return {
+        kind: "failed",
+        reason: "install",
+        branchName: worktree.branchName,
+        exitCode: 1,
+        completedItems: []
+      };
+    }
+  }
+  try {
+    ensureNotesIgnored(worktree.worktreePath);
+  } catch (err) {
+    d.log(
+      `  ${ticket.filename}: could not set up the notes directory: ${formatErrorMessage(err)}`
+    );
+  }
   const ticketSpec = lookupSpec(
     opts.specBodies,
     opts.specBody,
@@ -1131,7 +1277,17 @@ async function runTicketAttempt(opts) {
     prompt: renderPrompt(
       ticketSpec,
       ticket,
-      { testCmd: opts.testCmd }
+      {
+        testCmd: opts.testCmd,
+        installCmd: opts.installCmd,
+        // Rebuilt every attempt, so a retry sees the
+        // entry its previous attempt just wrote
+        history: buildHistory(
+          opts.learningsPath,
+          ticket,
+          d
+        )
+      }
     ),
     agentCmd: opts.agentCmd,
     model: opts.model,
@@ -1148,6 +1304,20 @@ async function runTicketAttempt(opts) {
     effort: opts.effort,
     onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
   });
+  let notes = null;
+  try {
+    notes = collectNotes(worktree.worktreePath);
+  } catch (err) {
+    d.log(
+      `  ${ticket.filename}: could not collect notes: ${formatErrorMessage(err)}`
+    );
+  }
+  const agentRun = {
+    exitCode: agentResult.exitCode,
+    completedItems: agentResult.completedItems,
+    timedOut: agentResult.timedOut,
+    notes
+  };
   if (agentResult.timedOut) {
     d.log(
       `  ${ticket.filename}: timed out; keeping the work it committed`
@@ -1162,7 +1332,8 @@ async function runTicketAttempt(opts) {
       reason: "exit",
       branchName: worktree.branchName,
       exitCode: agentResult.exitCode,
-      completedItems: agentResult.completedItems
+      completedItems: agentResult.completedItems,
+      agentRun
     };
   }
   if (isDirty(worktree.worktreePath)) {
@@ -1185,7 +1356,8 @@ async function runTicketAttempt(opts) {
     return {
       kind: "no-commits",
       worktreePath: worktree.worktreePath,
-      branchName: worktree.branchName
+      branchName: worktree.branchName,
+      agentRun
     };
   }
   const passed = await runTestGate({
@@ -1208,44 +1380,130 @@ async function runTicketAttempt(opts) {
       reason: "tests",
       branchName: worktree.branchName,
       exitCode: 1,
-      completedItems: agentResult.completedItems
+      completedItems: agentResult.completedItems,
+      agentRun
     };
   }
   return {
     kind: "ready",
     worktreePath: worktree.worktreePath,
     branchName: worktree.branchName,
-    completedItems: agentResult.completedItems
+    completedItems: agentResult.completedItems,
+    agentRun
   };
 }
 __name(runTicketAttempt, "runTicketAttempt");
-async function runTicketAttempts(opts) {
-  const { ticket, d } = opts;
-  const maxAttempts = opts.retries + 1;
-  const providerName = basename(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(readFileSync(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: basename(path), logTail: readLogTail(path) };
+  }, "logFor");
+  switch (outcome.kind) {
+    case "ready":
+      return {
+        ...base,
+        outcome: "done",
+        run: outcome.agentRun,
+        effort
+      };
+    case "failed":
+      switch (outcome.reason) {
+        case "exit":
+          return {
+            ...base,
+            outcome: "exit",
+            run: outcome.agentRun,
+            effort
+          };
+        case "tests":
+          return {
+            ...base,
+            outcome: "tests",
+            run: outcome.agentRun,
+            effort,
+            ...logFor(".test.log")
+          };
+        case "install":
+          return {
+            ...base,
+            outcome: "install",
+            ...logFor(".install.log")
+          };
+        default: {
+          const _exhaustive = outcome;
+          return _exhaustive;
+        }
       }
-      const delay = retryDelayFor(opts.retryDelay, attempt);
-      d.log(
-        `  ${ticket.filename}: retrying (attempt ${attempt}/${maxAttempts}` + (isKnown && effort ? `, effort ${effort}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
-      );
-      if (delay > 0) await sleep(delay * 1e3);
+    case "no-commits":
+      return {
+        ...base,
+        outcome: "no-commits",
+        run: outcome.agentRun,
+        effort
+      };
+    case "error":
+    case "worktree-error":
+      return {
+        ...base,
+        outcome: "error",
+        error: formatErrorMessage(outcome.error)
+      };
+    default: {
+      const _exhaustive = outcome;
+      return _exhaustive;
     }
+  }
+}
+__name(attemptEntry, "attemptEntry");
+function recordAttempt(opts) {
+  try {
+    const entry = attemptEntry(opts);
+    if (!entry) return;
+    appendEntry(opts.learningsPath, renderEntry(entry));
+  } catch (err) {
+    opts.d.log(
+      `  ${opts.ticket.filename}: could not record learnings: ${formatErrorMessage(err)}`
+    );
+  }
+}
+__name(recordAttempt, "recordAttempt");
+async function runTicketAttempts(opts) {
+  const { ticket, d } = opts;
+  return runWithRetries({
+    maxAttempts: opts.retries + 1,
+    retryDelay: opts.retryDelay,
+    agentCmd: opts.agentCmd,
+    effort: opts.effort,
+    label: ticket.filename,
+    log: /* @__PURE__ */ __name((msg) => d.log(msg), "log")
+  }, async (attempt, effort) => {
+    const record = /* @__PURE__ */ __name((o) => {
+      recordAttempt({
+        learningsPath: opts.learningsPath,
+        logsDir: opts.logsDir,
+        ticket,
+        attempt,
+        effort,
+        outcome: o,
+        d
+      });
+    }, "record");
+    let outcome;
     try {
       outcome = await runTicketAttempt({
         ...opts,
@@ -1256,25 +1514,46 @@ async function runTicketAttempts(opts) {
       d.log(
         `  ${ticket.filename}: attempt ${attempt} threw: ${formatErrorMessage(error)}`
       );
-      return { kind: "error", error };
+      const errorOutcome = { kind: "error", error };
+      record(errorOutcome);
+      return { result: errorOutcome, stop: true };
     }
+    record(outcome);
     if (outcome.kind === "ready") {
       d.setTicketStatus(
         ticket.num,
         "awaiting-merge",
         ticket.feature
       );
-      return outcome;
+      return { result: outcome, stop: true };
     }
-    if (outcome.kind === "worktree-error") return outcome;
-  }
-  return outcome;
+    return {
+      result: outcome,
+      stop: outcome.kind === "worktree-error"
+    };
+  });
 }
 __name(runTicketAttempts, "runTicketAttempts");
+function failureNote(reason) {
+  if (reason === "tests") return "tests failed";
+  if (reason === "install") return "install failed";
+  return "failed";
+}
+__name(failureNote, "failureNote");
+function isRegularFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+__name(isRegularFile, "isRegularFile");
 async function saveProgress(repoRoot, progressPath, progress, message, d) {
   writeProgress(progressPath, progress);
+  const learningsPath = learningsPathFor(progressPath);
+  const paths = isRegularFile(learningsPath) ? [progressPath, learningsPath] : progressPath;
   try {
-    await commitProgress(repoRoot, progressPath, message);
+    await commitProgress(repoRoot, paths, message);
   } catch (err) {
     d.log(
       "  Failed to commit progress: " + formatErrorMessage(err)
@@ -1344,6 +1623,29 @@ function renderFinishSummary(tickets, totalCompleted, failedKeys) {
   return lines.join("\n");
 }
 __name(renderFinishSummary, "renderFinishSummary");
+function sessionTickets(tickets) {
+  return [...tickets].filter((t) => t.status === "ready-for-agent").sort((a, b) => a.feature.localeCompare(b.feature) || a.num - b.num);
+}
+__name(sessionTickets, "sessionTickets");
+function toRef(t) {
+  return { num: t.num, filename: t.filename, feature: t.feature };
+}
+__name(toRef, "toRef");
+function reportBlocked(d, tickets, failedKeys) {
+  const byKey = new Map(
+    tickets.map((t) => [ticketKey(t.feature, t.num), t])
+  );
+  for (const [key, dead] of findBlockedTickets(
+    tickets,
+    failedKeys
+  )) {
+    const ticket = byKey.get(key);
+    if (!ticket) continue;
+    const labels = dead.map((k) => byKey.get(k)).filter((t) => t !== void 0).map((t) => ticketLabel(toRef(t)));
+    d.setBlocked(ticket.num, ticket.feature, labels);
+  }
+}
+__name(reportBlocked, "reportBlocked");
 function runProgress(tickets) {
   return {
     completed: tickets.filter((t) => t.status === "done").length,
@@ -1364,7 +1666,9 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
   let totalCompleted = 0;
   let waveNum = 0;
   const failedKeys = /* @__PURE__ */ new Set();
+  const session = sessionTickets(tickets);
   while (true) {
+    if (waveNum > 0) reportBlocked(d, tickets, failedKeys);
     const ready = findReadyTickets(tickets).filter(
       (t) => !failedKeys.has(
         ticketKey(t.feature, t.num)
@@ -1372,12 +1676,10 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
     );
     if (ready.length === 0) break;
     waveNum++;
-    const readyKeys = new Set(
-      ready.map((t) => ticketKey(t.feature, t.num))
-    );
-    const remaining2 = tickets.filter(
-      (t) => t.status === "ready-for-agent" && !readyKeys.has(ticketKey(t.feature, t.num))
-    );
+    if (waveNum === 1) {
+      d.startRun(session.map(toRef));
+      reportBlocked(d, tickets, failedKeys);
+    }
     d.startWave(
       waveNum,
       totalWaves,
@@ -1386,12 +1688,7 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
         filename: t.filename,
         feature: t.feature
       })),
-      runProgress(tickets),
-      remaining2.map((t) => ({
-        num: t.num,
-        filename: t.filename,
-        feature: t.feature
-      }))
+      runProgress(session)
     );
     const results = await runPool(
       ready,
@@ -1488,10 +1785,10 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
       );
     }
     if (waveCompleted === 0) {
-      const remaining3 = findReadyTickets(tickets).filter((t) => !failedKeys.has(
+      const remaining2 = findReadyTickets(tickets).filter((t) => !failedKeys.has(
         ticketKey(t.feature, t.num)
       ));
-      if (remaining3.length === 0) {
+      if (remaining2.length === 0) {
         d.log(
           "\nNo tickets completed this wave and no ready tickets remain. Stopping."
         );
@@ -1499,10 +1796,11 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, te
       }
       d.log(
         `
-No tickets completed this wave. ${remaining3.length} ready ticket${remaining3.length === 1 ? "" : "s"} remain; continuing.`
+No tickets completed this wave. ${remaining2.length} ready ticket${remaining2.length === 1 ? "" : "s"} remain; continuing.`
       );
     }
   }
+  if (waveNum > 0) reportBlocked(d, tickets, failedKeys);
   const remaining = tickets.filter(
     (t) => t.status === "ready-for-agent"
   );
@@ -1531,6 +1829,7 @@ 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)
   );
@@ -1595,7 +1894,9 @@ async function runWavesIsolated(opts) {
   let totalCompleted = 0;
   let waveNum = 0;
   const failedKeys = /* @__PURE__ */ new Set();
+  const session = sessionTickets(opts.tickets);
   while (true) {
+    if (waveNum > 0) reportBlocked(d, opts.tickets, failedKeys);
     const ready = findReadyTickets(opts.tickets).filter(
       (t) => !failedKeys.has(
         ticketKey(t.feature, t.num)
@@ -1603,12 +1904,10 @@ async function runWavesIsolated(opts) {
     );
     if (ready.length === 0) break;
     waveNum++;
-    const readyKeys = new Set(
-      ready.map((t) => ticketKey(t.feature, t.num))
-    );
-    const remaining2 = opts.tickets.filter(
-      (t) => t.status === "ready-for-agent" && !readyKeys.has(ticketKey(t.feature, t.num))
-    );
+    if (waveNum === 1) {
+      d.startRun(session.map(toRef));
+      reportBlocked(d, opts.tickets, failedKeys);
+    }
     d.startWave(
       waveNum,
       totalWaves,
@@ -1617,12 +1916,7 @@ async function runWavesIsolated(opts) {
         filename: t.filename,
         feature: t.feature
       })),
-      runProgress(opts.tickets),
-      remaining2.map((t) => ({
-        num: t.num,
-        filename: t.filename,
-        feature: t.feature
-      }))
+      runProgress(session)
     );
     const settled = await runPool(
       ready,
@@ -1639,13 +1933,34 @@ async function runWavesIsolated(opts) {
         timeout: opts.timeout,
         logsDir: opts.logsDir,
         testCmd: opts.testCmd,
+        installCmd: opts.installCmd,
         maxTurns: opts.maxTurns,
         effort: opts.effort,
+        learningsPath: learningsPathFor(
+          tracker.pathFor(t.feature)
+        ),
         retries,
         retryDelay,
         d
       })
     );
+    const touched = new Set(ready.map((t) => {
+      return learningsPathFor(tracker.pathFor(t.feature));
+    }));
+    for (const path of touched) {
+      if (!isRegularFile(path)) continue;
+      try {
+        await commitProgress(
+          repoRoot,
+          path,
+          "nightralph: record attempt learnings"
+        );
+      } catch (err) {
+        d.log(
+          "  Failed to commit learnings: " + formatErrorMessage(err)
+        );
+      }
+    }
     const outcomes = settled.map(
       (r) => r.status === "fulfilled" ? r.value : { kind: "error", error: r.reason }
     );
@@ -1749,7 +2064,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;
@@ -1785,6 +2100,7 @@ async function runWavesIsolated(opts) {
         branches: successfulBranches,
         strategy: opts.conflictStrategy
       });
+      const doneThisWave = [];
       for (const branchResult of mergeResult.merged) {
         const bk = branchToKey.get(
           branchResult.branch
@@ -1793,6 +2109,7 @@ async function runWavesIsolated(opts) {
         if (!ticket) continue;
         if (branchResult.merged) {
           markDone(ticket);
+          doneThisWave.push(ticket);
           waveCompleted++;
           totalCompleted++;
           d.setTicketStatus(
@@ -1842,11 +2159,13 @@ async function runWavesIsolated(opts) {
             timeout: opts.timeout,
             logsDir: opts.logsDir,
             testCmd: opts.testCmd,
+            installCmd: opts.installCmd,
             maxTurns: opts.maxTurns,
             onLine: /* @__PURE__ */ __name((msg) => d.log(msg), "onLine")
           }) : false;
           if (recovered) {
             markDone(ticket);
+            doneThisWave.push(ticket);
             waveCompleted++;
             totalCompleted++;
             d.setTicketStatus(
@@ -1884,6 +2203,11 @@ async function runWavesIsolated(opts) {
             failedKeys.add(
               ticketKey(ticket.feature, ticket.num)
             );
+            d.setTicketStatus(
+              ticket.num,
+              "failed",
+              ticket.feature
+            );
             d.log(
               `  ${ticket.filename}: merge failed, staying ready-for-agent`
             );
@@ -1897,6 +2221,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),
@@ -1907,6 +2253,7 @@ async function runWavesIsolated(opts) {
           }
         }
       }
+      await commitTicketFiles(repoRoot, doneThisWave, d);
       if (mergeResult.stoppedAt) {
         d.log(
           `
@@ -1931,12 +2278,12 @@ Merge stopped at ${mergeResult.stoppedAt.branch}`
       }
     }
     if (waveCompleted === 0) {
-      const remaining3 = findReadyTickets(
+      const remaining2 = findReadyTickets(
         opts.tickets
       ).filter((t) => !failedKeys.has(
         ticketKey(t.feature, t.num)
       ));
-      if (remaining3.length === 0) {
+      if (remaining2.length === 0) {
         d.log(
           "\nNo tickets completed this wave and no ready tickets remain. Stopping."
         );
@@ -1944,10 +2291,46 @@ Merge stopped at ${mergeResult.stoppedAt.branch}`
       }
       d.log(
         `
-No tickets completed this wave. ${remaining3.length} ready ticket${remaining3.length === 1 ? "" : "s"} remain; continuing.`
+No tickets completed this wave. ${remaining2.length} ready ticket${remaining2.length === 1 ? "" : "s"} remain; continuing.`
       );
     }
   }
+  if (waveNum > 0) reportBlocked(d, opts.tickets, failedKeys);
+  let reviewLine = null;
+  if (opts.review) {
+    try {
+      const outcome = await runReviewPass({
+        repoRoot,
+        repoName,
+        baseBranch,
+        reviewPath: opts.review.reviewPath,
+        forkedFrom: opts.review.forkedFrom,
+        launchCommit,
+        specBody: reviewSpecBody(
+          opts.specBody,
+          opts.specBodies
+        ),
+        agentCmd: opts.agentCmd,
+        model: opts.model,
+        timeout: opts.timeout,
+        logsDir: opts.logsDir,
+        testCmd: opts.testCmd,
+        installCmd: opts.installCmd,
+        maxTurns: opts.maxTurns,
+        effort: opts.effort,
+        retries,
+        retryDelay,
+        log: /* @__PURE__ */ __name((msg) => d.log(msg), "log")
+      }, { spawnAgent, registry: runningAgents });
+      reviewLine = renderReviewSummary(
+        outcome,
+        relative(repoRoot, opts.review.reviewPath)
+      );
+    } catch (err) {
+      d.log(`
+Review failed: ${formatErrorMessage(err)}`);
+    }
+  }
   const remaining = opts.tickets.filter(
     (t) => t.status === "ready-for-agent"
   );
@@ -1956,8 +2339,10 @@ No tickets completed this wave. ${remaining3.length} ready ticket${remaining3.le
     totalCompleted,
     failedKeys
   ));
+  if (reviewLine) d.log(reviewLine);
+  d.log(`Work is on ${baseBranch}`);
   d.cleanup();
-  return { allDone: remaining.length === 0 };
+  return { allDone: remaining.length === 0, branch: baseBranch };
 }
 __name(runWavesIsolated, "runWavesIsolated");
 export {
@@ -1966,7 +2351,7 @@ export {
   DEFAULT_CONCURRENCY,
   DEFAULT_RETRIES,
   DEFAULT_RETRY_DELAY,
-  EFFORT_LADDERS,
+  EFFORT_LADDERS2 as EFFORT_LADDERS,
   HUMAN_STATUS,
   TICKET_RE,
   TOOL_USE_RE,
@@ -1974,7 +2359,8 @@ export {
   createPiStreamFormatter,
   dryRun,
   dryRunIsolated,
-  escalateEffort,
+  escalateEffort2 as escalateEffort,
+  findBlockedTickets,
   findReadyTickets,
   formatErrorMessage,
   formatStreamLine,
@@ -1989,7 +2375,7 @@ export {
   renderFinishSummary,
   renderMergePrompt,
   renderPrompt,
-  retryDelayFor,
+  retryDelayFor2 as retryDelayFor,
   runPool,
   runWaves,
   runWavesIsolated,