@a-t-h-i/bot-lobby 0.6.59 → 0.6.60

package/src/desk/delivery.ts

@@ -0,0 +1,243 @@
+/**
+ * Durable delivery of board posts to each recipient: who was actually shown
+ * which post, kept beside the board so a post that lands while its reader is
+ * not attached still reaches it at its next safe boundary, and a restart or
+ * retry never re-delivers or skips one. `lastSeq` means the text reached the
+ * recipient (a steer or a shown read); `handledSeq`/`handled` mean the
+ * recipient said so itself — receipt is not proof of incorporation, so only
+ * an explicit acknowledgement (`ack_board`) moves them. Posts seen out of
+ * order (a fresh blocker pushed ahead of a long backlog) sit in `seen` until
+ * the cursor grows past them, and the cursor itself only moves over posts
+ * the recipient was actually shown: it never advances past an omitted one.
+ * Relevance is routing: the recipient's kind subscription, a post's explicit
+ * targets (its assignment id exactly, or the role it answers to), or — for a
+ * post naming files — holding one of them; an unrouted post never holds a
+ * cursor back. Two same-role workers are two recipients: each has its own
+ * cursors, and only what each was shown and acknowledged moves them.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { readBoard, recipientId, roleOf, subscriptionFor, type BoardPost, type PostKind } from "./board.ts";
+import { tempName, withFileLock } from "./lock.ts";
+
+/** How many undelivered posts one catch-up or push hands over at most. */
+export const REPLAY_LIMIT = 8;
+
+export interface RecipientState {
+  /** Highest sequence the recipient was actually shown; nothing above it is assumed seen. */
+  lastSeq: number;
+  /** Sequences shown out of order above `lastSeq`, waiting for the cursor to grow past them. */
+  seen?: number[];
+  /** Sequences acknowledged above `handledSeq`, waiting for earlier relevant posts to be acknowledged too. */
+  handled?: number[];
+  /** Highest sequence the recipient itself acknowledged (contiguous; `ack_board`), when it has. */
+  handledSeq?: number;
+  at: string;
+}
+
+export interface DeliveryFile { version: 1; recipients: Record<string, RecipientState> }
+
+/** What routes a post to one recipient: its identity, the kinds it follows, and the files it holds or is queued for. */
+export interface RecipientScope {
+  /** The recipient's identity (an assignment id like `backend:9f2c1e`, a domain, a child run id): a post addressing it reaches it alone. */
+  recipient: string;
+  /** The role (domain) the recipient also answers to: a post addressed to the role reaches every worker of that role. */
+  role?: string;
+  /** The post kinds the recipient follows. */
+  kinds: readonly PostKind[];
+  /** Repository files the recipient holds or is queued for: a post naming files reaches intersecting holders. */
+  files?: readonly string[];
+}
+
+/** Whether one explicit target of a post names this recipient: its assignment id exactly, the role it answers to, or the same worker under its other spelling (`backend:9f2c1e` vs `9f2c1e`). */
+export function addressesPost(target: string, scope: RecipientScope): boolean {
+  const id = recipientId(target);
+  const role = scope.role ?? roleOf(scope.recipient);
+  if (id === scope.recipient || (!!role && id === recipientId(role))) return true;
+  const tail = (name: string): string | undefined =>
+    role !== undefined && roleOf(name) === role && name.includes(":") ? name.slice(role.length + 1) : undefined;
+  const targetTail = tail(id);
+  const recipientTail = tail(scope.recipient);
+  return (targetTail !== undefined && targetTail === scope.recipient) || (recipientTail !== undefined && id === recipientTail);
+}
+
+/** Whether a post routes to one recipient: addressed posts to their targets alone (assignment or role), file-named ones to intersecting subscribed holders (or every subscribed reader when no claims are known), the rest to every subscribed reader. */
+export function routedTo(post: BoardPost, scope: RecipientScope): boolean {
+  if (post.to?.length) return post.to.some((target) => addressesPost(target, scope));
+  if (post.files?.length) return scope.kinds.includes(post.kind) && (scope.files === undefined || scope.files.some((file) => post.files!.includes(file)));
+  return scope.kinds.includes(post.kind);
+}
+
+/** Where the delivery state for the board at `boardPath` lives. */
+export function deliveryPath(boardPath: string): string {
+  return `${boardPath}.delivery.json`;
+}
+
+/** The delivery state, or an empty one when absent or corrupt; never throws. */
+export function readDelivery(path: string): DeliveryFile {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<DeliveryFile>;
+    return parsed.version === 1 && typeof parsed.recipients === "object" && parsed.recipients !== null
+      ? { version: 1, recipients: parsed.recipients }
+      : { version: 1, recipients: {} };
+  } catch {
+    return { version: 1, recipients: {} };
+  }
+}
+
+function writeDelivery(path: string, state: DeliveryFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = tempName(path);
+  writeFileSync(temp, JSON.stringify(state), "utf8");
+  renameSync(temp, path);
+}
+
+function update(path: string, recipient: string, next: RecipientState): RecipientState {
+  return withFileLock(path, () => {
+    const state = readDelivery(path);
+    state.recipients[recipient] = next;
+    writeDelivery(path, state);
+    return next;
+  });
+}
+
+/** Advance a recipient's delivered cursor to `seq`, never backwards; `seen` entries it covers are absorbed. Idempotent. */
+export function markDelivered(path: string, recipient: string, seq: number, now = new Date()): RecipientState {
+  const prior = readDelivery(path).recipients[recipient];
+  if (prior && seq <= prior.lastSeq) return prior;
+  const base = prior ?? { lastSeq: 0, at: now.toISOString() };
+  return update(path, recipient, { ...base, lastSeq: Math.max(seq, base.lastSeq), seen: (base.seen ?? []).filter((entry) => entry > seq), at: now.toISOString() });
+}
+
+/** Record an out-of-order delivery without moving the cursor. Idempotent. */
+export function markSeen(path: string, recipient: string, seq: number, now = new Date()): RecipientState {
+  const prior = readDelivery(path).recipients[recipient] ?? { lastSeq: 0, at: now.toISOString() };
+  if (seq <= prior.lastSeq || (prior.seen ?? []).includes(seq)) return prior;
+  return update(path, recipient, { ...prior, seen: [...(prior.seen ?? []), seq].sort((a, b) => a - b), at: now.toISOString() });
+}
+
+/** Which posts an acknowledgement may cover: everything the recipient's subscription, its role or an explicit address makes its business — and so everything a kinds-only window (a read or a start context) must not be allowed to skip. */
+export function ackRelevant(post: BoardPost, recipient: string, kinds: readonly PostKind[]): boolean {
+  const role = roleOf(recipient);
+  return kinds.includes(post.kind) || !!post.to?.some((target) => [recipient, ...(role ? [role] : [])].includes(recipientId(target)));
+}
+
+/** The post one acknowledged event names: a sequence (`3`, `#3`) or a stable post id. */
+function resolveEvent(event: string | number, posts: readonly BoardPost[]): BoardPost | undefined {
+  if (typeof event === "number") return posts.find((post) => post.seq === event);
+  const trimmed = event.trim().replace(/^#/, "");
+  return /^\d+$/.test(trimmed)
+    ? posts.find((post) => post.seq === Number(trimmed))
+    : posts.find((post) => post.id === event.trim());
+}
+
+/**
+ * Fold acknowledgements into handled state: the contiguous `handledSeq`
+ * cursor stops before the first relevant post the recipient has not
+ * acknowledged, and out-of-order acknowledgements wait in `handled`.
+ */
+function handledAfter(posts: readonly BoardPost[], prior: RecipientState | undefined, recipient: string, acked: readonly number[], now: Date): RecipientState {
+  const kinds = subscriptionFor(recipient);
+  const done = new Set([...(prior?.handled ?? []), ...acked]);
+  let cursor = prior?.handledSeq ?? 0;
+  for (const post of [...posts].sort((a, b) => a.seq - b.seq)) {
+    if (!ackRelevant(post, recipient, kinds)) continue;
+    if (!done.has(post.seq) && post.seq > cursor) break;
+    cursor = Math.max(cursor, post.seq);
+  }
+  const handled = [...done].filter((seq) => seq > cursor).sort((a, b) => a - b);
+  const next: RecipientState = { ...(prior ?? { lastSeq: 0 }), handled, handledSeq: cursor, at: now.toISOString() };
+  if (handled.length === 0) delete next.handled;
+  return next;
+}
+
+export interface AckResult {
+  /** The posts the acknowledgement covers, oldest first (already-acknowledged ones included: it is idempotent). */
+  acknowledged: BoardPost[];
+  /** Events that name nothing on this board; nothing was recorded for them. */
+  unknown: string[];
+  /** Events outside the recipient's scope, as `#seq`; nothing was recorded at all. */
+  refused: string[];
+  state: RecipientState;
+}
+
+/**
+ * Record that `recipient` incorporated the given board events (sequences or
+ * stable ids). Idempotent, atomic, and scope-checked: an event that is
+ * neither in the recipient's subscription nor addressed to it refuses the
+ * whole call, and the handled cursor never skips a relevant post waiting for
+ * its own acknowledgement.
+ */
+export function markHandled(boardPath: string, recipient: string, events: readonly (string | number)[], now = new Date()): AckResult {
+  const path = deliveryPath(boardPath);
+  const board = readBoard(boardPath);
+  const kinds = subscriptionFor(recipient);
+  const found = events.map((event) => ({ event, post: resolveEvent(event, board) }));
+  const unknown = found.filter((entry) => !entry.post).map((entry) => String(entry.event));
+  const acknowledged = found.filter((entry) => entry.post).map((entry) => entry.post!);
+  const refused = acknowledged.filter((post) => !ackRelevant(post, recipient, kinds)).map((post) => `#${post.seq}`);
+  const prior = readDelivery(path).recipients[recipient] ?? { lastSeq: 0, at: now.toISOString() };
+  if (refused.length > 0) return { acknowledged: [], unknown, refused, state: prior };
+  const state = update(path, recipient, handledAfter(board, prior, recipient, acknowledged.map((post) => post.seq), now));
+  return { acknowledged, unknown, refused: [], state };
+}
+
+/** The posts that route to this recipient's scope and that it has not been shown yet, oldest first. */
+export function undeliveredFor(posts: readonly BoardPost[], state: RecipientState | undefined, scope: RecipientScope): BoardPost[] {
+  const seen = new Set(state?.seen ?? []);
+  return posts
+    .filter((post) => routedTo(post, scope) && post.seq > (state?.lastSeq ?? 0) && !seen.has(post.seq))
+    .sort((a, b) => a.seq - b.seq);
+}
+
+/** One bounded catch-up: the oldest undelivered posts, and the sequence the cursor may safely move to. */
+export function replayFor(posts: readonly BoardPost[], state: RecipientState | undefined, scope: RecipientScope, limit = REPLAY_LIMIT): { posts: BoardPost[]; through: number; waiting: number } {
+  const pending = undeliveredFor(posts, state, scope);
+  const batch = pending.slice(0, limit);
+  return { posts: batch, through: batch.at(-1)?.seq ?? (state?.lastSeq ?? 0), waiting: pending.length - batch.length };
+}
+
+/**
+ * The newest sequence one shown window proves delivered: the cursor grows
+ * over the relevant posts the window showed, oldest first, and stops at the
+ * first relevant one the window omitted — nothing unshown is ever claimed.
+ */
+export function provenThrough(posts: readonly BoardPost[], shown: ReadonlySet<number>, relevant: (post: BoardPost) => boolean, start = 0): number {
+  let through = start;
+  for (const post of [...posts].sort((a, b) => a.seq - b.seq)) {
+    if (post.seq <= through || !relevant(post)) continue;
+    if (!shown.has(post.seq)) break;
+    through = post.seq;
+  }
+  return through;
+}
+
+/**
+ * The sequence a start context (the board lines in a prompt) lets a
+ * recipient assume seen: the cursor grows over the relevant posts the
+ * context showed — its kinds, and anything addressed to it — and stops at
+ * the first one it did not. A truncated context proves nothing above its
+ * oldest shown post; posts routed only by files wait for the desk that
+ * knows the claims.
+ */
+export function deliveredThrough(posts: readonly BoardPost[], recipient: string, limit: number): number {
+  const kinds = subscriptionFor(recipient);
+  const shown = new Set(posts.filter((post) => kinds.includes(post.kind)).sort((a, b) => a.seq - b.seq).slice(-limit).map((post) => post.seq));
+  return provenThrough(posts, shown, (post) => ackRelevant(post, recipient, kinds));
+}
+
+/**
+ * Seed a recipient's cursor from the board lines its start prompt showed,
+ * before any push can race the read. Never lowers the cursor; posts the
+ * context showed beyond the stop are recorded seen so they are not
+ * re-delivered later.
+ */
+export function seedDelivery(boardPath: string, recipient: string, limit = 30, now = new Date()): void {
+  const posts = readBoard(boardPath);
+  const kinds = subscriptionFor(recipient);
+  const window = posts.filter((post) => kinds.includes(post.kind)).sort((a, b) => a.seq - b.seq).slice(-limit);
+  const through = provenThrough(posts, new Set(window.map((post) => post.seq)), (post) => ackRelevant(post, recipient, kinds));
+  const state = deliveryPath(boardPath);
+  if (through > 0) markDelivered(state, recipient, through, now);
+  for (const post of window) if (post.seq > through) markSeen(state, recipient, post.seq, now);
+}

package/src/desk/ipc.ts

@@ -9,7 +9,22 @@ 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" | "delegate" | "cancel_delegate" | "consult" | "cancel_consult" | "post" | "ask" | "answer";
+export type DeskOp =
+  | "hello"
+  | "check"
+  | "claim"
+  | "handover"
+  | "mine"
+  | "wait"
+  | "delegate"
+  | "cancel_delegate"
+  | "consult"
+  | "cancel_consult"
+  | "post"
+  | "ack"
+  | "ask"
+  | "answer"
+  | "artifact";
 
 export interface DeskRequest {
   id: number;
@@ -25,12 +40,30 @@ export interface DeskRequest {
   kind?: string;
   text?: string;
   files?: string[];
+  /** post: recipients the post is addressed to (worker ids or domains); it is pushed only to them. */
+  targets?: string[];
+  /** ack: the board events (sequences or stable ids) the caller says it incorporated. */
+  events?: Array<string | number>;
   /** ask: who the question is for (DEV, DESIGN, QA); `path` asks whoever holds that file. */
   to?: string;
   /** answer: the question being answered. */
   questionId?: number;
   /** An expert consult's own id, so the worker can cancel it. */
   consultId?: string;
+  /** artifact: the caller's own assignment id; volunteered, never trusted on its own. */
+  assignment?: string;
+  /** artifact: the O-… reference to open. */
+  ref?: string;
+  /** artifact: byte offset to continue from. */
+  offset?: number;
+}
+
+/**
+ * The artifact op's caller identity: the socket token already names the caller, and any
+ * assignment it volunteers must be the host's own, so unrelated or unregistered ids deny.
+ */
+export function artifactIdentity(request: Pick<DeskRequest, "op" | "assignment">, hostAssignment: string | undefined): boolean {
+  return request.op === "artifact" && typeof hostAssignment === "string" && hostAssignment.length > 0 && request.assignment === hostAssignment;
 }
 
 export interface DeskResponse {

package/src/desk/lock.ts

@@ -0,0 +1,81 @@
+/**
+ * A cooperative file lock shared by the board, its delivery state and the
+ * scout-note and file caches: a directory made atomically beside the target
+ * file, so several processes take turns over one read-modify-write. A lock
+ * left behind by a crashed process is broken once stale; a caller that
+ * cannot get the lock in time fails closed rather than writing beside the
+ * holder and losing changes. Temp names carry the pid and a random suffix,
+ * so concurrent writers never collide.
+ */
+import { mkdirSync, rmSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** How long a writer waits for another process's write, and when a lock is taken to be left behind. */
+export const LOCK_WAIT_MS = 2000;
+export const STALE_LOCK_MS = 10_000;
+
+export const LOCK_BUSY = "the board is busy; try again";
+
+function sleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** A lock's identity: the inode of the directory currently holding it. */
+function lockIdentity(lock: string): string | undefined {
+  try {
+    return String(statSync(lock).ino);
+  } catch {
+    return undefined;
+  }
+}
+
+/** False once the lock directory was broken and replaced: another writer may hold it. */
+function stillOurs(lock: string, identity: string | undefined): boolean {
+  return identity !== undefined && lockIdentity(lock) === identity;
+}
+
+/**
+ * Run `write` holding the lock for `path` (a directory beside it, made
+ * atomically). Throws `LOCK_BUSY` when another live writer holds it past the
+ * wait, so no write ever happens beside the holder's. A lock broken as stale
+ * while its (slow, not dead) holder kept running is detected before the
+ * write: the holder retries from acquisition instead of writing beside the
+ * writer that broke it, and never removes a successor's lock on release.
+ */
+export function withFileLock<T>(path: string, write: () => T): T {
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = `${path}.lock`;
+  const until = Date.now() + LOCK_WAIT_MS;
+  while (true) {
+    try {
+      mkdirSync(lock);
+    } catch {
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > STALE_LOCK_MS) rmSync(lock, { recursive: true, force: true });
+      } catch {
+        // Released meanwhile; the next attempt takes it.
+      }
+      if (Date.now() > until) throw new Error(LOCK_BUSY);
+      sleep(5);
+      continue;
+    }
+    const identity = lockIdentity(lock);
+    if (!stillOurs(lock, identity)) {
+      // Broken from under us before the write: take it again rather than write beside the breaker.
+      if (Date.now() > until) throw new Error(LOCK_BUSY);
+      sleep(5);
+      continue;
+    }
+    try {
+      return write();
+    } finally {
+      if (stillOurs(lock, identity)) rmSync(lock, { recursive: true, force: true });
+    }
+  }
+}
+
+/** A temp file name for `path` that no concurrent writer can also pick. */
+export function tempName(path: string): string {
+  return `${path}.${process.pid}.${randomUUID()}.tmp`;
+}

package/src/desk/session.ts

@@ -8,7 +8,9 @@ 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";
-import { appendPost, formatPost, isPostKind, PUSHED_KINDS, SUBSCRIPTIONS, subscriptionFor, type BoardPost } from "./board.ts";
+import { appendPost, formatPosts, isPostKind, posterName, PUSHED_KINDS, readBoard, recipientId, roleOf, subscriptionFor, type BoardPost } from "./board.ts";
+import { ackText } from "./board-client.ts";
+import { deliveryPath, markDelivered, markHandled, markSeen, readDelivery, replayFor, routedTo, type RecipientScope, REPLAY_LIMIT, undeliveredFor } from "./delivery.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"];
@@ -35,15 +37,15 @@ export function isEditTool(name: string): boolean {
 }
 
 function label(worker: WorkerId): string {
-  const names: Record<string, string> = { backend: "DEV", designer: "DESIGN", qa: "QA" };
-  return names[worker] ?? worker.toUpperCase();
+  return posterName(worker);
 }
 
-/** A peer named the way workers know each other (DEV, DESIGN, QA) or by domain. */
+/** A holder named for a handover message: its role when it has one (the note speaks for the role), its full identity otherwise. */
+const roleLabel = (worker: WorkerId): string => label((roleOf(worker) ?? worker) as WorkerId);
+
+/** A peer named the way workers know each other (DEV, DESIGN, QA) or by domain; a child run id is itself. */
 export function peerId(name: string): WorkerId {
-  const key = name.trim().toLowerCase();
-  const ids: Record<string, string> = { dev: "backend", backend: "backend", design: "designer", designer: "designer", qa: "qa" };
-  return ids[key] ?? name.trim();
+  return recipientId(name) as WorkerId;
 }
 
 function flat(text: string, max: number): string {
@@ -77,7 +79,7 @@ export function queueMessage(path: string, queue: readonly Claim[]): string {
 /** 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}`;
+  return `bot-lobby desk: \`${event.path}\` is yours now (for: ${event.intent}). ${roleLabel(event.from)}'s handover note: ${event.note || "none"}. Re-read the file before editing it.${behind}`;
 }
 
 function describeHeld(files: readonly FileView[]): string {
@@ -131,9 +133,10 @@ export class DeskSession {
     return { [DESK_ENV.address]: this.server.address, [DESK_ENV.worker]: worker };
   }
 
-  /** Remember the running attempt's handle so the desk can steer it. */
+  /** Remember the running attempt's handle so the desk can steer it, and catch it up on what it has not been shown. */
   attach(worker: WorkerId, handle: AgentHandle): void {
     this.handles.set(worker, handle);
+    this.catchUp(worker);
   }
 
   /** False when every worker has a checkout of its own and edits need no claim. */
@@ -194,7 +197,7 @@ export class DeskSession {
       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 });
+    this.handles.get(event.to)?.annotate({ note: `got ${basename(event.path)} from ${roleLabel(event.from)}`, noteKind: "info", waitingFor: undefined });
   }
 
   private async handle(request: DeskRequest): Promise<Omit<DeskResponse, "id">> {
@@ -214,7 +217,9 @@ export class DeskSession {
       case "wait":
         return this.wait(worker, Math.min(MAX_WAIT_MS, Math.max(1000, request.timeoutMs ?? MAX_WAIT_MS)));
       case "post":
-        return this.post(request.from?.trim() || worker, worker, request.kind ?? "", request.text ?? "", request.files ?? []);
+        return this.post(request.from?.trim() || worker, worker, request.kind ?? "", request.text ?? "", request.files ?? [], request.targets ?? []);
+      case "ack":
+        return this.ack(worker, request.events ?? []);
       case "ask":
         return this.ask(worker, request.to ?? "", request.path ?? "", request.text ?? "", Math.min(MAX_ASK_WAIT_MS, Math.max(5000, request.timeoutMs ?? ASK_WAIT_MS)));
       case "answer":
@@ -279,24 +284,86 @@ export class DeskSession {
     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.` };
   }
 
-  private post(from: string, worker: WorkerId, kind: string, text: string, files: readonly string[]): Omit<DeskResponse, "id"> {
+  private post(from: string, worker: WorkerId, kind: string, text: string, files: readonly string[], targets: readonly string[]): Omit<DeskResponse, "id"> {
     if (!this.options.boardPath) return { ok: false, text: "This task has no board." };
     if (!isPostKind(kind)) return { ok: false, text: `Unknown post kind "${kind}".` };
+    const to = [...new Set(targets.map((target) => recipientId(target)).filter(Boolean))];
     let post: BoardPost;
     try {
-      post = appendPost(this.options.boardPath, { from, kind, text, files: files.map((file) => this.desk.normalize(file)) });
+      post = appendPost(this.options.boardPath, { from, kind, text, files: files.map((file) => this.desk.normalize(file)), ...(to.length > 0 ? { to } : {}) });
     } catch (error) {
       return { ok: false, text: (error as Error).message };
     }
     let told: string[] = [];
-    if (PUSHED_KINDS.has(post.kind)) {
-      // Only the batch's named workers hear posts as they land; children read the board when they need it.
-      told = [...this.handles.keys()].filter((peer) => peer !== worker && peer in SUBSCRIPTIONS && subscriptionFor(peer).includes(post.kind));
-      for (const peer of told) this.steer(peer, `bot-lobby board: ${formatPost(post)}`);
-    }
+    // Unaddressed contracts and blockers reach the other workers at once; addressed or file-named posts reach exactly who they route to.
+    if (PUSHED_KINDS.has(post.kind) || to.length > 0 || post.files?.length) told = this.deliverPost(post, worker);
     return { ok: true, text: `Posted #${post.seq}.${told.length > 0 ? ` ${told.map(label).join(", ")} ${told.length === 1 ? "was" : "were"} told now.` : ""}` };
   }
 
+  /** The worker's acknowledgements of board events it incorporated: scope-checked, idempotent, never skipping an earlier relevant one. */
+  private ack(worker: WorkerId, events: Array<string | number>): Omit<DeskResponse, "id"> {
+    if (!this.options.boardPath) return { ok: false, text: "This task has no board." };
+    if (events.length === 0) return { ok: false, text: "ack_board needs the events: `#3`-style numbers or post ids." };
+    return { ok: true, text: ackText(markHandled(this.options.boardPath, worker, events)) };
+  }
+
+  /** A consequential post just landed: each peer it routes to hears it now, never only when it next reads. */
+  private deliverPost(post: BoardPost, worker: WorkerId): WorkerId[] {
+    const told: WorkerId[] = [];
+    for (const peer of this.peersFor(post, worker)) {
+      if (this.deliverTo(peer, post)) told.push(peer);
+    }
+    return told;
+  }
+
+  private peersFor(post: BoardPost, worker: WorkerId): WorkerId[] {
+    return [...this.handles.keys()].filter((peer) => peer !== worker && routedTo(post, this.scopeFor(peer)));
+  }
+
+  /** One peer's delivery scope: its subscription, its role, and the files it holds or is queued for (when claims carry meaning). */
+  private scopeFor(peer: WorkerId): RecipientScope {
+    const kinds = subscriptionFor(peer);
+    const role = roleOf(peer);
+    const base = { recipient: peer, ...(role && role !== peer ? { role } : {}), kinds };
+    if (!this.usesClaims) return base;
+    const files = [...this.desk.heldBy(peer).map((file) => file.path), ...this.desk.waitingFor(peer).map((entry) => entry.path)];
+    return { ...base, files };
+  }
+
+  /** Show one peer the fresh post behind any backlog, oldest first; the cursor moves only over what was sent, so a skipped steer is retried later. */
+  private deliverTo(peer: WorkerId, post: BoardPost): boolean {
+    const board = this.options.boardPath!;
+    const path = deliveryPath(board);
+    const queue = undeliveredFor(readBoard(board), readDelivery(path).recipients[peer], this.scopeFor(peer));
+    const batch = queue.slice(0, REPLAY_LIMIT);
+    const extra = queue.filter((entry) => !batch.includes(entry));
+    const shown = extra.includes(post) ? [...batch, post] : batch;
+    const waiting = queue.length - shown.length;
+    try {
+      this.steer(peer, `bot-lobby board: ${formatPosts(shown)}${waiting > 0 ? `\n(+${waiting} older board posts waiting; read_board shows them.)` : ""}`);
+    } catch {
+      return false;
+    }
+    markDelivered(path, peer, batch.at(-1)?.seq ?? post.seq);
+    // Only the batch and the fresh post were shown; the backlog beyond them stays pending for the next catch-up.
+    if (extra.includes(post)) markSeen(path, peer, post.seq);
+    return true;
+  }
+
+  /** Show a just-attached worker the board posts it was never shown, bounded; a steer that cannot be sent leaves them undelivered. */
+  private catchUp(worker: WorkerId): void {
+    if (!this.options.boardPath) return;
+    const path = deliveryPath(this.options.boardPath);
+    const { posts, through, waiting } = replayFor(readBoard(this.options.boardPath), readDelivery(path).recipients[worker], this.scopeFor(worker));
+    if (posts.length === 0) return;
+    try {
+      this.steer(worker, `bot-lobby board: ${formatPosts(posts)}${waiting > 0 ? `\n(+${waiting} older board posts waiting; read_board shows them.)` : ""}`);
+    } catch {
+      return;
+    }
+    markDelivered(path, worker, through);
+  }
+
   private async ask(worker: WorkerId, to: string, path: string, question: string, timeoutMs: number): Promise<Omit<DeskResponse, "id">> {
     if (!this.options.peers) return { ok: false, text: "No peers work alongside you here." };
     const text = flat(question, MAX_QUESTION);

package/src/execution/agent-runner.ts

@@ -6,6 +6,7 @@ import { roleSpec } from "../roles/registry.ts";
 import { compilePrompt } from "../prompts/compiler.ts";
 import { EditLog } from "../state/changes.ts";
 import { runPiAgent, spawnPiProcess, type ProcessRunner, type RelayAsk } from "./pi-runner.ts";
+import { KNOWLEDGE_TOOLS, TASK_ID_ENV } from "../knowledge/catalog-tools.ts";
 import { ASK_ENV } from "../ask/relay.ts";
 import type { EffortRouter, RunProfileLike } from "../classifier/effort.ts";
 import { ASK_TOOL } from "../ask/types.ts";
@@ -16,6 +17,8 @@ export interface AgentContext {
   standards?: string;
   knowledge?: string;
   decisions?: string;
+  /** Assignment bookmarks: bounded reference metadata pointing into the knowledge catalogue. */
+  bookmarks?: string;
   /** The shared scripts that fit the step. */
   scripts?: string;
   /** Per-agent custom instructions from the global config. */
@@ -148,9 +151,14 @@ function baseRun(request: AgentRequest, runId: string, startedAt: string, attemp
   };
 }
 
+/** Compiled repository roles may read knowledge; prompt contents never confer access. */
+function hasKnowledgeAccess(request: AgentRequest): boolean {
+  return request.systemPrompt === undefined && ["scout", "worker", "reviewer"].includes(request.role);
+}
+
 function toolsFor(request: AgentRequest): readonly string[] | undefined {
   const tools = roleSpec(request.role).tools;
-  const extra = [...(request.extraTools ?? []), ...(request.onAsk ? [ASK_TOOL] : [])];
+  const extra = [...(request.extraTools ?? []), ...(hasKnowledgeAccess(request) ? KNOWLEDGE_TOOLS : []), ...(request.onAsk ? [ASK_TOOL] : [])];
   if (extra.length === 0) return tools;
   return [...(tools ?? []), ...extra];
 }
@@ -197,7 +205,7 @@ async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt:
       signal,
       ...(request.onAsk ? { onAsk: request.onAsk } : {}),
       ...(request.harness ? { harness: request.harness } : {}),
-      env: request.onAsk ? { ...request.env, [ASK_ENV]: "1" } : request.env,
+      env: { ...request.env, [TASK_ID_ENV]: request.taskId, ...(request.onAsk ? { [ASK_ENV]: "1" } : {}) },
       stallTimeoutMs: request.stallTimeoutMs,
       toolStallTimeoutMs: request.toolStallTimeoutMs,
       onEvent: (event) => {