@a-t-h-i/bot-lobby 0.3.0 → 0.5.0

package/src/desk/desk.ts

@@ -0,0 +1,249 @@
+/**
+ * The file desk: checkout and handover of repository files between workers
+ * that run in parallel, the way people share a physical document.
+ *
+ * A worker claims a file with a one-line intent before editing it. A free
+ * file is granted at once; a held file queues the claimant behind the holder,
+ * and the holder is told who is waiting and what they intend. When the holder
+ * hands the file over (with a note written for the next worker's intent), or
+ * finishes, the file passes to the head of the queue together with that note.
+ * Reads never need a claim. Everything lives in the master process, so a
+ * crashed worker can never leave a stale lock behind.
+ */
+import { isAbsolute, relative, resolve } from "node:path";
+
+export type WorkerId = string;
+
+export interface Claim {
+  worker: WorkerId;
+  intent: string;
+}
+
+/** One file's checkout state as a worker sees it. */
+export interface FileView {
+  path: string;
+  holder: Claim;
+  queue: Claim[];
+}
+
+export interface Handover {
+  path: string;
+  from: WorkerId;
+  to: WorkerId;
+  note: string;
+  auto: boolean;
+  at: number;
+}
+
+export type ClaimResult =
+  | { status: "granted"; path: string; queue: Claim[] }
+  | { status: "held"; path: string; queue: Claim[] }
+  | { status: "queued"; path: string; holder: Claim; position: number };
+
+export type HandoverResult =
+  | { ok: true; path: string; to?: Claim; queue: Claim[] }
+  | { ok: false; path: string; error: string };
+
+/** What the desk tells workers; the session turns these into steering messages. */
+export type DeskEvent =
+  /** `to` holds `path` and its queue changed (someone joined or left). */
+  | { type: "queue"; to: WorkerId; path: string; queue: Claim[] }
+  /** `to` now holds `path`, handed over by `from` with `note`; `queue` is who waits behind it. */
+  | { type: "granted"; to: WorkerId; path: string; from: WorkerId; note: string; intent: string; queue: Claim[] }
+  /** `worker` joined the queue for `path` behind `holder`. */
+  | { type: "queued"; worker: WorkerId; path: string; holder: WorkerId; position: number };
+
+interface Entry {
+  holder: Claim;
+  queue: Claim[];
+}
+
+interface Waiter {
+  resolve: (grants: DeskEvent[]) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const MAX_INTENT = 160;
+const MAX_NOTE = 1200;
+
+function clean(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+export class FileDesk {
+  private readonly files = new Map<string, Entry>();
+  private readonly waiters = new Map<WorkerId, Waiter>();
+  private readonly pendingGrants = new Map<WorkerId, DeskEvent[]>();
+  private readonly log: Handover[] = [];
+  private readonly cwd: string;
+  private readonly onEvent: (event: DeskEvent) => void;
+  private readonly now: () => number;
+
+  constructor(cwd: string, onEvent: (event: DeskEvent) => void = () => {}, now: () => number = Date.now) {
+    this.cwd = resolve(cwd);
+    this.onEvent = onEvent;
+    this.now = now;
+  }
+
+  /** A stable key and display path for a file, relative to the repository root. */
+  normalize(path: string): string {
+    const absolute = isAbsolute(path) ? resolve(path) : resolve(this.cwd, path);
+    const rel = relative(this.cwd, absolute);
+    const display = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : absolute;
+    return display.replace(/\\/g, "/");
+  }
+
+  /** Claim `path` for `worker` with a short intent; grants a free file, queues behind a holder. */
+  claim(worker: WorkerId, path: string, intent: string): ClaimResult {
+    const key = this.normalize(path);
+    const claim = { worker, intent: clean(intent || "edit", MAX_INTENT) };
+    const entry = this.files.get(key);
+    if (!entry) {
+      this.files.set(key, { holder: claim, queue: [] });
+      return { status: "granted", path: key, queue: [] };
+    }
+    if (entry.holder.worker === worker) {
+      entry.holder = claim;
+      return { status: "held", path: key, queue: [...entry.queue] };
+    }
+    const existing = entry.queue.findIndex((queued) => queued.worker === worker);
+    if (existing >= 0) entry.queue[existing] = claim;
+    else entry.queue.push(claim);
+    const position = entry.queue.findIndex((queued) => queued.worker === worker) + 1;
+    if (existing < 0) {
+      this.onEvent({ type: "queued", worker, path: key, holder: entry.holder.worker, position });
+      this.onEvent({ type: "queue", to: entry.holder.worker, path: key, queue: [...entry.queue] });
+    }
+    return { status: "queued", path: key, holder: entry.holder, position };
+  }
+
+  /** True when `worker` currently holds `path`. */
+  holds(worker: WorkerId, path: string): boolean {
+    return this.files.get(this.normalize(path))?.holder.worker === worker;
+  }
+
+  /** Who holds `path`, if anyone. */
+  holderOf(path: string): Claim | undefined {
+    return this.files.get(this.normalize(path))?.holder;
+  }
+
+  /** Hand `path` to whoever is next in its queue, with a note for them; free it when nobody waits. */
+  handover(worker: WorkerId, path: string, note: string): HandoverResult {
+    const key = this.normalize(path);
+    const entry = this.files.get(key);
+    if (!entry || entry.holder.worker !== worker) {
+      return { ok: false, path: key, error: `you do not hold ${key}${entry ? ` (${entry.holder.worker} does)` : ""}` };
+    }
+    const next = this.pass(key, entry, worker, clean(note || "no note", MAX_NOTE), false);
+    return { ok: true, path: key, ...(next ? { to: next } : {}), queue: [...(this.files.get(key)?.queue ?? [])] };
+  }
+
+  /**
+   * Release everything `worker` holds (handing each file to its next worker
+   * with `note(path, next)`) and drop it from every queue. Used when a worker
+   * finishes, crashes or retries.
+   */
+  release(worker: WorkerId, note: (path: string, next: Claim) => string): Handover[] {
+    const passed: Handover[] = [];
+    for (const [key, entry] of [...this.files]) {
+      const before = entry.queue.length;
+      entry.queue = entry.queue.filter((queued) => queued.worker !== worker);
+      if (entry.holder.worker === worker) {
+        const head = entry.queue[0];
+        const next = this.pass(key, entry, worker, head ? clean(note(key, head), MAX_NOTE) : "", true);
+        if (next) passed.push(this.log.at(-1)!);
+      } else if (entry.queue.length !== before) {
+        this.onEvent({ type: "queue", to: entry.holder.worker, path: key, queue: [...entry.queue] });
+      }
+    }
+    const waiter = this.waiters.get(worker);
+    if (waiter) {
+      clearTimeout(waiter.timer);
+      this.waiters.delete(worker);
+      waiter.resolve([]);
+    }
+    this.pendingGrants.delete(worker);
+    return passed;
+  }
+
+  private pass(key: string, entry: Entry, from: WorkerId, note: string, auto: boolean): Claim | undefined {
+    const next = entry.queue.shift();
+    if (!next) {
+      this.files.delete(key);
+      return undefined;
+    }
+    entry.holder = next;
+    this.log.push({ path: key, from, to: next.worker, note, auto, at: this.now() });
+    const event: DeskEvent = { type: "granted", to: next.worker, path: key, from, note, intent: next.intent, queue: [...entry.queue] };
+    this.onEvent(event);
+    this.deliver(next.worker, event);
+    return next;
+  }
+
+  /** Wake a worker blocked in `wait` with its grant, or keep it for its next wait. */
+  private deliver(worker: WorkerId, event: DeskEvent): void {
+    const waiter = this.waiters.get(worker);
+    if (waiter) {
+      clearTimeout(waiter.timer);
+      this.waiters.delete(worker);
+      waiter.resolve([event]);
+      return;
+    }
+    this.pendingGrants.set(worker, [...(this.pendingGrants.get(worker) ?? []), event]);
+  }
+
+  /** Files `worker` holds that someone is waiting for; it must hand these over before it may wait. */
+  owed(worker: WorkerId): FileView[] {
+    return this.heldBy(worker).filter((file) => file.queue.length > 0);
+  }
+
+  heldBy(worker: WorkerId): FileView[] {
+    return [...this.files].filter(([, entry]) => entry.holder.worker === worker).map(([path, entry]) => ({ path, holder: entry.holder, queue: [...entry.queue] }));
+  }
+
+  /** Files `worker` is queued for, with its position. */
+  waitingFor(worker: WorkerId): Array<{ path: string; holder: Claim; position: number }> {
+    return [...this.files].flatMap(([path, entry]) => {
+      const index = entry.queue.findIndex((queued) => queued.worker === worker);
+      return index >= 0 ? [{ path, holder: entry.holder, position: index + 1 }] : [];
+    });
+  }
+
+  /**
+   * Wait up to `timeoutMs` for a file to be handed to `worker`. Refuses while
+   * the worker holds files others are waiting for, which breaks deadlock
+   * cycles: whoever waits first hands over first.
+   */
+  wait(worker: WorkerId, timeoutMs: number): Promise<{ refused?: FileView[]; grants: DeskEvent[] }> {
+    const owed = this.owed(worker);
+    if (owed.length > 0) return Promise.resolve({ refused: owed, grants: [] });
+    const pending = this.pendingGrants.get(worker);
+    if (pending?.length) {
+      this.pendingGrants.delete(worker);
+      return Promise.resolve({ grants: pending });
+    }
+    if (this.waitingFor(worker).length === 0) return Promise.resolve({ grants: [] });
+    return new Promise((done) => {
+      const timer = setTimeout(() => {
+        this.waiters.delete(worker);
+        done({ grants: [] });
+      }, Math.max(0, timeoutMs));
+      this.waiters.set(worker, { resolve: (grants) => done({ grants }), timer });
+    });
+  }
+
+  /** Every handover so far, oldest first. */
+  handovers(): Handover[] {
+    return [...this.log];
+  }
+
+  /** Wake every waiter; called when the batch ends. */
+  close(): void {
+    for (const [worker, waiter] of this.waiters) {
+      clearTimeout(waiter.timer);
+      waiter.resolve([]);
+      this.waiters.delete(worker);
+    }
+  }
+}

package/src/desk/ipc.ts

@@ -0,0 +1,178 @@
+/**
+ * Transport between the file desk (master process) and the workers' pi
+ * processes: newline-delimited JSON requests and responses over a private
+ * Unix socket (a named pipe on Windows). One server per parallel batch.
+ */
+import { randomBytes } from "node:crypto";
+import { chmodSync, rmSync } from "node:fs";
+import { createConnection, createServer, type Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export type DeskOp = "hello" | "check" | "claim" | "handover" | "mine" | "wait";
+
+export interface DeskRequest {
+  id: number;
+  worker: string;
+  op: DeskOp;
+  path?: string;
+  intent?: string;
+  note?: string;
+  timeoutMs?: number;
+}
+
+export interface DeskResponse {
+  id: number;
+  ok: boolean;
+  /** Human-readable answer for the worker's tool result or block reason. */
+  text: string;
+  /** `check` only: whether the worker may edit the file. */
+  allowed?: boolean;
+}
+
+export type DeskHandler = (request: DeskRequest) => Promise<Omit<DeskResponse, "id">>;
+
+export interface DeskServer {
+  address: string;
+  close(): Promise<void>;
+}
+
+function socketAddress(): string {
+  const name = `bl-desk-${process.pid}-${randomBytes(4).toString("hex")}`;
+  return process.platform === "win32" ? `\\\\.\\pipe\\${name}` : join(tmpdir(), `${name}.sock`);
+}
+
+/** Split a byte stream into complete lines, keeping any partial tail. */
+function lineReader(onLine: (line: string) => void): (chunk: string) => void {
+  let buffer = "";
+  return (chunk) => {
+    buffer += chunk;
+    let at = buffer.indexOf("\n");
+    while (at >= 0) {
+      const line = buffer.slice(0, at).trim();
+      buffer = buffer.slice(at + 1);
+      if (line) onLine(line);
+      at = buffer.indexOf("\n");
+    }
+  };
+}
+
+function serve(socket: Socket, handler: DeskHandler): void {
+  socket.setEncoding("utf8");
+  socket.on("error", () => socket.destroy());
+  socket.on(
+    "data",
+    lineReader((line) => {
+      let request: DeskRequest;
+      try {
+        request = JSON.parse(line) as DeskRequest;
+      } catch {
+        return;
+      }
+      handler(request)
+        .catch((error: Error) => ({ ok: false, text: `desk error: ${error.message}` }))
+        .then((response) => {
+          if (!socket.destroyed) socket.write(`${JSON.stringify({ ...response, id: request.id })}\n`);
+        });
+    }),
+  );
+}
+
+/** Start a desk server on a fresh private socket. */
+export async function startDeskServer(handler: DeskHandler): Promise<DeskServer> {
+  const address = socketAddress();
+  const sockets = new Set<Socket>();
+  const server = createServer((socket) => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+    serve(socket, handler);
+  });
+  await new Promise<void>((done, fail) => {
+    server.once("error", fail);
+    server.listen(address, () => done());
+  });
+  if (process.platform !== "win32") {
+    try {
+      chmodSync(address, 0o600);
+    } catch {
+      // Best effort: the socket already lives in the private temp dir.
+    }
+  }
+  return {
+    address,
+    close: () =>
+      new Promise((done) => {
+        for (const socket of sockets) socket.destroy();
+        server.close(() => {
+          if (process.platform !== "win32") rmSync(address, { force: true });
+          done();
+        });
+      }),
+  };
+}
+
+export interface DeskClient {
+  request(request: Omit<DeskRequest, "id" | "worker">, timeoutMs?: number): Promise<DeskResponse>;
+  close(): void;
+}
+
+/** A persistent connection from one worker to the desk; requests fail (never hang) when it is gone. */
+export function createDeskClient(address: string, worker: string): DeskClient {
+  let socket: Socket | undefined;
+  let nextId = 1;
+  const pending = new Map<number, { done: (response: DeskResponse) => void; timer: ReturnType<typeof setTimeout> }>();
+  const failAll = (text: string) => {
+    for (const [id, entry] of pending) {
+      clearTimeout(entry.timer);
+      entry.done({ id, ok: false, text });
+    }
+    pending.clear();
+  };
+  const connect = (): Socket => {
+    if (socket && !socket.destroyed) return socket;
+    const next = createConnection(address);
+    next.setEncoding("utf8");
+    next.on(
+      "data",
+      lineReader((line) => {
+        let response: DeskResponse;
+        try {
+          response = JSON.parse(line) as DeskResponse;
+        } catch {
+          return;
+        }
+        const entry = pending.get(response.id);
+        if (!entry) return;
+        pending.delete(response.id);
+        clearTimeout(entry.timer);
+        entry.done(response);
+      }),
+    );
+    next.on("error", () => failAll("the file desk is unavailable"));
+    next.on("close", () => failAll("the file desk closed"));
+    next.unref();
+    socket = next;
+    return next;
+  };
+  return {
+    request(request, timeoutMs = 10_000) {
+      const id = nextId++;
+      return new Promise((done) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          done({ id, ok: false, text: "the file desk did not answer" });
+        }, timeoutMs);
+        pending.set(id, { done, timer });
+        try {
+          connect().write(`${JSON.stringify({ ...request, id, worker })}\n`);
+        } catch {
+          failAll("the file desk is unavailable");
+        }
+      });
+    },
+    close() {
+      socket?.destroy();
+      socket = undefined;
+    },
+  };
+}

package/src/desk/session.ts

@@ -0,0 +1,214 @@
+/**
+ * One parallel batch's file desk as the master sees it: the checkout table,
+ * the socket the workers talk to, and the messages that keep every worker
+ * informed. Queue changes and handovers reach the right worker as steering
+ * messages over its RPC stdin, and the zen panel sees who is waiting.
+ */
+import { basename } from "node:path";
+import type { AgentHandle } from "../execution/agent-runner.ts";
+import { FileDesk, type Claim, type DeskEvent, type FileView, type Handover, type WorkerId } from "./desk.ts";
+import { startDeskServer, type DeskRequest, type DeskResponse, type DeskServer } from "./ipc.ts";
+
+/** Tools the desk adds to every parallel worker's allowlist. */
+export const DESK_TOOLS: readonly string[] = ["claim_file", "handover_file", "my_files", "wait_for_files"];
+
+/** Env names the desk client extension reads inside a worker process. */
+export const DESK_ENV = { address: "BOT_LOBBY_DESK", worker: "BOT_LOBBY_DESK_ID" } as const;
+
+/** Longest a single `wait_for_files` call may block. */
+export const MAX_WAIT_MS = 120_000;
+
+const EDIT_TOOLS = new Set(["edit", "write"]);
+
+export function isEditTool(name: string): boolean {
+  return EDIT_TOOLS.has(name);
+}
+
+function label(worker: WorkerId): string {
+  const names: Record<string, string> = { backend: "DEV", designer: "DESIGN", qa: "QA" };
+  return names[worker] ?? worker.toUpperCase();
+}
+
+function queueLines(queue: readonly Claim[]): string {
+  return queue.map((claim, index) => `${index + 1}) ${label(claim.worker)} — ${claim.intent}`).join("; ");
+}
+
+/** Steering text for a holder whose queue changed. */
+export function queueMessage(path: string, queue: readonly Claim[]): string {
+  if (queue.length === 0) return `bot-lobby desk: nobody is waiting for \`${path}\` any more.`;
+  const next = queue[0]!;
+  return [
+    `bot-lobby desk: queue for \`${path}\` (you hold it): ${queueLines(queue)}.`,
+    `As soon as you are done with it, call handover_file with a short note for ${label(next.worker)}, who wants to: ${next.intent}.`,
+  ].join(" ");
+}
+
+/** Steering text for a worker who just received a file. */
+export function grantMessage(event: Extract<DeskEvent, { type: "granted" }>): string {
+  const behind = event.queue.length > 0 ? ` Queued behind you: ${queueLines(event.queue)}; hand it over when you are done.` : "";
+  return `bot-lobby desk: \`${event.path}\` is yours now (for: ${event.intent}). ${label(event.from)}'s handover note: ${event.note || "none"}. Re-read the file before editing it.${behind}`;
+}
+
+function describeHeld(files: readonly FileView[]): string {
+  if (files.length === 0) return "You hold no files.";
+  return files
+    .map((file) => `You hold \`${file.path}\` (${file.holder.intent})${file.queue.length > 0 ? `; waiting: ${queueLines(file.queue)}` : "; nobody waiting"}.`)
+    .join("\n");
+}
+
+export interface DeskSessionOptions {
+  cwd: string;
+  /** A worker that finished without handing a file over leaves this note for the next worker. */
+  onHandover?: (handover: Handover) => void;
+}
+
+/** Master-side desk for one batch of parallel workers. */
+export class DeskSession {
+  readonly desk: FileDesk;
+  private server?: DeskServer;
+  private readonly handles = new Map<WorkerId, AgentHandle>();
+  private readonly greeted = new Set<WorkerId>();
+  private readonly options: DeskSessionOptions;
+
+  constructor(options: DeskSessionOptions) {
+    this.options = options;
+    this.desk = new FileDesk(options.cwd, (event) => this.onEvent(event));
+  }
+
+  async open(): Promise<void> {
+    this.server = await startDeskServer((request) => this.handle(request));
+  }
+
+  /** Environment that points one worker's pi process at this desk. */
+  env(worker: WorkerId): Record<string, string> {
+    if (!this.server) throw new Error("desk is not open");
+    return { [DESK_ENV.address]: this.server.address, [DESK_ENV.worker]: worker };
+  }
+
+  /** Remember the running attempt's handle so the desk can steer it. */
+  attach(worker: WorkerId, handle: AgentHandle): void {
+    this.handles.set(worker, handle);
+  }
+
+  /** True once the worker's desk extension has checked in. */
+  greetedBy(worker: WorkerId): boolean {
+    return this.greeted.has(worker);
+  }
+
+  /** End of one attempt: hand everything it held to whoever is next, with `note` for them. */
+  release(worker: WorkerId, note: (path: string, next: Claim) => string): void {
+    this.handles.get(worker)?.annotate({ waitingFor: undefined });
+    this.handles.delete(worker);
+    for (const handover of this.desk.release(worker, note)) this.options.onHandover?.(handover);
+  }
+
+  handovers(): Handover[] {
+    return this.desk.handovers();
+  }
+
+  async close(): Promise<void> {
+    this.desk.close();
+    await this.server?.close();
+    this.server = undefined;
+  }
+
+  private steer(worker: WorkerId, text: string): void {
+    this.handles.get(worker)?.steer(text);
+  }
+
+  private onEvent(event: DeskEvent): void {
+    if (event.type === "queue") {
+      this.steer(event.to, queueMessage(event.path, event.queue));
+      return;
+    }
+    if (event.type === "queued") {
+      this.handles.get(event.worker)?.annotate({ note: `queued for ${basename(event.path)} behind ${label(event.holder)}`, noteKind: "info" });
+      return;
+    }
+    this.steer(event.to, grantMessage(event));
+    this.handles.get(event.to)?.annotate({ note: `got ${basename(event.path)} from ${label(event.from)}`, noteKind: "info", waitingFor: undefined });
+  }
+
+  private async handle(request: DeskRequest): Promise<Omit<DeskResponse, "id">> {
+    const worker = request.worker;
+    switch (request.op) {
+      case "hello":
+        this.greeted.add(worker);
+        return { ok: true, text: "desk connected" };
+      case "check":
+        return this.check(worker, request.path ?? "");
+      case "claim":
+        return this.claim(worker, request.path ?? "", request.intent ?? "");
+      case "handover":
+        return this.handover(worker, request.path ?? "", request.note ?? "");
+      case "mine":
+        return { ok: true, text: this.mine(worker) };
+      case "wait":
+        return this.wait(worker, Math.min(MAX_WAIT_MS, Math.max(1000, request.timeoutMs ?? MAX_WAIT_MS)));
+      default:
+        return { ok: false, text: `unknown desk operation ${String(request.op)}` };
+    }
+  }
+
+  private check(worker: WorkerId, path: string): Omit<DeskResponse, "id"> {
+    if (this.desk.holds(worker, path)) return { ok: true, allowed: true, text: "" };
+    const key = this.desk.normalize(path);
+    const holder = this.desk.holderOf(path);
+    if (!holder) {
+      return { ok: true, allowed: false, text: `Claim \`${key}\` first: call claim_file with its path and a one-line intent (what you will change), then retry this edit.` };
+    }
+    return {
+      ok: true,
+      allowed: false,
+      text: `\`${key}\` is checked out by ${label(holder.worker)} (${holder.intent}). Call claim_file to join its queue, keep working on your other files, and edit it once it is handed to you.`,
+    };
+  }
+
+  private claim(worker: WorkerId, path: string, intent: string): Omit<DeskResponse, "id"> {
+    if (!path.trim()) return { ok: false, text: "claim_file needs a path" };
+    const result = this.desk.claim(worker, path, intent);
+    if (result.status === "queued") {
+      return {
+        ok: true,
+        text: `\`${result.path}\` is with ${label(result.holder.worker)} (${result.holder.intent}); you are #${result.position} in line. Keep working on your other files — you will be told when it is handed to you, with their notes.`,
+      };
+    }
+    const behind = result.queue.length > 0 ? ` Waiting behind you: ${queueLines(result.queue)}.` : "";
+    return { ok: true, text: `\`${result.path}\` is yours. Edit it, then call handover_file with a note as soon as you are done with it.${behind}` };
+  }
+
+  private handover(worker: WorkerId, path: string, note: string): Omit<DeskResponse, "id"> {
+    const result = this.desk.handover(worker, path, note);
+    if (!result.ok) return { ok: false, text: result.error };
+    const handover = this.desk.handovers().at(-1);
+    if (result.to && handover) this.options.onHandover?.(handover);
+    if (!result.to) return { ok: true, text: `\`${result.path}\` released; nobody was waiting for it.` };
+    return { ok: true, text: `\`${result.path}\` handed to ${label(result.to.worker)} with your note.` };
+  }
+
+  private mine(worker: WorkerId): string {
+    const waiting = this.desk.waitingFor(worker).map((entry) => `You are #${entry.position} for \`${entry.path}\` (held by ${label(entry.holder.worker)}: ${entry.holder.intent}).`);
+    return [describeHeld(this.desk.heldBy(worker)), ...waiting].join("\n");
+  }
+
+  private async wait(worker: WorkerId, timeoutMs: number): Promise<Omit<DeskResponse, "id">> {
+    const queuedFor = this.desk.waitingFor(worker);
+    if (queuedFor.length > 0) this.handles.get(worker)?.annotate({ waitingFor: basename(queuedFor[0]!.path) });
+    const result = await this.desk.wait(worker, timeoutMs);
+    this.handles.get(worker)?.annotate({ waitingFor: undefined });
+    if (result.refused) {
+      return { ok: false, text: `Hand these over first — others are waiting for them:\n${describeHeld(result.refused)}` };
+    }
+    const grants = result.grants.filter((event): event is Extract<DeskEvent, { type: "granted" }> => event.type === "granted");
+    if (grants.length > 0) return { ok: true, text: grants.map(grantMessage).join("\n") };
+    if (queuedFor.length === 0) return { ok: true, text: "You are not waiting for any file." };
+    return { ok: true, text: `Still waiting:\n${this.mine(worker)}\nIf nothing else is left, finish your report and list the dependency under Notes; files are handed over automatically when their holder finishes.` };
+  }
+}
+
+/** A handover note for `next`, written from a finished worker's report. */
+export function autoNote(from: WorkerId, path: string, next: Claim, changes: ReadonlyArray<{ path: string; change: string }>, completed: string): string {
+  const match = changes.find((change) => change.path.replace(/\\/g, "/").endsWith(path) || path.endsWith(change.path.replace(/\\/g, "/")));
+  const what = match ? `changed it: ${match.change}` : completed ? `finished; its report says: ${completed.replace(/\s+/g, " ").slice(0, 300)}` : "finished without describing its change";
+  return `${label(from)} ${what} (auto-handover on finish; you asked for: ${next.intent})`;
+}