@maycombhq/atticus 2.0.0-beta.18 → 2.0.0-beta.21

package/dist/{chunk-GTW54D3D.js → chunk-Y6K3CJBU.js}

@@ -4,57 +4,60 @@ var require = __atticusCreateRequire(import.meta.url);
 var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
 var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
 import {
+  slug,
+  writeGateRound
+} from "./chunk-EZIN5E5B.js";
+import {
+  catchUpChangeBranch,
   changeWorktree,
   handDown,
   loadTask,
   openTaskWorktree,
-  readChangeTasks
-} from "./chunk-2ZICHO3V.js";
+  readChangeTasks,
+  setTaskDone
+} from "./chunk-YWAKDNMH.js";
 import {
   buildEngineFor
-} from "./chunk-BAXM3JFQ.js";
-import {
-  slug,
-  writeGateRound
-} from "./chunk-YC2K3FJG.js";
+} from "./chunk-3AQ2R5NL.js";
 import {
   conform,
   readConformDeltas,
   readTaskSteps,
   renderTaskContext,
-  taskContext
-} from "./chunk-XO5RQKNM.js";
+  taskContext,
+  withBuildLine
+} from "./chunk-BEPCKDCP.js";
 import {
   readChangeFiles,
   readRound,
+  readStoryIndex,
   roundsOf,
   writeQuarantineItems
-} from "./chunk-VEJYZEPC.js";
+} from "./chunk-K332XW7K.js";
 import {
   changeFolder,
   changeStore
-} from "./chunk-IOW6BF3U.js";
+} from "./chunk-HSZMPH5T.js";
 import {
-  AdapterError,
   createAdapters,
   fileStepStore,
   requireApproval
-} from "./chunk-V3UEPUHT.js";
+} from "./chunk-4KNOJC6J.js";
 import {
   scanEstate
-} from "./chunk-EZBAS5BL.js";
+} from "./chunk-4SLBCEPD.js";
 import {
   baseClonePath,
   createGit,
   toRepoRelative
-} from "./chunk-ZQC7MNQB.js";
+} from "./chunk-XOL3GFW2.js";
 import {
   HandoffRuntime,
   buildContextPack,
   createRuntime,
   quarantineItems,
   toRunSummary
-} from "./chunk-QNMLLYTN.js";
+} from "./chunk-QHJJMZLX.js";
 import {
   AgentDefinition,
   ChecklistPack,
@@ -74,10 +77,12 @@ import {
   stateDirOf,
   taskBranch,
   toCanonicalYaml
-} from "./chunk-YK6CSODO.js";
+} from "./chunk-PAINMSID.js";
 import {
+  LockHeldError,
+  acquireLock,
   writeFileAtomic
-} from "./chunk-MMB2OHUY.js";
+} from "./chunk-ODMBPDDV.js";
 import {
   __toESM
 } from "./chunk-TV45EUGM.js";
@@ -156,27 +161,162 @@ async function applyChanges(worktree, changes) {
 
 // packages/taskrun/dist/commands.js
 import { spawn } from "node:child_process";
+var KEEP_OUTPUT = 4 * 1024 * 1024;
+function tail(max = KEEP_OUTPUT) {
+  let text = "";
+  let dropped = 0;
+  return {
+    add(d) {
+      text += d;
+      if (text.length > max) {
+        dropped += text.length - max;
+        text = text.slice(text.length - max);
+      }
+    },
+    get text() {
+      return dropped ? `[${dropped} characters of output left out]
+${text}` : text;
+    }
+  };
+}
+function stopTree(child, signal = "SIGTERM") {
+  if (child.pid === void 0)
+    return;
+  if (process.platform === "win32") {
+    const k = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true });
+    k.on("error", () => child.kill());
+    return;
+  }
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    child.kill(signal);
+  }
+}
+var live = /* @__PURE__ */ new Set();
+var SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+var stopping = false;
+var stopRequested = () => stopping;
+var stopper = new AbortController();
+var stopSignal = stopper.signal;
+function stopAllBuilds() {
+  stopping = true;
+  for (const c of live)
+    stopTree(c);
+  if (!stopper.signal.aborted)
+    stopper.abort();
+}
+var holds = 0;
+var pending;
+var SIGNAL_GRACE_MS = 1e4;
+var onSignal = (sig) => {
+  stopAllBuilds();
+  if (process.listenerCount(sig) > 1)
+    return;
+  if (!pending) {
+    pending = sig;
+    setTimeout(raise, SIGNAL_GRACE_MS);
+  }
+  settle();
+};
+function raise() {
+  const sig = pending;
+  if (!sig)
+    return;
+  unhook();
+  process.kill(process.pid, sig);
+}
+function settle() {
+  if (holds > 0 || live.size > 0)
+    return;
+  if (pending)
+    raise();
+  else
+    unhook();
+}
+var onExit = () => {
+  for (const c of live)
+    stopTree(c, "SIGKILL");
+};
+var hooked = false;
+function hook() {
+  if (hooked)
+    return;
+  hooked = true;
+  for (const s of SIGNALS)
+    process.prependListener(s, onSignal);
+  process.on("exit", onExit);
+}
+function unhook() {
+  if (!hooked)
+    return;
+  hooked = false;
+  for (const s of SIGNALS)
+    process.off(s, onSignal);
+  process.off("exit", onExit);
+}
+function holdSignals() {
+  holds++;
+  hook();
+  let released = false;
+  return () => {
+    if (released)
+      return;
+    released = true;
+    holds--;
+    settle();
+  };
+}
+var track = (c) => {
+  live.add(c);
+  hook();
+};
+var untrack = (c) => {
+  live.delete(c);
+  settle();
+};
+var STOP_GRACE_MS = 5e3;
 function shellCommandRunner() {
   return (command, cwd, o = {}) => new Promise((resolve) => {
+    if (stopping) {
+      resolve({ exitCode: null, stdout: "", stderr: "Atticus is stopping.", stopped: true });
+      return;
+    }
     const child = spawn(command, {
       cwd,
       shell: true,
       env: { ...process.env, ...o.env },
-      windowsHide: true
+      windowsHide: true,
+      // Its own process group off Windows, so a timeout stops the build, not only the shell.
+      detached: process.platform !== "win32"
     });
-    let stdout = "";
-    let stderr = "";
-    const timer = setTimeout(() => child.kill(), o.timeoutMs ?? 30 * 6e4);
-    child.stdout.setEncoding("utf8").on("data", (d) => stdout += d);
-    child.stderr.setEncoding("utf8").on("data", (d) => stderr += d);
-    child.on("error", (e) => {
+    track(child);
+    const out = tail();
+    const err = tail();
+    let done2 = false;
+    let kill;
+    let drain;
+    const finish2 = (r) => {
+      if (done2)
+        return;
+      done2 = true;
       clearTimeout(timer);
-      resolve({ exitCode: null, stdout, stderr: stderr + e.message });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      resolve({ exitCode: code, stdout, stderr });
+      clearTimeout(kill);
+      clearTimeout(drain);
+      untrack(child);
+      resolve(stopping ? { ...r, stopped: true } : r);
+    };
+    const timer = setTimeout(() => {
+      stopTree(child);
+      kill = setTimeout(() => stopTree(child, "SIGKILL"), STOP_GRACE_MS);
+    }, o.timeoutMs ?? 30 * 6e4);
+    child.stdout.setEncoding("utf8").on("data", (d) => out.add(d));
+    child.stderr.setEncoding("utf8").on("data", (d) => err.add(d));
+    child.on("error", (e) => finish2({ exitCode: null, stdout: out.text, stderr: err.text + e.message }));
+    child.on("exit", (code) => {
+      drain = setTimeout(() => finish2({ exitCode: code, stdout: out.text, stderr: err.text }), 2e3);
     });
+    child.on("close", (code) => finish2({ exitCode: code, stdout: out.text, stderr: err.text }));
   });
 }
 
@@ -189,13 +329,16 @@ var TaskRunState = external_exports.enum([
   "planned",
   /** Hand-off mode: the person's assistant is doing the step. */
   "waiting",
-  /** Draft finished with a passing build, committed on the task branch. */
+  /**
+   * Draft finished with a passing build, committed on the task branch. Also a PR that wasn't
+   * raised (the push or the Git host failed): its note says why, and it can be raised again.
+   */
   "built",
   /** Draft finished but the repo has no build command, so nothing was checked. */
   "unverified",
   /** The PR from the task branch to the change branch is open. */
   "pr-open",
-  /** The build still fails after the allowed fix rounds, or a PR can't be opened: a person takes over. */
+  /** The build still fails after the allowed fix rounds, or a step after it can't be done: a person takes over. */
   "needs-person",
   /** The AI run itself failed. */
   "failed"
@@ -234,6 +377,16 @@ var TaskRunRecord = external_exports.strictObject({
   changed: external_exports.array(external_exports.string()).default([]),
   commit: external_exports.string().optional(),
   pr: external_exports.strictObject({ number: external_exports.number().int().positive(), url: external_exports.string() }).optional(),
+  /**
+   * Seventh UX walk: when Atticus ticked the task in tasks.md because its PR merged. It ticks a
+   * task once, so a person who unticks it keeps it unticked.
+   */
+  ticked: external_exports.string().optional(),
+  /**
+   * Eighth UX walk: who last ticked (done) or unticked the task by hand on the Task board, and
+   * when, so a task Atticus ticked and a person ticked again says who did.
+   */
+  marked: external_exports.strictObject({ done: external_exports.boolean(), by: external_exports.string().min(1), at: external_exports.string() }).optional(),
   startedAt: external_exports.string(),
   finishedAt: external_exports.string().optional(),
   notes: external_exports.array(external_exports.string()).default([])
@@ -266,6 +419,23 @@ async function saveRunSummary(root, change, task, s) {
   await writeFileAtomic(join2(changeFolder(root, change), rel), toCanonicalYaml(RunSummary.parse(s), ["schemaVersion", "runId"]));
   return rel;
 }
+async function taskRunOfRun(root, change, runId) {
+  for (const t of (await readdir(join2(changeFolder(root, change), "tasks"), { withFileTypes: true }).catch(() => [])).filter((d) => d.isDirectory())) {
+    const r = await readTaskRun(root, change, t.name).catch(() => void 0);
+    if (r && (r.waiting === runId || r.runs.includes(runId)))
+      return r;
+  }
+  return void 0;
+}
+async function findTaskRunOfRun(root, runId) {
+  const changes = changesDirOf(root);
+  for (const c of (await readdir(changes, { withFileTypes: true }).catch(() => [])).filter((d) => d.isDirectory() && d.name !== "archive")) {
+    const r = await taskRunOfRun(root, c.name, runId).catch(() => void 0);
+    if (r)
+      return r;
+  }
+  return void 0;
+}
 async function findWaitingTaskRun(root, runId) {
   const changes = changesDirOf(root);
   for (const c of (await readdir(changes, { withFileTypes: true }).catch(() => [])).filter((d) => d.isDirectory())) {
@@ -374,19 +544,21 @@ ${s.body.trim()}`,
       trusted: true
     }))
   ];
-  const artifact = (rel, priority) => {
+  const artifact = (rel, priority, text = (raw) => raw) => {
     const d = t.files.docs.get(rel);
     if (d)
       sources.push({
         id: rel,
         kind: "artifact",
         origin: `${changesRelOf(t.root)}/${t.change.id}/${rel}`,
-        text: d.raw,
+        text: text(d.raw),
         classification: "internal",
         priority
       });
   };
-  const context = await taskContext(t.root, t.change.id, t.task.id).catch(() => void 0);
+  const context = await taskContext(t.root, t.change.id, t.task.id, {
+    at: { worktree: p.worktreeRel, branch: taskBranch(t.change.id, t.task.id) }
+  }).catch(() => void 0);
   if (context)
     sources.push({
       id: "task-context",
@@ -397,7 +569,7 @@ ${s.body.trim()}`,
       priority: 35
     });
   for (const s of t.task.stories)
-    artifact(`stories/${s}.md`, 30);
+    artifact(`stories/${s}.md`, 30, (raw) => withBuildLine(raw, t.repo.id, t.repo.build));
   for (const a of ["design.md", "interfaces.md", "mappings.md", "data.md"])
     artifact(a, 20);
   const needs = await readIf(join3(t.root, ...changesRelOf(t.root).split("/"), t.change.id, "needs.md"));
@@ -501,6 +673,7 @@ function gitScanAt(root, git) {
       return {
         records: s.records,
         files,
+        basis: s.basis?.[repo] ?? { from: "readers" },
         problems: s.problems.filter((p) => !p.repo || p.repo === repo).map((p) => `${p.repo ? `${p.repo}: ` : ""}${p.source}: ${p.message}`)
       };
     } finally {
@@ -654,7 +827,8 @@ async function conformChange(root, change, o = {}) {
       tasks,
       before: before.records,
       after: after.records,
-      files: after.files
+      files: after.files,
+      basis: after.basis
     });
     const count = (s) => r.items.filter((i) => i.status === s).length;
     const result = {
@@ -814,7 +988,7 @@ async function aiStep(c, buildLog) {
   if (c.runtime instanceof HandoffRuntime) {
     await writeFile2(join5(runsDirOf(c.root), request.change, prepared.runId, "prompt.md"), handoffPrompt(c, prepared), "utf8");
   }
-  const run = await c.runtime.run(prepared.runId);
+  const run = await c.runtime.run(prepared.runId, stopSignal);
   await summarise(c, run);
   return run;
 }
@@ -827,7 +1001,7 @@ function handoffPrompt(c, run) {
     "",
     run.request.pack.prompt.trimEnd(),
     "",
-    `When you are done, run: atticus handoff done ${run.runId}`,
+    c.record.level === "pr" ? `When you are done, stop and ask the person to run: atticus handoff done ${run.runId} --approve (it pushes the branch and opens a PR, so the person runs it, never you)` : `When you are done, run: atticus handoff done ${run.runId}`,
     ""
   ].join("\n");
 }
@@ -837,6 +1011,8 @@ async function build(c, runId, fixRun) {
     return void 0;
   const n = c.record.attempts.length + 1;
   const res = await c.commands(command, c.worktree);
+  if (res.stopped)
+    c.stopped = true;
   const logRel = `${runsRelOf(c.root)}/${c.t.change.id}/${runId}/build-${n}.log`;
   await mkdir3(join5(runsDirOf(c.root), c.t.change.id, runId), { recursive: true });
   await writeFile2(join5(c.root, logRel), `$ ${command}
@@ -856,14 +1032,24 @@ ${res.stderr}` : ""}
   c.record.attempts.push(a);
   return a;
 }
+async function changedFiles(c) {
+  const r = await c.git(["-c", "core.quotePath=false", "status", "--porcelain", "-z"], c.worktree);
+  const parts = r.stdout.split("\0").filter(Boolean);
+  const out = [];
+  for (let k = 0; k < parts.length; k++) {
+    const e = parts[k];
+    if (/^[RC]/.test(e))
+      k++;
+    if (e.slice(3))
+      out.push(e.slice(3));
+  }
+  return out;
+}
 async function applyAnswer(c, run) {
   if (c.runtime.kind === "headless-claude-code") {
-    const changed = await c.git(["status", "--porcelain"], c.worktree);
-    for (const l of changed.stdout.split("\n").filter(Boolean)) {
-      const p = l.slice(3).trim();
+    for (const p of await changedFiles(c))
       if (!c.record.changed.includes(p))
         c.record.changed.push(p);
-    }
     await writeReport(c, run.output ?? "");
     return [];
   }
@@ -892,7 +1078,8 @@ async function buildAndFix(c, runId) {
     return;
   }
   let fixes = 0;
-  while (!a.passed && fixes < c.maxFix && c.runtime.kind !== "hand-off") {
+  const halted = () => c.stopped || stopRequested();
+  while (!a.passed && !halted() && fixes < c.maxFix && c.runtime.kind !== "hand-off") {
     fixes++;
     const log = await import("node:fs/promises").then((fs) => fs.readFile(join5(c.root, a.log), "utf8"));
     const fix = await aiStep(c, { command: a.command, text: log, attempt: fixes });
@@ -900,6 +1087,8 @@ async function buildAndFix(c, runId) {
       c.record.notes.push(`Fix round ${fixes} failed: ${fix.errors.join("; ") || fix.state}.`);
       break;
     }
+    if (halted())
+      break;
     const problems = await applyAnswer(c, fix);
     if (problems.length) {
       c.record.notes.push(`Fix round ${fixes} was not applied: ${problems.join("; ")}.`);
@@ -907,6 +1096,11 @@ async function buildAndFix(c, runId) {
     }
     a = await build(c, runId, fix.runId);
   }
+  if (halted()) {
+    c.record.state = "needs-person";
+    c.record.notes.push(`Atticus was stopped while the build ran, so nothing more was done; a person takes over in ${c.record.worktree}. See ${a.log}.`);
+    return;
+  }
   if (!a.passed) {
     c.record.state = "needs-person";
     c.record.notes.push(`The build still fails after ${fixes} fix round${fixes === 1 ? "" : "s"}; a person takes over in ${c.record.worktree}. See ${a.log}.`);
@@ -918,8 +1112,9 @@ async function commit(c, runId) {
   await c.git(["add", "-A", "--", "."], c.worktree);
   const staged = (await c.git(["diff", "--cached", "--name-only"], c.worktree)).stdout.trim();
   if (!staged) {
-    c.record.notes.push("Nothing to commit.");
-    return;
+    c.record.state = "needs-person";
+    c.record.notes.push(`The AI's answer changed nothing in ${c.record.branch}, so there is nothing to commit: run the task again, or do it by hand in ${c.record.worktree}.`);
+    return false;
   }
   await c.git([
     "commit",
@@ -933,6 +1128,7 @@ Atticus-Run: ${runId}
 Requested-By: ${c.record.by}`
   ], c.worktree);
   c.record.commit = (await c.git(["rev-parse", "HEAD"], c.worktree)).stdout.trim();
+  return true;
 }
 async function openPr(c) {
   if (c.record.state !== "built") {
@@ -948,20 +1144,25 @@ async function openPr(c) {
     return;
   }
   const base = changeBranch(c.t.change.id);
-  const info = await c.gitHost.getRepo(c.t.repo.id);
-  for (const b of [c.record.branch, base])
-    if (info.protectedBranches.includes(b))
-      throw new TaskRunError("refused", `${b} is protected in ${c.t.repo.id}; Run with AI never pushes to or opens a PR into a protected branch.`);
-  if (base === info.defaultBranch)
-    throw new TaskRunError("refused", `${base} is ${c.t.repo.id}'s default branch; task PRs go into the change branch.`);
-  await c.git([
-    "push",
-    "-q",
-    "origin",
-    `refs/heads/${base}:refs/heads/${base}`,
-    `refs/heads/${c.record.branch}:refs/heads/${c.record.branch}`
-  ], c.worktree);
+  if (!c.record.commit)
+    throw new TaskRunError("refused", `Task ${c.t.task.id} has no commit to raise: run the task again, or do it by hand in ${c.record.worktree}.`);
+  const head = (await c.git(["rev-parse", "--verify", "-q", `refs/heads/${c.record.branch}`], c.worktree).catch(() => ({ stdout: "" }))).stdout.trim();
+  if (!head)
+    throw new TaskRunError("refused", `Task ${c.t.task.id}'s branch ${c.record.branch} isn't in ${c.record.worktree} any more: run the task again.`);
+  if (head !== c.record.commit)
+    throw new TaskRunError("refused", `Task ${c.t.task.id}'s branch ${c.record.branch} has commits that weren't built (it is at ${head.slice(0, 12)}; the build passed at ${c.record.commit.slice(0, 12)}): run the task again so its build checks them, or push ${c.record.branch} and open its PR into ${base} yourself.`);
   try {
+    const info = await c.gitHost.getRepo(c.t.repo.id);
+    for (const b of [c.record.branch, base])
+      if (info.protectedBranches.includes(b))
+        throw new TaskRunError("refused", `${b} is protected in ${c.t.repo.id}; Run with AI never pushes to or opens a PR into a protected branch.`);
+    if (base === info.defaultBranch)
+      throw new TaskRunError("refused", `${base} is ${c.t.repo.id}'s default branch; task PRs go into the change branch.`);
+    const onHost = (await c.git(["ls-remote", "--heads", "origin", `refs/heads/${base}`], c.worktree)).stdout.trim();
+    const refs = [`refs/heads/${c.record.branch}:refs/heads/${c.record.branch}`];
+    if (!onHost)
+      refs.unshift(`refs/heads/${base}:refs/heads/${base}`);
+    await c.git(["push", "-q", ...refs.length > 1 ? ["--atomic"] : [], "origin", ...refs], c.worktree);
     const pr = await c.gitHost.createPullRequest({
       repo: c.t.repo.id,
       head: c.record.branch,
@@ -979,15 +1180,18 @@ async function openPr(c) {
     c.record.pr = { number: pr.number, url: pr.url };
     c.record.state = "pr-open";
   } catch (e) {
-    if (e instanceof AdapterError) {
-      c.record.state = "needs-person";
-      c.record.notes.push(`The PR couldn't be opened: ${e.message}`);
-      return;
-    }
-    throw e;
+    if (e instanceof TaskRunError)
+      throw e;
+    c.record.notes.push(`${PR_NOT_RAISED} ${(e instanceof Error ? e.message : String(e)).replace(/\.?$/, ".")} The build still passes: fix that and raise the task's PR again (Raise the task's PR on the Task board), or push ${c.record.branch} and open its PR into ${base} yourself.`);
   }
 }
+var PR_NOT_RAISED = "The PR wasn't raised:";
 async function finish(c, run) {
+  if (stopRequested()) {
+    c.record.state = "needs-person";
+    c.record.notes.push(c.runtime.kind === "headless-claude-code" ? `Atticus was stopped while Claude Code worked, so nothing more was done; the worktree ${c.record.worktree} may hold some of its edits.` : `Atticus was stopped before the answer was applied, so nothing was written; run the task again.`);
+    return done(c);
+  }
   if (c.record.level === "plan") {
     if (c.runtime.kind !== "hand-off")
       await writeFileAtomic(join5(changeFolder(c.root, c.t.change.id), run.request.outputPath), `${(run.output ?? "").trim()}
@@ -1003,39 +1207,233 @@ async function finish(c, run) {
       }
     }
     await buildAndFix(c, run.runId);
-    if (c.record.state === "built" || c.record.state === "unverified")
-      await commit(c, run.runId);
+    await afterBuild(c, run.runId, c.record.state === "built" || c.record.state === "unverified");
+  }
+  return done(c);
+}
+async function afterBuild(c, runId, commitIt, first) {
+  try {
+    await first?.();
+    if (commitIt && !await commit(c, runId))
+      return;
     await conformAfterBuild(c);
     if (c.record.level === "pr")
       await openPr(c);
+  } catch (e) {
+    c.record.state = "needs-person";
+    c.record.notes.push(`${e instanceof Error ? e.message : String(e)} \u2014 the work is in ${c.record.worktree} (branch ${c.record.branch}): finish it there by hand, or fix that and run the task again.`);
   }
-  return done(c);
 }
 async function done(c) {
   delete c.record.waiting;
   c.record.finishedAt = stamp2(c.now());
   return saveTaskRun(c.root, c.record);
 }
+function levelOf(t, asked) {
+  const rt = t.ctx.orgPack.runtime;
+  const cap = rt.autonomy.capPerRepo[t.repo.id];
+  const capped = cap ? AUTONOMY[cap] : void 0;
+  if (asked === void 0) {
+    const level = AUTONOMY[rt.autonomy.default];
+    return capped && LEVEL_RANK[level] > LEVEL_RANK[capped] ? capped : level;
+  }
+  if (capped && LEVEL_RANK[asked] > LEVEL_RANK[capped])
+    throw new TaskRunError("refused", `${t.repo.id} allows Run with AI up to ${cap} (runtime.yaml autonomy.capPerRepo); ask for a lower level.`);
+  return asked;
+}
+async function ownTaskPr(host, r, held) {
+  const pr = await host.getPullRequest(r.repo, held.number);
+  if (pr.head === r.branch)
+    return pr;
+  const mine = await host.listPullRequests(r.repo, { head: r.branch });
+  const own = mine.find((x) => x.url === held.url) ?? mine.at(-1);
+  if (own)
+    return own;
+  throw new TaskRunError("refused", `PR #${held.number} on the Git host is from ${pr.head}, not ${r.branch}, and no PR from ${r.branch} was found`);
+}
+async function refuseIfHeld(root, t, host) {
+  const before = await readTaskRun(root, t.change.id, t.task.id);
+  if (before?.state === "pr-open") {
+    let state;
+    let why = "";
+    try {
+      const h = host();
+      if (!h)
+        why = "no Git host is connected (runtime.yaml adapters.gitHost)";
+      else if (before.pr)
+        state = (await ownTaskPr(h, before, before.pr)).state;
+    } catch (e) {
+      why = e instanceof Error ? e.message : String(e);
+    }
+    if (before.pr && (state === "merged" || state === "closed"))
+      return [`Its earlier PR ${before.pr.url} is ${state}.`];
+    throw new TaskRunError("refused", `Task ${t.task.id}'s PR is open (${before.pr?.url ?? "see its run"}): running the task again would start over beside it. Merge or close the PR first, then run the task again.${why ? ` (Atticus couldn't ask the Git host whether it still is: ${why}.)` : ""}`);
+  }
+  const open = ["prepared", "waiting", "produced", "failed"];
+  if (before?.state === "waiting" && before.waiting && open.includes(await handoffRunState(root, t.change.id, before.waiting) ?? ""))
+    throw new TaskRunError("refused", `Task ${t.task.id} already waits on your assistant (run ${before.waiting}, in ${before.worktree}): finish it with Done on its run page (Model runs) or atticus handoff done ${before.waiting}, or Cancel it there and run the task again.`);
+  return [];
+}
+async function taskPrState(root, changeId, taskId, o = {}) {
+  const r = await readTaskRun(root, changeId, taskId).catch(() => void 0);
+  if (r?.state !== "pr-open" || !r.pr)
+    return void 0;
+  const pr = r.pr;
+  const ask = async () => {
+    const host = o.gitHost ?? gitHostOf(root, await loadTask(root, changeId, taskId));
+    if (!host)
+      return void 0;
+    const s = (await ownTaskPr(host, r, pr)).state;
+    return s === "merged" || s === "closed" ? s : "open";
+  };
+  let timer;
+  const late = new Promise((res) => {
+    timer = setTimeout(() => res(void 0), o.timeoutMs ?? 3e3);
+  });
+  try {
+    return await Promise.race([ask(), late]);
+  } catch {
+    return void 0;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function settleTaskPr(root, changeId, taskId, o = {}) {
+  const r = await readTaskRun(root, changeId, taskId).catch(() => void 0);
+  if (r?.state !== "pr-open" || !r.pr)
+    return {};
+  const recorded = r.pr;
+  const ask = async () => {
+    const host = o.gitHost ?? gitHostOf(root, await loadTask(root, changeId, taskId));
+    if (!host)
+      return void 0;
+    return ownTaskPr(host, r, recorded);
+  };
+  let timer;
+  const late = new Promise((res) => {
+    timer = setTimeout(() => res(void 0), o.timeoutMs ?? 3e3);
+  });
+  const pr = await Promise.race([ask(), late]).catch(() => void 0).finally(() => clearTimeout(timer));
+  if (!pr)
+    return {};
+  const state = pr.state === "merged" || pr.state === "closed" ? pr.state : "open";
+  const cur = await readTaskRun(root, changeId, taskId).catch(() => void 0);
+  if (cur?.state !== "pr-open" || cur.pr?.url !== recorded.url)
+    return { state };
+  let changed = false;
+  if (pr.number !== recorded.number || pr.url !== recorded.url) {
+    cur.pr = { number: pr.number, url: pr.url };
+    changed = true;
+  }
+  let ticked = false;
+  if (state === "merged" && !cur.ticked) {
+    ticked = await setTaskDone(root, changeId, taskId, true);
+    cur.ticked = stamp2((o.now ?? (() => /* @__PURE__ */ new Date()))());
+    if (ticked)
+      cur.notes.push(`Ticked ${taskId} in tasks.md: PR #${pr.number} merged on the Git host. The tick rides the change's build hand-off.`);
+    changed = true;
+  }
+  if (changed)
+    await saveTaskRun(root, cur);
+  return { state, ...ticked ? { ticked: true } : {} };
+}
+function gitHostConnected(root, t, given) {
+  try {
+    return !!(given ?? gitHostOf(root, t));
+  } catch {
+    return false;
+  }
+}
+async function previewTaskRun(root, changeId, taskId, o = {}) {
+  const t = await loadTask(root, changeId, taskId);
+  const level = levelOf(t, o.level);
+  await refuseIfHeld(root, t, () => o.gitHost ?? gitHostOf(root, t));
+  return {
+    change: t.change.id,
+    task: t.task.id,
+    repo: t.repo.id,
+    level,
+    branch: taskBranch(t.change.id, t.task.id),
+    gitHost: level === "pr" && !o.skipGitHost ? gitHostConnected(root, t, o.gitHost) : false
+  };
+}
+async function cancelTaskRunWait(root, runId, o) {
+  const r = await findWaitingTaskRun(root, runId);
+  if (!r) {
+    await o.cancelRun?.();
+    return void 0;
+  }
+  const lock = await holdTask(root, r.change, r.task);
+  try {
+    const cur = await findWaitingTaskRun(root, runId);
+    await o.cancelRun?.();
+    if (!cur)
+      return void 0;
+    delete cur.waiting;
+    cur.state = "failed";
+    cur.notes.push(`Run ${runId} was cancelled by ${o.by}, so nothing more was done; run the task again.`);
+    cur.finishedAt = stamp2((o.now ?? (() => /* @__PURE__ */ new Date()))());
+    return await saveTaskRun(root, cur);
+  } finally {
+    await lock.release();
+  }
+}
+async function handoffRunState(root, change, runId) {
+  const text = await import("node:fs/promises").then((fs) => fs.readFile(join5(runsDirOf(root), change, runId, "run.json"), "utf8").catch(() => void 0));
+  if (!text)
+    return void 0;
+  try {
+    return JSON.parse(text).state;
+  } catch {
+    return void 0;
+  }
+}
+async function holdTask(root, change, task) {
+  try {
+    return await acquireLock(root, `task-run-${change}-${task}`, `run of task ${task} of ${change}`, void 0, { maxAgeMs: 12 * 60 * 6e4 });
+  } catch (e) {
+    if (e instanceof LockHeldError)
+      throw new TaskRunError("refused", e.message);
+    throw e;
+  }
+}
 async function runTask(root, changeId, taskId, o) {
+  const lock = await holdTask(root, changeId, taskId);
+  const release = holdSignals();
+  try {
+    return await runTaskHeld(root, changeId, taskId, o);
+  } finally {
+    await lock.release();
+    release();
+  }
+}
+async function runTaskHeld(root, changeId, taskId, o) {
   const now = o.now ?? (() => /* @__PURE__ */ new Date());
   const git = o.git ?? createGit();
   let t = await loadTask(root, changeId, taskId);
   const rt = t.ctx.orgPack.runtime;
-  const level = o.level ?? AUTONOMY[rt.autonomy.default];
-  const cap = rt.autonomy.capPerRepo[t.repo.id];
-  if (cap && LEVEL_RANK[level] > LEVEL_RANK[AUTONOMY[cap]])
-    throw new TaskRunError("refused", `${t.repo.id} allows Run with AI up to ${cap} (runtime.yaml autonomy.capPerRepo); ask for a lower level.`);
+  const level = levelOf(t, o.level);
+  const earlier = await refuseIfHeld(root, t, () => o.gitHost ?? gitHostOf(root, t));
   if (level === "pr") {
     try {
       requireApproval("git-host", o.approval);
     } catch {
-      throw new TaskRunError("refused", "The pr level pushes the task branch and opens a PR, which needs your approval: run it again with --approve.");
+      throw new TaskRunError("refused", "The pr level pushes the task branch and opens a PR, which needs the person's yes: ask them to run it with --approve (an assistant never approves a push).");
     }
   }
   const engine = buildEngineFor(t.ctx.orgPack, t.repo.id);
   const changeDir = await changeWorktree(root, t.change.id, t.repo.id);
   const handed = engine === "speckit" ? `specs/${t.task.id}/plan.md` : `.atticus/tasks/${t.task.id}.md`;
-  const notes = [];
+  const notes = [...earlier];
+  try {
+    const caught = await catchUpChangeBranch(root, t.change.id, t.task.id, t.repo.id, changeDir, git);
+    if (caught)
+      notes.push(caught);
+  } catch (e) {
+    if (e instanceof Error && e.name === "SpecKitError")
+      throw new TaskRunError("refused", e.message);
+    throw e;
+  }
   if (!existsSync2(join5(changeDir, handed))) {
     const h = await handDown(root, t.change.id, t.task.id, { git });
     notes.push(`Handed the task down first (${h.feature} in ${h.repo}${h.commit ? `, commit ${h.commit.slice(0, 12)}` : ""}).`);
@@ -1097,16 +1495,36 @@ async function runTask(root, changeId, taskId, o) {
     record.waiting = run.runId;
     return saveTaskRun(root, record);
   }
-  if (run.state !== "validated") {
+  if (run.state !== "validated" && !stopRequested()) {
     record.notes.push(`The AI run ended ${run.state}: ${run.errors.join("; ") || "no reason given"}.`);
     return done(c);
   }
   return finish(c, run);
 }
 async function completeTaskHandoff(root, runId, o = {}) {
-  const record = await findWaitingTaskRun(root, runId);
-  if (!record)
+  const waiting = await findWaitingTaskRun(root, runId);
+  if (!waiting)
     throw new TaskRunError("not-found", `No task run is waiting on ${runId}.`);
+  if (waiting.level === "pr" && !o.approval)
+    throw new TaskRunError("refused", `Task ${waiting.task} runs at the pr level, which pushes ${waiting.branch} and opens a PR: ask the person to run atticus handoff done ${runId} --approve (an assistant never approves a push).`);
+  const lock = await holdTask(root, waiting.change, waiting.task);
+  const release = holdSignals();
+  try {
+    const state = await handoffRunState(root, waiting.change, runId);
+    if (state === void 0)
+      throw new TaskRunError("refused", `Run ${runId} isn't on this machine (its files are kept where it was started): run the task again here (atticus task run ${waiting.change} ${waiting.task}).`);
+    if (state === "cancelled")
+      throw new TaskRunError("refused", `Run ${runId} was cancelled; run the task again (atticus task run ${waiting.change} ${waiting.task}).`);
+    const record = await findWaitingTaskRun(root, runId);
+    if (!record)
+      throw new TaskRunError("not-found", `No task run is waiting on ${runId}.`);
+    return await completeHeld(root, runId, record, o);
+  } finally {
+    await lock.release();
+    release();
+  }
+}
+async function completeHeld(root, runId, record, o) {
   const now = o.now ?? (() => /* @__PURE__ */ new Date());
   const git = o.git ?? createGit();
   const t = await loadTask(root, record.change, record.task);
@@ -1138,7 +1556,11 @@ async function completeTaskHandoff(root, runId, o = {}) {
         return [`${file.slice(root.length + 1)} is empty`];
       if (record.level === "plan")
         return [];
+      if (stopRequested())
+        return ["Atticus was stopped"];
       attempt = await build(c, runId);
+      if (c.stopped)
+        return ["Atticus was stopped while the build ran"];
       if (!attempt)
         return [];
       return attempt.passed ? [] : [`${attempt.command} failed; see ${attempt.log}`];
@@ -1154,19 +1576,32 @@ async function completeTaskHandoff(root, runId, o = {}) {
       record.state = attempt ? "built" : "unverified";
       if (!attempt)
         record.notes.push(`${t.repo.id} has no build command in repos.manifest.yaml, so the change wasn't built or tested.`);
-      const changed = await git(["status", "--porcelain"], c.worktree);
-      for (const l of changed.stdout.split("\n").filter(Boolean)) {
-        const p = l.slice(3).trim();
-        if (!record.changed.includes(p))
-          record.changed.push(p);
-      }
-      await commit(c, runId);
-      await conformAfterBuild(c);
-      if (record.level === "pr")
-        await openPr(c);
+      await afterBuild(c, runId, true, async () => {
+        for (const p of await changedFiles(c))
+          if (!record.changed.includes(p))
+            record.changed.push(p);
+      });
     }
     return done(c);
   }
+  if (c.stopped || stopRequested()) {
+    if (c.stopped && record.attempts.at(-1)?.passed === false)
+      record.attempts.pop();
+    record.state = "waiting";
+    record.waiting = runId;
+    await handoff.retry(runId);
+    await handoff.run(runId);
+    record.notes.push(`Atticus was stopped while it checked the work, so nothing more was done; run atticus handoff done ${runId} again.`);
+    return saveTaskRun(root, record);
+  }
+  if (!attempt) {
+    record.state = "waiting";
+    record.waiting = runId;
+    await handoff.retry(runId);
+    await handoff.run(runId);
+    record.notes.push(`${run.errors.join("; ") || "The answer isn't there yet"}: write it, then run atticus handoff done ${runId} again.`);
+    return saveTaskRun(root, record);
+  }
   const builds = record.attempts.length;
   if (attempt && !attempt.passed && builds <= c.maxFix) {
     await handoff.retry(runId);
@@ -1178,15 +1613,207 @@ async function completeTaskHandoff(root, runId, o = {}) {
   record.notes.push(attempt && !attempt.passed ? `The build still fails after ${builds} attempts; a person takes over in ${record.worktree}.` : `The hand-off failed: ${run.errors.join("; ")}.`);
   return done(c);
 }
+async function raiseTaskPr(root, changeId, taskId, o) {
+  try {
+    requireApproval("git-host", o.approval);
+  } catch {
+    throw new TaskRunError("refused", "A task's PR pushes its branch and opens a PR, which needs the person's yes (an assistant never approves a push).");
+  }
+  const lock = await holdTask(root, changeId, taskId);
+  try {
+    const record = await readTaskRun(root, changeId, taskId);
+    if (!record || record.level === "plan" || ["planned", "failed"].includes(record.state))
+      throw new TaskRunError("refused", `Task ${taskId} hasn't been drafted yet: run it with AI first; its PR comes after the draft.`);
+    if (record.state === "pr-open")
+      throw new TaskRunError("refused", `Task ${taskId}'s PR is already open: ${record.pr?.url ?? "see its run"}.`);
+    if (record.state === "waiting")
+      throw new TaskRunError("refused", `Task ${taskId} still waits on your assistant (run ${record.waiting ?? "on its page"}): finish it with Done first; its PR comes after the build.`);
+    const change = changeBranch(changeId);
+    if (record.state === "unverified")
+      throw new TaskRunError("refused", `Atticus opens a task's PR only after a passing build, and ${record.repo} has no build command in repos.manifest.yaml: add one and run task ${taskId} again, or push ${record.branch} and open its PR into ${change} yourself.`);
+    if (record.state !== "built" || !record.commit)
+      throw new TaskRunError("refused", `Task ${taskId} has no passing build to raise (it is ${record.state}): see its run's notes, then run it again.`);
+    const t = await loadTask(root, changeId, taskId);
+    const gitHost = o.gitHost ?? gitHostOf(root, t);
+    if (!gitHost)
+      throw new TaskRunError("refused", `No Git host is connected (runtime.yaml adapters.gitHost): push ${record.branch} and open its PR into ${change} yourself.`);
+    const now = o.now ?? (() => /* @__PURE__ */ new Date());
+    const c = {
+      root,
+      t,
+      record,
+      worktree: join5(root, record.worktree),
+      runtime: void 0,
+      commands: shellCommandRunner(),
+      git: o.git ?? createGit(),
+      gitHost,
+      approval: o.approval,
+      now,
+      maxFix: t.ctx.orgPack.runtime.autonomy.maxFixRounds
+    };
+    await openPr(c);
+    if (record.state === "pr-open")
+      record.notes.push(`PR raised by ${o.approval.by} after the draft (${o.approval.ref}).`);
+    return await done(c);
+  } finally {
+    await lock.release();
+  }
+}
 async function isTaskRun(root, runId) {
   return await findWaitingTaskRun(root, runId) !== void 0;
 }
 
+// packages/taskrun/dist/ready.js
+var PAST = {
+  waiting: "it is with your assistant: Done on its run carries on",
+  built: "it is drafted: its PR is the next step",
+  unverified: "it is drafted but not built: its repo has no build command",
+  "pr-open": "its PR is open on the Git host",
+  "needs-person": "it needs a person: carry on in its worktree, or Run with AI on it"
+};
+function sameRepoBefore(tasks, t) {
+  const mine = tasks.slice(0, tasks.indexOf(t)).filter((x) => x.repo === t.repo);
+  let cut = mine.length;
+  if (t.parallel)
+    while (cut > 0 && mine[cut - 1].parallel)
+      cut--;
+  return mine.slice(0, cut).filter((x) => !x.done).map((x) => x.id);
+}
+function planReadyTasks(o) {
+  const deps = new Map(o.stories.map((s) => [s.id, s.dependsOn]));
+  const rank = (repo) => {
+    const i = o.repoOrder?.indexOf(repo) ?? -1;
+    return i < 0 ? Number.MAX_SAFE_INTEGER : i;
+  };
+  const firstOfRepo = /* @__PURE__ */ new Map();
+  o.tasks.forEach((t, i) => {
+    if (!firstOfRepo.has(t.repo))
+      firstOfRepo.set(t.repo, i);
+  });
+  const order = o.tasks.map((t, i) => ({ t, i })).sort((a, b) => rank(a.t.repo) - rank(b.t.repo) || firstOfRepo.get(a.t.repo) - firstOfRepo.get(b.t.repo) || a.i - b.i).map((x) => x.t);
+  const out = [];
+  for (const t of order) {
+    if (t.done)
+      continue;
+    const before = new Set(t.stories.flatMap((s) => deps.get(s) ?? []));
+    const byStory = o.tasks.filter((x) => x.id !== t.id && !x.done && x.stories.some((s) => before.has(s))).map((x) => x.id);
+    const sameRepo = sameRepoBefore(o.tasks, t).filter((id) => !byStory.includes(id));
+    const waitsFor = o.tasks.map((x) => x.id).filter((id) => byStory.includes(id) || sameRepo.includes(id));
+    const past = t.state && !(t.state === "pr-open" && t.prSettled) ? PAST[t.state] : void 0;
+    const named = [
+      ...byStory,
+      ...sameRepo.length ? [`${sameRepo.join(", ")} (same repo)`] : []
+    ].join(", ");
+    const why = waitsFor.length ? `it waits for ${waitsFor.length === 1 ? "task" : "tasks"} ${named} to be done first` : past;
+    out.push({
+      id: t.id,
+      repo: t.repo,
+      ready: !why,
+      waitsFor,
+      ...sameRepo.length ? { sameRepo } : {},
+      ...why ? { why } : {}
+    });
+  }
+  return { tasks: out, ready: out.filter((t) => t.ready).map((t) => t.id) };
+}
+async function readyTasksOf(root, change, o = {}) {
+  const files = await readChangeFiles(changeFolder(root, change));
+  const tasks = [];
+  for (const t of readChangeTasks(files)) {
+    const r = await readTaskRun(root, change, t.id).catch(() => void 0);
+    const pr = o.prStates?.get(t.id);
+    tasks.push({
+      id: t.id,
+      repo: t.repo,
+      done: t.done,
+      stories: t.stories,
+      ...t.parallel ? { parallel: true } : {},
+      ...r ? { state: r.state } : {},
+      ...pr === "merged" || pr === "closed" ? { prSettled: pr } : {}
+    });
+  }
+  return planReadyTasks({
+    tasks,
+    stories: readStoryIndex(files),
+    ...o.repoOrder ? { repoOrder: o.repoOrder } : {}
+  });
+}
+function needsPerson(r) {
+  if (r.state === "failed")
+    return r.notes.at(-1) ?? `the run for task ${r.task} failed`;
+  if (r.state === "needs-person")
+    return r.notes.at(-1) ?? `task ${r.task} needs a person`;
+  if (r.state === "waiting")
+    return `task ${r.task} is with your assistant: Done on its run first`;
+  if (r.state === "unverified")
+    return `task ${r.task} is drafted but ${r.repo} has no build command, so nothing was built`;
+  if (r.level === "pr" && r.state === "built")
+    return r.notes.at(-1) ?? `task ${r.task}'s PR wasn't raised`;
+  return void 0;
+}
+async function runReadyTasks(root, change, o) {
+  const plan = await readyTasksOf(root, change, {
+    ...o.repoOrder ? { repoOrder: o.repoOrder } : {},
+    ...o.prStates ? { prStates: o.prStates } : {}
+  });
+  const planned = o.only ? plan.ready.filter((id) => o.only.includes(id)) : plan.ready;
+  const repoOf = new Map(plan.tasks.map((t) => [t.id, t.repo]));
+  if (o.dryRun) {
+    const previews = [];
+    for (const task of planned)
+      try {
+        previews.push(await previewTaskRun(root, change, task, {
+          ...o.level ? { level: o.level } : {},
+          ...o.gitHost ? { gitHost: o.gitHost } : {}
+        }));
+      } catch (e) {
+        previews.push({ task, refused: e.message });
+      }
+    return { planned, ran: [], previews };
+  }
+  const { only: _only, before, levelFor, progress, cancelled, repoOrder: _r, prStates: _p, dryRun: _d, ...run } = o;
+  const ran = [];
+  for (const [i, task] of planned.entries()) {
+    const repo = repoOf.get(task) ?? "";
+    if (cancelled?.())
+      return { planned, ran, stopped: { task, why: "the run was cancelled" } };
+    progress?.(i, planned.length, `Task ${task} on ${repo}`);
+    const refusedBefore = await before?.(task);
+    if (refusedBefore) {
+      ran.push({ task, repo, refused: refusedBefore });
+      return { planned, ran, stopped: { task, why: refusedBefore } };
+    }
+    let record;
+    try {
+      const level = run.level ?? await levelFor?.(task);
+      record = await runTask(root, change, task, { ...run, ...level ? { level } : {} });
+    } catch (e) {
+      const why2 = e.message;
+      ran.push({ task, repo, refused: why2 });
+      return { planned, ran, stopped: { task, why: why2 } };
+    }
+    ran.push({ task, repo, record });
+    const why = needsPerson(record);
+    if (why)
+      return { planned, ran, stopped: { task, why } };
+  }
+  progress?.(planned.length, planned.length, "Done");
+  return { planned, ran };
+}
+
 export {
   FILE_FORMAT,
   refusedPath,
   parseAnswer,
   applyChanges,
+  KEEP_OUTPUT,
+  tail,
+  stopRequested,
+  stopSignal,
+  stopAllBuilds,
+  SIGNAL_GRACE_MS,
+  holdSignals,
+  STOP_GRACE_MS,
   shellCommandRunner,
   TaskRunState,
   RunLevel,
@@ -1196,6 +1823,8 @@ export {
   saveTaskRun,
   readTaskRun,
   saveRunSummary,
+  taskRunOfRun,
+  findTaskRunOfRun,
   findWaitingTaskRun,
   TASK_RUNNER,
   taskRunnerAgent,
@@ -1211,7 +1840,16 @@ export {
   conformanceOf,
   conformAfterBuild,
   TaskRunError,
+  taskPrState,
+  settleTaskPr,
+  previewTaskRun,
+  cancelTaskRunWait,
   runTask,
   completeTaskHandoff,
-  isTaskRun
+  raiseTaskPr,
+  isTaskRun,
+  planReadyTasks,
+  readyTasksOf,
+  needsPerson,
+  runReadyTasks
 };