nightralph 0.0.19 → 0.0.22

package/dist/index.js

@@ -3,8 +3,8 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/index.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
-import { dirname as dirname3, join as join5 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
+import { dirname as dirname3, join as join6 } from "node:path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { select as select2 } from "@inquirer/prompts";
@@ -27,7 +27,8 @@ var SKILL_DIRS = [
   "domain-modeling",
   "to-spec",
   "to-tickets",
-  "tdd"
+  "tdd",
+  "codebase-design"
 ];
 var DOC_TEMPLATES = [
   "triage-labels.md",
@@ -181,17 +182,17 @@ Source: ${upstream.repo} @ ${upstream.commit}`
 __name(setup, "setup");
 
 // src/orchestrator.ts
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 import {
   createWriteStream,
   mkdirSync as mkdirSync2,
-  readFileSync as readFileSync3,
+  readFileSync as readFileSync4,
   writeFileSync as writeFileSync3,
   unlinkSync,
   readdirSync as readdirSync2
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join3, dirname, basename as basename2 } from "node:path";
+import { join as join4, dirname, basename as basename2 } from "node:path";
 import { createInterface } from "node:readline";
 
 // src/worktree.ts
@@ -235,7 +236,7 @@ async function branchExists(repoRoot, branchName) {
   }
 }
 __name(branchExists, "branchExists");
-async function createWorktree(opts) {
+async function createWorktreeNow(opts) {
   const { repoRoot, repoName, baseBranch, ticket } = opts;
   const branchName = `${repoName}/${String(
     ticket.num
@@ -286,12 +287,25 @@ async function createWorktree(opts) {
   );
   return { worktreePath, branchName };
 }
+__name(createWorktreeNow, "createWorktreeNow");
+var worktreeQueue = Promise.resolve();
+function createWorktree(opts) {
+  const result = worktreeQueue.then(() => createWorktreeNow(opts));
+  worktreeQueue = result.catch(() => {
+  });
+  return result;
+}
 __name(createWorktree, "createWorktree");
-async function removeWorktree(worktreePath) {
-  await execFileAsync(
-    "git",
-    ["-C", worktreePath, "worktree", "remove", worktreePath]
-  );
+async function removeWorktree(worktreePath, opts) {
+  const args = [
+    "-C",
+    worktreePath,
+    "worktree",
+    "remove"
+  ];
+  if (opts?.force) args.push("--force");
+  args.push(worktreePath);
+  await execFileAsync("git", args);
 }
 __name(removeWorktree, "removeWorktree");
 function hasNewCommits(repoRoot, base, branch) {
@@ -482,11 +496,21 @@ async function commitProgress(repoRoot, progressPath, message) {
     ["add", "--force", progressPath],
     { cwd: repoRoot }
   );
+  try {
+    await execFileAsync2(
+      "git",
+      ["diff", "--cached", "--quiet", "--", progressPath],
+      { cwd: repoRoot }
+    );
+    return false;
+  } catch {
+  }
   await execFileAsync2(
     "git",
     ["commit", "-m", message, "--", progressPath],
     { cwd: repoRoot }
   );
+  return true;
 }
 __name(commitProgress, "commitProgress");
 
@@ -768,7 +792,6 @@ var StatusDisplay = class {
   config;
   viewportStart = 0;
   resizeListener = null;
-  signalHandler = null;
   constructor(config) {
     this.config = {
       stream: config?.stream ?? process.stdout
@@ -810,13 +833,6 @@ var StatusDisplay = class {
         this.resizeListener
       );
     }
-    if (this.signalHandler) {
-      process.removeListener("SIGINT", this.signalHandler);
-      process.removeListener("SIGTERM", this.signalHandler);
-    }
-    this.signalHandler = () => this.cleanup();
-    process.on("SIGINT", this.signalHandler);
-    process.on("SIGTERM", this.signalHandler);
     this.render();
   }
   setTicketStatus(num, status) {
@@ -852,10 +868,6 @@ var StatusDisplay = class {
     if (this.resizeListener && this.config.stream.isTTY) {
       this.config.stream.removeListener("resize", this.resizeListener);
     }
-    if (this.signalHandler) {
-      process.removeListener("SIGINT", this.signalHandler);
-      process.removeListener("SIGTERM", this.signalHandler);
-    }
     this.config.stream.write(ansi.cursorShow());
   }
   render() {
@@ -988,11 +1000,83 @@ function createDisplay(stream) {
 }
 __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 runTestCmd(opts) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const child = spawn("sh", ["-c", opts.cmd], {
+      cwd: opts.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: 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);
+      chunks.push(String(err));
+      resolve({
+        exitCode: 1,
+        output: chunks.join("")
+      });
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        exitCode: code ?? 1,
+        output: chunks.join("")
+      });
+    });
+  });
+}
+__name(runTestCmd, "runTestCmd");
+
 // src/orchestrator.ts
 function formatErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 __name(formatErrorMessage, "formatErrorMessage");
+async function removeWorktreeQuietly(worktreePath, d) {
+  try {
+    await removeWorktree(worktreePath, { force: true });
+  } catch (err) {
+    d.log(
+      `  Failed to remove worktree ${worktreePath}: ` + formatErrorMessage(err)
+    );
+  }
+}
+__name(removeWorktreeQuietly, "removeWorktreeQuietly");
 var TICKET_RE = /^(\d+)-(.+)\.md$/;
 function parseTicketFilename(filename) {
   const m = filename.match(TICKET_RE);
@@ -1027,8 +1111,8 @@ function scanTickets(dir) {
   ));
   return files.map((filename) => {
     const parsed = parseTicketFilename(filename);
-    const filepath = join3(dir, filename);
-    const body = readFileSync3(filepath, "utf8");
+    const filepath = join4(dir, filename);
+    const body = readFileSync4(filepath, "utf8");
     return {
       num: parsed.num,
       slug: parsed.slug,
@@ -1083,7 +1167,39 @@ function markDone(ticket) {
   ticket.body = updated;
 }
 __name(markDone, "markDone");
-function renderPrompt(specBody, ticket) {
+function stripSpecSection(specBody, heading) {
+  const out = [];
+  let skipping = false;
+  let skipLevel = 0;
+  let inFence = false;
+  for (const line of specBody.split("\n")) {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+    }
+    if (!inFence) {
+      const m = /^(#{1,6})\s+(.*?)\s*$/.exec(line);
+      if (m) {
+        const level = m[1].length;
+        if (skipping && level <= skipLevel) {
+          skipping = false;
+        }
+        if (!skipping && m[2] === heading) {
+          skipping = true;
+          skipLevel = level;
+          continue;
+        }
+      }
+    }
+    if (!skipping) out.push(line);
+  }
+  return out.join("\n");
+}
+__name(stripSpecSection, "stripSpecSection");
+function renderPrompt(specBody, ticket, opts = {}) {
+  const testRules = opts.testCmd ? [
+    "- Work test-first. For each checklist 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.",
+    `- Run \`${opts.testCmd}\` before committing. Do not commit with failing tests. The orchestrator runs the same command after you exit and rejects the ticket if it fails.`
+  ] : [];
   return [
     "---- SPEC CONTEXT ----",
     specBody,
@@ -1095,10 +1211,12 @@ function renderPrompt(specBody, ticket) {
     "---- AGENT INSTRUCTIONS ----",
     "You are an autonomous coding agent. Implement the ticket.",
     "",
-    "Time is limited. Follow these rules:",
-    "- Spend at most 2 minutes reading existing code. Read only the files directly relevant to the ticket.",
+    "Follow these rules:",
+    "- Read the files directly relevant to the ticket before writing code.",
     "- Do NOT research external APIs or services via web search. Use the spec and ticket body as your sole reference for API shapes.",
-    "- Start writing code as soon as you understand the immediate context. You can read more files as needed while implementing.",
+    ...testRules,
+    "- Do NOT read or modify files outside your current directory (the worktree).",
+    "- Do NOT run git push.",
     "- Commit your work when finished.",
     "- After completing each checklist item in the ticket, print a line: [x] <item text> (matching the checklist text exactly).",
     ""
@@ -1124,7 +1242,8 @@ function renderMergePrompt(specBody, ticket) {
     "2. Make sure the code compiles and tests pass.",
     "3. Commit the resolved files.",
     "",
-    "Do NOT re-implement the ticket from scratch."
+    "Do NOT re-implement the ticket from scratch.",
+    "Do NOT run git push."
   ].join("\n");
 }
 __name(renderMergePrompt, "renderMergePrompt");
@@ -1203,7 +1322,11 @@ var PROVIDER_ARGS = {
     "stream-json",
     "--dangerously-skip-permissions"
   ],
-  codex: ["exec", "--full-auto"],
+  // codex removed --full-auto; this is the counterpart
+  // of claude's --dangerously-skip-permissions, and the
+  // workspace-write sandbox would block commits because
+  // a worktree's .git link points outside the tree
+  codex: ["exec", "--dangerously-bypass-approvals-and-sandbox"],
   pi: [
     "-p",
     "--verbose",
@@ -1218,6 +1341,21 @@ function getProviderArgs(cmd) {
   return PROVIDER_ARGS[name] ?? [];
 }
 __name(getProviderArgs, "getProviderArgs");
+var THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+];
+function escalateThinking(level) {
+  if (!level) return "high";
+  const i = THINKING_LEVELS.indexOf(level);
+  return THINKING_LEVELS[Math.min(i + 1, THINKING_LEVELS.length - 1)];
+}
+__name(escalateThinking, "escalateThinking");
 function formatStreamLine(line) {
   let obj;
   try {
@@ -1318,7 +1456,7 @@ function createPiStreamFormatter() {
 __name(createPiStreamFormatter, "createPiStreamFormatter");
 function writePromptFile(prompt) {
   const name = `nightralph-${Date.now()}-${Math.random().toString(36).slice(2)}.md`;
-  const filePath = join3(tmpdir(), name);
+  const filePath = join4(tmpdir(), name);
   writeFileSync3(filePath, prompt);
   return filePath;
 }
@@ -1330,6 +1468,22 @@ function cleanupPromptFile(filePath) {
   }
 }
 __name(cleanupPromptFile, "cleanupPromptFile");
+var CLOSE_GRACE_MS = 2e3;
+function killProcessGroup(pid) {
+  if (pid === void 0) return;
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+  }
+}
+__name(killProcessGroup, "killProcessGroup");
+var runningAgents = /* @__PURE__ */ new Set();
+function killRunningAgents() {
+  for (const pid of runningAgents) {
+    killProcessGroup(pid);
+  }
+}
+__name(killRunningAgents, "killRunningAgents");
 function spawnAgent(opts) {
   const args = [
     ...getProviderArgs(opts.agentCmd)
@@ -1337,9 +1491,15 @@ function spawnAgent(opts) {
   if (opts.model) {
     args.push("--model", opts.model);
   }
+  if (opts.maxTurns) {
+    args.push("--max-turns", String(opts.maxTurns));
+  }
   const providerName = basename2(opts.agentCmd);
   const isClaude = providerName === "claude";
   const isPi = providerName === "pi";
+  if (isPi && opts.thinking) {
+    args.push("--thinking", opts.thinking);
+  }
   const prefix = opts.label ? `  [${opts.label}] ` : "  ";
   let promptFile = null;
   if (isPi) {
@@ -1350,10 +1510,12 @@ function spawnAgent(opts) {
     opts.logPath,
     { flags: "w" }
   );
-  const proc = spawn(opts.agentCmd, args, {
+  const proc = spawn2(opts.agentCmd, args, {
     stdio: ["pipe", "pipe", "pipe"],
-    cwd: opts.cwd
+    cwd: opts.cwd,
+    detached: true
   });
+  if (proc.pid !== void 0) runningAgents.add(proc.pid);
   proc.stdout.pipe(logStream);
   const piFormatter = isPi ? createPiStreamFormatter() : null;
   const completedItems = [];
@@ -1407,21 +1569,41 @@ function spawnAgent(opts) {
       console.error(output);
     }
   });
+  let timedOut = false;
   const timeout = setTimeout(() => {
-    if (!proc.killed) {
-      console.warn(
-        `Agent did not exit in ${opts.timeout}s; killing.`
-      );
-      proc.kill("SIGKILL");
+    if (proc.killed) return;
+    timedOut = true;
+    const msg = `agent timed out after ${opts.timeout}s; killing it`;
+    logStream.write(`nightralph: ${msg}
+`);
+    if (opts.onLine) {
+      opts.onLine(`${prefix}${msg}`);
+    } else {
+      console.warn(`${prefix}${msg}`);
     }
+    killProcessGroup(proc.pid);
   }, opts.timeout * 1e3);
+  proc.stdin.on("error", (err) => {
+    logStream.write(
+      `nightralph: stdin write failed: ${formatErrorMessage(err)}
+`
+    );
+  });
   if (!promptFile) {
     proc.stdin.write(opts.prompt);
   }
   proc.stdin.end();
   return new Promise((resolve) => {
-    proc.on("close", (code) => {
+    let settled = false;
+    let graceTimer;
+    function finish(exitCode) {
+      if (settled) return;
+      settled = true;
       clearTimeout(timeout);
+      if (graceTimer) clearTimeout(graceTimer);
+      if (proc.pid !== void 0) {
+        runningAgents.delete(proc.pid);
+      }
       if (piFormatter) {
         for (const line of piFormatter.flush()) {
           collectCompleted(line);
@@ -1437,13 +1619,27 @@ function spawnAgent(opts) {
       rlErr.close();
       logStream.end();
       if (promptFile) cleanupPromptFile(promptFile);
-      resolve({
-        exitCode: code ?? 1,
-        completedItems
-      });
+      resolve({ exitCode, completedItems, timedOut });
+    }
+    __name(finish, "finish");
+    proc.on("exit", (code) => {
+      graceTimer = setTimeout(() => {
+        proc.stdout.destroy();
+        proc.stderr.destroy();
+        finish(code ?? 1);
+      }, CLOSE_GRACE_MS);
+    });
+    proc.on("close", (code) => {
+      finish(code ?? 1);
     });
     proc.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      if (graceTimer) clearTimeout(graceTimer);
       clearTimeout(timeout);
+      if (proc.pid !== void 0) {
+        runningAgents.delete(proc.pid);
+      }
       rl.close();
       rlErr.close();
       logStream.end();
@@ -1452,7 +1648,11 @@ function spawnAgent(opts) {
         "Agent process error:",
         formatErrorMessage(err)
       );
-      resolve({ exitCode: 1, completedItems });
+      resolve({
+        exitCode: 1,
+        completedItems,
+        timedOut
+      });
     });
   });
 }
@@ -1515,18 +1715,65 @@ Prompt for first ready ticket (${firstReady[0].filename}):
 `
     );
     console.log(
-      renderPrompt(opts.specBody, firstReady[0])
+      renderPrompt(
+        opts.specBody,
+        firstReady[0],
+        { testCmd: opts.testCmd }
+      )
     );
   }
   const strategyDesc = opts.conflictStrategy === "respawn" ? "respawn (re-run agent on conflict)" : "stop (stop merging on conflict)";
   console.log(
     `
+Test command: ${opts.testCmd ?? "(none)"}`
+  );
+  console.log(
+    `Thinking:     ${opts.thinking ?? "(provider default)"}`
+  );
+  console.log(
+    `Retries:      ${opts.retries ?? DEFAULT_RETRIES}`
+  );
+  console.log(
+    `Retry delay:  ${opts.retryDelay ?? DEFAULT_RETRY_DELAY}s`
+  );
+  console.log(
+    `
 Merge strategy: ${strategyDesc}`
   );
   console.log(`Progress file: ${opts.progressPath}`);
 }
 __name(dryRunIsolated, "dryRunIsolated");
+async function runTestGate(opts) {
+  const result = await runTestCmd({
+    cmd: opts.testCmd,
+    cwd: opts.worktreePath,
+    timeout: opts.timeout
+  });
+  const testLogPath = attemptLogPath(
+    opts.logsDir,
+    opts.ticket,
+    opts.attempt ?? 1,
+    ".test.log"
+  );
+  writeFileSync3(testLogPath, result.output);
+  if (result.exitCode !== 0) {
+    opts.log(
+      `  ${opts.ticket.filename}: tests failed (exit ${result.exitCode}); see ${testLogPath}`
+    );
+    return false;
+  }
+  opts.log(`  ${opts.ticket.filename}: tests passed`);
+  return true;
+}
+__name(runTestGate, "runTestGate");
 async function respawnAndRetryMerge(opts) {
+  const log = /* @__PURE__ */ __name((msg) => {
+    if (opts.onLine) {
+      opts.onLine(msg);
+    } else {
+      console.log(msg);
+    }
+  }, "log");
   await updateWorktreeFromBase(
     opts.worktreePath,
     opts.baseBranch
@@ -1541,7 +1788,7 @@ async function respawnAndRetryMerge(opts) {
     opts.specBody,
     opts.ticket
   );
-  const logPath = join3(
+  const logPath = join4(
     opts.logsDir,
     opts.ticket.filename.replace(/\.md$/, ".respawn.log")
   );
@@ -1557,6 +1804,7 @@ async function respawnAndRetryMerge(opts) {
     logPath,
     cwd: opts.worktreePath,
     label,
+    maxTurns: opts.maxTurns,
     onLine: opts.onLine
   });
   if (result.exitCode !== 0) {
@@ -1568,6 +1816,22 @@ async function respawnAndRetryMerge(opts) {
     }
     return false;
   }
+  if (opts.testCmd) {
+    const passed = await runTestGate({
+      testCmd: opts.testCmd,
+      ticket: opts.ticket,
+      worktreePath: opts.worktreePath,
+      timeout: opts.timeout,
+      logsDir: opts.logsDir,
+      log
+    });
+    if (!passed) {
+      log(
+        `  ${opts.ticket.filename}: tests failed after conflict respawn; not merging`
+      );
+      return false;
+    }
+  }
   const mergeResult = await mergeBranch(
     opts.repoRoot,
     opts.branch
@@ -1591,6 +1855,171 @@ async function respawnAndRetryMerge(opts) {
   return mergeResult.success;
 }
 __name(respawnAndRetryMerge, "respawnAndRetryMerge");
+var DEFAULT_RETRIES = 2;
+var DEFAULT_RETRY_DELAY = 30;
+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 join4(logsDir, `${stem}${suffix}${ext}`);
+}
+__name(attemptLogPath, "attemptLogPath");
+async function runTicketAttempt(opts) {
+  const { ticket, d } = opts;
+  let worktree;
+  try {
+    worktree = await createWorktree({
+      repoRoot: opts.repoRoot,
+      repoName: opts.repoName,
+      baseBranch: opts.baseBranch,
+      ticket
+    });
+  } catch (error) {
+    return { kind: "worktree-error", error };
+  }
+  d.setTicketStatus(ticket.num, "in-progress");
+  const agentResult = await spawnAgent({
+    prompt: renderPrompt(
+      opts.specBody,
+      ticket,
+      { testCmd: opts.testCmd }
+    ),
+    agentCmd: opts.agentCmd,
+    model: opts.model,
+    timeout: opts.timeout,
+    logPath: attemptLogPath(
+      opts.logsDir,
+      ticket,
+      opts.attempt,
+      ".log"
+    ),
+    cwd: worktree.worktreePath,
+    label: ticket.filename.replace(/\.md$/, ""),
+    maxTurns: opts.maxTurns,
+    thinking: opts.thinking,
+    onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
+  });
+  if (agentResult.timedOut) {
+    d.log(
+      `  ${ticket.filename}: timed out; keeping the work it committed`
+    );
+  } else if (agentResult.exitCode !== 0) {
+    d.log(
+      `  ${ticket.filename}: agent exited ${agentResult.exitCode}`
+    );
+    await removeWorktreeQuietly(worktree.worktreePath, d);
+    return {
+      kind: "failed",
+      reason: "exit",
+      branchName: worktree.branchName,
+      exitCode: agentResult.exitCode,
+      completedItems: agentResult.completedItems
+    };
+  }
+  if (isDirty(worktree.worktreePath)) {
+    const committed = await commitDirty(
+      worktree.worktreePath,
+      `nightralph: auto-commit ${ticket.filename} remaining changes`
+    );
+    if (committed) {
+      d.log(
+        `  ${ticket.filename}: auto-committed remaining changes`
+      );
+    }
+  }
+  if (!hasNewCommits(
+    opts.repoRoot,
+    opts.baseBranch,
+    worktree.branchName
+  )) {
+    return { kind: "no-commits" };
+  }
+  if (opts.testCmd) {
+    const passed = await runTestGate({
+      testCmd: opts.testCmd,
+      ticket,
+      worktreePath: worktree.worktreePath,
+      timeout: opts.timeout,
+      logsDir: opts.logsDir,
+      attempt: opts.attempt,
+      log: /* @__PURE__ */ __name((msg) => d.log(msg), "log")
+    });
+    if (!passed) {
+      await removeWorktreeQuietly(
+        worktree.worktreePath,
+        d
+      );
+      return {
+        kind: "failed",
+        reason: "tests",
+        branchName: worktree.branchName,
+        exitCode: 1,
+        completedItems: agentResult.completedItems
+      };
+    }
+  }
+  return {
+    kind: "ready",
+    worktreePath: worktree.worktreePath,
+    branchName: worktree.branchName,
+    completedItems: agentResult.completedItems
+  };
+}
+__name(runTicketAttempt, "runTicketAttempt");
+async function runTicketAttempts(opts) {
+  const { ticket, d } = opts;
+  const maxAttempts = opts.retries + 1;
+  const isPi = basename2(opts.agentCmd) === "pi";
+  let thinking = opts.thinking;
+  let outcome = { kind: "no-commits" };
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (attempt === 1) {
+      d.log(`  Starting ${ticket.filename}`);
+    } else {
+      thinking = escalateThinking(thinking);
+      const delay = retryDelayFor(opts.retryDelay, attempt);
+      d.log(
+        `  ${ticket.filename}: retrying (attempt ${attempt}/${maxAttempts}` + (isPi ? `, thinking ${thinking}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
+      );
+      if (delay > 0) await sleep(delay * 1e3);
+    }
+    try {
+      outcome = await runTicketAttempt({
+        ...opts,
+        attempt,
+        thinking
+      });
+    } catch (error) {
+      d.log(
+        `  ${ticket.filename}: attempt ${attempt} threw: ${formatErrorMessage(error)}`
+      );
+      return { kind: "error", error };
+    }
+    if (outcome.kind === "ready" || outcome.kind === "worktree-error") {
+      return outcome;
+    }
+  }
+  return outcome;
+}
+__name(runTicketAttempts, "runTicketAttempts");
+async function saveProgress(repoRoot, progressPath, progress, message, d) {
+  writeProgress(progressPath, progress);
+  try {
+    await commitProgress(repoRoot, progressPath, message);
+  } catch (err) {
+    d.log(
+      "  Failed to commit progress: " + formatErrorMessage(err)
+    );
+  }
+}
+__name(saveProgress, "saveProgress");
 function runProgress(tickets) {
   return {
     completed: tickets.filter((t) => t.status === "done").length,
@@ -1598,15 +2027,21 @@ function runProgress(tickets) {
   };
 }
 __name(runProgress, "runProgress");
-async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, display) {
+async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, display, maxTurns, thinking, retries, retryDelay) {
   mkdirSync2(logsDir, { recursive: true });
   const d = display ?? createDisplay();
+  const maxAttempts = (retries ?? DEFAULT_RETRIES) + 1;
+  const delayBase = retryDelay ?? 0;
+  const isPi = basename2(agentCmd) === "pi";
   let totalWaves = 0;
   for (const _ of simulateWaves(tickets)) totalWaves++;
   let totalCompleted = 0;
   let waveNum = 0;
+  const failedNums = /* @__PURE__ */ new Set();
   while (true) {
-    const ready = findReadyTickets(tickets);
+    const ready = findReadyTickets(tickets).filter(
+      (t) => !failedNums.has(t.num)
+    );
     if (ready.length === 0) break;
     waveNum++;
     const readyNums = new Set(ready.map((t) => t.num));
@@ -1629,25 +2064,48 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, di
     const results = await Promise.allSettled(
       ready.map(async (t) => {
         const prompt = renderPrompt(specBody, t);
-        const logPath = join3(
-          logsDir,
-          t.filename.replace(/\.md$/, ".log")
-        );
         const label = t.filename.replace(
           /\.md$/,
           ""
         );
         d.setTicketStatus(t.num, "in-progress");
         d.log(`  Starting ${t.filename}`);
-        const result = await spawnAgent({
+        let level = thinking;
+        let result = await spawnAgent({
           prompt,
           agentCmd,
           model,
           timeout,
-          logPath,
+          logPath: attemptLogPath(logsDir, t, 1, ".log"),
           label,
+          maxTurns,
+          thinking: level,
           onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
         });
+        for (let attempt = 2; result.exitCode !== 0 && !result.timedOut && attempt <= maxAttempts; attempt++) {
+          level = escalateThinking(level);
+          const delay = retryDelayFor(delayBase, attempt);
+          d.log(
+            `  ${t.filename}: agent exited ${result.exitCode}; retrying (attempt ${attempt}/${maxAttempts}` + (isPi ? `, thinking ${level}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
+          );
+          if (delay > 0) await sleep(delay * 1e3);
+          result = await spawnAgent({
+            prompt,
+            agentCmd,
+            model,
+            timeout,
+            logPath: attemptLogPath(
+              logsDir,
+              t,
+              attempt,
+              ".log"
+            ),
+            label,
+            maxTurns,
+            thinking: level,
+            onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
+          });
+        }
         return { ticket: t, result };
       })
     );
@@ -1656,6 +2114,7 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, di
       if (r.status === "rejected") continue;
       const { ticket, result } = r.value;
       if (result.exitCode !== 0) {
+        failedNums.add(ticket.num);
         d.setTicketStatus(ticket.num, "failed");
         d.log(
           `  ${ticket.filename}: agent exited ${result.exitCode}`
@@ -1683,7 +2142,7 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, di
   );
   d.log(
     `
-Finished: ${totalCompleted} completed` + (remaining.length > 0 ? `, ${remaining.length} remaining` : "")
+Finished: ${totalCompleted} completed` + (remaining.length > 0 ? `, ${remaining.length} remaining` : "") + (failedNums.size > 0 ? `, ${failedNums.size} failed` : "")
   );
   d.cleanup();
   return { allDone: remaining.length === 0 };
@@ -1692,6 +2151,8 @@ __name(runWaves, "runWaves");
 async function runWavesIsolated(opts) {
   mkdirSync2(opts.logsDir, { recursive: true });
   const d = opts.display ?? createDisplay();
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const retryDelay = opts.retryDelay ?? 0;
   let totalWaves = 0;
   for (const _ of simulateWaves(opts.tickets)) totalWaves++;
   const repoRoot = getRepoRoot();
@@ -1702,7 +2163,7 @@ async function runWavesIsolated(opts) {
       "Working tree is dirty; commit or stash changes before running"
     );
   }
-  const progressPath = join3(
+  const progressPath = join4(
     dirname(opts.logsDir),
     "progress.md"
   );
@@ -1710,16 +2171,23 @@ async function runWavesIsolated(opts) {
     generateProgress(opts.featureName, opts.tickets),
     readProgress(progressPath)
   );
-  writeProgress(progressPath, progress);
-  await commitProgress(
+  await saveProgress(
     repoRoot,
     progressPath,
-    `nightralph: start ${opts.featureName}`
+    progress,
+    `nightralph: start ${opts.featureName}`,
+    d
   );
+  if (!opts.testCmd) {
+    d.log("  Test gate disabled: no test command");
+  }
   let totalCompleted = 0;
   let waveNum = 0;
+  const failedNums = /* @__PURE__ */ new Set();
   while (true) {
-    const ready = findReadyTickets(opts.tickets);
+    const ready = findReadyTickets(opts.tickets).filter(
+      (t) => !failedNums.has(t.num)
+    );
     if (ready.length === 0) break;
     waveNum++;
     const readyNums = new Set(ready.map((t) => t.num));
@@ -1739,125 +2207,89 @@ async function runWavesIsolated(opts) {
         filename: t.filename
       }))
     );
-    const worktreeSettled = await Promise.allSettled(
-      ready.map((t) => createWorktree({
+    const outcomes = await Promise.all(
+      ready.map((t) => runTicketAttempts({
+        ticket: t,
         repoRoot,
         repoName,
         baseBranch,
-        ticket: t
+        specBody: opts.specBody,
+        agentCmd: opts.agentCmd,
+        model: opts.model,
+        timeout: opts.timeout,
+        logsDir: opts.logsDir,
+        testCmd: opts.testCmd,
+        maxTurns: opts.maxTurns,
+        thinking: opts.thinking,
+        retries,
+        retryDelay,
+        d
       }))
     );
-    const activeTickets = [];
-    const worktrees = [];
-    for (let i = 0; i < worktreeSettled.length; i++) {
-      const settled = worktreeSettled[i];
+    let waveCompleted = 0;
+    const successfulBranches = [];
+    const ticketsByNum = /* @__PURE__ */ new Map();
+    const worktreePathsByNum = /* @__PURE__ */ new Map();
+    for (let i = 0; i < outcomes.length; i++) {
+      const outcome = outcomes[i];
       const ticket = ready[i];
-      if (settled.status === "rejected") {
+      if (outcome.kind === "worktree-error") {
+        failedNums.add(ticket.num);
         d.setTicketStatus(ticket.num, "failed");
         d.log(
-          `  ${ticket.filename}: failed to create worktree: ${formatErrorMessage(settled.reason)}`
+          `  ${ticket.filename}: failed to create worktree: ${formatErrorMessage(outcome.error)}`
         );
         continue;
       }
-      activeTickets.push(ticket);
-      worktrees.push(settled.value);
-    }
-    const results = await Promise.allSettled(
-      activeTickets.map((t, i) => {
-        const prompt = renderPrompt(opts.specBody, t);
-        const logPath = join3(
-          opts.logsDir,
-          t.filename.replace(/\.md$/, ".log")
-        );
-        const label = t.filename.replace(
-          /\.md$/,
-          ""
+      if (outcome.kind === "error") {
+        failedNums.add(ticket.num);
+        d.setTicketStatus(ticket.num, "failed");
+        d.log(
+          `  ${ticket.filename}: attempt error: ` + formatErrorMessage(outcome.error)
         );
-        d.setTicketStatus(t.num, "in-progress");
-        d.log(`  Starting ${t.filename}`);
-        return spawnAgent({
-          prompt,
-          agentCmd: opts.agentCmd,
-          model: opts.model,
-          timeout: opts.timeout,
-          logPath,
-          cwd: worktrees[i].worktreePath,
-          label,
-          onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
-        });
-      })
-    );
-    let waveCompleted = 0;
-    const successfulBranches = [];
-    const ticketsByNum = /* @__PURE__ */ new Map();
-    const worktreePathsByNum = /* @__PURE__ */ new Map();
-    for (let i = 0; i < results.length; i++) {
-      const r = results[i];
-      if (r.status === "rejected") continue;
-      const agentResult = r.value;
-      const ticket = activeTickets[i];
-      const worktree = worktrees[i];
-      if (agentResult.exitCode !== 0) {
+        continue;
+      }
+      if (outcome.kind === "no-commits") {
+        failedNums.add(ticket.num);
         d.setTicketStatus(ticket.num, "failed");
         d.log(
-          `  ${ticket.filename}: agent exited ${agentResult.exitCode}`
+          `  ${ticket.filename}: agent exited 0 but made no changes; leaving ticket ready-for-agent`
         );
-        checkItems(ticket, agentResult.completedItems);
+        continue;
+      }
+      if (outcome.kind === "failed") {
+        failedNums.add(ticket.num);
+        d.setTicketStatus(ticket.num, "failed");
+        if (outcome.reason === "exit") {
+          checkItems(ticket, outcome.completedItems);
+        }
         checkTicket(progress, ticket.num, {
-          branch: worktree.branchName,
-          exitCode: agentResult.exitCode,
+          branch: outcome.branchName,
+          exitCode: outcome.exitCode,
           done: false
         });
-        writeProgress(progressPath, progress);
-        await commitProgress(
+        await saveProgress(
           repoRoot,
           progressPath,
-          `nightralph: ${ticket.filename} failed`
-        );
-        try {
-          await removeWorktree(worktree.worktreePath);
-        } catch (err) {
-          d.log(
-            `  Failed to remove worktree ${worktree.worktreePath}: ` + formatErrorMessage(err)
-          );
-        }
-        continue;
-      }
-      if (isDirty(worktree.worktreePath)) {
-        const committed = await commitDirty(
-          worktree.worktreePath,
-          `nightralph: auto-commit ${ticket.filename} remaining changes`
-        );
-        if (committed) {
-          d.log(
-            `  ${ticket.filename}: auto-committed remaining changes`
-          );
-        }
-      }
-      if (!hasNewCommits(
-        repoRoot,
-        baseBranch,
-        worktree.branchName
-      )) {
-        d.setTicketStatus(ticket.num, "failed");
-        d.log(
-          `  ${ticket.filename}: agent exited 0 but made no changes; leaving ticket ready-for-agent`
+          progress,
+          `nightralph: ${ticket.filename} ` + (outcome.reason === "tests" ? "tests failed" : "failed"),
+          d
         );
         continue;
       }
-      checkItems(ticket, agentResult.completedItems);
+      checkItems(ticket, outcome.completedItems);
       d.log(
         `  ${ticket.filename}: agent finished, awaiting merge`
       );
       ticketsByNum.set(ticket.num, ticket);
       worktreePathsByNum.set(
         ticket.num,
-        worktree.worktreePath
+        outcome.worktreePath
       );
       successfulBranches.push({
-        branch: worktree.branchName,
+        branch: outcome.branchName,
         ticketNum: ticket.num,
-        worktreePath: worktree.worktreePath
+        worktreePath: outcome.worktreePath
       });
     }
     if (successfulBranches.length > 0) {
@@ -1884,23 +2316,21 @@ async function runWavesIsolated(opts) {
             branch: branchResult.branch,
             exitCode: 0
           });
-          writeProgress(progressPath, progress);
-          await commitProgress(
+          await saveProgress(
             repoRoot,
             progressPath,
-            `nightralph: ${ticket.filename} done`
+            progress,
+            `nightralph: ${ticket.filename} done`,
+            d
           );
           const worktreePath = worktreePathsByNum.get(
             ticket.num
           );
           if (worktreePath) {
-            try {
-              await removeWorktree(worktreePath);
-            } catch (err) {
-              d.log(
-                `  Failed to remove worktree ${worktreePath}: ` + formatErrorMessage(err)
-              );
-            }
+            await removeWorktreeQuietly(
+              worktreePath,
+              d
+            );
           }
         } else {
           const worktreePath = worktreePathsByNum.get(
@@ -1917,6 +2347,8 @@ async function runWavesIsolated(opts) {
             model: opts.model,
             timeout: opts.timeout,
             logsDir: opts.logsDir,
+            testCmd: opts.testCmd,
+            maxTurns: opts.maxTurns,
             onLine: /* @__PURE__ */ __name((msg) => d.log(msg), "onLine")
           }) : false;
           if (recovered) {
@@ -1931,15 +2363,19 @@ async function runWavesIsolated(opts) {
               branch: branchResult.branch,
               exitCode: 0
             });
-            writeProgress(progressPath, progress);
-            await commitProgress(
+            await saveProgress(
               repoRoot,
               progressPath,
-              `nightralph: ${ticket.filename} done (respawn)`
+              progress,
+              `nightralph: ${ticket.filename} done (respawn)`,
+              d
             );
             if (worktreePath) {
               try {
-                await removeWorktree(worktreePath);
+                await removeWorktree(
+                  worktreePath,
+                  { force: true }
+                );
               } catch (err) {
                 d.log(
                   `  Failed to remove worktree ${worktreePath}: ` + formatErrorMessage(err)
@@ -1960,11 +2396,12 @@ async function runWavesIsolated(opts) {
               exitCode: 0,
               done: false
             });
-            writeProgress(progressPath, progress);
-            await commitProgress(
+            await saveProgress(
               repoRoot,
               progressPath,
-              `nightralph: ${ticket.filename} merge failed`
+              progress,
+              `nightralph: ${ticket.filename} merge failed`,
+              d
             );
           }
         }
@@ -1978,7 +2415,10 @@ Merge stopped at ${mergeResult.stoppedAt.branch}`
           const ticket = ticketsByNum.get(sb.ticketNum);
           if (ticket && ticket.status === "done") continue;
           try {
-            await removeWorktree(sb.worktreePath);
+            await removeWorktree(
+              sb.worktreePath,
+              { force: true }
+            );
           } catch (err) {
             d.log(
               `  Failed to remove worktree ${sb.worktreePath}: ` + formatErrorMessage(err)
@@ -2000,7 +2440,7 @@ Merge stopped at ${mergeResult.stoppedAt.branch}`
   );
   d.log(
     `
-Finished: ${totalCompleted} completed` + (remaining.length > 0 ? `, ${remaining.length} remaining` : "")
+Finished: ${totalCompleted} completed` + (remaining.length > 0 ? `, ${remaining.length} remaining` : "") + (failedNums.size > 0 ? `, ${failedNums.size} failed` : "")
   );
   d.cleanup();
   return { allDone: remaining.length === 0 };
@@ -2008,8 +2448,8 @@ Finished: ${totalCompleted} completed` + (remaining.length > 0 ? `, ${remaining.
 __name(runWavesIsolated, "runWavesIsolated");
 
 // src/resolve.ts
-import { existsSync as existsSync3, readdirSync as readdirSync3 } from "node:fs";
-import { dirname as dirname2, join as join4 } from "node:path";
+import { existsSync as existsSync4, readdirSync as readdirSync3 } from "node:fs";
+import { dirname as dirname2, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { select } from "@inquirer/prompts";
 function getScriptDir(metaUrl) {
@@ -2017,8 +2457,8 @@ function getScriptDir(metaUrl) {
 }
 __name(getScriptDir, "getScriptDir");
 function findFeatureDirs(cwd) {
-  const scratchDir = join4(cwd, ".scratch");
-  if (!existsSync3(scratchDir)) return [];
+  const scratchDir = join5(cwd, ".scratch");
+  if (!existsSync4(scratchDir)) return [];
   const entries = readdirSync3(
     scratchDir,
     { withFileTypes: true }
@@ -2026,17 +2466,17 @@ function findFeatureDirs(cwd) {
   const results = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const issuesDir = join4(
+    const issuesDir = join5(
       scratchDir,
       entry.name,
       "issues"
     );
-    const specFile = join4(
+    const specFile = join5(
       scratchDir,
       entry.name,
       "spec.md"
     );
-    if (existsSync3(issuesDir)) {
+    if (existsSync4(issuesDir)) {
       results.push({
         name: entry.name,
         dir: issuesDir,
@@ -2049,10 +2489,10 @@ function findFeatureDirs(cwd) {
 __name(findFeatureDirs, "findFeatureDirs");
 async function resolveIssuesDir(specName, cwd = process.cwd()) {
   if (specName) {
-    const featureDir = join4(cwd, ".scratch", specName);
+    const featureDir = join5(cwd, ".scratch", specName);
     return {
-      dir: join4(featureDir, "issues"),
-      spec: join4(featureDir, "spec.md")
+      dir: join5(featureDir, "issues"),
+      spec: join5(featureDir, "spec.md")
     };
   }
   const features = findFeatureDirs(cwd);
@@ -2115,8 +2555,8 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
       }
     }
     setup({
-      bundledSkillsDir: join5(scriptDir, "skills"),
-      docsTemplatesDir: join5(
+      bundledSkillsDir: join6(scriptDir, "skills"),
+      docsTemplatesDir: join6(
         scriptDir,
         "docs-templates"
       ),
@@ -2146,11 +2586,29 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
   }).option("timeout", {
     type: "number",
     describe: "Kill agent after N seconds",
-    default: 900
+    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" when package.json has a test script. Pass "" to disable.'
   }).option("X", {
     type: "boolean",
     describe: "Stop on merge conflict instead of re-spawning",
     default: false
+  }).option("max-turns", {
+    type: "number",
+    describe: "Max agentic turns per ticket (forwarded to the agent CLI)"
+  }).option("thinking", {
+    type: "string",
+    choices: THINKING_LEVELS,
+    describe: "Starting thinking level for the pi provider. Omitted = pi's default. Retries step up from here."
+  }).option("retries", {
+    type: "number",
+    default: DEFAULT_RETRIES,
+    describe: "Extra attempts per ticket after a failed run, each with a higher thinking level (pi). 0 disables retries."
+  }).option("retry-delay", {
+    type: "number",
+    default: DEFAULT_RETRY_DELAY,
+    describe: "Seconds to wait before the first retry; doubles each further retry. 0 disables the wait."
   }),
   async (argv) => {
     await runExecute({
@@ -2159,7 +2617,12 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
       spec: argv.spec,
       dryRun: argv.dryRun,
       timeout: argv.timeout,
-      stopOnConflict: argv.X
+      testCmd: argv.testCmd,
+      stopOnConflict: argv.X,
+      maxTurns: argv.maxTurns,
+      thinking: argv.thinking,
+      retries: argv.retries,
+      retryDelay: argv.retryDelay
     });
   }
 ).strict().demandCommand(1, "Specify a command or provider").help().parse();
@@ -2187,15 +2650,18 @@ async function runExecute(argv) {
   const { dir, spec } = await resolveIssuesDir(
     argv.spec
   );
-  if (!existsSync4(dir)) {
+  if (!existsSync5(dir)) {
     console.error(`Directory not found: ${dir}`);
     process.exit(2);
   }
-  if (!existsSync4(spec)) {
+  if (!existsSync5(spec)) {
     console.error(`Spec file not found: ${spec}`);
     process.exit(2);
   }
-  const specBody = readFileSync4(spec, "utf8");
+  const specBody = stripSpecSection(
+    readFileSync5(spec, "utf8"),
+    "User Stories"
+  );
   const tickets = scanTickets(dir);
   if (tickets.length === 0) {
     console.log("No ticket files found. Exiting.");
@@ -2216,11 +2682,14 @@ async function runExecute(argv) {
       (b) => knownNums.has(b)
     );
   }
-  const logsDir = join5(dirname3(dir), "logs");
-  const timeout = argv.timeout ?? 300;
+  const logsDir = join6(dirname3(dir), "logs");
+  const timeout = argv.timeout ?? 900;
+  const testCmd = argv.testCmd === void 0 ? detectTestCmd(
+    isGitRepo() ? getRepoRoot() : process.cwd()
+  ) : argv.testCmd || null;
   const featureName = extractFeatureName(spec);
   const conflictStrategy = argv.stopOnConflict ? "stop" : "respawn";
-  const progressPath = join5(
+  const progressPath = join6(
     dirname3(dir),
     "progress.md"
   );
@@ -2232,7 +2701,11 @@ async function runExecute(argv) {
         specBody,
         repoName,
         conflictStrategy,
-        progressPath
+        progressPath,
+        testCmd,
+        thinking: argv.thinking,
+        retries: argv.retries,
+        retryDelay: argv.retryDelay
       });
     } else {
       dryRun(tickets, specBody);
@@ -2240,6 +2713,14 @@ async function runExecute(argv) {
     return;
   }
   const display = createDisplay();
+  function onSignal(exitCode) {
+    killRunningAgents();
+    display.cleanup();
+    process.exit(exitCode);
+  }
+  __name(onSignal, "onSignal");
+  process.on("SIGINT", () => onSignal(130));
+  process.on("SIGTERM", () => onSignal(143));
   let result;
   if (isGitRepo()) {
     result = await runWavesIsolated({
@@ -2251,7 +2732,12 @@ async function runExecute(argv) {
       logsDir,
       featureName,
       conflictStrategy,
-      display
+      display,
+      testCmd,
+      maxTurns: argv.maxTurns,
+      thinking: argv.thinking,
+      retries: argv.retries,
+      retryDelay: argv.retryDelay
     });
   } else {
     result = await runWaves(
@@ -2261,7 +2747,11 @@ async function runExecute(argv) {
       argv.model ?? null,
       timeout,
       logsDir,
-      display
+      display,
+      argv.maxTurns,
+      argv.thinking,
+      argv.retries,
+      argv.retryDelay
     );
   }
   if (!result.allDone) {