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

package/src/collab/store.js

@@ -0,0 +1,1452 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, readdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { CODEFLOW_HOME } from "../config.js";
+import { logError, logWarn } from "../log.js";
+import { actorRole, assertCanChangeOwner, assignOwner, ATTEMPT_ID, ATTEMPT_STATES, busyAttempt, CHECKPOINT_ID, clone, CollabError, COMMIT_ID, isTaskOwner, latestCheckpoint, MAX, mentionsIn, newCheckpointId, newId, newRunnerId, newRunnerToken, newTaskId, ownerChangedMessage, PATH_ID, PREFIXED_ID, pushBounded, recordAudit, REPO_KEY, roleAtLeast, RUNNER_ID, RUNNER_TOKEN, SHA256_HEX, summarize, TASK_ID, TASK_STATUSES, transition, truncateText, validateCheckpointInput, validateCommit, validateProgress, validateProgressReport, validateRepoRefs, validateTaskInput, validateTaskPatch, validateText, validateUserRef, whoOf } from "./model.js";
+const RUNNER_LOCAL = "local";
+const READ_LIMIT = 16 * 1024 * 1024, RING = 1e3, TOUCH_MS = 1e4, FLUSH_MS = 3e4, RETENTION_MS = 30 * 24 * 60 * 6e4, STALE_ATTEMPT_MS = 24 * 60 * 6e4;
+const TERMINAL = ["finished", "failed", "superseded"], FINISH_STATES = ["finished", "failed", "stopped", "paused", "unknown"];
+const INBOX_KINDS = ["assigned", "mention", "review-requested", "review-recorded", "handoff-offered", "handoff-accepted", "handoff-declined", "handoff-cancelled", "instruction-proposed", "blocked", "attempt-finished", "attempt-failed", "comment"];
+const sha256Hex = (value) => createHash("sha256").update(value).digest("hex");
+const short = (commit) => commit.slice(0, 12);
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const integer = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const UNSAFE_KEYS = ["__proto__", "constructor", "prototype"];
+const ownerActor = (displayName = "Owner") => ({ kind: "owner", userId: "owner", displayName });
+const memberActor = (user, via, runnerId) => {
+  const actor = { kind: "member", userId: user.userId, username: user.username, displayName: user.displayName, roles: { ...user.roles }, via };
+  if (runnerId !== void 0) actor.runnerId = runnerId;
+  return actor;
+};
+const runnerPublic = (runner, now) => {
+  const pub = { id: runner.id, userId: runner.userId, name: runner.name, createdAt: runner.createdAt, lastSeenAt: runner.lastSeenAt, online: runner.revokedAt === void 0 && now - runner.lastSeenAt < MAX.heartbeatLiveMs };
+  if (runner.revokedAt !== void 0) pub.revokedAt = runner.revokedAt;
+  return pub;
+};
+class InvalidDocument extends Error {
+}
+function invalid(what) {
+  throw new InvalidDocument(what);
+}
+function fields(v, allowed, what) {
+  if (!object(v)) invalid(`${what} is not an object`);
+  const extra = Object.keys(v).find((key) => !allowed.includes(key));
+  if (extra !== void 0) invalid(`${what} has an unknown field ${JSON.stringify(extra.slice(0, 40))}`);
+  return v;
+}
+function time(v, what) {
+  if (!integer(v)) invalid(`${what} is not a time`);
+  return v;
+}
+function matching(v, pattern, what) {
+  if (typeof v !== "string" || !pattern.test(v) || UNSAFE_KEYS.includes(v)) invalid(`${what} has an unexpected format`);
+  return v;
+}
+function text(v, max, what, required = false) {
+  if (v === void 0 && !required) return "";
+  try {
+    return validateText(v, max, what, { required });
+  } catch (error) {
+    return invalid(error instanceof Error ? error.message : String(error));
+  }
+}
+function oneOf(v, values, what) {
+  if (typeof v !== "string" || !values.includes(v)) invalid(`${what} is not one of ${values.join(", ")}`);
+  return v;
+}
+function list(v, max, what) {
+  if (!Array.isArray(v) || v.length > max) invalid(`${what} is not a list of at most ${max} entries`);
+  return v;
+}
+function who(v, what) {
+  const w = fields(v, ["userId", "displayName", "via"], what);
+  matching(w.userId, PATH_ID, `${what} user id`);
+  text(w.displayName, MAX.displayName, `${what} display name`, true);
+  if (w.via !== void 0) oneOf(w.via, ["browser", "runner", "local"], `${what} via`);
+  return w;
+}
+function model(what, run) {
+  try {
+    return run();
+  } catch (error) {
+    return invalid(`${what}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+const runnerIdOk = (v) => v === RUNNER_LOCAL || typeof v === "string" && RUNNER_ID.test(v);
+const TASK_KEYS = ["id", "projectId", "repository", "title", "goal", "acceptance", "status", "blocker", "owner", "collaborators", "reviewer", "dependsOn", "baseRef", "labels", "revision", "createdAt", "updatedAt", "createdBy", "attempts", "checkpoints", "decisions", "discussion", "instructions", "reviews", "handoff", "handoffs", "audit"];
+const ATTEMPT_KEYS = ["id", "taskId", "runnerId", "runnerName", "user", "state", "runId", "baseCommit", "fromCheckpointId", "branch", "head", "createdAt", "startedAt", "endedAt", "lastSeq", "lastHeartbeatAt", "progress", "checkpointId", "reason"];
+const CHECKPOINT_KEYS = ["id", "taskId", "attemptId", "commit", "baseCommit", "branch", "size", "sha256", "ref", "createdBy", "at", "note", "requirements", "decisions", "testResults", "remaining", "changedFiles", "bundle"];
+function validateAttemptRecord(v, taskId) {
+  const a = fields(v, ATTEMPT_KEYS, "attempt");
+  matching(a.id, ATTEMPT_ID, "attempt id");
+  if (a.taskId !== taskId) invalid("attempt task id does not match its task");
+  if (!runnerIdOk(a.runnerId)) invalid("attempt runner id has an unexpected format");
+  text(a.runnerName, MAX.runnerName, "runner name", true);
+  who(a.user, "attempt user");
+  oneOf(a.state, ATTEMPT_STATES, "attempt state");
+  if (a.runId !== void 0) matching(a.runId, PATH_ID, "attempt run id");
+  matching(a.baseCommit, COMMIT_ID, "attempt base commit");
+  if (a.fromCheckpointId !== void 0) matching(a.fromCheckpointId, CHECKPOINT_ID, "attempt checkpoint id");
+  if (a.branch !== void 0) text(a.branch, MAX.branch, "attempt branch", true);
+  if (a.head !== void 0) matching(a.head, COMMIT_ID, "attempt head");
+  time(a.createdAt, "attempt createdAt");
+  if (a.startedAt !== void 0) time(a.startedAt, "attempt startedAt");
+  if (a.endedAt !== void 0) time(a.endedAt, "attempt endedAt");
+  if (!integer(a.lastSeq)) invalid("attempt lastSeq is not a count");
+  time(a.lastHeartbeatAt, "attempt heartbeat");
+  model("attempt progress", () => validateProgress(a.progress));
+  if (!object(a.progress) || !integer(a.progress.updatedAt)) invalid("attempt progress has no update time");
+  if (a.checkpointId !== void 0) matching(a.checkpointId, CHECKPOINT_ID, "attempt checkpoint");
+  if (a.reason !== void 0) text(a.reason, MAX.reason, "attempt reason");
+  return a;
+}
+function validateCheckpointRecord(v, taskId) {
+  const c = fields(v, CHECKPOINT_KEYS, "checkpoint"), id = matching(c.id, CHECKPOINT_ID, "checkpoint id");
+  if (c.taskId !== taskId) invalid("checkpoint task id does not match its task");
+  matching(c.attemptId, ATTEMPT_ID, "checkpoint attempt id");
+  model("checkpoint manifest", () => validateCheckpointInput({ commit: c.commit, baseCommit: c.baseCommit, branch: c.branch, size: c.size, sha256: c.sha256, note: c.note, requirements: c.requirements, decisions: c.decisions, testResults: c.testResults, remaining: c.remaining, changedFiles: c.changedFiles }));
+  if (c.ref !== `refs/codeflow/team/${id}`) invalid("checkpoint ref does not match its id");
+  who(c.createdBy, "checkpoint creator");
+  time(c.at, "checkpoint time");
+  oneOf(c.bundle, ["pending", "available", "deleted"], "checkpoint bundle state");
+  return c;
+}
+function validateEntryRecord(v, kind) {
+  switch (kind) {
+    case "comment": {
+      const e = fields(v, ["id", "by", "text", "mentions", "at", "kind"], "comment");
+      matching(e.id, PREFIXED_ID, "comment id");
+      who(e.by, "comment author");
+      text(e.text, MAX.text, "comment", true);
+      for (const m of list(e.mentions, 200, "comment mentions")) matching(m, PATH_ID, "mention");
+      time(e.at, "comment time");
+      oneOf(e.kind, ["comment", "review-request", "system"], "comment kind");
+      return;
+    }
+    case "decision": {
+      const e = fields(v, ["id", "by", "text", "at"], "decision");
+      matching(e.id, PREFIXED_ID, "decision id");
+      who(e.by, "decision author");
+      text(e.text, MAX.decision, "decision", true);
+      time(e.at, "decision time");
+      return;
+    }
+    case "instruction": {
+      const e = fields(v, ["id", "by", "text", "at", "state", "decidedBy", "decidedAt", "attemptId"], "instruction");
+      matching(e.id, PREFIXED_ID, "instruction id");
+      who(e.by, "instruction author");
+      text(e.text, MAX.text, "instruction", true);
+      time(e.at, "instruction time");
+      oneOf(e.state, ["proposed", "approved", "declined", "delivered"], "instruction state");
+      if (e.decidedBy !== void 0) who(e.decidedBy, "instruction decider");
+      if (e.decidedAt !== void 0) time(e.decidedAt, "instruction decision time");
+      if (e.attemptId !== void 0) matching(e.attemptId, ATTEMPT_ID, "instruction attempt");
+      return;
+    }
+    case "review": {
+      const e = fields(v, ["id", "checkpointId", "commit", "by", "verdict", "text", "at", "stale"], "review");
+      matching(e.id, PREFIXED_ID, "review id");
+      matching(e.checkpointId, CHECKPOINT_ID, "review checkpoint");
+      matching(e.commit, COMMIT_ID, "review commit");
+      who(e.by, "reviewer");
+      oneOf(e.verdict, ["approve", "request-changes"], "review verdict");
+      text(e.text, MAX.text, "review");
+      time(e.at, "review time");
+      if (typeof e.stale !== "boolean") invalid("review stale flag");
+      return;
+    }
+    case "handoff": {
+      const e = fields(v, ["id", "from", "to", "checkpointId", "note", "state", "offeredAt", "respondedAt", "reason"], "hand-over");
+      matching(e.id, PREFIXED_ID, "hand-over id");
+      who(e.from, "hand-over sender");
+      who(e.to, "hand-over recipient");
+      matching(e.checkpointId, CHECKPOINT_ID, "hand-over checkpoint");
+      text(e.note, MAX.note, "hand-over note");
+      oneOf(e.state, ["offered", "accepted", "declined", "cancelled"], "hand-over state");
+      time(e.offeredAt, "hand-over time");
+      if (e.respondedAt !== void 0) time(e.respondedAt, "hand-over response time");
+      if (e.reason !== void 0) text(e.reason, MAX.reason, "hand-over reason");
+      return;
+    }
+    case "audit": {
+      const e = fields(v, ["at", "by", "action", "detail"], "audit entry");
+      time(e.at, "audit time");
+      who(e.by, "audit actor");
+      text(e.action, MAX.auditAction, "audit action", true);
+      if (e.detail !== void 0) text(e.detail, MAX.auditDetail, "audit detail");
+      return;
+    }
+  }
+}
+function validateTaskRecord(v) {
+  const t = fields(v, TASK_KEYS, "task"), id = matching(t.id, TASK_ID, "task id");
+  matching(t.projectId, PATH_ID, "task project id");
+  matching(t.repository, REPO_KEY, "task repository key");
+  text(t.title, MAX.title, "title", true);
+  text(t.goal, MAX.goal, "goal");
+  text(t.acceptance, MAX.acceptance, "acceptance criteria");
+  const status = oneOf(t.status, TASK_STATUSES, "task status");
+  if (t.blocker !== void 0) text(t.blocker, MAX.blocker, "blocker", true);
+  if (status === "blocked" && typeof t.blocker !== "string") invalid("blocked task has no blocker");
+  if (t.owner !== void 0) who(t.owner, "task owner");
+  for (const c of list(t.collaborators, MAX.collaborators, "collaborators")) who(c, "collaborator");
+  if (t.reviewer !== void 0) who(t.reviewer, "task reviewer");
+  for (const d of list(t.dependsOn, MAX.dependsOn, "dependencies")) matching(d, TASK_ID, "dependency");
+  if (t.baseRef !== void 0) text(t.baseRef, MAX.baseRef, "base branch", true);
+  for (const l of list(t.labels, MAX.labels, "labels")) text(l, MAX.label, "label", true);
+  if (!integer(t.revision) || t.revision < 1) invalid("task revision is not a positive count");
+  time(t.createdAt, "task createdAt");
+  time(t.updatedAt, "task updatedAt");
+  who(t.createdBy, "task creator");
+  const attempts = /* @__PURE__ */ new Set();
+  for (const a of list(t.attempts, MAX.attempts, "attempts")) {
+    const attempt = validateAttemptRecord(a, id);
+    if (attempts.has(attempt.id)) invalid(`duplicate attempt ${attempt.id}`);
+    attempts.add(attempt.id);
+  }
+  const checkpoints = /* @__PURE__ */ new Set();
+  for (const c of list(t.checkpoints, MAX.checkpoints, "checkpoints")) {
+    const checkpoint = validateCheckpointRecord(c, id);
+    if (checkpoints.has(checkpoint.id)) invalid(`duplicate checkpoint ${checkpoint.id}`);
+    checkpoints.add(checkpoint.id);
+  }
+  for (const e of list(t.decisions, MAX.decisions, "decisions")) validateEntryRecord(e, "decision");
+  for (const e of list(t.discussion, MAX.discussion, "discussion")) validateEntryRecord(e, "comment");
+  for (const e of list(t.instructions, MAX.instructions, "instructions")) validateEntryRecord(e, "instruction");
+  for (const e of list(t.reviews, MAX.reviews, "reviews")) validateEntryRecord(e, "review");
+  if (t.handoff !== void 0) validateEntryRecord(t.handoff, "handoff");
+  for (const e of list(t.handoffs, MAX.handoffs, "hand-over history")) validateEntryRecord(e, "handoff");
+  for (const e of list(t.audit, MAX.audit, "audit")) validateEntryRecord(e, "audit");
+  return t;
+}
+function validateBoardDocument(raw, trusted) {
+  const d = fields(raw, ["version", "revision", "ownerName", "projects", "tasks"], "board");
+  if (d.version !== 1) invalid("board version is not 1");
+  if (!integer(d.revision)) invalid("board revision is not a count");
+  if (d.ownerName !== void 0) text(d.ownerName, MAX.displayName, "owner name", true);
+  if (!object(d.projects)) invalid("board projects is not a map");
+  for (const [projectId, entry] of Object.entries(d.projects)) {
+    matching(projectId, PATH_ID, "project id");
+    const p = fields(entry, ["repositories"], `project ${projectId}`);
+    model(`project ${projectId} repositories`, () => validateRepoRefs(p.repositories));
+  }
+  const ids = /* @__PURE__ */ new Set(), attempts = /* @__PURE__ */ new Set(), checkpoints = /* @__PURE__ */ new Set();
+  for (const entry of list(d.tasks, MAX.tasks, "tasks")) {
+    const task = trusted?.has(entry) ? entry : validateTaskRecord(entry);
+    trusted?.add(task);
+    if (ids.has(task.id)) invalid(`duplicate task ${task.id}`);
+    ids.add(task.id);
+    for (const a of task.attempts) {
+      if (attempts.has(a.id)) invalid(`attempt ${a.id} appears in two tasks`);
+      attempts.add(a.id);
+    }
+    for (const c of task.checkpoints) {
+      if (checkpoints.has(c.id)) invalid(`checkpoint ${c.id} appears in two tasks`);
+      checkpoints.add(c.id);
+    }
+  }
+  return d;
+}
+function validateRunnersDocument(raw) {
+  const d = fields(raw, ["version", "runners"], "runners");
+  if (d.version !== 1) invalid("runners version is not 1");
+  const ids = /* @__PURE__ */ new Set(), hashes = /* @__PURE__ */ new Set();
+  for (const entry of list(d.runners, MAX.runners, "runners")) {
+    const r = fields(entry, ["id", "userId", "name", "tokenHash", "createdAt", "lastSeenAt", "revokedAt", "lastAddress"], "runner"), id = matching(r.id, RUNNER_ID, "runner id"), hash = matching(r.tokenHash, SHA256_HEX, "runner token hash");
+    matching(r.userId, PATH_ID, "runner account");
+    text(r.name, MAX.runnerName, "runner name", true);
+    time(r.createdAt, "runner createdAt");
+    time(r.lastSeenAt, "runner lastSeenAt");
+    if (r.revokedAt !== void 0) time(r.revokedAt, "runner revokedAt");
+    if (r.lastAddress !== void 0) text(r.lastAddress, 128, "runner address");
+    if (ids.has(id) || hashes.has(hash)) invalid(`duplicate runner ${id}`);
+    ids.add(id);
+    hashes.add(hash);
+  }
+  return d;
+}
+function validateInboxDocument(raw) {
+  const d = fields(raw, ["version", "items"], "inbox");
+  if (d.version !== 1) invalid("inbox version is not 1");
+  const ids = /* @__PURE__ */ new Set();
+  for (const entry of list(d.items, MAX.inboxTotal, "inbox items")) {
+    const i = fields(entry, ["id", "userId", "kind", "taskId", "taskTitle", "text", "by", "at", "readAt"], "inbox item"), id = matching(i.id, PREFIXED_ID, "inbox item id");
+    matching(i.userId, PATH_ID, "inbox account");
+    oneOf(i.kind, INBOX_KINDS, "inbox kind");
+    matching(i.taskId, TASK_ID, "inbox task");
+    text(i.taskTitle, MAX.title, "inbox task title", true);
+    text(i.text, MAX.inboxText, "inbox text");
+    who(i.by, "inbox actor");
+    time(i.at, "inbox time");
+    if (i.readAt !== void 0) time(i.readAt, "inbox read time");
+    if (ids.has(id)) invalid(`duplicate inbox item ${id}`);
+    ids.add(id);
+  }
+  return d;
+}
+const emptyBoard = () => ({ version: 1, revision: 0, projects: {}, tasks: [] }), emptyRunners = () => ({ version: 1, runners: [] }), emptyInbox = () => ({ version: 1, items: [] });
+async function readDocument(file) {
+  let body;
+  try {
+    const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const info = await handle.stat();
+      if (!info.isFile()) throw new Error(`${file} is not a regular file`);
+      if (info.size > READ_LIMIT) throw new Error(`${file} exceeds the 16 MiB limit`);
+      body = await handle.readFile("utf8");
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+  try {
+    return JSON.parse(body);
+  } catch (error) {
+    throw new InvalidDocument(`not valid JSON (${error.message})`);
+  }
+}
+class CollabStore {
+  constructor(options) {
+    this.options = options;
+    this.dir = options.dir ?? join(CODEFLOW_HOME, "team");
+    this.bundleDir = join(this.dir, "checkpoints");
+    this.random = options.random ?? randomBytes;
+    this.now = options.now ?? Date.now;
+    this.epoch = this.random(8).toString("hex");
+  }
+  dir;
+  bundleDir;
+  state = { board: emptyBoard(), runners: emptyRunners(), inbox: emptyInbox() };
+  loaded = false;
+  loading;
+  readable = true;
+  queue = Promise.resolve();
+  listeners = /* @__PURE__ */ new Set();
+  ring = [];
+  seq = 0;
+  /** Random per process: a client whose cursor names another epoch gets a resync instead of a replay from the wrong ring. */
+  epoch;
+  /** Write-behind state: runner lastSeen touches and board telemetry wait for the next durable change or the flush timer. */
+  runnersDirty = false;
+  boardPending = false;
+  flushTimer;
+  /** Task objects validateBoardDocument has passed, so a write re-validates only the tasks the mutation cloned. */
+  validated = /* @__PURE__ */ new WeakSet();
+  /** Documents that did not load as written (set aside or unreadable); a bundle sweep never trusts a board that was. */
+  degraded = /* @__PURE__ */ new Set();
+  random;
+  now;
+  get available() {
+    return this.loaded && this.readable;
+  }
+  /** The hub owner's display name as teammates see it: the saved profile, else what the server passes, else "Owner". */
+  get ownerName() {
+    return this.state.board.ownerName ?? this.options.ownerName?.() ?? "Owner";
+  }
+  load() {
+    return this.loading ??= (async () => {
+      try {
+        await mkdir(this.bundleDir, { recursive: true, mode: 448 });
+      } catch (error) {
+        this.readable = false;
+        logError(`Couldn't create ${this.dir}; the team board is unavailable until it can be created`, error);
+      }
+      const board = await this.loadDocument("board.json", (raw) => validateBoardDocument(raw, this.validated), emptyBoard), runners = await this.loadDocument("runners.json", validateRunnersDocument, emptyRunners), inbox = await this.loadDocument("inbox.json", validateInboxDocument, emptyInbox);
+      this.state = { board, runners, inbox };
+      this.loaded = true;
+      if (this.readable) await this.sweepBundles(board, !this.degraded.has("board.json"));
+    })();
+  }
+  /** Removes what an upload interrupted by a crash, or a crash between a board write and its cleanup, left in `checkpoints/`: temp files always, and bundle files no available checkpoint names only when board.json itself loaded, since a board set aside as corrupt may be repaired and still name them. Runs once, at load, when no upload is in flight. */
+  async sweepBundles(board, unreferenced) {
+    const wanted = /* @__PURE__ */ new Set();
+    for (const task of board.tasks) for (const checkpoint of task.checkpoints) if (checkpoint.bundle === "available") wanted.add(`${checkpoint.id}.bundle`);
+    let names;
+    try {
+      names = await readdir(this.bundleDir);
+    } catch (error) {
+      logError(`The checkpoint folder ${this.bundleDir} could not be listed for cleanup`, error);
+      return;
+    }
+    const stale = names.filter((name) => /^[a-f0-9]{32}\.bundle\.[a-f0-9]{12}\.tmp$/.test(name) || unreferenced && /^[a-f0-9]{32}\.bundle$/.test(name) && !wanted.has(name));
+    for (const name of stale) await rm(join(this.bundleDir, name), { force: true }).catch((error) => logError(`Stale checkpoint file ${name} could not be removed from ${this.bundleDir}`, error));
+    if (stale.length) logWarn(`Removed ${stale.length} stale checkpoint file(s) left in ${this.bundleDir} by an interrupted upload or cleanup`);
+  }
+  /** Persists pending telemetry and runner lastSeen touches and stops the write-behind timer; nothing else is held open. */
+  async close() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = void 0;
+    }
+    if ((this.runnersDirty || this.boardPending) && this.available) await this.change(() => void 0).catch(() => void 0);
+  }
+  /** Arms the 30 s write-behind once; a durable change in the meantime carries the pending documents along and the timer finds nothing to do. */
+  armFlush() {
+    this.flushTimer ??= setTimeout(() => {
+      this.flushTimer = void 0;
+      if ((this.runnersDirty || this.boardPending) && this.available) this.change(() => void 0).catch(() => void 0);
+    }, FLUSH_MS);
+    this.flushTimer.unref?.();
+  }
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** Replays the ring after `<epoch>:<seq>`; a cursor from another process or older than the ring asks the client to reload instead of missing changes silently. */
+  eventsSince(cursor) {
+    const page = { epoch: this.epoch, seq: this.seq, events: [], resync: false };
+    if (cursor === void 0 || cursor === "") return page;
+    const match = /^([a-f0-9]{16}):(\d{1,15})$/.exec(cursor);
+    if (!match || match[1] !== this.epoch) return { ...page, resync: true };
+    const after = Number(match[2]), first = this.ring[0];
+    if (after > this.seq || after < this.seq && (!first || first.seq > after + 1)) return { ...page, resync: true };
+    page.events = this.ring.filter((event) => event.seq > after);
+    return page;
+  }
+  // ---- Reads
+  async board(actor, projectId) {
+    await this.load();
+    this.require();
+    const now = this.now(), { board, inbox, runners } = this.state;
+    let projects = this.options.projects().filter((project) => actorRole(actor, project.id) !== void 0);
+    if (projectId !== void 0) {
+      const one = projects.find((project) => project.id === projectId);
+      if (!one) throw new CollabError("Project not found", 404);
+      projects = [one];
+    }
+    const visible = new Set(projects.map((project) => project.id)), mentions = /* @__PURE__ */ new Map();
+    let inboxUnread = 0;
+    for (const item of this.visibleInbox(board, inbox, actor)) if (item.readAt === void 0) {
+      inboxUnread++;
+      if (item.kind === "mention") mentions.set(item.taskId, (mentions.get(item.taskId) ?? 0) + 1);
+    }
+    const online = this.onlineUsers(now), roles = actor.kind === "owner" ? Object.fromEntries(this.options.projects().map((project) => [project.id, "maintainer"])) : { ...actor.roles };
+    const me = { ...whoOf(actor), roles, runners: runners.runners.filter((runner) => runner.userId === actor.userId).map((runner) => runnerPublic(runner, now)) };
+    return { revision: board.revision, projects: projects.map((project) => this.projectView(board, project, actor, online)), tasks: board.tasks.filter((task) => visible.has(task.projectId)).map((task) => summarize(task, actor.userId, now, mentions.get(task.id) ?? 0)), me, inboxUnread };
+  }
+  async task(actor, id) {
+    await this.load();
+    this.require();
+    return clone(this.findTask(this.state.board, actor, id));
+  }
+  async inbox(actor, after) {
+    await this.load();
+    this.require();
+    const since = after === void 0 || after === null || after === "" ? void 0 : Number(after);
+    if (since !== void 0 && !Number.isSafeInteger(since)) throw new CollabError("Send after as a Unix time in milliseconds");
+    const mine = this.visibleInbox(this.state.board, this.state.inbox, actor);
+    return { items: clone(mine.filter((item) => since === void 0 || item.at > since).reverse()), unread: mine.filter((item) => item.readAt === void 0).length };
+  }
+  /** Runners are account-wide: only the hub owner may see or revoke another account's runners. */
+  async runners(actor) {
+    await this.load();
+    this.require();
+    const now = this.now(), all = this.seesAllRunners(actor);
+    return this.state.runners.runners.filter((runner) => all || runner.userId === actor.userId).map((runner) => runnerPublic(runner, now));
+  }
+  /** Constant-time against every stored hash; a revoked runner or a disabled account is refused. lastSeenAt moves at most every 10 s and reaches disk with the next mutation or the 30 s write-behind, so a heartbeat storm never turns into an fsync storm. */
+  authenticateRunner(token) {
+    if (!this.available || typeof token !== "string" || !RUNNER_TOKEN.test(token)) return void 0;
+    const hash = Buffer.from(sha256Hex(token), "hex");
+    let match;
+    for (const runner of this.state.runners.runners) {
+      const stored = Buffer.from(runner.tokenHash, "hex");
+      if (stored.length === hash.length && timingSafeEqual(stored, hash) && !match) match = runner;
+    }
+    if (!match || match.revokedAt !== void 0) return void 0;
+    const userId = match.userId;
+    const member = this.options.members().find((entry) => entry.userId === userId);
+    if (!member?.enabled) return void 0;
+    const now = this.now();
+    if (now - match.lastSeenAt >= TOUCH_MS) {
+      match.lastSeenAt = now;
+      this.runnersDirty = true;
+      this.armFlush();
+    }
+    return { runnerId: match.id, userId };
+  }
+  // ---- Shared helpers
+  require() {
+    if (!this.loaded) throw new CollabError("Team storage has not finished loading; retry in a moment", 503);
+    if (!this.readable) throw new CollabError(`Team storage is unavailable; repair the files in ${this.dir} (see server.log), then restart code-flow`, 503);
+  }
+  bundleFile(checkpointId) {
+    return join(this.bundleDir, `${checkpointId}.bundle`);
+  }
+  onlineUsers(now) {
+    const online = /* @__PURE__ */ new Set();
+    for (const runner of this.state.runners.runners) if (runner.revokedAt === void 0 && now - runner.lastSeenAt < MAX.heartbeatLiveMs) online.add(runner.userId);
+    return online;
+  }
+  seesAllRunners(actor) {
+    return actor.kind === "owner";
+  }
+  visibleInbox(board, inbox, actor) {
+    const projects = new Set(this.options.projects().filter((project) => actorRole(actor, project.id) !== void 0).map((project) => project.id));
+    const tasks = new Set(board.tasks.filter((task) => projects.has(task.projectId)).map((task) => task.id));
+    return inbox.items.filter((item) => item.userId === actor.userId && tasks.has(item.taskId));
+  }
+  projectView(board, project, actor, online) {
+    const members = [{ userId: "owner", username: "owner", displayName: this.ownerName, role: "maintainer", online: true }];
+    for (const member of this.membersOf(project.id)) members.push({ userId: member.userId, username: member.username, displayName: member.displayName, role: member.roles[project.id], online: online.has(member.userId) });
+    return { id: project.id, name: project.name, role: actorRole(actor, project.id), repositories: clone(Object.hasOwn(board.projects, project.id) ? board.projects[project.id].repositories : []), members };
+  }
+  membersOf(projectId) {
+    return this.options.members().filter((member) => member.enabled && Object.hasOwn(member.roles, projectId) && member.roles[projectId] !== void 0);
+  }
+  /** `@owner` reaches the person running the hub first, then members by username (model.mentionsIn keeps the first listed on a clash). */
+  mentionTargets(projectId) {
+    return [{ userId: "owner", username: "owner" }, ...this.membersOf(projectId).map((member) => ({ userId: member.userId, username: member.username }))];
+  }
+  /** Unknown ids and ids in projects where the actor holds no role are the same 404, so a task id never confirms existence. */
+  findTask(board, actor, id) {
+    const task = typeof id === "string" && TASK_ID.test(id) ? board.tasks.find((entry) => entry.id === id) : void 0;
+    if (!task || actorRole(actor, task.projectId) === void 0) throw new CollabError("Task not found", 404);
+    return task;
+  }
+  findAttempt(board, actor, id) {
+    const found = this.attemptById(board, id);
+    if (!found || actorRole(actor, found.task.projectId) === void 0) throw new CollabError("Attempt not found", 404);
+    return found;
+  }
+  attemptById(board, id) {
+    if (typeof id !== "string" || !ATTEMPT_ID.test(id)) return void 0;
+    for (const task of board.tasks) {
+      const attempt = task.attempts.find((entry) => entry.id === id);
+      if (attempt) return { task, attempt };
+    }
+    return void 0;
+  }
+  findCheckpoint(board, actor, id) {
+    if (typeof id === "string" && CHECKPOINT_ID.test(id)) for (const task of board.tasks) {
+      const checkpoint = task.checkpoints.find((entry) => entry.id === id);
+      if (checkpoint && actorRole(actor, task.projectId) !== void 0) {
+        const attempt = task.attempts.find((entry) => entry.id === checkpoint.attemptId);
+        if (attempt) return { task, checkpoint, attempt };
+      }
+    }
+    throw new CollabError("Checkpoint not found", 404);
+  }
+  project(projectId, actor) {
+    const project = typeof projectId === "string" ? this.options.projects().find((entry) => entry.id === projectId) : void 0;
+    if (!project || actorRole(actor, project.id) === void 0) throw new CollabError("Project not found", 404);
+    return project;
+  }
+  need(actor, projectId, role, action) {
+    const held = actorRole(actor, projectId);
+    if (!roleAtLeast(held, role)) throw new CollabError(`A project ${role} role is required to ${action}`, 403);
+    return held;
+  }
+  /** Progress, heartbeats, finishes and checkpoints come only from the machine executing the attempt: the owner process for "local" attempts, otherwise the very runner credential the attempt was claimed with, used by the same account. */
+  assertAttemptRunner(attempt, actor) {
+    const ok = actor.kind === "owner" ? attempt.runnerId === RUNNER_LOCAL && attempt.user.userId === "owner" : actor.via === "runner" && actor.runnerId !== void 0 && actor.runnerId === attempt.runnerId && actor.userId === attempt.user.userId;
+    if (!ok) throw new CollabError("Only the runner executing this attempt may report on it", 403);
+  }
+  cas(task, revision) {
+    if (revision === void 0 || revision === null) throw new CollabError("Send the task's current revision with the change");
+    if (!integer(revision) || revision !== task.revision) throw new CollabError("Task changed; reload before saving", 409);
+  }
+  resolveWho(projectId, userId, minRole, label) {
+    const id = validateUserRef(userId, label);
+    if (id === "owner") return { userId: "owner", displayName: this.ownerName };
+    const member = this.options.members().find((entry) => entry.userId === id);
+    if (!member || !member.enabled || !Object.hasOwn(member.roles, projectId)) throw new CollabError(`Choose the ${label} from the project's members`);
+    if (!roleAtLeast(member.roles[projectId], minRole)) throw new CollabError(`The ${label} needs at least the ${minRole} role in this project`);
+    return { userId: member.userId, displayName: member.displayName };
+  }
+  assertRepository(board, projectId, key) {
+    const repositories = Object.hasOwn(board.projects, projectId) ? board.projects[projectId].repositories : [];
+    if (!repositories.some((repo) => repo.key === key)) throw new CollabError(repositories.length ? `Choose the repository from this project's keys: ${repositories.map((repo) => repo.key).join(", ")}` : "Define this project's repository keys in People first");
+  }
+  dependencies(board, projectId, ids, self) {
+    for (const id of ids) if (id === self || !board.tasks.some((task) => task.id === id && task.projectId === projectId)) throw new CollabError("Choose the tasks this one depends on from the board");
+    return ids;
+  }
+  stakeholders(task) {
+    const ids = task.collaborators.map((who2) => who2.userId);
+    if (task.owner) ids.unshift(task.owner.userId);
+    if (task.reviewer) ids.push(task.reviewer.userId);
+    return ids;
+  }
+  /** Every change to a task bumps the task and board revisions and leaves an audit line; progress and heartbeats bypass this on purpose. */
+  commit(draft, task, by, action, detail, now) {
+    task.revision++;
+    task.updatedAt = now;
+    recordAudit(task, by, action, detail, now);
+    draft.board.revision++;
+    draft.dirty.add("board");
+    draft.events.push({ kind: "task", taskId: task.id, projectId: task.projectId });
+  }
+  /** A system line in the discussion; skipped rather than failing the mutation when the discussion is full. */
+  system(task, by, text2, now, kind = "system") {
+    if (task.discussion.length < MAX.discussion) task.discussion.push({ id: newId("comment", this.random), by, text: text2, mentions: [], at: now, kind });
+  }
+  /** Inbox items for everyone named except the actor; each user keeps at most 500 (oldest read first), the hub at most 5000. */
+  notify(draft, task, actor, userIds, kind, text2) {
+    if (!this.options.projects().some((project) => project.id === task.projectId)) return;
+    const members = /* @__PURE__ */ new Set(["owner", ...this.membersOf(task.projectId).map((member) => member.userId)]);
+    const targets = new Set([...userIds].filter((id) => members.has(id)));
+    targets.delete(actor.userId);
+    if (!targets.size) return;
+    const now = this.now(), items = draft.inbox.items;
+    for (const userId of targets) {
+      items.push({ id: newId("inbox", this.random), userId, kind, taskId: task.id, taskTitle: task.title, text: truncateText(text2, MAX.inboxText), by: whoOf(actor), at: now });
+      const mine = items.filter((item) => item.userId === userId);
+      while (mine.length > MAX.inboxPerUser) {
+        const victim = mine.find((item) => item.readAt !== void 0) ?? mine[0];
+        items.splice(items.indexOf(victim), 1);
+        mine.splice(mine.indexOf(victim), 1);
+      }
+    }
+    while (items.length > MAX.inboxTotal) {
+      const victim = items.find((item) => item.readAt !== void 0) ?? items[0];
+      items.splice(items.indexOf(victim), 1);
+    }
+    draft.dirty.add("inbox");
+    draft.events.push({ kind: "inbox", userIds: [...targets] });
+  }
+  // ---- Persistence
+  async loadDocument(name, validate, empty) {
+    const file = join(this.dir, name);
+    let raw;
+    try {
+      raw = await readDocument(file);
+    } catch (error) {
+      this.degraded.add(name);
+      if (error instanceof InvalidDocument) return this.setAside(file, error.message, empty);
+      this.readable = false;
+      logError(`Couldn't read ${file}; the team board is unavailable and the file is left untouched until it can be read`, error);
+      return empty();
+    }
+    if (raw === void 0) return empty();
+    try {
+      return validate(raw);
+    } catch (error) {
+      this.degraded.add(name);
+      return this.setAside(file, error instanceof Error ? error.message : String(error), empty);
+    }
+  }
+  async setAside(file, why, empty) {
+    const aside = `${file}.corrupt-${new Date(this.now()).toISOString().replace(/[:.]/g, "-")}`;
+    try {
+      await rename(file, aside);
+      logError(`${file} is unusable (${why}): moved it to ${aside}; the team board starts without it`);
+    } catch (error) {
+      this.readable = false;
+      logError(`${file} is unusable (${why}) and couldn't be moved aside; the team board is unavailable until it's fixed`, error);
+    }
+    return empty();
+  }
+  serialize(document, validate, name) {
+    try {
+      validate(document);
+    } catch (error) {
+      throw new CollabError(`Team storage refused to write an inconsistent ${name} document: ${error instanceof Error ? error.message : String(error)}`, 500);
+    }
+    const body = JSON.stringify(document);
+    if (Buffer.byteLength(body) > READ_LIMIT) throw new CollabError(`The team ${name} has reached its 16 MiB storage limit; delete finished tasks first`, 413);
+    return body;
+  }
+  async writeDocument(name, body) {
+    const file = join(this.dir, name);
+    try {
+      const info = await lstat(file);
+      if (!info.isFile()) throw new CollabError(`Refusing to replace ${file}: it is not a regular file`, 503);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    const temp = `${file}.${this.random(8).toString("hex")}.tmp`;
+    try {
+      const handle = await open(temp, "wx", 384);
+      try {
+        await handle.writeFile(body);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temp, file);
+      await chmod(file, 384);
+      if (process.platform !== "win32") {
+        const dir = await open(this.dir, "r");
+        try {
+          await dir.sync();
+        } finally {
+          await dir.close();
+        }
+      }
+    } finally {
+      await rm(temp, { force: true }).catch(() => {
+      });
+    }
+  }
+  draft() {
+    const state = this.state, cloned = /* @__PURE__ */ new Map();
+    let runners, inbox;
+    const draft = {
+      board: { ...state.board, projects: { ...state.board.projects }, tasks: [...state.board.tasks] },
+      dirty: /* @__PURE__ */ new Set(),
+      events: [],
+      after: [],
+      undo: [],
+      get runners() {
+        return runners ??= clone(state.runners);
+      },
+      get inbox() {
+        return inbox ??= clone(state.inbox);
+      },
+      task(id, dirty = "board") {
+        let task = cloned.get(id);
+        if (!task) {
+          const index = draft.board.tasks.findIndex((entry) => entry.id === id);
+          if (index < 0) return void 0;
+          task = clone(draft.board.tasks[index]);
+          draft.board.tasks[index] = task;
+          cloned.set(id, task);
+        }
+        draft.dirty.add(dirty);
+        return task;
+      },
+      snapshot: () => ({ board: draft.board, runners: runners ?? state.runners, inbox: inbox ?? state.inbox })
+    };
+    return draft;
+  }
+  /** The one mutation queue: apply to a draft, validate, write the touched documents (board last, as the commit point), swap, then announce. A failed write leaves memory and the announced state untouched. A mutation that touched telemetry alone skips the write: it is swapped in and announced, and the board is flagged for the next durable change or the write-behind timer. */
+  change(fn) {
+    const run = this.queue.catch(() => void 0).then(async () => {
+      await this.load();
+      this.require();
+      const draft = this.draft();
+      const result = await fn(draft);
+      if (draft.dirty.has("telemetry") && draft.dirty.size === 1) {
+        this.state = draft.snapshot();
+        this.boardPending = true;
+        this.armFlush();
+        this.announce(draft);
+        return result;
+      }
+      if (this.runnersDirty) draft.dirty.add("runners");
+      if (this.boardPending || draft.dirty.delete("telemetry")) draft.dirty.add("board");
+      if (draft.dirty.size) {
+        const bodies = [];
+        if (draft.dirty.has("runners")) bodies.push(["runners.json", this.serialize(draft.runners, validateRunnersDocument, "runners")]);
+        if (draft.dirty.has("inbox")) bodies.push(["inbox.json", this.serialize(draft.inbox, validateInboxDocument, "inbox")]);
+        if (draft.dirty.has("board")) bodies.push(["board.json", this.serialize(draft.board, (raw) => validateBoardDocument(raw, this.validated), "board")]);
+        try {
+          for (const [name, body] of bodies) await this.writeDocument(name, body);
+        } catch (error) {
+          for (const undo of draft.undo) await undo().catch(() => void 0);
+          throw error instanceof CollabError ? error : new CollabError(`Team storage could not be written: ${error instanceof Error ? error.message : String(error)}`, 503);
+        }
+        this.state = draft.snapshot();
+        if (draft.dirty.has("runners")) this.runnersDirty = false;
+        if (draft.dirty.has("board")) this.boardPending = false;
+        this.announce(draft);
+        for (const task of draft.after) await task().catch((error) => logError("Team storage could not finish a cleanup after a durable change", error));
+      }
+      return result;
+    });
+    this.queue = run;
+    return run;
+  }
+  /** Each distinct event once, in order; listeners that throw cannot undo a durable change. */
+  announce(draft) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const event of draft.events) {
+      const key = JSON.stringify(event);
+      if (!seen.has(key)) {
+        seen.add(key);
+        this.emit(event);
+      }
+    }
+  }
+  /** Wake project-filtered team views after a durable host queue or policy change. */
+  hostExecutionChanged(projectId, taskId) {
+    if (projectId) this.emit({ kind: "task", projectId, taskId });
+    else for (const project of this.options.projects()) this.emit({ kind: "task", projectId: project.id });
+  }
+  emit(event) {
+    const full = { ...event, seq: ++this.seq };
+    this.ring.push(full);
+    if (this.ring.length > RING) this.ring.splice(0, this.ring.length - RING);
+    for (const listener of this.listeners) {
+      try {
+        listener(full);
+      } catch {
+      }
+    }
+  }
+  // ---- Tasks
+  async createTask(actor, input) {
+    const data = validateTaskInput(input);
+    return this.change((draft) => {
+      const now = this.now(), project = this.project(data.projectId, actor), by = whoOf(actor);
+      this.need(actor, project.id, "contributor", "create tasks");
+      this.assertRepository(draft.board, project.id, data.repository);
+      const task = { id: newTaskId(this.random), projectId: project.id, repository: data.repository, title: data.title, goal: data.goal, acceptance: data.acceptance, status: "planned", collaborators: data.collaborators.map((id) => this.resolveWho(project.id, id, "viewer", "collaborator")), dependsOn: this.dependencies(draft.board, project.id, data.dependsOn, void 0), labels: data.labels, revision: 1, createdAt: now, updatedAt: now, createdBy: by, attempts: [], checkpoints: [], decisions: [], discussion: [], instructions: [], reviews: [], handoffs: [], audit: [] };
+      if (data.baseRef) task.baseRef = data.baseRef;
+      if (data.reviewer) task.reviewer = this.resolveWho(project.id, data.reviewer, "reviewer", "reviewer");
+      if (data.owner) {
+        const owner = this.resolveWho(project.id, data.owner, "contributor", "owner");
+        assertCanChangeOwner(task, actor, owner);
+        assignOwner(task, owner, now);
+      }
+      if (data.status !== "planned") transition(task, data.status, actor, data.blocker, now);
+      recordAudit(task, by, "created", void 0, now);
+      pushBounded(draft.board.tasks, task, MAX.tasks, "tasks");
+      draft.board.revision++;
+      draft.dirty.add("board");
+      draft.events.push({ kind: "task", taskId: task.id, projectId: task.projectId }, { kind: "board", projectId: task.projectId });
+      if (task.owner) this.notify(draft, task, actor, [task.owner.userId], "assigned", `${actor.displayName} assigned you \u201C${task.title}\u201D`);
+      if (task.reviewer) this.notify(draft, task, actor, [task.reviewer.userId], "review-requested", `${actor.displayName} asked you to review \u201C${task.title}\u201D`);
+      if (task.status === "blocked") this.notify(draft, task, actor, this.stakeholders(task), "blocked", `\u201C${task.title}\u201D is blocked: ${task.blocker}`);
+      return clone(task);
+    });
+  }
+  /** A partial save under the owner rules (assertCanChangeOwner/assignOwner) and the status rules (transition); `null` clears an optional field. */
+  async updateTask(actor, id, patch, revision) {
+    const changes = validateTaskPatch(patch);
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, id);
+      this.need(actor, current.projectId, "contributor", "edit tasks");
+      this.cas(current, revision);
+      const task = draft.task(current.id), changed = [], before = { owner: task.owner?.userId, reviewer: task.reviewer?.userId, status: task.status };
+      if (changes.repository !== void 0 && changes.repository !== task.repository) {
+        this.assertRepository(draft.board, task.projectId, changes.repository);
+        task.repository = changes.repository;
+        changed.push("repository");
+      }
+      if (changes.title !== void 0 && changes.title !== task.title) {
+        task.title = changes.title;
+        changed.push("title");
+      }
+      if (changes.goal !== void 0 && changes.goal !== task.goal) {
+        task.goal = changes.goal;
+        changed.push("goal");
+      }
+      if (changes.acceptance !== void 0 && changes.acceptance !== task.acceptance) {
+        task.acceptance = changes.acceptance;
+        changed.push("acceptance");
+      }
+      if (changes.labels !== void 0) {
+        task.labels = changes.labels;
+        changed.push("labels");
+      }
+      if (changes.dependsOn !== void 0) {
+        task.dependsOn = this.dependencies(draft.board, task.projectId, changes.dependsOn, task.id);
+        changed.push("dependencies");
+      }
+      if (changes.baseRef !== void 0) {
+        if (changes.baseRef === null) delete task.baseRef;
+        else task.baseRef = changes.baseRef;
+        changed.push("base");
+      }
+      if (changes.collaborators !== void 0) {
+        task.collaborators = changes.collaborators.map((userId) => this.resolveWho(task.projectId, userId, "viewer", "collaborator"));
+        changed.push("collaborators");
+      }
+      if (changes.reviewer !== void 0) {
+        if (changes.reviewer === null) delete task.reviewer;
+        else task.reviewer = this.resolveWho(task.projectId, changes.reviewer, "reviewer", "reviewer");
+        changed.push("reviewer");
+      }
+      if (changes.owner !== void 0) {
+        const next = changes.owner === null ? void 0 : this.resolveWho(task.projectId, changes.owner, "contributor", "owner");
+        assertCanChangeOwner(task, actor, next);
+        assignOwner(task, next, now);
+        changed.push("owner");
+      }
+      if (changes.status !== void 0 || changes.blocker !== void 0) {
+        transition(task, changes.status ?? task.status, actor, changes.blocker, now);
+        changed.push(changes.status !== void 0 ? "status" : "blocker");
+      }
+      this.commit(draft, task, whoOf(actor), "updated", changed.join(", ") || void 0, now);
+      if (task.owner && task.owner.userId !== before.owner) this.notify(draft, task, actor, [task.owner.userId], "assigned", `${actor.displayName} assigned you \u201C${task.title}\u201D`);
+      if (task.reviewer && task.reviewer.userId !== before.reviewer) this.notify(draft, task, actor, [task.reviewer.userId], "review-requested", `${actor.displayName} asked you to review \u201C${task.title}\u201D`);
+      if (task.status === "blocked" && before.status !== "blocked") this.notify(draft, task, actor, this.stakeholders(task), "blocked", `\u201C${task.title}\u201D is blocked: ${task.blocker}`);
+      return clone(task);
+    });
+  }
+  async deleteTask(actor, id, revision) {
+    return this.change((draft) => {
+      const now = this.now(), task = this.findTask(draft.board, actor, id);
+      this.need(actor, task.projectId, "maintainer", "delete tasks");
+      this.cas(task, revision);
+      const busy = busyAttempt(task);
+      if (busy) throw new CollabError(`Stop the attempt running on ${busy.runnerName} before deleting the task`, 409);
+      draft.board.tasks = draft.board.tasks.filter((entry) => entry.id !== task.id);
+      draft.board.revision++;
+      draft.dirty.add("board");
+      draft.events.push({ kind: "task", taskId: task.id, projectId: task.projectId }, { kind: "board", projectId: task.projectId });
+      for (const other of draft.board.tasks) if (other.dependsOn.includes(task.id)) {
+        const dependent = draft.task(other.id);
+        dependent.dependsOn = dependent.dependsOn.filter((dep) => dep !== task.id);
+        this.commit(draft, dependent, whoOf(actor), "dependency-removed", task.title, now);
+      }
+      const affected = /* @__PURE__ */ new Set(), items = draft.inbox.items.filter((item) => {
+        if (item.taskId !== task.id) return true;
+        affected.add(item.userId);
+        return false;
+      });
+      if (affected.size) {
+        draft.inbox.items = items;
+        draft.dirty.add("inbox");
+        draft.events.push({ kind: "inbox", userIds: [...affected] });
+      }
+      const files = task.checkpoints.filter((checkpoint) => checkpoint.bundle === "available").map((checkpoint) => this.bundleFile(checkpoint.id));
+      if (files.length) draft.after.push(async () => {
+        for (const file of files) await rm(file, { force: true });
+      });
+      return { deleted: true };
+    });
+  }
+  /** Repository keys are what every teammate maps to a clone, so a key still used by a task cannot disappear. The board revision is the CAS here. */
+  async setRepositories(actor, projectId, repositories, revision) {
+    const refs = validateRepoRefs(repositories);
+    return this.change((draft) => {
+      const project = this.project(projectId, actor);
+      this.need(actor, project.id, "maintainer", "define repositories");
+      if (revision === void 0 || revision === null) throw new CollabError("Send the board's current revision with the change");
+      if (!integer(revision) || revision !== draft.board.revision) throw new CollabError("Team board changed; reload before saving", 409);
+      const keys = new Set(refs.map((repo) => repo.key)), used = draft.board.tasks.find((task) => task.projectId === project.id && !keys.has(task.repository));
+      if (used) throw new CollabError(`Task \u201C${used.title}\u201D still uses repository ${used.repository}; move it to another repository before removing that key`, 409);
+      draft.board.projects[project.id] = { repositories: refs };
+      draft.board.revision++;
+      draft.dirty.add("board");
+      draft.events.push({ kind: "board", projectId: project.id });
+      return this.projectView(draft.board, project, actor, this.onlineUsers(this.now()));
+    });
+  }
+  async setOwnerName(actor, name) {
+    return this.change((draft) => {
+      if (actor.kind !== "owner") throw new CollabError("Only the hub owner may change the owner's display name", 403);
+      const label = validateText(name, MAX.displayName, "display name", { required: true, singleLine: true });
+      draft.board.ownerName = label;
+      draft.board.revision++;
+      draft.dirty.add("board");
+      draft.events.push({ kind: "board" });
+      return { ownerName: label };
+    });
+  }
+  // ---- Discussion, decisions, reviews, instructions
+  async comment(actor, taskId, text2) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId);
+      this.need(actor, current.projectId, "reviewer", "comment");
+      const body = validateText(text2, MAX.text, "comment", { required: true });
+      const task = draft.task(current.id), mentions = mentionsIn(body, this.mentionTargets(task.projectId));
+      pushBounded(task.discussion, { id: newId("comment", this.random), by: whoOf(actor), text: body, mentions, at: now, kind: "comment" }, MAX.discussion, "comments");
+      this.commit(draft, task, whoOf(actor), "commented", truncateText(body, 120), now);
+      this.notify(draft, task, actor, mentions, "mention", `${actor.displayName} mentioned you: ${body}`);
+      this.notify(draft, task, actor, this.stakeholders(task).filter((id) => !mentions.includes(id)), "comment", `${actor.displayName} commented: ${body}`);
+      return clone(task);
+    });
+  }
+  async decide(actor, taskId, text2) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId);
+      this.need(actor, current.projectId, "contributor", "add decisions");
+      const body = validateText(text2, MAX.decision, "decision", { required: true });
+      const task = draft.task(current.id), mentions = mentionsIn(body, this.mentionTargets(task.projectId));
+      pushBounded(task.decisions, { id: newId("decision", this.random), by: whoOf(actor), text: body, at: now }, MAX.decisions, "decisions");
+      this.commit(draft, task, whoOf(actor), "decided", truncateText(body, 120), now);
+      this.notify(draft, task, actor, mentions, "mention", `${actor.displayName} mentioned you in a decision: ${body}`);
+      return clone(task);
+    });
+  }
+  async requestReview(actor, taskId, reviewerUserId, revision) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId);
+      this.need(actor, current.projectId, "contributor", "request reviews");
+      this.cas(current, revision);
+      const task = draft.task(current.id), reviewer = this.resolveWho(task.projectId, reviewerUserId, "reviewer", "reviewer");
+      task.reviewer = reviewer;
+      this.system(task, whoOf(actor), `${actor.displayName} asked ${reviewer.displayName} to review this task`, now, "review-request");
+      this.commit(draft, task, whoOf(actor), "review-requested", reviewer.displayName, now);
+      this.notify(draft, task, actor, [reviewer.userId], "review-requested", `${actor.displayName} asked you to review \u201C${task.title}\u201D`);
+      return clone(task);
+    });
+  }
+  /** A review names an existing checkpoint of the task; reviews of anything but the latest checkpoint are stale, which reviewState ignores. */
+  async review(actor, taskId, input, revision) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId);
+      this.need(actor, current.projectId, "reviewer", "record reviews");
+      this.cas(current, revision);
+      if (!object(input)) throw new CollabError("Send the review as { checkpointId, verdict, text }");
+      const checkpoint = current.checkpoints.find((entry) => entry.id === input.checkpointId);
+      if (!checkpoint) throw new CollabError("Checkpoint not found", 404);
+      if (input.verdict !== "approve" && input.verdict !== "request-changes") throw new CollabError('Choose a verdict: "approve" or "request-changes"');
+      const body = validateText(input.text, MAX.text, "review");
+      const task = draft.task(current.id), latest = latestCheckpoint(task), mentions = mentionsIn(body, this.mentionTargets(task.projectId));
+      pushBounded(task.reviews, { id: newId("review", this.random), checkpointId: checkpoint.id, commit: checkpoint.commit, by: whoOf(actor), verdict: input.verdict, text: body, at: now, stale: checkpoint.id !== latest.id }, MAX.reviews, "reviews");
+      for (const entry of task.reviews) entry.stale = entry.checkpointId !== latest.id;
+      this.commit(draft, task, whoOf(actor), "reviewed", `${input.verdict} on ${short(checkpoint.commit)}`, now);
+      this.notify(draft, task, actor, mentions, "mention", `${actor.displayName} mentioned you in a review: ${body}`);
+      if (task.owner) this.notify(draft, task, actor, [task.owner.userId], "review-recorded", `${actor.displayName} ${input.verdict === "approve" ? "approved" : "requested changes on"} \u201C${task.title}\u201D${body ? `: ${body}` : ""}`);
+      return clone(task);
+    });
+  }
+  /** "Send to agent": the task owner's own instructions are approved at once; anyone else's wait for the owner (or a maintainer). */
+  async proposeInstruction(actor, taskId, text2) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId);
+      this.need(actor, current.projectId, "contributor", "send instructions to the agent");
+      const body = validateText(text2, MAX.text, "instruction", { required: true });
+      const task = draft.task(current.id), by = whoOf(actor), approved = isTaskOwner(task, actor), instruction = { id: newId("instruction", this.random), by, text: body, at: now, state: approved ? "approved" : "proposed" };
+      if (approved) {
+        instruction.decidedBy = by;
+        instruction.decidedAt = now;
+      }
+      pushBounded(task.instructions, instruction, MAX.instructions, "instructions");
+      this.commit(draft, task, by, approved ? "instruction-approved" : "instruction-proposed", truncateText(body, 120), now);
+      this.notify(draft, task, actor, mentionsIn(body, this.mentionTargets(task.projectId)), "mention", `${actor.displayName} mentioned you in an instruction: ${body}`);
+      if (!approved && task.owner) this.notify(draft, task, actor, [task.owner.userId], "instruction-proposed", `${actor.displayName} proposed an instruction for the agent on \u201C${task.title}\u201D: ${body}`);
+      return clone(task);
+    });
+  }
+  async decideInstruction(actor, taskId, instructionId, action) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId);
+      if (!isTaskOwner(current, actor) && !roleAtLeast(actorRole(actor, current.projectId), "maintainer")) throw new CollabError("Only the task owner or a project maintainer may approve or decline instructions", 403);
+      if (action !== "approve" && action !== "decline") throw new CollabError('Choose an action: "approve" or "decline"');
+      const existing = current.instructions.find((entry) => entry.id === instructionId);
+      if (!existing) throw new CollabError("Instruction not found", 404);
+      if (existing.state !== "proposed") throw new CollabError(`This instruction was already ${existing.state}`, 409);
+      const task = draft.task(current.id), instruction = task.instructions.find((entry) => entry.id === instructionId), by = whoOf(actor);
+      instruction.state = action === "approve" ? "approved" : "declined";
+      instruction.decidedBy = by;
+      instruction.decidedAt = now;
+      this.commit(draft, task, by, `instruction-${instruction.state}`, truncateText(instruction.text, 120), now);
+      return clone(task);
+    });
+  }
+  /** The runner records delivery so a reconnect never hands the agent the same instruction twice. */
+  async markInstructionDelivered(actor, taskId, instructionId, attemptId) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId), attempt = current.attempts.find((entry) => entry.id === attemptId);
+      if (!attempt) throw new CollabError("Attempt not found", 404);
+      this.assertAttemptRunner(attempt, actor);
+      const existing = current.instructions.find((entry) => entry.id === instructionId);
+      if (!existing) throw new CollabError("Instruction not found", 404);
+      if (existing.state === "delivered" && existing.attemptId === attempt.id) return clone(current);
+      if (existing.state !== "approved") throw new CollabError(`Only approved instructions can be delivered; this one is ${existing.state}`, 409);
+      const task = draft.task(current.id), instruction = task.instructions.find((entry) => entry.id === instructionId);
+      instruction.state = "delivered";
+      instruction.attemptId = attempt.id;
+      this.commit(draft, task, whoOf(actor), "instruction-delivered", attempt.runnerName, now);
+      return clone(task);
+    });
+  }
+  // ---- Attempts
+  /** Only the task owner's own machine claims: the owner process with runner id "local", or a member's runner credential naming itself. Idempotent on attemptId, so a runner that crashed after claiming can resume safely. */
+  async claimAttempt(actor, taskId, input) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId);
+      this.need(actor, current.projectId, "contributor", "run tasks");
+      if (!object(input)) throw new CollabError("Send the attempt as { attemptId, runnerId, runnerName, baseCommit, fromCheckpointId?, revision }");
+      if (typeof input.attemptId !== "string" || !ATTEMPT_ID.test(input.attemptId)) throw new CollabError("Send the attempt id as 32 lowercase hexadecimal characters");
+      const attemptId = input.attemptId;
+      const runnerName = validateText(input.runnerName, MAX.runnerName, "runner name", { required: true, singleLine: true }), baseCommit = validateCommit(input.baseCommit, "base commit");
+      const fromCheckpointId = input.fromCheckpointId === void 0 || input.fromCheckpointId === null ? void 0 : input.fromCheckpointId;
+      if (fromCheckpointId !== void 0 && (typeof fromCheckpointId !== "string" || !CHECKPOINT_ID.test(fromCheckpointId))) throw new CollabError("Send the checkpoint id as 32 lowercase hexadecimal characters");
+      if (!isTaskOwner(current, actor)) throw new CollabError("Only the task owner may start an attempt; take the task first", 403);
+      const runnerId = this.claimRunnerId(actor, input.runnerId), existing = this.attemptById(draft.board, attemptId);
+      if (existing) {
+        if (existing.task.id === current.id && existing.attempt.runnerId === runnerId && existing.attempt.user.userId === actor.userId) return clone(current);
+        throw new CollabError("That attempt id already belongs to another attempt; generate a new one", 409);
+      }
+      this.cas(current, input.revision);
+      const busy = busyAttempt(current);
+      if (busy) throw new CollabError(`Stop the attempt running on ${busy.runnerName} before starting another`, 409);
+      if (current.handoff?.state === "offered") throw new CollabError("Accept, decline or cancel the offered hand-over before starting an attempt", 409);
+      if (current.status === "done") throw new CollabError("Move the task out of Done before starting an attempt", 409);
+      if (fromCheckpointId !== void 0) {
+        const checkpoint = current.checkpoints.find((entry) => entry.id === fromCheckpointId);
+        if (!checkpoint) throw new CollabError("Checkpoint not found", 404);
+        const latest = latestCheckpoint(current);
+        if (checkpoint.id !== latest.id && !roleAtLeast(actorRole(actor, current.projectId), "maintainer")) throw new CollabError(`Continue from the latest checkpoint (${short(latest.commit)}); only a project maintainer may start from an older one`, 409);
+      }
+      const task = draft.task(current.id), attempt = { id: attemptId, taskId: task.id, runnerId, runnerName, user: whoOf(actor), state: "claimed", baseCommit, createdAt: now, lastSeq: 0, lastHeartbeatAt: now, progress: { updatedAt: now } };
+      if (fromCheckpointId !== void 0) attempt.fromCheckpointId = fromCheckpointId;
+      pushBounded(task.attempts, attempt, MAX.attempts, "attempts");
+      if (task.status !== "working") transition(task, "working", actor, void 0, now);
+      this.commit(draft, task, whoOf(actor), "attempt-claimed", `${runnerName} from ${short(baseCommit)}`, now);
+      return clone(task);
+    });
+  }
+  claimRunnerId(actor, runnerId) {
+    if (actor.kind === "owner") {
+      if (runnerId !== RUNNER_LOCAL) throw new CollabError(`The hub owner runs tasks in-process; send runnerId "${RUNNER_LOCAL}"`);
+      return RUNNER_LOCAL;
+    }
+    if (actor.via !== "runner" || actor.runnerId === void 0) throw new CollabError("Start attempts from your own code-flow (Connections \u2192 Share access \u2192 Connect this computer), not from the browser", 403);
+    if (runnerId !== actor.runnerId) throw new CollabError("The attempt's runnerId must be the runner id of the credential making the request", 403);
+    return actor.runnerId;
+  }
+  /** Reports are ordered by `seq`; a stale or duplicate report is a no-op that returns the current attempt. Progress never bumps revisions, so an editing teammate is not conflicted by a running agent, and on an attempt already running it is telemetry (announced at once, written behind). A report that revives a paused, stopped or unknown attempt is a state change under the claim's rules: refused when the attempt's user no longer owns the task (403), on a Done task, while another attempt is busy on the task or while a hand-over is offered (409; so a stale Resume never puts two runs on one task or reopens a finished one), and written at once like the first report of a claimed attempt. */
+  async attemptProgress(actor, attemptId, report) {
+    const parsed = validateProgressReport(report, this.now());
+    return this.change((draft) => {
+      const now = this.now(), found = this.findAttempt(draft.board, actor, attemptId);
+      this.assertAttemptRunner(found.attempt, actor);
+      this.assertNotEnded(found.attempt);
+      if (parsed.seq <= found.attempt.lastSeq) return { attempt: clone(found.attempt) };
+      if (found.attempt.state !== "claimed" && found.attempt.state !== "running") {
+        if (!isTaskOwner(found.task, actor)) throw new CollabError(ownerChangedMessage(found.task), 403);
+        if (found.task.status === "done") throw new CollabError("Move the task out of Done before resuming the attempt", 409);
+        const busy = busyAttempt(found.task);
+        if (busy && busy.id !== found.attempt.id) throw new CollabError(`Stop the attempt running on ${busy.runnerName} before resuming this one`, 409);
+        if (found.task.handoff?.state === "offered") throw new CollabError("Accept, decline or cancel the offered hand-over before resuming the attempt", 409);
+      }
+      const task = draft.task(found.task.id, found.attempt.state === "running" ? "telemetry" : "board"), attempt = task.attempts.find((entry) => entry.id === found.attempt.id);
+      attempt.progress = parsed.progress;
+      attempt.lastSeq = parsed.seq;
+      attempt.lastHeartbeatAt = now;
+      attempt.state = "running";
+      attempt.startedAt ??= now;
+      delete attempt.endedAt;
+      delete attempt.reason;
+      if (parsed.runId !== void 0) attempt.runId = parsed.runId;
+      if (parsed.progress.head) attempt.head = parsed.progress.head;
+      if (parsed.progress.branch) attempt.branch = parsed.progress.branch;
+      draft.events.push({ kind: "task", taskId: task.id, projectId: task.projectId });
+      return { attempt: clone(attempt) };
+    });
+  }
+  async heartbeat(actor, attemptId) {
+    return this.change((draft) => {
+      const found = this.findAttempt(draft.board, actor, attemptId);
+      this.assertAttemptRunner(found.attempt, actor);
+      this.assertNotEnded(found.attempt);
+      const task = draft.task(found.task.id, "telemetry"), attempt = task.attempts.find((entry) => entry.id === found.attempt.id);
+      attempt.lastHeartbeatAt = this.now();
+      draft.events.push({ kind: "task", taskId: task.id, projectId: task.projectId });
+      return { attempt: clone(attempt), instructions: clone(task.instructions.filter((entry) => entry.state === "approved")) };
+    });
+  }
+  assertNotEnded(attempt) {
+    if (TERMINAL.includes(attempt.state)) throw new CollabError(`This attempt ${attempt.state === "superseded" ? "was superseded by a change of owner or recovery" : `already ended as ${attempt.state}`}; start a new attempt instead`, 409);
+  }
+  /** Idempotent for the runner's retries: finishing again with the same state returns the attempt unchanged. paused/stopped/unknown attempts can be resumed, finished/failed cannot. */
+  async finishAttempt(actor, attemptId, input) {
+    return this.change((draft) => {
+      const now = this.now(), found = this.findAttempt(draft.board, actor, attemptId);
+      this.assertAttemptRunner(found.attempt, actor);
+      if (!object(input) || !FINISH_STATES.includes(input.state)) throw new CollabError('Choose the final state: "finished", "failed", "stopped", "paused" or "unknown"');
+      const state = input.state;
+      const head = input.head === void 0 || input.head === null ? void 0 : validateCommit(input.head, "head"), summary = validateText(input.summary, MAX.summary, "summary"), reason = validateText(input.reason, MAX.reason, "reason");
+      if (found.attempt.state === state) return { attempt: clone(found.attempt) };
+      this.assertNotEnded(found.attempt);
+      const task = draft.task(found.task.id), attempt = task.attempts.find((entry) => entry.id === found.attempt.id);
+      attempt.state = state;
+      if (state === "unknown") delete attempt.endedAt;
+      else attempt.endedAt = now;
+      attempt.lastHeartbeatAt = now;
+      if (head) attempt.head = head;
+      if (summary) {
+        attempt.progress.summary = summary;
+        attempt.progress.updatedAt = now;
+      }
+      if (reason) attempt.reason = reason;
+      this.commit(draft, task, whoOf(actor), `attempt-${state}`, truncateText(reason || summary, 200) || void 0, now);
+      const label = state === "finished" ? "finished" : state === "failed" ? "failed" : state === "stopped" ? "stopped at a limit" : state === "paused" ? "paused" : "lost contact";
+      if (task.owner) this.notify(draft, task, actor, [task.owner.userId], state === "failed" || state === "unknown" ? "attempt-failed" : "attempt-finished", `The attempt on ${attempt.runnerName} ${label}${reason ? `: ${reason}` : ""}`);
+      return { attempt: clone(attempt) };
+    });
+  }
+  /** A human recovery decision, never a heartbeat timeout: confirm the original execution has stopped before releasing its reservation. */
+  async recoverAttempt(actor, attemptId, input) {
+    return this.change((draft) => {
+      const found = this.findAttempt(draft.board, actor, attemptId), role = actorRole(actor, found.task.projectId);
+      if (!(isTaskOwner(found.task, actor) && roleAtLeast(role, "contributor")) && !roleAtLeast(role, "maintainer")) throw new CollabError("Only the task owner or a project maintainer may recover an attempt", 403);
+      this.cas(found.task, input.revision);
+      if (found.attempt.state !== "unknown") throw new CollabError("Only an unknown attempt can be recovered; reconcile or stop its runner first", 409);
+      if (input.confirmedStopped !== true) throw new CollabError("Confirm that the original agent has stopped before releasing this task");
+      const reason = validateText(input.reason, MAX.reason, "recovery reason", { required: true }), now = this.now();
+      const task = draft.task(found.task.id), attempt = task.attempts.find((entry) => entry.id === attemptId);
+      attempt.state = "superseded";
+      attempt.endedAt = now;
+      attempt.reason = reason;
+      this.commit(draft, task, whoOf(actor), "attempt-recovered", reason, now);
+      this.system(task, whoOf(actor), `${actor.displayName} confirmed execution on ${attempt.runnerName} has stopped: ${reason}`, now);
+      return clone(task);
+    });
+  }
+  // ---- Checkpoints
+  /** The manifest may name the checkpoint (`id`): the runner mints it before bundling, so the bundle's only ref, the board and the branch `team/<task>/<id8>` agree and every importing machine lands `refs/codeflow/team/<id>` under the id the board shows. Ids are random, so one already on the board (any task) is a stale retry and is refused; hub-side callers that send none get a generated id. */
+  async addCheckpoint(actor, attemptId, input) {
+    const manifest = validateCheckpointInput(input);
+    return this.change((draft) => {
+      const now = this.now(), found = this.findAttempt(draft.board, actor, attemptId);
+      this.assertAttemptRunner(found.attempt, actor);
+      if (found.attempt.state === "superseded") throw new CollabError("This attempt was superseded by a change of owner; its work can no longer be checkpointed", 409);
+      if (manifest.id !== void 0 && draft.board.tasks.some((entry) => entry.checkpoints.some((checkpoint2) => checkpoint2.id === manifest.id))) throw new CollabError("A checkpoint with this id already exists; create the bundle again under a new id", 409);
+      const task = draft.task(found.task.id), attempt = task.attempts.find((entry) => entry.id === found.attempt.id), id = manifest.id ?? newCheckpointId(this.random);
+      const checkpoint = { id, taskId: task.id, attemptId: attempt.id, commit: manifest.commit, baseCommit: manifest.baseCommit, branch: manifest.branch, size: manifest.size, sha256: manifest.sha256, ref: `refs/codeflow/team/${id}`, createdBy: whoOf(actor), at: now, note: manifest.note, requirements: manifest.requirements, decisions: manifest.decisions, remaining: manifest.remaining, changedFiles: manifest.changedFiles, bundle: "pending" };
+      if (manifest.testResults) checkpoint.testResults = manifest.testResults;
+      pushBounded(task.checkpoints, checkpoint, MAX.checkpoints, "checkpoints");
+      attempt.checkpointId = id;
+      attempt.head = manifest.commit;
+      for (const review of task.reviews) review.stale = review.checkpointId !== id;
+      this.commit(draft, task, whoOf(actor), "checkpoint-added", short(manifest.commit), now);
+      return clone(checkpoint);
+    });
+  }
+  /** Streams to a temp file while hashing and counting (outside the mutation queue, so a slow upload blocks nobody), then moves it into place and marks the bundle available in one durable step. */
+  async storeBundle(actor, checkpointId, stream, info) {
+    await this.load();
+    this.require();
+    const found = this.findCheckpoint(this.state.board, actor, checkpointId);
+    this.assertAttemptRunner(found.attempt, actor);
+    this.assertPendingBundle(found.checkpoint);
+    if (!object(info) || info.size !== found.checkpoint.size || typeof info.sha256 !== "string" || info.sha256.toLowerCase() !== found.checkpoint.sha256) throw new CollabError("The upload's size and sha256 must match the checkpoint manifest");
+    await mkdir(this.bundleDir, { recursive: true, mode: 448 });
+    const temp = `${this.bundleFile(found.checkpoint.id)}.${this.random(6).toString("hex")}.tmp`, hash = createHash("sha256");
+    let received = 0;
+    try {
+      const handle = await open(temp, "wx", 384);
+      try {
+        for await (const chunk of stream) {
+          const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+          received += bytes.length;
+          if (received > MAX.bundle) throw new CollabError(`Checkpoint bundles are limited to ${MAX.bundle / 1024 / 1024} MiB`, 413);
+          if (received > found.checkpoint.size) throw new CollabError("The uploaded bundle is larger than the checkpoint manifest says; upload the file the manifest describes");
+          hash.update(bytes);
+          await handle.write(bytes);
+        }
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      if (received !== found.checkpoint.size || hash.digest("hex") !== found.checkpoint.sha256) throw new CollabError("The uploaded bundle does not match the checkpoint's size or sha256 digest; upload it again");
+    } catch (error) {
+      await rm(temp, { force: true }).catch(() => void 0);
+      throw error instanceof CollabError ? error : new CollabError(`The bundle upload failed: ${error instanceof Error ? error.message : String(error)}; upload it again`);
+    }
+    let installed = false;
+    try {
+      return await this.change(async (draft) => {
+        const now = this.now(), again = this.findCheckpoint(draft.board, actor, checkpointId);
+        this.assertPendingBundle(again.checkpoint);
+        const evicted = this.makeRoom(draft, whoOf(actor), now);
+        const task = draft.task(again.task.id), checkpoint = task.checkpoints.find((entry) => entry.id === again.checkpoint.id), file = this.bundleFile(checkpoint.id);
+        checkpoint.bundle = "available";
+        try {
+          await rename(temp, file);
+        } catch (error) {
+          logError(`A checkpoint bundle could not be moved into place as ${file}`, error);
+          throw new CollabError("Team storage could not store the checkpoint bundle; check the team server's checkpoints folder (see server.log), then upload it again", 503);
+        }
+        installed = true;
+        draft.undo.push(() => rm(file, { force: true }));
+        if (evicted.length) draft.after.push(async () => {
+          for (const old of evicted) await rm(old, { force: true });
+        });
+        this.commit(draft, task, whoOf(actor), "bundle-stored", `${checkpoint.size} bytes`, now);
+        return clone(checkpoint);
+      });
+    } finally {
+      if (!installed) await rm(temp, { force: true }).catch(() => void 0);
+    }
+  }
+  assertPendingBundle(checkpoint) {
+    if (checkpoint.bundle !== "pending") throw new CollabError(checkpoint.bundle === "available" ? "This checkpoint's bundle was already uploaded" : "This checkpoint's bundle was deleted; create a new checkpoint", 409);
+  }
+  /** Keeps at most 200 bundles on disk by retiring the oldest bundle of a done task; when none qualifies the upload fails with 507 instead of removing live work. */
+  makeRoom(draft, by, now) {
+    const available = [];
+    for (const task of draft.board.tasks) for (const checkpoint of task.checkpoints) if (checkpoint.bundle === "available") available.push({ taskId: task.id, checkpointId: checkpoint.id, at: checkpoint.at, done: task.status === "done" && !(task.handoff?.state === "offered" && task.handoff.checkpointId === checkpoint.id) });
+    const files = [];
+    while (available.length >= MAX.bundlesOnDisk) {
+      const victim = available.filter((entry) => entry.done).sort((a, b) => a.at - b.at)[0];
+      if (!victim) throw new CollabError("Team checkpoint storage is full; delete checkpoints of finished tasks first", 507);
+      const task = draft.task(victim.taskId), checkpoint = task.checkpoints.find((entry) => entry.id === victim.checkpointId);
+      checkpoint.bundle = "deleted";
+      this.commit(draft, task, by, "bundle-evicted", `${short(checkpoint.commit)} to make room`, now);
+      available.splice(available.indexOf(victim), 1);
+      files.push(this.bundleFile(checkpoint.id));
+    }
+    return files;
+  }
+  async bundlePath(actor, checkpointId) {
+    await this.load();
+    this.require();
+    const found = this.findCheckpoint(this.state.board, actor, checkpointId);
+    this.need(actor, found.task.projectId, "contributor", "download checkpoint bundles");
+    if (found.checkpoint.bundle !== "available") throw new CollabError("Checkpoint bundle is not available", 404);
+    const path = this.bundleFile(found.checkpoint.id), info = await lstat(path).catch(() => void 0);
+    if (!info?.isFile() || info.size !== found.checkpoint.size) throw new CollabError("The checkpoint bundle is missing from the hub's storage; create a new checkpoint", 404);
+    return { path, checkpoint: clone(found.checkpoint) };
+  }
+  async deleteCheckpoint(actor, id) {
+    return this.change((draft) => {
+      const now = this.now(), found = this.findCheckpoint(draft.board, actor, id);
+      this.need(actor, found.task.projectId, "maintainer", "delete checkpoints");
+      if (found.checkpoint.bundle === "deleted") return clone(found.checkpoint);
+      if (found.task.handoff?.state === "offered" && found.task.handoff.checkpointId === found.checkpoint.id) throw new CollabError("Cancel the offered hand-over before deleting its checkpoint", 409);
+      const task = draft.task(found.task.id), checkpoint = task.checkpoints.find((entry) => entry.id === found.checkpoint.id), hadFile = checkpoint.bundle === "available";
+      checkpoint.bundle = "deleted";
+      this.commit(draft, task, whoOf(actor), "checkpoint-deleted", short(checkpoint.commit), now);
+      if (hadFile) {
+        const file = this.bundleFile(checkpoint.id);
+        draft.after.push(() => rm(file, { force: true }));
+      }
+      return clone(checkpoint);
+    });
+  }
+  // ---- Hand-overs
+  /** The task owner (or a maintainer) offers a contributor the task at an available checkpoint; nothing moves until the recipient accepts, so a declined or failed hand-over leaves the owner in place. */
+  async offerHandoff(actor, taskId, input, revision) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId), role = actorRole(actor, current.projectId);
+      if (!(isTaskOwner(current, actor) && roleAtLeast(role, "contributor")) && !roleAtLeast(role, "maintainer")) throw new CollabError("Only the task owner or a project maintainer may hand the task over", 403);
+      this.cas(current, revision);
+      if (!object(input)) throw new CollabError("Send the hand-over as { to, checkpointId, note }");
+      const to = this.resolveWho(current.projectId, input.to, "contributor", "teammate");
+      if (to.userId === current.owner?.userId) throw new CollabError("Choose a teammate other than the task's current owner to hand over to");
+      const busy = busyAttempt(current);
+      if (busy) throw new CollabError(`Stop the attempt running on ${busy.runnerName} before handing the task over`, 409);
+      if (current.handoff?.state === "offered") throw new CollabError(`A hand-over to ${current.handoff.to.displayName} is already offered; cancel it before offering another`, 409);
+      const checkpoint = current.checkpoints.find((entry) => entry.id === input.checkpointId);
+      if (!checkpoint) throw new CollabError("Checkpoint not found", 404);
+      if (checkpoint.bundle !== "available") throw new CollabError("The checkpoint's bundle is not on the hub; upload it or choose another checkpoint", 409);
+      const note = validateText(input.note, MAX.note, "note"), task = draft.task(current.id), by = whoOf(actor), handoff = { id: newId("handoff", this.random), from: by, to, checkpointId: checkpoint.id, note, state: "offered", offeredAt: now };
+      task.handoff = handoff;
+      this.system(task, by, `${actor.displayName} offered to hand this task over to ${to.displayName}`, now);
+      this.commit(draft, task, by, "handoff-offered", to.displayName, now);
+      this.notify(draft, task, actor, [to.userId], "handoff-offered", `${actor.displayName} offered you \u201C${task.title}\u201D${note ? `: ${note}` : ""}`);
+      this.notify(draft, task, actor, mentionsIn(note, this.mentionTargets(task.projectId)).filter((id) => id !== to.userId), "mention", `${actor.displayName} mentioned you in a hand-over note: ${note}`);
+      return clone(task);
+    });
+  }
+  /** accept (recipient): the task changes hands through assignOwner, superseding paused or stopped attempts; decline (recipient) and cancel (sender or maintainer) leave the owner as is. */
+  async respondHandoff(actor, taskId, handoffId, action, revision) {
+    return this.change((draft) => {
+      const now = this.now(), current = this.findTask(draft.board, actor, taskId);
+      this.cas(current, revision);
+      const offered = current.handoff;
+      if (!offered || offered.id !== handoffId) {
+        const past = current.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);
+      }
+      if (action !== "accept" && action !== "decline" && action !== "cancel") throw new CollabError('Choose an action: "accept", "decline" or "cancel"');
+      const role = actorRole(actor, current.projectId);
+      if (action === "cancel") {
+        if (offered.from.userId !== actor.userId && !roleAtLeast(role, "maintainer")) throw new CollabError("Only the teammate who offered the hand-over or a project maintainer may cancel it", 403);
+      } else {
+        if (offered.to.userId !== actor.userId) throw new CollabError("Only the teammate the task was offered to may accept or decline it", 403);
+        if (action === "accept" && !roleAtLeast(role, "contributor")) throw new CollabError("A project contributor role is required to accept a hand-over", 403);
+      }
+      const task = draft.task(current.id), handoff = task.handoff, by = whoOf(actor);
+      if (action === "accept") assignOwner(task, handoff.to, now);
+      handoff.state = action === "accept" ? "accepted" : action === "decline" ? "declined" : "cancelled";
+      handoff.respondedAt = now;
+      delete task.handoff;
+      pushBounded(task.handoffs, handoff, MAX.handoffs, "hand-overs", "drop-oldest");
+      this.system(task, by, `${actor.displayName} ${handoff.state} the hand-over ${action === "cancel" ? `to ${handoff.to.displayName}` : `from ${handoff.from.displayName}`}`, now);
+      this.commit(draft, task, by, `handoff-${handoff.state}`, action === "cancel" ? handoff.to.displayName : handoff.from.displayName, now);
+      this.notify(draft, task, actor, [action === "cancel" ? handoff.to.userId : handoff.from.userId], `handoff-${handoff.state}`, `${actor.displayName} ${handoff.state} the hand-over of \u201C${task.title}\u201D`);
+      return clone(task);
+    });
+  }
+  // ---- Inbox and runners
+  async markRead(actor, ids) {
+    if (ids !== "all" && (!Array.isArray(ids) || ids.length > MAX.inboxPerUser || ids.some((id) => typeof id !== "string" || !PREFIXED_ID.test(id)))) throw new CollabError(`Send the inbox item ids to mark read as a list of at most ${MAX.inboxPerUser} ids, or "all"`);
+    return this.change((draft) => {
+      const now = this.now(), wanted = ids === "all" ? void 0 : new Set(ids);
+      let changed = false;
+      const visible = this.visibleInbox(draft.board, draft.inbox, actor);
+      for (const item of visible) if (item.readAt === void 0 && (wanted === void 0 || wanted.has(item.id))) {
+        item.readAt = now;
+        changed = true;
+      }
+      if (changed) {
+        draft.dirty.add("inbox");
+        draft.events.push({ kind: "inbox", userIds: [actor.userId] });
+      }
+      return { unread: visible.filter((item) => item.readAt === void 0).length };
+    });
+  }
+  /** Called after the connect handshake proved the password; the token is returned once and only its sha256 is stored. */
+  async registerRunner(userId, name, address) {
+    return this.change((draft) => {
+      const now = this.now(), id = validateUserRef(userId, "account"), member = this.options.members().find((entry) => entry.userId === id);
+      if (!member || !member.enabled || !Object.values(member.roles).some((role) => roleAtLeast(role, "contributor"))) throw new CollabError("A contributor role in at least one project is required to link a runner", 403);
+      const label = validateText(name, MAX.runnerName, "runner name", { required: true, singleLine: true }), lastAddress = validateText(address, 128, "address", { singleLine: true });
+      if (draft.runners.runners.filter((runner2) => runner2.revokedAt === void 0 && runner2.userId === id).length >= MAX.runnersPerUser) throw new CollabError(`At most ${MAX.runnersPerUser} runners may be linked per account; revoke one in Connections \u2192 Share access first`, 409);
+      while (draft.runners.runners.length >= MAX.runners) {
+        const revoked = draft.runners.runners.filter((runner2) => runner2.revokedAt !== void 0).sort((a, b) => a.revokedAt - b.revokedAt)[0];
+        if (!revoked) throw new CollabError(`The hub has reached its limit of ${MAX.runners} linked runners; revoke unused runners first`, 409);
+        draft.runners.runners.splice(draft.runners.runners.indexOf(revoked), 1);
+      }
+      const token = newRunnerToken(this.random), runner = { id: newRunnerId(this.random), userId: id, name: label, tokenHash: sha256Hex(token), createdAt: now, lastSeenAt: now };
+      if (lastAddress) runner.lastAddress = lastAddress;
+      draft.runners.runners.push(runner);
+      draft.dirty.add("runners");
+      draft.events.push({ kind: "runners", userIds: [id] });
+      return { runner: runnerPublic(runner, now), token };
+    });
+  }
+  /** A revoked runner can no longer report. Its attempts remain reserved as unknown until explicitly recovered. */
+  async revokeRunner(actor, id) {
+    return this.change((draft) => {
+      const now = this.now(), runner = typeof id === "string" ? draft.runners.runners.find((entry) => entry.id === id) : void 0;
+      if (!runner || runner.userId !== actor.userId && !this.seesAllRunners(actor)) throw new CollabError("Runner not found", 404);
+      if (runner.revokedAt !== void 0) return runnerPublic(runner, now);
+      runner.revokedAt = now;
+      draft.dirty.add("runners");
+      draft.events.push({ kind: "runners", userIds: [runner.userId] });
+      for (const current of draft.board.tasks) for (const entry of current.attempts) if (entry.runnerId === runner.id && (entry.state === "claimed" || entry.state === "running")) {
+        const task = draft.task(current.id), attempt = task.attempts.find((candidate) => candidate.id === entry.id);
+        attempt.state = "unknown";
+        delete attempt.endedAt;
+        attempt.reason = `Runner ${runner.name} was revoked while this attempt was active`;
+        this.commit(draft, task, whoOf(actor), "attempt-unknown", `runner ${runner.name} revoked`, now);
+      }
+      return runnerPublic(runner, now);
+    });
+  }
+  /** Housekeeping: drops old revoked runners and read inbox items; silent attempts become unknown but retain their execution reservation. */
+  async prune(now = this.now()) {
+    return this.change((draft) => {
+      const runners = draft.runners.runners.filter((runner) => runner.revokedAt === void 0 || now - runner.revokedAt < RETENTION_MS), prunedRunners = draft.runners.runners.length - runners.length;
+      if (prunedRunners) {
+        draft.runners.runners = runners;
+        draft.dirty.add("runners");
+        draft.events.push({ kind: "runners" });
+      }
+      const items = draft.inbox.items.filter((item) => item.readAt === void 0 || now - item.readAt < RETENTION_MS), prunedItems = draft.inbox.items.length - items.length;
+      if (prunedItems) {
+        draft.inbox.items = items;
+        draft.dirty.add("inbox");
+      }
+      let attempts = 0;
+      const by = { userId: "owner", displayName: this.ownerName };
+      for (const current of draft.board.tasks) {
+        const busy = busyAttempt(current);
+        if (busy && busy.state !== "unknown" && now - busy.lastHeartbeatAt >= STALE_ATTEMPT_MS) {
+          const task = draft.task(current.id), attempt = task.attempts.find((entry) => entry.id === busy.id);
+          attempt.state = "unknown";
+          delete attempt.endedAt;
+          attempt.reason = "No heartbeat for 24 hours; reconcile the runner or confirm execution has stopped before recovering this task";
+          this.commit(draft, task, by, "attempt-unknown", "no heartbeat for 24 hours", now);
+          attempts++;
+        }
+      }
+      return { runners: prunedRunners, inbox: prunedItems, attempts };
+    });
+  }
+}
+export {
+  CollabStore,
+  RUNNER_LOCAL,
+  memberActor,
+  ownerActor
+};