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

package/src/collab/host-execution.js

@@ -0,0 +1,347 @@
+import { randomBytes, createHash } from "node:crypto";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join, dirname } from "node:path";
+import { realpath } from "node:fs/promises";
+import { CODEFLOW_HOME } from "../config.js";
+import { readJson, send } from "../http.js";
+import { logError } from "../log.js";
+import { roleAtLeast } from "../shared-accounts.js";
+import { busyAttempt, CollabError, latestCheckpoint } from "./model.js";
+import { memberActor, ownerActor } from "./store.js";
+import { LocalHub } from "./hub-client.js";
+import { CollabRunner } from "./runner.js";
+const active = (job) => ["queued", "starting", "running", "stopping"].includes(job.state);
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const integer = (v, min, max) => typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+const id = (v) => typeof v === "string" && /^[a-zA-Z0-9_-]{1,100}$/.test(v);
+const keys = (v, allowed) => {
+  if (Object.keys(v).some((key) => !allowed.includes(key))) throw new CollabError("Unknown host execution field");
+};
+function policy(value) {
+  if (!object(value)) throw new CollabError("Invalid host execution policy");
+  keys(value, ["projectId", "enabled", "userIds", "agent", "trust", "maxMinutes", "maxSteps"]);
+  if (!id(value.projectId) || typeof value.enabled !== "boolean" || !Array.isArray(value.userIds) || value.userIds.length > 128 || !value.userIds.every(id) || new Set(value.userIds).size !== value.userIds.length || !["claude", "codex", "agy"].includes(String(value.agent)) || !["safe", "standard"].includes(String(value.trust)) || !integer(value.maxMinutes, 1, 120) || !integer(value.maxSteps, 1, 100)) throw new CollabError("Choose a project, teammates, an installed CLI, permissions, 1\u2013120 minutes and 1\u2013100 steps");
+  return structuredClone(value);
+}
+const taskHash = (task) => createHash("sha256").update(JSON.stringify([task.projectId, task.repository, task.title, task.goal, task.acceptance, task.baseRef, task.owner?.userId, task.decisions, latestCheckpoint(task)?.id])).digest("hex");
+function publicJob(job) {
+  const { id: id2, taskId, projectId, userId, displayName, state, createdAt, endedAt, runId, attemptId, message } = job;
+  return { id: id2, taskId, projectId, userId, displayName, state, createdAt, endedAt, runId, attemptId, message };
+}
+class HostExecution {
+  constructor(options) {
+    this.options = options;
+    this.dir = options.dir ?? join(CODEFLOW_HOME, "host-execution");
+    this.file = join(this.dir, "queue.json");
+  }
+  state = { version: 1, revision: 0, concurrency: 1, policies: [], jobs: [] };
+  ready = false;
+  closed = false;
+  chain = Promise.resolve();
+  runners = /* @__PURE__ */ new Map();
+  timer;
+  dir;
+  file;
+  serial(fn) {
+    const next = this.chain.catch(() => void 0).then(fn);
+    this.chain = next;
+    return next;
+  }
+  require() {
+    if (!this.ready || this.closed) throw new CollabError("Host execution is unavailable", 503);
+  }
+  async load() {
+    if (this.ready) return;
+    try {
+      const handle = await open(this.file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+      let value;
+      try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > 4 * 1024 * 1024) throw new Error("Invalid queue storage");
+        value = JSON.parse(await handle.readFile("utf8"));
+      } finally {
+        await handle.close();
+      }
+      if (!object(value) || value.version !== 1 || !integer(value.revision, 0, Number.MAX_SAFE_INTEGER) || !integer(value.concurrency, 1, 4) || !Array.isArray(value.policies) || value.policies.length > 200 || !Array.isArray(value.jobs) || value.jobs.length > 250) throw new Error("Invalid queue storage");
+      value.policies.forEach(policy);
+      for (const j of value.jobs) {
+        if (!object(j) || typeof j.id !== "string" || !/^h-[a-f0-9]{16}$/.test(j.id) || !id(j.taskId) || !id(j.projectId) || !id(j.userId) || typeof j.username !== "string" || typeof j.displayName !== "string" || typeof j.repo !== "string" || typeof j.contentHash !== "string" || !/^[a-f0-9]{64}$/.test(j.contentHash) || !integer(j.createdAt, 0, Number.MAX_SAFE_INTEGER) || !["queued", "starting", "running", "stopping", "finished", "failed", "cancelled", "interrupted"].includes(String(j.state)) || j.runId !== void 0 && !id(j.runId) || j.attemptId !== void 0 && (typeof j.attemptId !== "string" || !/^[a-f0-9]{32}$/.test(j.attemptId))) throw new Error("Invalid queue job");
+        const p = policy(j.policy);
+        if (p.projectId !== j.projectId || !p.userIds.includes(j.userId)) throw new Error("Invalid queue grant");
+      }
+      if (new Set(value.jobs.map((j) => j.id)).size !== value.jobs.length || new Set(value.policies.map((p) => p.projectId)).size !== value.policies.length) throw new Error("Duplicate queue records");
+      this.state = value;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    this.ready = true;
+    try {
+      for (const job of this.state.jobs.filter((j) => active(j) && j.state !== "queued")) {
+        const runner = this.runner(job);
+        await runner.reconcile();
+        const record = await runner.attemptForTask(job.taskId);
+        if (record?.runId) {
+          job.runId = record.runId;
+          job.attemptId = record.attemptId;
+          if (job.state !== "stopping") job.state = "running";
+        } else {
+          job.state = "interrupted";
+          job.message = "Start interrupted. Review the task attempt before queuing it again.";
+          job.endedAt = Date.now();
+        }
+      }
+      await this.persist();
+    } catch (error) {
+      this.ready = false;
+      await Promise.all([...this.runners.values()].map((runner) => runner.close()));
+      throw error;
+    }
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => void this.tick().catch((error) => logError("Host execution queue failed", error)), 2e3);
+    this.timer.unref();
+  }
+  async persist() {
+    const retained = new Set(this.state.jobs.filter((job) => !active(job)).slice(-200).map((job) => job.id));
+    this.state.jobs = this.state.jobs.filter((job) => active(job) || retained.has(job.id));
+    const temp = `${this.file}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+      await mkdir(dirname(this.file), { recursive: true, mode: 448 });
+      const handle = await open(temp, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify(this.state));
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temp, this.file);
+      if (process.platform !== "win32") {
+        const folder = await open(dirname(this.file), "r");
+        try {
+          await folder.sync();
+        } finally {
+          await folder.close();
+        }
+      }
+    } catch (error) {
+      this.ready = false;
+      for (const job of this.state.jobs) if (active(job) && job.runId) this.options.manager.cancel(job.runId);
+      throw error;
+    } finally {
+      await rm(temp, { force: true }).catch(() => {
+      });
+    }
+  }
+  changed(job) {
+    this.options.store.hostExecutionChanged(job?.projectId, job?.taskId);
+  }
+  view(actor) {
+    this.require();
+    const owner = actor.kind === "owner";
+    const member = owner ? void 0 : this.options.members().find((m) => m.userId === actor.userId && m.enabled);
+    const visible = (p) => !!this.options.projectRepos(p) && (owner || !!member?.roles[p]);
+    const jobs = this.state.jobs.filter((j) => visible(j.projectId)).map(publicJob);
+    const policies = this.state.policies.filter((p) => visible(p.projectId));
+    return {
+      revision: this.state.revision,
+      concurrency: this.state.concurrency,
+      available: this.options.enabled(),
+      policies: owner ? structuredClone(policies) : policies.map((p) => ({ projectId: p.projectId, agent: p.agent, allowed: p.enabled && p.userIds.includes(actor.userId) && roleAtLeast(member?.roles[p.projectId], "contributor") })),
+      jobs
+    };
+  }
+  configure(raw) {
+    return this.serial(async () => {
+      this.require();
+      keys(raw, ["revision", "concurrency", "policy"]);
+      if (raw.revision !== this.state.revision) throw new CollabError("Host settings changed; reload before saving", 409);
+      if (raw.concurrency !== void 0) {
+        if (!integer(raw.concurrency, 1, 4)) throw new CollabError("Choose 1\u20134 concurrent host tasks");
+      }
+      let next;
+      if (raw.policy !== void 0) {
+        next = policy(raw.policy);
+        if (!this.options.projectRepos(next.projectId)) throw new CollabError("Project not found", 404);
+        if (!this.state.policies.some((p) => p.projectId === next.projectId) && this.state.policies.length >= 200) throw new CollabError("At most 200 project execution policies may be configured");
+        if (next.userIds.some((uid) => !this.options.members().some((m) => m.userId === uid && m.enabled && roleAtLeast(m.roles[next.projectId], "contributor")))) throw new CollabError("Grant execution only to enabled project contributors or maintainers");
+        if (next.enabled && !(await this.options.availableAgents()).includes(next.agent)) throw new CollabError("This CLI is not installed on the host");
+      }
+      if (next) this.state.policies = [...this.state.policies.filter((p) => p.projectId !== next.projectId), next];
+      if (raw.concurrency !== void 0) this.state.concurrency = raw.concurrency;
+      this.state.revision++;
+      await this.persist();
+      this.changed();
+      return this.view(ownerActor());
+    });
+  }
+  async authorize(job) {
+    this.require();
+    if (!this.options.enabled()) throw new CollabError("Host execution is disabled or unavailable", 403);
+    const member = this.options.members().find((m) => m.userId === job.userId && m.enabled);
+    const p = this.state.policies.find((p2) => p2.projectId === job.projectId);
+    if (!member || !roleAtLeast(member.roles[job.projectId], "contributor") || !p?.enabled || !p.userIds.includes(job.userId) || JSON.stringify(p) !== JSON.stringify(job.policy)) throw new CollabError("Host execution permission or settings changed; ask the owner and queue again", 403);
+    const task = await this.options.store.task(memberActor(member, "browser"), job.taskId);
+    if (task.owner?.userId !== job.userId || taskHash(task) !== job.contentHash) throw new CollabError("Task changed while queued; review it and queue again", 409);
+    const mapped = this.options.resolveRepo(task.projectId, task.repository);
+    const repos = this.options.projectRepos(task.projectId);
+    if (!mapped || mapped !== job.repo || !repos?.includes(mapped) || await realpath(mapped) !== mapped) throw new CollabError("The host repository mapping is unavailable or changed", 409);
+    return task;
+  }
+  enqueue(actor, taskId, raw) {
+    return this.serial(async () => {
+      this.require();
+      keys(raw, ["revision"]);
+      if (actor.kind !== "member" || actor.via !== "browser") throw new CollabError("Sign in with your teammate account to queue a host task", 403);
+      const member = this.options.members().find((m) => m.userId === actor.userId && m.enabled);
+      if (!member) throw new CollabError("Account unavailable", 403);
+      const task = await this.options.store.task(memberActor(member, "browser"), taskId);
+      if (raw.revision !== task.revision) throw new CollabError("Task changed; reload before queuing", 409);
+      const p = this.state.policies.find((p2) => p2.projectId === task.projectId);
+      if (!p) throw new CollabError("The owner has not enabled host execution for this project", 403);
+      const job = { id: `h-${randomBytes(8).toString("hex")}`, taskId, projectId: task.projectId, userId: member.userId, username: member.username, displayName: member.displayName, state: "queued", createdAt: Date.now(), policy: structuredClone(p), repo: this.options.resolveRepo(task.projectId, task.repository) ?? "", contentHash: taskHash(task) };
+      await this.authorize(job);
+      if (task.status === "done" || busyAttempt(task) || task.handoff?.state === "offered") throw new CollabError("This task cannot start while done, executing or being handed over", 409);
+      const duplicate = this.state.jobs.find((j) => active(j) && j.taskId === taskId);
+      if (duplicate) return publicJob(duplicate);
+      if (this.state.jobs.filter(active).length >= 50) throw new CollabError("The host queue is full (50 tasks)", 409);
+      this.state.jobs = [...this.state.jobs.filter(active), ...this.state.jobs.filter((j) => !active(j)).slice(-199)].sort((a, b) => a.createdAt - b.createdAt);
+      this.state.jobs.push(job);
+      await this.persist();
+      this.changed(job);
+      return publicJob(job);
+    });
+  }
+  cancel(actor, jobId) {
+    return this.serial(async () => {
+      this.require();
+      const visible = this.view(actor).jobs.find((j) => j.id === jobId);
+      if (!visible) throw new CollabError("Host task not found", 404);
+      if (actor.kind !== "owner" && visible.userId !== actor.userId) throw new CollabError("Only the requester or host owner may cancel this task", 403);
+      const job = this.state.jobs.find((j) => j.id === jobId);
+      if (!active(job)) return publicJob(job);
+      if (job.state === "queued") {
+        job.state = "cancelled";
+        job.endedAt = Date.now();
+      } else {
+        job.state = "stopping";
+      }
+      await this.persist();
+      if (job.runId && job.state === "stopping") this.options.manager.cancel(job.runId);
+      this.changed(job);
+      return publicJob(job);
+    });
+  }
+  runner(job) {
+    let runner = this.runners.get(job.id);
+    if (runner) return runner;
+    const actor = memberActor({ userId: job.userId, username: job.username, displayName: job.displayName, enabled: true, roles: { [job.projectId]: "contributor" } }, "runner", `r-${job.id.slice(2)}`);
+    const hub = new LocalHub(this.options.store, actor, { runnerId: actor.kind === "member" ? actor.runnerId : void 0, runnerName: "Host computer" });
+    runner = new CollabRunner({ manager: this.options.manager, findPattern: this.options.findPattern, hub: () => hub, dir: join(this.dir, job.id), projectFor: () => job.projectId, beforeStart: async () => {
+      await this.authorize(job);
+    } });
+    this.runners.set(job.id, runner);
+    return runner;
+  }
+  tick() {
+    return this.serial(async () => {
+      this.require();
+      for (const job of this.state.jobs.filter((j) => active(j) && j.state !== "queued")) {
+        const runner = this.runner(job), run = job.runId ? this.options.manager.get(job.runId) : void 0;
+        if (run?.status === "running") {
+          if (job.state !== "stopping") {
+            try {
+              await this.authorize(job);
+            } catch {
+              job.state = "stopping";
+              job.message = "Stopped because execution permission, task or repository changed.";
+              await this.persist();
+              this.changed(job);
+            }
+          }
+          if (job.state === "stopping") this.options.manager.cancel(run.id);
+          continue;
+        }
+        await runner.reconcile();
+        const record = await runner.attemptForTask(job.taskId);
+        if (record?.pendingFinish) continue;
+        job.state = job.state === "stopping" ? record?.state === "failed" ? "failed" : "cancelled" : run?.status === "done" ? "finished" : run?.status === "interrupted" || !run ? "interrupted" : "failed";
+        job.endedAt = Date.now();
+        await this.persist();
+        this.changed(job);
+        await runner.close();
+        this.runners.delete(job.id);
+      }
+      while (this.state.jobs.filter((j) => active(j) && j.state !== "queued").length < this.state.concurrency) {
+        const job = this.state.jobs.find((j) => j.state === "queued");
+        if (!job) break;
+        try {
+          const task = await this.authorize(job);
+          if (!(await this.options.availableAgents()).includes(job.policy.agent)) throw new CollabError("The configured CLI is unavailable on the host");
+          job.state = "starting";
+          await this.persist();
+          this.changed(job);
+          const checkpoint = latestCheckpoint(task);
+          const started = await this.runner(job).startAttempt(task.id, { repo: job.repo, pattern: "solo", roles: { agent: [job.policy.agent] }, trust: job.policy.trust, loop: { maxMinutes: job.policy.maxMinutes, maxSteps: job.policy.maxSteps }, ...checkpoint ? { fromCheckpointId: checkpoint.id } : {} });
+          Object.assign(job, started);
+          job.state = "running";
+          await this.persist();
+          this.changed(job);
+        } catch (error) {
+          if (!this.ready) throw error;
+          const runner = this.runners.get(job.id), record = await runner?.attemptForTask(job.taskId);
+          if (record?.runId || record?.pendingFinish) {
+            job.runId = record.runId;
+            job.attemptId = record.attemptId;
+            job.state = "stopping";
+            if (record.runId) this.options.manager.cancel(record.runId);
+          } else {
+            job.state = "failed";
+            job.endedAt = Date.now();
+          }
+          job.message = error instanceof CollabError && !record ? error.message : "The host could not start this task. Ask the owner to check its execution log.";
+          logError(`Host task ${job.id} could not start`, error);
+          await this.persist();
+          this.changed(job);
+          if (runner && !record?.pendingFinish && !record?.runId) {
+            await runner.close();
+            this.runners.delete(job.id);
+          }
+        }
+      }
+    });
+  }
+  async close() {
+    this.closed = true;
+    if (this.timer) clearInterval(this.timer);
+    await this.chain.catch(() => {
+    });
+    await Promise.all([...this.runners.values()].map((runner) => runner.close()));
+  }
+}
+async function handleHostExecution(req, res, parts, queue, actor, mutation) {
+  try {
+    const method = req.method ?? "GET";
+    if (parts.length === 2 && method === "GET") return send(res, 200, queue.view(actor));
+    if (method !== "GET") mutation();
+    if (parts.length === 3 && parts[2] === "settings" && method === "PUT") {
+      if (actor.kind !== "owner") throw new CollabError("Only the host owner may grant execution", 403);
+      return send(res, 200, await queue.configure(await readJson(req, 32 * 1024, { timeoutMs: 1e4 })));
+    }
+    if (parts.length === 4 && parts[2] === "tasks" && method === "POST") return send(res, 202, await queue.enqueue(actor, parts[3], await readJson(req, 1024, { timeoutMs: 1e4 })));
+    if (parts.length === 5 && parts[2] === "jobs" && parts[4] === "cancel" && method === "POST") {
+      const raw = await readJson(req, 1024, { timeoutMs: 1e4 });
+      keys(raw, []);
+      return send(res, 200, await queue.cancel(actor, parts[3]));
+    }
+    throw new CollabError("Unknown host execution operation", 404);
+  } catch (error) {
+    if (error instanceof CollabError) return send(res, error.status, { error: error.message });
+    throw error;
+  }
+}
+export {
+  HostExecution,
+  handleHostExecution
+};

package/src/collab/hub-client.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream } from "node:fs";
+import { copyFile, lstat, open, rm } from "node:fs/promises";
+import { hostname } from "node:os";
+import { Readable } from "node:stream";
+import { CollabError, MAX, SHA256_HEX } from "./model.js";
+import { RUNNER_LOCAL, ownerActor } from "./store.js";
+const enc = encodeURIComponent;
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const BUNDLE_TIMEOUT_MS = 10 * 6e4;
+class LocalHub {
+  constructor(store, actor, options = {}) {
+    this.store = store;
+    this.actorOf = typeof actor === "function" ? actor : actor ? () => actor : () => ownerActor(store.ownerName);
+    this.runnerId = options.runnerId ?? RUNNER_LOCAL;
+    this.runnerName = options.runnerName ?? (hostname() || "this computer").slice(0, MAX.runnerName);
+  }
+  runnerId;
+  runnerName;
+  actorOf;
+  get actor() {
+    return this.actorOf();
+  }
+  async me() {
+    const board = await this.store.board(this.actor);
+    const { runners, ...me } = board.me;
+    return { me, runners, linked: false };
+  }
+  board(projectId) {
+    return this.store.board(this.actor, projectId);
+  }
+  task(id) {
+    return this.store.task(this.actor, id);
+  }
+  inbox(after) {
+    return this.store.inbox(this.actor, after);
+  }
+  claimAttempt(taskId, input) {
+    return this.store.claimAttempt(this.actor, taskId, input);
+  }
+  progress(attemptId, report) {
+    return this.store.attemptProgress(this.actor, attemptId, report);
+  }
+  heartbeat(attemptId) {
+    return this.store.heartbeat(this.actor, attemptId);
+  }
+  finish(attemptId, input) {
+    return this.store.finishAttempt(this.actor, attemptId, input);
+  }
+  addCheckpoint(attemptId, input) {
+    return this.store.addCheckpoint(this.actor, attemptId, input);
+  }
+  uploadBundle(checkpointId, file, info) {
+    return this.store.storeBundle(this.actor, checkpointId, createReadStream(file), info);
+  }
+  async downloadBundle(checkpointId, toFile) {
+    const { path, checkpoint } = await this.store.bundlePath(this.actor, checkpointId);
+    try {
+      await copyFile(path, toFile, constants.COPYFILE_EXCL);
+    } catch (error) {
+      throw new CollabError(`The checkpoint bundle could not be copied to ${toFile}: ${error instanceof Error ? error.message : String(error)}`, 500);
+    }
+    return checkpoint;
+  }
+  markInstructionDelivered(taskId, instructionId, attemptId) {
+    return this.store.markInstructionDelivered(this.actor, taskId, instructionId, attemptId);
+  }
+  offerHandoff(taskId, input, revision) {
+    return this.store.offerHandoff(this.actor, taskId, input, revision);
+  }
+  respondHandoff(taskId, handoffId, action, revision) {
+    return this.store.respondHandoff(this.actor, taskId, handoffId, action, revision);
+  }
+}
+class RemoteHub {
+  constructor(link) {
+    this.link = link;
+  }
+  get runnerId() {
+    return this.link.runnerId;
+  }
+  get runnerName() {
+    return this.link.runnerName;
+  }
+  get url() {
+    return this.link.url;
+  }
+  me() {
+    return this.link.json("/api/team/me");
+  }
+  board(projectId) {
+    return this.link.json(`/api/team/board${projectId ? `?project=${enc(projectId)}` : ""}`);
+  }
+  task(id) {
+    return this.link.json(`/api/team/tasks/${enc(id)}`);
+  }
+  inbox(after) {
+    return this.link.json(`/api/team/inbox${after === void 0 ? "" : `?after=${enc(String(after))}`}`);
+  }
+  claimAttempt(taskId, input) {
+    return this.link.json(`/api/team/tasks/${enc(taskId)}/attempts`, { method: "POST", json: input });
+  }
+  progress(attemptId, report) {
+    return this.link.json(`/api/team/attempts/${enc(attemptId)}/progress`, { method: "POST", json: report });
+  }
+  heartbeat(attemptId) {
+    return this.link.json(`/api/team/attempts/${enc(attemptId)}/heartbeat`, { method: "POST", json: {} });
+  }
+  finish(attemptId, input) {
+    return this.link.json(`/api/team/attempts/${enc(attemptId)}/finish`, { method: "POST", json: input });
+  }
+  addCheckpoint(attemptId, input) {
+    return this.link.json(`/api/team/attempts/${enc(attemptId)}/checkpoints`, { method: "POST", json: input });
+  }
+  /** The bytes travel as one `application/octet-stream` body with an exact `content-length` and the digest the hub verifies while it streams to disk. */
+  async uploadBundle(checkpointId, file, info) {
+    if (!object(info) || !Number.isSafeInteger(info.size) || info.size < 1 || info.size > MAX.bundle || typeof info.sha256 !== "string" || !SHA256_HEX.test(info.sha256)) throw new CollabError("Upload a bundle of 1 byte to 64 MiB with its sha256 digest", 400);
+    const stat = await lstat(file).catch(() => void 0);
+    if (!stat?.isFile() || stat.size !== info.size) throw new CollabError(`The bundle file ${file} is missing or its size differs from the manifest; create the checkpoint again`, 400);
+    const body = Readable.toWeb(createReadStream(file));
+    const result = await this.link.json(`/api/team/checkpoints/${enc(checkpointId)}/bundle`, { method: "PUT", body, duplex: "half", headers: { "content-type": "application/octet-stream", "content-length": String(info.size), "x-codeflow-sha256": info.sha256 }, timeoutMs: BUNDLE_TIMEOUT_MS });
+    return "checkpoint" in result && object(result.checkpoint) ? result.checkpoint : result;
+  }
+  /** The manifest comes first so the bytes can be checked against what the hub promised; a short or tampered download never reaches the importer. */
+  async downloadBundle(checkpointId, toFile) {
+    const manifest = await this.link.json(`/api/team/checkpoints/${enc(checkpointId)}`);
+    if (manifest.bundle !== "available") throw new CollabError("Checkpoint bundle is not available", 404);
+    const response = await this.link.request(`/api/team/checkpoints/${enc(checkpointId)}/bundle`, { headers: { accept: "application/octet-stream" }, timeoutMs: BUNDLE_TIMEOUT_MS });
+    if (!response.ok) {
+      const error = await readError(response);
+      throw new CollabError(error.message, error.status);
+    }
+    const declared = Number(response.headers.get("content-length")), digest = (response.headers.get("x-codeflow-sha256") ?? "").toLowerCase();
+    if (declared !== manifest.size || digest !== manifest.sha256) {
+      await response.body?.cancel().catch(() => void 0);
+      throw new CollabError("The team server's bundle headers do not match the checkpoint manifest; retry, or delete the checkpoint if it keeps failing", 502);
+    }
+    if (!response.body) throw new CollabError("The team server sent an empty bundle; retry", 502);
+    const hash = createHash("sha256");
+    let received = 0;
+    const handle = await open(toFile, "wx", 384);
+    try {
+      for await (const chunk of Readable.fromWeb(response.body)) {
+        const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        received += bytes.length;
+        if (received > manifest.size) throw new CollabError("The team server sent more bundle bytes than the manifest says; retry", 502);
+        hash.update(bytes);
+        await handle.write(bytes);
+      }
+      await handle.sync();
+    } catch (error) {
+      await handle.close();
+      await rm(toFile, { force: true }).catch(() => void 0);
+      throw error instanceof CollabError ? error : new CollabError(`The bundle download failed: ${error instanceof Error ? error.message : String(error)}; retry`, 502);
+    }
+    await handle.close();
+    if (received !== manifest.size || hash.digest("hex") !== manifest.sha256) {
+      await rm(toFile, { force: true }).catch(() => void 0);
+      throw new CollabError("The downloaded bundle does not match the checkpoint's size or sha256 digest; retry", 502);
+    }
+    return manifest;
+  }
+  markInstructionDelivered(taskId, instructionId, attemptId) {
+    return this.link.json(`/api/team/tasks/${enc(taskId)}/instructions/${enc(instructionId)}`, { method: "POST", json: { action: "delivered", attemptId } });
+  }
+  offerHandoff(taskId, input, revision) {
+    return this.link.json(`/api/team/tasks/${enc(taskId)}/handoff`, { method: "POST", json: { ...input, revision } });
+  }
+  respondHandoff(taskId, handoffId, action, revision) {
+    return this.link.json(`/api/team/tasks/${enc(taskId)}/handoff/${enc(handoffId)}`, { method: "POST", json: { action, revision } });
+  }
+}
+async function readBounded(response, limit, options = {}) {
+  if (!response.body) return "";
+  const declared = Number(response.headers.get("content-length") ?? 0);
+  if (declared > limit && !options.truncate) {
+    await response.body.cancel().catch(() => void 0);
+    throw new CollabError(`The team server's answer exceeds ${Math.round(limit / 1024)} KiB`, 502);
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of Readable.fromWeb(response.body)) {
+    const bytes = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+    size += bytes.length;
+    if (size > limit) {
+      if (!options.truncate) throw new CollabError(`The team server's answer exceeds ${Math.round(limit / 1024)} KiB`, 502);
+      chunks.push(bytes.subarray(0, bytes.length - (size - limit)));
+      break;
+    }
+    chunks.push(bytes);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readError(response, connecting = false, limit = 64 * 1024) {
+  let message = "";
+  try {
+    const text = await readBounded(response, limit, { truncate: true });
+    const parsed = JSON.parse(text);
+    if (object(parsed) && typeof parsed.error === "string") message = parsed.error.slice(0, 2e3);
+  } catch {
+  }
+  if (response.status === 401 && !connecting) return new CollabError(`${message || "The team server no longer accepts this computer's credential"}; reconnect in Settings \u2192 Team`, 401);
+  return new CollabError(message || `The team server answered HTTP ${response.status}`, response.status >= 400 && response.status <= 599 ? response.status : 502);
+}
+export {
+  LocalHub,
+  RemoteHub,
+  readBounded,
+  readError
+};