@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.3

package/src/collab/runner.js

@@ -0,0 +1,1014 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { copyFile, mkdir, open, readdir, realpath, rename, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { CODEFLOW_HOME } from "../config.js";
+import { assertWorktree, commitAll, git, repoRoot, resolveCommit, uncommittedCount } from "../git.js";
+import { logError } from "../log.js";
+import { redactText } from "../privacy.js";
+import { assertTransferTree } from "../remote-workers/bundles.js";
+import { taskDraftPattern } from "../patterns/task-draft.js";
+import { checkpointContext, checkpointRef, createCheckpointBundle, ensureCheckpointBranch, importCheckpointBundle } from "./checkpoints.js";
+import { ATTEMPT_ID, busyAttempt, CHECKPOINT_ID, CollabError, COMMIT_ID, latestCheckpoint, roleAtLeast, MAX, newAttemptId, newCheckpointId, ownerChangedMessage, TASK_ID } from "./model.js";
+const PUBLISH_INTERVAL_MS = 2e3, HEARTBEAT_INTERVAL_MS = 2e4, RETRY_INTERVAL_MS = 6e4;
+const MAX_FINISH_TRIES = 48;
+const RETRY_BASE_MS = 3e4, RETRY_MAX_MS = 30 * 6e4;
+const HUB_FINAL = /* @__PURE__ */ new Set([401, 403, 409]);
+const LOCAL_STATES = ["claiming", "claimed", "running", "finished", "failed", "paused", "stopped", "unknown"];
+const RECORD_LIMIT = 256 * 1024, MAX_DELIVERED = 200;
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const count = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const CONTROL = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, LINE_CONTROL = /[\x00-\x1f\x7f]/g;
+function clean(value, max, singleLine = false) {
+  let text = typeof value === "string" ? value.replace(singleLine ? LINE_CONTROL : CONTROL, " ") : "";
+  if (singleLine) text = text.trim();
+  const chars = [...text];
+  if (max >= 1024 && max % 1024 === 0) return Buffer.byteLength(text) <= max ? text : chars.slice(0, fitBytes(chars, max)).join("");
+  return chars.length <= max ? text : `${chars.slice(0, max - 1).join("")}\u2026`;
+}
+function fitBytes(chars, max, fromEnd = false) {
+  let low = 0, high = chars.length;
+  while (low < high) {
+    const mid = low + high + 1 >> 1, slice = fromEnd ? chars.slice(chars.length - mid) : chars.slice(0, mid);
+    if (Buffer.byteLength(slice.join("")) <= max) low = mid;
+    else high = mid - 1;
+  }
+  return low;
+}
+function tail(value, max) {
+  const text = clean(value, Number.MAX_SAFE_INTEGER);
+  if (Buffer.byteLength(text) <= max) return text;
+  const chars = [...text];
+  return `\u2026${chars.slice(chars.length - fitBytes(chars, max - 3, true)).join("")}`;
+}
+const message = (error) => error instanceof Error ? error.message : String(error);
+const asCollab = (error, status = 400) => error instanceof CollabError ? error : new CollabError(message(error), status);
+const retryDelay = (tries) => Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** Math.min(Math.max(0, tries - 1), 20));
+const PLACEHOLDER = "<local path>", PATH_TAIL = "[^\\s\"'`)\\]<>,;:]*";
+const ABSOLUTE_PATH = new RegExp(`(?<=^|[\\s"'\`(\\[<=,])(?:\\/|~\\/|[A-Za-z]:[\\\\/])${PATH_TAIL}`, "g"), PLACEHOLDER_TAIL = new RegExp(`${PLACEHOLDER}${PATH_TAIL}`, "g");
+function scrubLocalPaths(text, known = []) {
+  let out = text;
+  for (const path of [...new Set(known.filter((entry) => !!entry && isAbsolute(entry)))].sort((a, b) => b.length - a.length)) out = out.split(path).join(PLACEHOLDER);
+  return out.replace(ABSOLUTE_PATH, PLACEHOLDER).replace(PLACEHOLDER_TAIL, PLACEHOLDER);
+}
+const localPaths = (run) => [run.repo, ...(run.worktrees ?? []).map((worktree) => worktree.path), CODEFLOW_HOME, tmpdir(), homedir()].filter((path) => !!path);
+function sharedText(value, max, singleLine = false, paths = []) {
+  return clean(scrubLocalPaths(redactText(typeof value === "string" ? value : ""), paths), max, singleLine);
+}
+function progressFromRun(run, extra = {}, now = Date.now()) {
+  const share = (value, max, singleLine = false) => sharedText(value, max, singleLine, localPaths(run));
+  const steps = run.steps ?? [], progress = { updatedAt: now, runStatus: clean(run.status, MAX.runStatus, true) || "running" };
+  const running = [...steps].reverse().find((step) => step.status === "running");
+  const stage = running ? `${running.title}${running.role && running.role !== running.title ? ` (${running.role})` : ""}` : run.status === "running" ? steps.length ? "Between steps" : "Preparing the worktree" : "";
+  if (stage) progress.stage = share(stage, MAX.stage, true);
+  const summary = share(run.summary, MAX.summary);
+  if (summary.trim()) progress.summary = summary;
+  progress.steps = { done: steps.filter((step) => step.status !== "running").length, total: steps.length };
+  if (run.verdict === "passed" || run.verdict === "failing") progress.verdict = run.verdict;
+  if (run.lastCheck) progress.tests = { ok: run.lastCheck.ok, command: share(run.lastCheck.command, MAX.command, true) || "check", at: count(run.lastCheck.at) ? run.lastCheck.at : now };
+  const blockers = [];
+  if (run.awaiting) blockers.push(share(`Waiting for approval: ${run.awaiting.title}`, MAX.blockerItem, true));
+  const question = run.team?.awaitingRequestId ? run.team.messages.find((entry) => entry.requestId === run.team.awaitingRequestId || entry.id === run.team.awaitingRequestId) : void 0;
+  if (question) blockers.push(share(`Question from ${question.sender}: ${question.body}`, MAX.blockerItem, true));
+  else if (run.team?.awaitingRequestId) blockers.push("Waiting for an answer to the team's question");
+  if (blockers.length) progress.blockers = blockers.slice(0, MAX.blockers);
+  const branch = run.worktrees[0]?.branch;
+  if (branch && branch.length <= MAX.branch) progress.branch = share(branch, MAX.branch, true);
+  const head = extra.head?.toLowerCase();
+  if (head && COMMIT_ID.test(head)) progress.head = head;
+  if (extra.changedFiles?.length) progress.changedFiles = extra.changedFiles.slice(0, MAX.changedFiles).map((path) => share(path, MAX.path, true)).filter(Boolean);
+  return progress;
+}
+function mapRunStatus(run) {
+  const scrub = (text) => sharedText(text, MAX.reason, false, localPaths(run));
+  switch (run.status) {
+    case "done":
+      return { state: "finished" };
+    case "failed":
+      return { state: "failed", reason: scrub(run.error) || "The run failed" };
+    case "cancelled":
+      return { state: "paused", reason: "Stopped on this computer; resume it from here to continue" };
+    case "stopped":
+      return { state: "stopped", reason: scrub(run.stopReason) || "The run stopped at a limit; resume it to continue" };
+    case "interrupted":
+      return { state: "paused", reason: "interrupted by a restart; resume from this computer" };
+    default:
+      throw new CollabError("The run is still running; stop it before finishing the attempt", 409);
+  }
+}
+function taskPrompt(task, context = {}) {
+  const section = (title, body) => body.trim() ? `## ${title}
+
+${body.trim()}` : "";
+  const parts = [
+    `Team task ${task.id} in project ${context.projectName?.trim() || task.projectId}; your result will be published to the team board.`,
+    `# ${task.title.trim()}`,
+    section("Goal", task.goal),
+    section("Acceptance criteria", task.acceptance),
+    task.decisions.length ? section("Decisions already made", task.decisions.slice(0, MAX.decisions).map((decision) => `- ${decision.text}`).join("\n")) : "",
+    context.checkpoint ? checkpointContext(context.checkpoint) : ""
+  ];
+  return parts.filter(Boolean).join("\n\n").trimEnd() + "\n";
+}
+function instructionNote(instruction) {
+  return `Instruction from ${clean(instruction.by.displayName, MAX.displayName, true) || "a teammate"} via the team board:
+${clean(instruction.text, MAX.text)}`;
+}
+function validateRecord(raw) {
+  if (!object(raw) || typeof raw.attemptId !== "string" || !ATTEMPT_ID.test(raw.attemptId) || typeof raw.taskId !== "string" || !TASK_ID.test(raw.taskId) || typeof raw.repo !== "string" || !isAbsolute(raw.repo) || typeof raw.base !== "string" || !COMMIT_ID.test(raw.base)) return void 0;
+  if (typeof raw.state !== "string" || !LOCAL_STATES.includes(raw.state) || !count(raw.lastSeq) || !count(raw.lastAckedSeq) || !count(raw.updatedAt) || !Array.isArray(raw.deliveredInstructionIds) || raw.deliveredInstructionIds.some((id) => typeof id !== "string" || id.length > 40)) return void 0;
+  const record = { attemptId: raw.attemptId, taskId: raw.taskId, repo: raw.repo, base: raw.base, state: raw.state, lastSeq: raw.lastSeq, lastAckedSeq: raw.lastAckedSeq, deliveredInstructionIds: raw.deliveredInstructionIds.slice(0, MAX_DELIVERED), updatedAt: raw.updatedAt };
+  if (typeof raw.hubUrl === "string" && raw.hubUrl.length <= 2048) record.hubUrl = raw.hubUrl;
+  if (typeof raw.runId === "string" && /^[a-zA-Z0-9_-]{1,100}$/.test(raw.runId)) record.runId = raw.runId;
+  if (typeof raw.checkpointId === "string" && CHECKPOINT_ID.test(raw.checkpointId)) record.checkpointId = raw.checkpointId;
+  if (object(raw.pendingFinish) && typeof raw.pendingFinish.state === "string" && ["finished", "failed", "stopped", "paused", "unknown"].includes(raw.pendingFinish.state)) {
+    const p = raw.pendingFinish, pending = { state: p.state, error: typeof p.error === "string" ? p.error.slice(0, 1e3) : "", at: count(p.at) ? p.at : 0, tries: count(p.tries) ? p.tries : 0 };
+    if (typeof p.head === "string" && COMMIT_ID.test(p.head)) pending.head = p.head;
+    if (typeof p.summary === "string") pending.summary = clean(p.summary, MAX.summary);
+    if (typeof p.reason === "string") pending.reason = clean(p.reason, MAX.reason);
+    if (typeof p.bundleFile === "string" && isAbsolute(p.bundleFile)) pending.bundleFile = p.bundleFile;
+    record.pendingFinish = pending;
+  }
+  return record;
+}
+async function embeddedCheckpointId(repo, file) {
+  const heads = await git(["bundle", "list-heads", file], repo, { timeoutMs: 3e4 });
+  if (heads.code) throw new CollabError(`Git cannot read the downloaded checkpoint bundle (${heads.stderr.trim().slice(-300) || "unknown error"}); download it again`);
+  const lines = heads.stdout.trim().split("\n").filter(Boolean), match = lines.length === 1 ? /^[a-f0-9]{40,64} refs\/codeflow\/team\/([a-f0-9]{32})$/.exec(lines[0]) : null;
+  if (!match) throw new CollabError("The checkpoint bundle does not advertise exactly one team checkpoint reference; download it again or delete the checkpoint");
+  return match[1];
+}
+async function assertCheckpointable(repo, commit) {
+  try {
+    await assertTransferTree(repo, commit);
+  } catch (error) {
+    const text = message(error), why = text.includes("submodule") ? "it has a submodule" : text.includes("checkout filters") ? "it configures a checkout filter such as Git LFS in .gitattributes" : text.includes("20,000 files") ? "its tree exceeds 20,000 files, 256 MiB or 100 attribute files" : text.includes("256 KiB") ? "its checkout attributes exceed 256 KiB" : scrubLocalPaths(text, [repo]);
+    throw new CollabError(`This repository cannot carry team checkpoints (${why}); use a repository without submodules or checkout filters for board tasks`);
+  }
+}
+const emptyResult = () => ({ attached: 0, finished: 0, removed: 0, unknown: 0, retried: 0 });
+class CollabRunner {
+  constructor(options) {
+    this.options = options;
+    this.dir = options.dir ?? join(CODEFLOW_HOME, "team-link");
+    this.attemptsDir = join(this.dir, "attempts");
+    this.bundlesDir = join(this.dir, "bundles");
+    this.now = options.now ?? Date.now;
+    const interval = options.retryIntervalMs ?? RETRY_INTERVAL_MS;
+    if (interval > 0) {
+      this.retryTimer = setInterval(() => void this.retryPending().catch((error) => logError("The team attempt recovery pass failed; it runs again in a minute", error)), interval);
+      this.retryTimer.unref?.();
+    }
+  }
+  dir;
+  attemptsDir;
+  bundlesDir;
+  records = /* @__PURE__ */ new Map();
+  loading;
+  journalVersions = /* @__PURE__ */ new Map();
+  active = /* @__PURE__ */ new Map();
+  chains = /* @__PURE__ */ new Map();
+  closed = false;
+  /** Attempts between startAttempt's first journal write and its attach(): a recovery pass must not read them as claims that never got their answer. */
+  starting = /* @__PURE__ */ new Set();
+  retryTimer;
+  now;
+  /** The hub as currently linked; the provider lets the server swap a LocalHub for a RemoteHub when the link changes. */
+  get hub() {
+    return this.options.hub();
+  }
+  get manager() {
+    return this.options.manager;
+  }
+  /** Planning is a local run, with no task/attempt claim or publication to the shared hub. */
+  async draftTask(input) {
+    this.assertOpen();
+    const project = (await this.hub.board(input.projectId)).projects.find((entry) => entry.id === input.projectId);
+    if (!project) throw new CollabError("Project not found", 404);
+    if (!roleAtLeast(project.role, "contributor")) throw new CollabError("A project contributor role is required to draft tasks", 403);
+    if (!project.repositories.some((entry) => entry.key === input.repository)) throw new CollabError("Choose a repository belonging to this project");
+    const repo = await this.resolveRepo(input, input.repo);
+    const run = await this.manager.start({
+      pattern: taskDraftPattern,
+      repo,
+      baseRef: input.baseRef || "HEAD",
+      task: input.idea,
+      roles: { agent: [input.agent] },
+      options: {},
+      agentSettings: input.agentSettings,
+      trust: "safe",
+      approvals: { plan: false, tools: false },
+      loop: { check: "", setup: "", copy: [], maxMinutes: 5, maxSteps: 2, maxInvocations: 2 },
+      project: this.options.projectFor?.(repo)
+    });
+    return { runId: run.id };
+  }
+  // ---- Local records: journaled before every step the hub must see at most once.
+  /** Re-reading the files never replaces a record that work in progress holds (a run being followed, a start under way, or an operation queued on its chain): that object carries changes its save has not finished writing, and a stale copy from disk would make the next pass publish the finish a second time or reuse a report number. */
+  load(force = false) {
+    if (force) this.loading = void 0;
+    return this.loading ??= (async () => {
+      const versions = new Map(this.journalVersions), busy = /* @__PURE__ */ new Set([...this.active.keys(), ...this.starting, ...this.chains.keys()]);
+      const protectedRecord = (id) => busy.has(id) || versions.get(id) !== this.journalVersions.get(id) || this.active.has(id) || this.starting.has(id) || this.chains.has(id);
+      let names;
+      try {
+        names = await readdir(this.attemptsDir);
+      } catch (error) {
+        if (error.code !== "ENOENT") logError(`Couldn't list ${this.attemptsDir}; local attempt records are unavailable`, error);
+        names = [];
+      }
+      const seen = /* @__PURE__ */ new Set();
+      for (const name of names) {
+        if (!/^[a-f0-9]{32}\.json$/.test(name)) continue;
+        const file = join(this.attemptsDir, name);
+        try {
+          const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+          let body;
+          try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > RECORD_LIMIT) throw new Error("not a regular file within 256 KiB");
+            body = await handle.readFile("utf8");
+          } finally {
+            await handle.close();
+          }
+          const record = validateRecord(JSON.parse(body));
+          if (!record || `${record.attemptId}.json` !== name) throw new Error("the record does not describe the attempt its file is named after");
+          if (record.hubUrl !== this.hub.url) continue;
+          if (protectedRecord(record.attemptId)) {
+            seen.add(record.attemptId);
+            continue;
+          }
+          this.records.set(record.attemptId, record);
+          seen.add(record.attemptId);
+        } catch (error) {
+          logError(`Skipping the unreadable attempt record ${file}; remove it if the attempt is over`, error);
+        }
+      }
+      for (const id of [...this.records.keys()]) if (!seen.has(id) && !protectedRecord(id)) this.records.delete(id);
+    })();
+  }
+  async record(attemptId) {
+    await this.load();
+    return this.records.get(attemptId);
+  }
+  async save(record) {
+    this.journalVersions.set(record.attemptId, (this.journalVersions.get(record.attemptId) ?? 0) + 1);
+    record.updatedAt = this.now();
+    this.records.set(record.attemptId, record);
+    await mkdir(this.attemptsDir, { recursive: true, mode: 448 });
+    const file = join(this.attemptsDir, `${record.attemptId}.json`), temp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+      const handle = await open(temp, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify(record));
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temp, file);
+    } finally {
+      await rm(temp, { force: true }).catch(() => {
+      });
+    }
+  }
+  async remove(attemptId) {
+    this.journalVersions.set(attemptId, (this.journalVersions.get(attemptId) ?? 0) + 1);
+    this.records.delete(attemptId);
+    await rm(join(this.attemptsDir, `${attemptId}.json`), { force: true }).catch(() => void 0);
+  }
+  /** One operation at a time per attempt, so report numbers go out in order and a finish never races a publish. */
+  serial(attemptId, fn) {
+    const previous = this.chains.get(attemptId) ?? Promise.resolve(), next = previous.catch(() => void 0).then(fn);
+    this.chains.set(attemptId, next);
+    next.finally(() => {
+      if (this.chains.get(attemptId) === next) this.chains.delete(attemptId);
+    }).catch(() => void 0);
+    return next;
+  }
+  async attempts() {
+    await this.load();
+    return [...this.records.values()].sort((a, b) => b.updatedAt - a.updatedAt).map((record) => structuredClone(record));
+  }
+  attemptForRun(runId) {
+    for (const record of this.records.values()) if (record.runId === runId) return structuredClone(record);
+    return void 0;
+  }
+  /** The latest local attempt of a task, optionally among some states; what the stop/resume/hand-over routes act on. */
+  async attemptForTask(taskId, states) {
+    await this.load();
+    let found;
+    for (const record of this.records.values()) if (record.taskId === taskId && (!states || states.includes(record.state)) && (!found || record.updatedAt >= found.updatedAt)) found = record;
+    return found && structuredClone(found);
+  }
+  assertOpen() {
+    if (this.closed) throw new CollabError("code-flow is shutting down; team attempts cannot start now", 503);
+  }
+  // ---- Repositories and checkpoints on this computer
+  async repoAt(path, hint) {
+    if (typeof path !== "string" || !isAbsolute(path) || path.length > 4096) throw new CollabError(hint);
+    try {
+      return await realpath(await repoRoot(path));
+    } catch {
+      throw new CollabError(`${path} is not inside a Git repository on this computer`);
+    }
+  }
+  resolveRepo(task, explicit) {
+    const path = explicit ?? this.options.resolveRepo?.(task.projectId, task.repository);
+    if (!path) throw new CollabError(`Map repository ${task.repository} to a folder in Settings \u2192 Team, or choose the folder when starting`);
+    return this.repoAt(path, "Repository must be an absolute path");
+  }
+  /** Download, verify and import a checkpoint's bundle into `repo` under `refs/codeflow/team/<checkpoint id>`; idempotent, and HEAD/branches stay untouched. A bundle whose ref names another checkpoint is refused (409) rather than filed under the wrong id on this computer. */
+  async importById(repo, checkpointId) {
+    if (!CHECKPOINT_ID.test(checkpointId)) throw new CollabError("Send the checkpoint id as 32 lowercase hexadecimal characters");
+    await mkdir(tmpdir(), { recursive: true }).catch(() => void 0);
+    const file = join(tmpdir(), `codeflow-team-download-${checkpointId}-${randomBytes(6).toString("hex")}.bundle`);
+    try {
+      const manifest = await this.hub.downloadBundle(checkpointId, file), embedded = await embeddedCheckpointId(repo, file);
+      if (embedded !== checkpointId) throw new CollabError(`The downloaded bundle does not belong to checkpoint ${checkpointId}; it advertises refs/codeflow/team/${embedded}. Delete this checkpoint and create a new one from the computer that holds the work`, 409);
+      const { commit } = await importCheckpointBundle(repo, file, { id: checkpointId, commit: manifest.commit, baseCommit: manifest.baseCommit, size: manifest.size, sha256: manifest.sha256, ref: checkpointRef(checkpointId) });
+      return { manifest, commit };
+    } finally {
+      await rm(file, { force: true }).catch(() => void 0);
+    }
+  }
+  /** The checkpoint of what a run left on its branch. Its id is minted here, before bundling, and travels in the manifest: the bundle's only ref is `refs/codeflow/team/<id>` and the hub keeps that id as the checkpoint's, so the board, the branch `team/<task>/<id8>` and the refs on every importing machine agree. The bundle is kept under this runner's folder until the hub has its bytes, so a failed upload is retried, never rebuilt; a bundle kept for an earlier checkpoint of the attempt is dropped first, never left behind. */
+  async publishCheckpoint(record, run, task, head, branch, note, changedFiles) {
+    await this.dropKept(record);
+    const parentId = task.attempts.find((attempt) => attempt.id === record.attemptId)?.fromCheckpointId;
+    const parent = parentId ? task.checkpoints.find((checkpoint2) => checkpoint2.id === parentId) : void 0;
+    if (parentId && !parent) throw new CollabError("The checkpoint this attempt continued from is missing; restore its manifest before publishing", 409);
+    const baseCommit = parent?.baseCommit ?? record.base;
+    const share = (value, max, singleLine = false) => sharedText(value, max, singleLine, localPaths(run));
+    const checkpointId = newCheckpointId(), bundle = await createCheckpointBundle(run.repo, head, baseCommit, checkpointId), kept = join(this.bundlesDir, `${checkpointId}.bundle`);
+    await mkdir(this.bundlesDir, { recursive: true, mode: 448 });
+    try {
+      await rename(bundle.file, kept);
+    } catch {
+      await copyFile(bundle.file, kept, constants.COPYFILE_EXCL);
+      await rm(bundle.file, { force: true });
+    }
+    const manifest = { id: checkpointId, commit: head, baseCommit, branch: share(branch, MAX.branch, true), size: bundle.size, sha256: bundle.sha256, note: share(note, MAX.note), requirements: share(`${task.title}
+
+## Goal
+${task.goal}
+
+## Acceptance criteria
+${task.acceptance}`, MAX.requirements), decisions: task.decisions.slice(0, MAX.decisions).map((decision) => share(decision.text, MAX.decision)).filter(Boolean), remaining: tail(share(run.summary, Number.MAX_SAFE_INTEGER), MAX.remaining), changedFiles: changedFiles.slice(0, MAX.changedFiles).map((path) => share(path, MAX.path, true)).filter(Boolean) };
+    if (run.lastCheck) manifest.testResults = { ok: run.lastCheck.ok, command: share(run.lastCheck.command, MAX.command, true) || "check", at: count(run.lastCheck.at) ? run.lastCheck.at : this.now() };
+    let checkpoint;
+    try {
+      checkpoint = await this.hub.addCheckpoint(record.attemptId, manifest);
+    } catch (error) {
+      await rm(kept, { force: true }).catch(() => void 0);
+      throw error;
+    }
+    if (checkpoint.id !== checkpointId) {
+      await rm(kept, { force: true }).catch(() => void 0);
+      throw new CollabError(`The team server named the checkpoint ${checkpoint.id} instead of ${checkpointId}, so its bundle could never be imported; update the team server to a code-flow that keeps checkpoint ids`, 502);
+    }
+    record.checkpointId = checkpoint.id;
+    record.pendingFinish = { state: run.status === "running" ? "finished" : mapRunStatus(run).state, error: "", at: this.now(), tries: 0, ...record.pendingFinish, bundleFile: kept };
+    await this.save(record);
+    await this.uploadKept(record, checkpoint);
+    return checkpoint;
+  }
+  /** Uploads the kept bundle of `checkpoint`. The hub refuses a repeated upload before reading the body and drops the socket, so a retry of an upload it already completed can end in a write error rather than its 409: the checkpoint on the hub, not the answer, says whether the bytes arrived. */
+  async uploadKept(record, checkpoint) {
+    const kept = record.pendingFinish?.bundleFile;
+    if (!kept) return;
+    try {
+      await this.hub.uploadBundle(checkpoint.id, kept, { size: checkpoint.size, sha256: checkpoint.sha256 });
+    } catch (error) {
+      const already = error instanceof CollabError && error.status === 409 && /already uploaded/.test(error.message);
+      const stored = already ? void 0 : await this.hub.task(record.taskId).then((task) => task.checkpoints.find((entry) => entry.id === checkpoint.id)).catch(() => void 0);
+      if (!already && !(stored?.bundle === "available" && stored.sha256 === checkpoint.sha256)) throw error;
+    }
+    await this.dropKept(record);
+    await this.save(record);
+  }
+  /** Removes the bundle kept for a checkpoint this computer no longer needs to upload (the hub has it, it was replaced, the attempt is over); the caller saves the record. */
+  async dropKept(record) {
+    const kept = record.pendingFinish?.bundleFile;
+    if (!kept) return;
+    await rm(kept, { force: true }).catch(() => void 0);
+    delete record.pendingFinish.bundleFile;
+  }
+  /**
+   * The hub's checkpoint of `head` for this attempt, bytes included: the one already recorded when it still names this
+   * head (its kept bundle uploaded when the hub lacks the bytes, dropped when the hub has them), else a new one. A
+   * checkpoint deleted on the hub, or left pending without a bundle here, is replaced. Runs under serial(record.attemptId).
+   */
+  async ensureCheckpoint(record, run, task, head, branch, note, files) {
+    const attempt = task.attempts.find((entry) => entry.id === record.attemptId), id = record.checkpointId ?? attempt?.checkpointId, existing = id ? task.checkpoints.find((entry) => entry.id === id) : void 0;
+    if (existing && existing.commit === head && existing.bundle !== "deleted") {
+      if (existing.bundle === "available") {
+        await this.dropKept(record);
+        await this.save(record);
+        return existing.id;
+      }
+      if (record.pendingFinish?.bundleFile) {
+        try {
+          await this.uploadKept(record, existing);
+          return existing.id;
+        } catch (error) {
+          if (!(error instanceof CollabError && error.status === 409 && /deleted/.test(error.message))) throw error;
+        }
+      }
+    }
+    return (await this.publishCheckpoint(record, run, task, head, branch, note, files)).id;
+  }
+  async changedFilesOf(runId, branch) {
+    try {
+      const coverage = await this.manager.reviewCoverage(runId, branch);
+      return { head: coverage.head, files: coverage.files };
+    } catch {
+      return void 0;
+    }
+  }
+  // ---- Starting, attaching, publishing
+  async startAttempt(taskId, input) {
+    this.assertOpen();
+    const hub = this.hub;
+    let task = await hub.task(taskId);
+    const pattern = typeof input.pattern === "string" ? this.options.findPattern(input.pattern) : input.pattern;
+    if (!pattern) throw new CollabError("Unknown pattern");
+    let busy = busyAttempt(task);
+    if (busy && busy.runnerId === hub.runnerId && await this.settleStale(busy.id)) {
+      task = await hub.task(taskId);
+      busy = busyAttempt(task);
+    }
+    if (busy) throw new CollabError(`Stop the attempt running on ${busy.runnerName} before starting another`, 409);
+    if (task.handoff?.state === "offered") throw new CollabError("Accept, decline or cancel the offered hand-over before starting an attempt", 409);
+    const repo = await this.resolveRepo(task, input.repo);
+    let checkpoint, base;
+    if (input.fromCheckpointId !== void 0) {
+      checkpoint = task.checkpoints.find((entry) => entry.id === input.fromCheckpointId);
+      if (!checkpoint) throw new CollabError("Checkpoint not found", 404);
+      if (checkpoint.bundle !== "available") throw new CollabError("The checkpoint's bundle is not on the team server; choose another checkpoint or start from the base branch", 409);
+      base = (await this.importById(repo, checkpoint.id)).commit;
+      task = await hub.task(taskId);
+      busy = busyAttempt(task);
+      if (busy) throw new CollabError(`Stop the attempt running on ${busy.runnerName} before starting another`, 409);
+      if (task.handoff?.state === "offered") throw new CollabError("Accept, decline or cancel the offered hand-over before starting an attempt", 409);
+    } else {
+      const ref = task.baseRef ?? "HEAD";
+      try {
+        base = await resolveCommit(repo, ref);
+      } catch {
+        throw new CollabError(`Base ${ref} does not exist in ${repo}; fetch it or change the task's base branch`);
+      }
+      await assertCheckpointable(repo, base);
+    }
+    const record = { attemptId: newAttemptId(), taskId: task.id, repo, base, state: "claiming", lastSeq: 0, lastAckedSeq: 0, deliveredInstructionIds: [], updatedAt: this.now() };
+    if (hub.url) record.hubUrl = hub.url;
+    this.starting.add(record.attemptId);
+    try {
+      await this.save(record);
+      let claimed;
+      try {
+        await this.options.beforeStart?.();
+        claimed = await hub.claimAttempt(task.id, { attemptId: record.attemptId, runnerId: hub.runnerId, runnerName: hub.runnerName, baseCommit: base, ...checkpoint ? { fromCheckpointId: checkpoint.id } : {}, revision: task.revision });
+      } catch (error) {
+        if (error instanceof CollabError && error.status < 500) await this.remove(record.attemptId);
+        throw error;
+      }
+      record.state = "claimed";
+      await this.save(record);
+      const projectName = await hub.board(task.projectId).then((board) => board.projects.find((project) => project.id === task.projectId)?.name).catch(() => void 0);
+      const handover = checkpoint ? [...claimed.handoffs].reverse().find((entry) => entry.state === "accepted" && entry.checkpointId === checkpoint.id) : void 0, handoverNote = handover?.note.trim() ?? "";
+      const context = checkpoint && handoverNote && handoverNote !== checkpoint.note.trim() ? { ...checkpoint, note: clean([checkpoint.note.trim(), `Hand-over note from ${clean(handover.from.displayName, MAX.displayName, true) || "a teammate"}: ${handoverNote}`].filter(Boolean).join("\n\n"), MAX.note) } : checkpoint;
+      const prompt = taskPrompt(claimed, { projectName, checkpoint: context });
+      let run;
+      try {
+        await this.options.beforeStart?.();
+        run = await this.manager.start({ checkpointOnFinish: true, pattern, task: prompt, repo, baseRef: base, roles: input.roles, options: {}, agentSettings: input.agentSettings, roleSettings: input.roleSettings, trust: input.trust, loop: input.loop, project: this.options.projectFor?.(repo), beforeDispatch: async (pending) => {
+          await this.options.beforeStart?.();
+          record.runId = pending.id;
+          await this.save(record);
+        } });
+      } catch (error) {
+        const reason = sharedText(`The run could not start on this computer: ${message(error)}`, MAX.reason, false, localPaths({ repo }));
+        record.state = "failed";
+        record.pendingFinish = { state: "failed", reason, error: "", at: this.now(), tries: 0 };
+        await this.save(record);
+        await this.withoutRun(record, "failed", reason).catch((failure) => logError("The team server could not be told that the run failed to start; the recovery pass retries it", failure));
+        throw asCollab(error);
+      }
+      record.runId = run.id;
+      record.state = "running";
+      await this.save(record);
+      await this.serial(record.attemptId, () => this.report(record, { runId: run.id, runStatus: "running", updatedAt: this.now() }));
+      this.attach(record.attemptId, run.id);
+      return { attemptId: record.attemptId, runId: run.id };
+    } finally {
+      this.starting.delete(record.attemptId);
+    }
+  }
+  /** Journals the next report number before it goes out, so a crash can never reuse one; a failed send is not retried (the next snapshot supersedes it). */
+  async report(record, body) {
+    const seq = ++record.lastSeq;
+    if (record.state === "claimed" || record.state === "paused" || record.state === "stopped" || record.state === "unknown") record.state = "running";
+    await this.save(record);
+    try {
+      await this.hub.progress(record.attemptId, { seq, ...body });
+      record.lastAckedSeq = seq;
+      await this.save(record);
+      return void 0;
+    } catch (error) {
+      logError(`Progress report ${seq} for attempt ${record.attemptId} did not reach the team server`, error);
+      return error instanceof CollabError ? error.status : void 0;
+    }
+  }
+  /** Losing execution authority stops the local agent as well as its reports. The hub keeps unknown attempts reserved until stopping is confirmed. */
+  hubEnded(live, status, what) {
+    if (status === void 0 || !HUB_FINAL.has(status)) return false;
+    logError(`The team server no longer accepts ${what} for attempt ${live.attemptId} (HTTP ${status}); stopping run ${live.runId}`);
+    this.detach(live);
+    this.manager.cancel(live.runId);
+    return true;
+  }
+  /** Follows a run already started for an attempt: bounded snapshots at most every 2 s (at once when it ends), the branch head after each step, heartbeats every 20 s, and the finish when the run ends. */
+  attach(attemptId, runId) {
+    if (this.closed || this.active.has(attemptId)) return;
+    const run = this.manager.get(runId);
+    if (!run) {
+      void this.serial(attemptId, async () => {
+        const record = await this.record(attemptId);
+        if (record) await this.lost(record, `Run ${runId} is missing from this computer`);
+      });
+      return;
+    }
+    const live = { attemptId, runId, unsubscribe: () => {
+    }, dirty: true, ended: false };
+    this.active.set(attemptId, live);
+    live.unsubscribe = this.manager.subscribe(runId, (event) => {
+      if (live.ended) return;
+      if (event.type === "step" && event.step.status !== "running") void this.refreshHead(live);
+      if (event.type === "run" || event.type === "step") this.schedulePublish(live);
+      if (event.type === "run" && event.run.status !== "running") this.terminal(live);
+    });
+    live.heartbeat = setInterval(() => void this.heartbeatNow(live), HEARTBEAT_INTERVAL_MS);
+    live.heartbeat.unref?.();
+    void this.refreshHead(live);
+    this.schedulePublish(live, true);
+    if (run.status !== "running") this.terminal(live);
+  }
+  refreshHead(live) {
+    const run = this.manager.get(live.runId), branch = run?.worktrees[0]?.branch;
+    if (!run || !branch) return Promise.resolve();
+    const work = this.changedFilesOf(run.id, branch).then((result) => {
+      if (result) {
+        live.head = result.head;
+        live.changedFiles = result.files;
+        live.dirty = true;
+      }
+    });
+    live.refreshing = work;
+    return work;
+  }
+  schedulePublish(live, immediate = false) {
+    live.dirty = true;
+    if (live.ended) return;
+    if (immediate) {
+      if (live.publishTimer) {
+        clearTimeout(live.publishTimer);
+        live.publishTimer = void 0;
+      }
+      void this.publish(live);
+      return;
+    }
+    if (live.publishTimer) return;
+    live.publishTimer = setTimeout(() => {
+      live.publishTimer = void 0;
+      void this.publish(live);
+    }, PUBLISH_INTERVAL_MS);
+    live.publishTimer.unref?.();
+  }
+  publish(live) {
+    return this.serial(live.attemptId, async () => {
+      if (!live.dirty || this.closed) return;
+      live.dirty = false;
+      await live.refreshing?.catch(() => void 0);
+      const record = await this.record(live.attemptId), run = this.manager.get(live.runId);
+      if (!record || !run || run.status !== "running" || record.state === "finished" || record.state === "failed") return;
+      this.hubEnded(live, await this.report(record, { ...progressFromRun(run, { head: live.head, changedFiles: live.changedFiles }, this.now()), runId: live.runId }), "progress reports");
+    });
+  }
+  detach(live) {
+    live.ended = true;
+    if (live.publishTimer) clearTimeout(live.publishTimer);
+    if (live.heartbeat) clearInterval(live.heartbeat);
+    live.unsubscribe();
+    if (this.active.get(live.attemptId) === live) this.active.delete(live.attemptId);
+  }
+  terminal(live) {
+    if (live.ended) return;
+    this.detach(live);
+    void this.serial(live.attemptId, async () => {
+      const record = await this.record(live.attemptId);
+      if (!record || this.closed) return;
+      await this.finishNow(record).catch((error) => logError(`Attempt ${record.attemptId} could not be finished on the team server; it is retried by the recovery pass`, error));
+    });
+  }
+  /** Delivers approved instructions once each: the note reaches the agent, the id is journaled, then the hub is told; a crash in between is caught by the journal, not by a second note. */
+  heartbeatNow(live) {
+    return this.serial(live.attemptId, async () => {
+      if (live.ended || this.closed) return [];
+      const record = await this.record(live.attemptId);
+      if (!record) return [];
+      let result;
+      try {
+        result = await this.hub.heartbeat(record.attemptId);
+      } catch (error) {
+        if (!this.hubEnded(live, error instanceof CollabError ? error.status : void 0, "heartbeats")) logError(`Heartbeat for attempt ${record.attemptId} did not reach the team server`, error);
+        return [];
+      }
+      const delivered = [];
+      for (const instruction of result.instructions) {
+        if (instruction.state !== "approved") continue;
+        if (!record.deliveredInstructionIds.includes(instruction.id)) {
+          try {
+            this.manager.addNote(live.runId, instructionNote(instruction));
+          } catch (error) {
+            logError(`Instruction ${instruction.id} could not be handed to the run ${live.runId}`, error);
+            continue;
+          }
+          record.deliveredInstructionIds.push(instruction.id);
+          if (record.deliveredInstructionIds.length > MAX_DELIVERED) record.deliveredInstructionIds.splice(0, record.deliveredInstructionIds.length - MAX_DELIVERED);
+          await this.save(record);
+          delivered.push(instruction.id);
+        }
+        try {
+          await this.hub.markInstructionDelivered(record.taskId, instruction.id, record.attemptId);
+        } catch (error) {
+          logError(`Instruction ${instruction.id} was delivered but the team server could not be told`, error);
+        }
+      }
+      return delivered;
+    });
+  }
+  /** A heartbeat on demand (the timer sends one every 20 s): returns the ids of instructions handed to the agent this time. */
+  async heartbeat(attemptId) {
+    const live = this.active.get(attemptId);
+    if (!live) throw new CollabError("This attempt is not running on this computer", 409);
+    return this.heartbeatNow(live);
+  }
+  // ---- Finishing
+  async finishAttempt(attemptId) {
+    const record = await this.record(attemptId);
+    if (!record) throw new CollabError("Attempt not found on this computer", 404);
+    return this.serial(attemptId, () => this.finishNow(record));
+  }
+  /**
+   * The terminal snapshot (with the branch head and changed files) goes out first, so the hub's attempt knows its run even
+   * when the finish is the first thing this computer managed to send; then the checkpoint, then the finish. Idempotent: an
+   * attempt whose publish failed keeps `pendingFinish` and is finished again with the same checkpoint on the next call. A
+   * checkpoint the hub or Git would refuse again (a tree checkpoints cannot carry, a bundle over 64 MiB, a manifest the hub
+   * rejects) does not hold the attempt open: the task is released with the reason, and the work stays on this computer's branch.
+   */
+  async finishNow(record) {
+    const run = record.runId ? this.manager.get(record.runId) : void 0;
+    if (!run && !record.runId && record.pendingFinish?.state === "failed") return this.withoutRun(record, "failed", record.pendingFinish.reason ?? "The run could not start on this computer");
+    if (!run) return this.lost(record, record.runId ? `Run ${record.runId} is missing from this computer` : "The run never started on this computer; start a new attempt");
+    if (run.status === "running") throw new CollabError("The run is still running; stop it before finishing the attempt", 409);
+    const outcome = mapRunStatus(run), branch = run.worktrees[0]?.branch, coverage = branch ? await this.changedFilesOf(run.id, branch) : void 0, head = coverage?.head ?? (branch ? await resolveCommit(run.repo, `refs/heads/${branch}`).catch(() => void 0) : void 0);
+    if (record.state !== "finished" && record.state !== "failed" && !record.pendingFinish) await this.report(record, { ...progressFromRun(run, { head, changedFiles: coverage?.files }, this.now()), runId: run.id });
+    const pending = { ...record.pendingFinish, state: outcome.state, error: record.pendingFinish?.error ?? "", at: this.now(), tries: record.pendingFinish?.tries ?? 0 };
+    if (head) pending.head = head;
+    else delete pending.head;
+    const summary = sharedText(run.summary, MAX.summary, false, localPaths(run));
+    if (summary.trim()) pending.summary = summary;
+    else delete pending.summary;
+    if (outcome.reason) pending.reason = outcome.reason;
+    else delete pending.reason;
+    record.pendingFinish = pending;
+    const finish = { state: pending.state, ...pending.head ? { head: pending.head } : {}, ...pending.summary ? { summary: pending.summary } : {}, ...pending.reason ? { reason: pending.reason } : {} };
+    let finishing = false;
+    try {
+      if (head && branch && head !== record.base) {
+        const task = await this.hub.task(record.taskId);
+        try {
+          await this.ensureCheckpoint(record, run, task, head, branch, "", coverage?.files ?? []);
+        } catch (error) {
+          if (!(error instanceof CollabError && error.status >= 400 && error.status < 500)) throw error;
+          await this.dropKept(record);
+          finish.state = pending.state === "finished" ? "failed" : pending.state;
+          finish.reason = sharedText(`No checkpoint was published: ${error.message}${pending.reason ? ` (${pending.reason})` : ""}`, MAX.reason, false, localPaths(run));
+          logError(`Attempt ${record.attemptId} ends on the team server without a checkpoint; its work stays on branch ${branch} of ${run.repo}`, error);
+        }
+      }
+      finishing = true;
+      await this.hub.finish(record.attemptId, finish);
+      await this.dropKept(record);
+      delete record.pendingFinish;
+      record.state = finish.state;
+      await this.save(record);
+      return structuredClone(record);
+    } catch (error) {
+      const status = error instanceof CollabError ? error.status : void 0;
+      if (status === 401 || finishing && status !== void 0 && HUB_FINAL.has(status)) {
+        logError(`The team server closed attempt ${record.attemptId} on its own (${message(error)}); this computer records the run's outcome and stops retrying`);
+        await this.dropKept(record);
+        delete record.pendingFinish;
+        record.state = pending.state;
+        await this.save(record);
+        return structuredClone(record);
+      }
+      const current = record.pendingFinish ?? pending;
+      current.error = clean(message(error), 1e3);
+      current.tries++;
+      current.at = this.now();
+      record.pendingFinish = current;
+      record.state = pending.state;
+      if (current.tries >= MAX_FINISH_TRIES) {
+        logError(`Attempt ${record.attemptId} could not be finished on the team server in ${current.tries} tries (${current.error}); this computer keeps the run's outcome and gives up`);
+        await this.dropKept(record);
+        delete record.pendingFinish;
+        await this.save(record);
+        return structuredClone(record);
+      }
+      await this.save(record);
+      throw asCollab(error, 502);
+    }
+  }
+  /** A missing run cannot prove execution stopped: leave the hub reservation unknown for explicit recovery. */
+  lost(record, reason) {
+    return this.withoutRun(record, "unknown", reason);
+  }
+  /** Publishes the finish of an attempt that has no run to report on: `unknown` when the run is gone, `failed` when it never started. The hub's final word and the retry bound apply as in finishNow. */
+  async withoutRun(record, state, reason) {
+    await this.dropKept(record);
+    const pending = { state, reason: sharedText(reason, MAX.reason, false, localPaths({ repo: record.repo })), error: record.pendingFinish?.error ?? "", at: this.now(), tries: record.pendingFinish?.tries ?? 0 };
+    try {
+      await this.hub.finish(record.attemptId, { state, reason: pending.reason });
+      delete record.pendingFinish;
+      record.state = state;
+      await this.save(record);
+      return structuredClone(record);
+    } catch (error) {
+      const status = error instanceof CollabError ? error.status : void 0;
+      record.state = state;
+      if (status !== void 0 && HUB_FINAL.has(status)) {
+        logError(`The team server closed attempt ${record.attemptId} on its own (${message(error)}); this computer records it as ${state} and stops retrying`);
+        delete record.pendingFinish;
+        await this.save(record);
+        return structuredClone(record);
+      }
+      pending.error = clean(message(error), 1e3);
+      pending.tries++;
+      record.pendingFinish = pending;
+      if (pending.tries >= MAX_FINISH_TRIES) {
+        logError(`Attempt ${record.attemptId} could not be reported ${state} to the team server in ${pending.tries} tries (${pending.error}); this computer gives up`);
+        delete record.pendingFinish;
+        await this.save(record);
+        return structuredClone(record);
+      }
+      await this.save(record);
+      throw asCollab(error, 502);
+    }
+  }
+  // ---- Stop, resume, hand over, accept, fetch
+  /** `manager.cancel` is the engine's stop; the run's terminal snapshot then finishes the attempt as paused, so it can be resumed from here. */
+  async stopAttempt(attemptId) {
+    const record = await this.record(attemptId);
+    if (!record) throw new CollabError("Attempt not found on this computer", 404);
+    if (!record.runId) throw new CollabError("This attempt has no run on this computer yet", 409);
+    const run = this.manager.get(record.runId);
+    if (!run || run.status !== "running") throw new CollabError("The run is not running; there is nothing to stop", 409);
+    if (!this.active.has(attemptId)) this.attach(attemptId, record.runId);
+    const cancelled = this.manager.cancel(record.runId);
+    return { attemptId, runId: record.runId, cancelled };
+  }
+  /** Resumes the paused run of an attempt the hub still considers this computer's: one superseded by a hand-over or a reassignment, or a task busy with another attempt, must not get its agent back here, where every report would be refused. */
+  async resumeAttempt(attemptId) {
+    this.assertOpen();
+    const record = await this.record(attemptId);
+    if (!record) throw new CollabError("Attempt not found on this computer", 404);
+    if (!record.runId) throw new CollabError("This attempt has no run on this computer to resume", 409);
+    if (record.state === "finished" || record.state === "failed") throw new CollabError(`This attempt already ${record.state}; start a new attempt instead`, 409);
+    const run = this.manager.get(record.runId);
+    if (!run) throw new CollabError(`Run ${record.runId} is missing from this computer`, 404);
+    if (run.status === "running") throw new CollabError("The run is already running", 409);
+    return this.serial(attemptId, async () => {
+      const task = await this.hub.task(record.taskId), attempt = task.attempts.find((entry) => entry.id === attemptId);
+      if (!attempt) throw new CollabError("The team server no longer lists this attempt; start a new attempt instead", 409);
+      if (attempt.state === "superseded") throw new CollabError("This attempt was superseded by a change of owner; start a new attempt from the latest checkpoint instead", 409);
+      if (attempt.state === "finished" || attempt.state === "failed") throw new CollabError(`This attempt already ended as ${attempt.state} on the team server; start a new attempt instead`, 409);
+      if (task.status === "done") throw new CollabError("Move the task out of Done before resuming the attempt", 409);
+      const busy = busyAttempt(task);
+      if (busy && busy.id !== attemptId) throw new CollabError(`Stop the attempt running on ${busy.runnerName} before resuming this one`, 409);
+      if (task.handoff?.state === "offered") throw new CollabError("Accept, decline or cancel the offered hand-over before resuming an attempt", 409);
+      if (task.owner?.userId !== attempt.user.userId) throw new CollabError(ownerChangedMessage(task), 409);
+      const previousState = record.state, seq = ++record.lastSeq;
+      record.state = "claimed";
+      await this.save(record);
+      try {
+        await this.hub.progress(record.attemptId, { seq, runId: record.runId, runStatus: "running", updatedAt: this.now() });
+      } catch (error) {
+        if (error instanceof CollabError && error.status < 500) {
+          record.state = previousState;
+          await this.save(record);
+        }
+        throw error;
+      }
+      record.lastAckedSeq = seq;
+      record.state = "claimed";
+      await this.dropKept(record);
+      delete record.pendingFinish;
+      await this.save(record);
+      try {
+        await this.manager.resume(record.runId);
+      } catch (error) {
+        await this.finishNow(record);
+        throw asCollab(error, 409);
+      }
+      record.state = "running";
+      await this.save(record);
+      this.attach(attemptId, record.runId);
+      return { attemptId, runId: record.runId };
+    });
+  }
+  /** Offers the task at a checkpoint of this computer's work: the attempt's existing checkpoint when it still matches the branch, else a new one (committing uncommitted changes first only when asked). Only the task's current attempt can be checkpointed: after a hand-over round trip this computer's latest record may be a superseded attempt, whose checkpoint is older than the task's latest. */
+  async handOver(taskId, input) {
+    const hub = this.hub, task = await hub.task(taskId), busy = busyAttempt(task);
+    if (busy) throw new CollabError(`Stop the attempt running on ${busy.runnerName} before handing the task over`, 409);
+    if (task.handoff?.state === "offered") throw new CollabError(`A hand-over to ${task.handoff.to.displayName} is already offered; cancel it before offering another`, 409);
+    const record = await this.attemptForTask(task.id);
+    let checkpointId;
+    const run = record?.runId ? this.manager.get(record.runId) : void 0, worktree = run?.worktrees[0], attempt = record ? task.attempts.find((entry) => entry.id === record.attemptId) : void 0;
+    const current = attempt !== void 0 && attempt.state !== "superseded" && [...task.attempts].reverse().find((entry) => entry.state !== "superseded")?.id === attempt.id;
+    if (record && run && worktree && attempt && current) {
+      if (run.status === "running") throw new CollabError("Stop the run before handing the task over", 409);
+      let head = await resolveCommit(run.repo, `refs/heads/${worktree.branch}`).catch(() => void 0);
+      const checkout = await assertWorktree(run.repo, { path: worktree.path, branch: worktree.branch }).catch(() => void 0), dirty = checkout ? await uncommittedCount(checkout).catch(() => 0) : 0;
+      if (dirty > 0) {
+        if (!input.includeUncommitted) throw new CollabError("Commit, discard, or include uncommitted changes first", 409);
+        head = await commitAll(run.repo, { name: worktree.name, path: worktree.path, branch: worktree.branch, base: run.baseRef }, "Hand-over checkpoint") ?? head;
+      }
+      if (head) {
+        const files = (await this.changedFilesOf(run.id, worktree.branch))?.files ?? [];
+        checkpointId = await this.serial(record.attemptId, async () => {
+          const live = this.records.get(record.attemptId) ?? record;
+          try {
+            const id = await this.ensureCheckpoint(live, run, task, head, worktree.branch, input.note ?? "", files);
+            if (live.pendingFinish && !live.pendingFinish.bundleFile && live.pendingFinish.state === attempt.state) delete live.pendingFinish;
+            await this.save(live);
+            return id;
+          } catch (error) {
+            if (live.pendingFinish?.bundleFile) {
+              live.pendingFinish.error = clean(message(error), 1e3);
+              live.pendingFinish.tries++;
+              live.pendingFinish.at = this.now();
+              await this.save(live);
+            }
+            throw error;
+          }
+        });
+      }
+    } else if (record && run && worktree && attempt) {
+      const head = await resolveCommit(run.repo, `refs/heads/${worktree.branch}`).catch(() => void 0), recorded = (attempt.checkpointId ? task.checkpoints.find((entry) => entry.id === attempt.checkpointId)?.commit : void 0) ?? attempt.head ?? record.base;
+      const checkout = input.includeUncommitted ? await assertWorktree(run.repo, { path: worktree.path, branch: worktree.branch }).catch(() => void 0) : void 0, dirty = checkout ? await uncommittedCount(checkout).catch(() => 0) : 0;
+      if (head && head !== recorded || dirty > 0) throw new CollabError(`Branch ${worktree.branch} on this computer holds work made after its attempt was superseded by a change of owner, which cannot be handed over; start a new attempt from the latest checkpoint to continue from it`, 409);
+    }
+    if (!checkpointId) {
+      const latest = latestCheckpoint(task);
+      if (latest?.bundle === "available") checkpointId = latest.id;
+      else throw new CollabError("Nothing to hand over yet: run the task on this computer first, or wait for a checkpoint", 409);
+    }
+    const fresh = await hub.task(task.id);
+    return hub.offerHandoff(task.id, { to: input.to, checkpointId, note: sharedText(input.note, MAX.note, false, localPaths(run ?? {})) }, fresh.revision);
+  }
+  /** The bundle is imported into the recipient's clone before ownership moves, so a failed download leaves the task with its current owner. The download can take minutes, during which comments and reviews bump the task's revision: the accept goes out against the task as it is afterwards, as long as the same offer still stands. */
+  async acceptHandoff(taskId, handoffId, input = {}) {
+    const hub = this.hub, task = await hub.task(taskId), handoff = task.handoff;
+    if (!handoff || handoff.id !== handoffId) {
+      const past = task.handoffs.find((entry) => entry.id === handoffId);
+      if (past) throw new CollabError(`This hand-over was already ${past.state}`, 409);
+      throw new CollabError("Hand-over not found", 404);
+    }
+    const checkpoint = task.checkpoints.find((entry) => entry.id === handoff.checkpointId);
+    if (!checkpoint) throw new CollabError("Checkpoint not found", 404);
+    if (checkpoint.bundle !== "available") throw new CollabError("The hand-over's checkpoint bundle is not on the team server; ask the sender to hand over again", 409);
+    const repo = await this.resolveRepo(task, input.repo);
+    await this.importById(repo, checkpoint.id);
+    const fresh = await hub.task(taskId), offer = fresh.handoff;
+    if (!offer || offer.id !== handoffId) {
+      const past = fresh.handoffs.find((entry) => entry.id === handoffId);
+      if (past) throw new CollabError(`This hand-over was already ${past.state}`, 409);
+      throw new CollabError("Hand-over not found", 404);
+    }
+    return hub.respondHandoff(fresh.id, offer.id, "accept", fresh.revision);
+  }
+  /** Imports a checkpoint for review or integration and puts it on `team/<task id>/<first 8 of the checkpoint id>`, never checking it out. */
+  async fetchCheckpoint(checkpointId, input) {
+    const repo = await this.repoAt(input.repo, "Repository must be an absolute path"), { manifest, commit } = await this.importById(repo, checkpointId);
+    const result = await ensureCheckpointBranch(repo, `team/${manifest.taskId}/${manifest.id.slice(0, 8)}`, commit);
+    return { commit, branch: result.branch, taskId: manifest.taskId, created: result.created };
+  }
+  // ---- Recovery
+  /** One record against the hub (under serial): a claim is settled or forgotten, a pending finish retried, a run that still goes is followed, one that ended is published, one that is missing reported lost. Never starts a run. */
+  async settle(attemptId, result) {
+    const current = this.records.get(attemptId);
+    if (!current || this.starting.has(attemptId)) return;
+    const neverStarted = current.state === "claiming";
+    if (current.state === "claiming") {
+      let task;
+      try {
+        task = await this.hub.task(current.taskId);
+      } catch (error) {
+        if (!(error instanceof CollabError && error.status === 404)) throw error;
+      }
+      if (!task?.attempts.some((attempt) => attempt.id === current.attemptId)) {
+        await this.remove(current.attemptId);
+        result.removed++;
+        return;
+      }
+      current.state = "claimed";
+      await this.save(current);
+    }
+    if (current.pendingFinish && !this.active.has(current.attemptId)) {
+      result.retried++;
+      await this.finishNow(current);
+      return;
+    }
+    const run = current.runId ? this.manager.get(current.runId) : void 0;
+    if (current.state === "claimed" || current.state === "running") {
+      if (!run) {
+        if (neverStarted) await this.withoutRun(current, "failed", "The run never started on this computer; start a new attempt");
+        else await this.lost(current, current.runId ? `Run ${current.runId} is missing from this computer` : "The run's id was not recorded; confirm execution has stopped before recovering the attempt");
+        result.unknown++;
+        return;
+      }
+      if (run.status === "running") {
+        if (!this.active.has(current.attemptId)) {
+          this.attach(current.attemptId, run.id);
+          result.attached++;
+        }
+        return;
+      }
+      await this.finishNow(current);
+      result.finished++;
+      return;
+    }
+    if ((current.state === "paused" || current.state === "stopped") && run?.status === "running" && !this.active.has(current.attemptId)) {
+      this.attach(current.attemptId, run.id);
+      result.attached++;
+    }
+  }
+  /** Settles the local record of an attempt the hub shows busy for this computer when nothing runs behind it here; true when a pass ran, so the caller rereads the task. */
+  async settleStale(attemptId) {
+    await this.load();
+    const record = this.records.get(attemptId);
+    if (!record || this.active.has(attemptId) || this.starting.has(attemptId)) return false;
+    await this.serial(attemptId, () => this.settle(attemptId, emptyResult())).catch((error) => logError(`Attempt ${attemptId} could not be settled with the team server before starting another`, error));
+    return true;
+  }
+  /** After a start, a reconnect or on demand: finish what ended, follow what still runs, forget claims that never reached the hub, and retry unacknowledged finishes at once. Never starts a run. */
+  async reconcile() {
+    await this.load(true);
+    const result = emptyResult();
+    for (const record of [...this.records.values()]) {
+      if (this.closed) break;
+      if (this.starting.has(record.attemptId)) continue;
+      await this.serial(record.attemptId, () => this.settle(record.attemptId, result)).catch((error) => logError(`Attempt ${record.attemptId} could not be reconciled with the team server; it is retried by the recovery pass`, error));
+    }
+    return result;
+  }
+  /** The recovery timer's pass (every minute): claims whose answer was lost are settled and unacknowledged finishes retried with backoff, so a hub attempt left claimed or running by a lost answer is released within minutes rather than at the next restart or reconnect. Returns how many records were due. */
+  async retryPending() {
+    if (this.closed) return 0;
+    await this.load();
+    const now = this.now();
+    let due = 0;
+    for (const record of [...this.records.values()]) {
+      if (this.closed) break;
+      if (this.starting.has(record.attemptId) || this.active.has(record.attemptId)) continue;
+      const pending = record.pendingFinish;
+      if (!(record.state === "claiming" || record.state === "claimed" || pending !== void 0 && now - pending.at >= retryDelay(pending.tries))) continue;
+      due++;
+      await this.serial(record.attemptId, () => this.settle(record.attemptId, emptyResult())).catch((error) => logError(`Attempt ${record.attemptId} could not be settled with the team server; it is retried later`, error));
+    }
+    return due;
+  }
+  /** Stops timers and listeners; runs keep going and are picked up again by reconcile() after a restart. */
+  async close() {
+    this.closed = true;
+    if (this.retryTimer) clearInterval(this.retryTimer);
+    for (const live of [...this.active.values()]) this.detach(live);
+    await Promise.allSettled([...this.chains.values()]);
+  }
+}
+export {
+  CollabRunner,
+  HEARTBEAT_INTERVAL_MS,
+  MAX_FINISH_TRIES,
+  PUBLISH_INTERVAL_MS,
+  RETRY_INTERVAL_MS,
+  clean,
+  instructionNote,
+  mapRunStatus,
+  progressFromRun,
+  scrubLocalPaths,
+  taskPrompt
+};