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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.6.59",
+  "version": "0.6.61",
   "description": "Structured multi-agent software engineering orchestrator for Pi",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,16 +47,16 @@
     "test": "node --test --test-reporter=dot test/*.test.ts"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=1.3.0 <1.4.0",
-    "@earendil-works/pi-coding-agent": ">=1.3.0 <1.4.0",
-    "@earendil-works/pi-tui": ">=1.3.0 <1.4.0",
+    "@earendil-works/pi-ai": ">=1.4.0 <1.5.0",
+    "@earendil-works/pi-coding-agent": ">=1.4.0 <1.5.0",
+    "@earendil-works/pi-tui": ">=1.4.0 <1.5.0",
     "typebox": "*"
   },
   "devDependencies": {
     "@axe-core/playwright": "4.13.0",
-    "@earendil-works/pi-ai": "1.3.0",
-    "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "1.3.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@fontsource-variable/dm-sans": "^5.3.0",
     "@fontsource-variable/figtree": "^5.3.0",
     "@fontsource-variable/fira-code": "^5.3.0",

package/prompts/global.md

@@ -38,7 +38,8 @@ are your authority, so:
 - Start from what your context already gives you: the brief's paths and
   `path:line` anchors, the **Repository map** (files matching your step, with
   what each is for and the names it declares) and any **Likely files**. Search
-  only for what they do not answer.
+  only for what they do not answer. All of them are hints: verify what you
+  rely on.
 - When you need several reads or searches that do not depend on each other,
   make them all in one turn (several tool calls in one message): they run in
   parallel and save a round trip each.

package/prompts/worker.md

@@ -9,10 +9,8 @@ domain-specific responsibility.
 - Inspect existing patterns.
 - Verify Scout findings against the repository.
 - Grep/find callers before changing shared behavior.
-- Open the files and `path:line` anchors your brief and the scout findings
-  name first, then the **Repository map** and any **Likely files** section;
-  with the `find_relevant_files` tool, describe what you need in plain words
-  before walking the tree. All of them are hints: verify what you rely on.
+- When the `find_relevant_files` tool is available, describe what you need in
+  plain words before walking the tree.
 - Identify relevant tests.
 
 You may disagree with Scout findings when repository evidence contradicts
@@ -20,11 +18,6 @@ them.
 
 ## Implementation
 
-- Follow the approved plan and your brief exactly: they are the Master's
-  decisions. Do not substitute your own design, rename things, or widen the
-  step. If the code contradicts the brief, do not improvise: report it.
-- Follow domain boundaries.
-
 If you need a new dependency, or you believe a significant architectural
 change is required, do not make that change. Report it under the matching
 section of your output instead and continue with the rest of the work.

package/src/classifier/files.ts

@@ -13,11 +13,12 @@
  * indexed.
  */
 import { execFile } from "node:child_process";
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { dataRoot } from "../state/project.ts";
+import { tempName, withFileLock } from "../desk/lock.ts";
 import type { Classifier } from "./classifier.ts";
 import { noul, yesOf, type SystemOneRequest } from "./client.ts";
 import { clip, LIMITS } from "./limits.ts";
@@ -240,7 +241,15 @@ interface CacheFile {
 }
 
 export function fileCachePath(scope: FileScope): string {
-  return join(dataRoot(scope.root, scope.configDir), "cache", "files.json");
+  // One cache per canonical worktree (symlinks resolved): parallel worktrees share a data root but not a cache, so they stop evicting each other.
+  let slug = "default";
+  try {
+    slug = realpathSync(scope.cwd).replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+/, "").slice(-48) || "default";
+  } catch {
+    // A missing tree gets no cache to thrash; the slug stays distinct from any real one.
+    slug = `missing-${scope.cwd.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+/, "").slice(-40)}` || "default";
+  }
+  return join(dataRoot(scope.root, scope.configDir), "cache", `files-${slug}.json`);
 }
 
 function readCache(scope: FileScope): Record<string, CacheEntry> {
@@ -255,11 +264,14 @@ function readCache(scope: FileScope): Record<string, CacheEntry> {
 function writeCache(scope: FileScope, files: Record<string, CacheEntry>): void {
   const path = fileCachePath(scope);
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(`${path}.tmp`, JSON.stringify({ version: 1, cwd: scope.cwd, files } satisfies CacheFile));
-    renameSync(`${path}.tmp`, path);
+    withFileLock(path, () => {
+      mkdirSync(dirname(path), { recursive: true });
+      const temp = tempName(path);
+      writeFileSync(temp, JSON.stringify({ version: 1, cwd: scope.cwd, files } satisfies CacheFile));
+      renameSync(temp, path);
+    });
   } catch {
-    // The cache is an optimisation; a read-only tree just re-reads next time.
+    // The cache is an optimisation; a busy or read-only tree just re-reads next time.
   }
 }
 

package/src/classifier/instance.ts

@@ -14,7 +14,7 @@ import type { ScriptPicker } from "../scripts/pick.ts";
 import type { KeySource, KeyStatus } from "./hosts.ts";
 import { fileHinter, type FileHinter, type FileScope } from "./files.ts";
 import { withRepoMap } from "../knowledge/repo-map.ts";
-import { knowledgePicker, type KnowledgePicker } from "./knowledge.ts";
+import { bookmarkSelector, knowledgePicker, type KnowledgePicker } from "./knowledge.ts";
 import { lobbyFeed } from "../lobby/feed.ts";
 import { triageLine, triageWithContext } from "./triage.ts";
 import type { TaskTriage } from "../schemas/task.ts";
@@ -67,7 +67,7 @@ export function hintsFor(scope: FileScope): FileHinter {
 /** Relevant knowledge and shared scripts for agents, with what Jev kept and matched logged to the lobby's activity feed. */
 export function knowledgeFor(): KnowledgePicker {
   const log = (text: string) => lobbyFeed.log("CLASSIFIER", text, "info");
-  return { ...knowledgePicker(classifier(), log), scripts: scriptPicker(classifier(), log) };
+  return { ...knowledgePicker(classifier(), log), scripts: scriptPicker(classifier(), log), bookmarks: bookmarkSelector(classifier(), log) };
 }
 
 /** Shared scripts for a lobby chat agent, with what Jev matched logged to the lobby's activity feed. */

package/src/classifier/knowledge.ts

@@ -12,10 +12,13 @@
  * keyword selection, which is what agents got before.
  */
 import { basename } from "node:path";
+import { createHash } from "node:crypto";
 import { score, selectRelevant, splitSections, tokenize, type KnowledgeInput, type KnowledgeSelection } from "../knowledge/selector.ts";
+import { BOOKMARK_DEADLINE_MS, lexicalBookmarks, MAX_AUTO_BOOKMARKS, type Selection } from "../knowledge/bookmarks.ts";
+import type { CatalogueEntry } from "../knowledge/catalogue.ts";
 import type { Classifier } from "./classifier.ts";
-import { noul, yesOf, type SystemOneRequest } from "./client.ts";
 import { clip } from "./limits.ts";
+import { noul, yesOf, type SystemOneRequest } from "./client.ts";
 import type { ScriptPicker } from "../scripts/pick.ts";
 
 /** How many characters of each knowledge file a prompt has room for. */
@@ -106,6 +109,8 @@ export interface KnowledgePicker {
   select(task: string, files: KnowledgeInput, options?: { signal?: AbortSignal; paths?: KnowledgePaths }): Promise<KnowledgeSelection>;
   /** Which shared scripts fit a step; shared words when absent. */
   scripts?: ScriptPicker;
+  /** Picks assignment bookmarks from bounded catalogue metadata; absent leaves bookmarks to the lexical fallback. */
+  bookmarks?: BookmarkSelector;
 }
 
 const SLICES: readonly KnowledgeSlice[] = ["knowledge", "standards", "decisions"];
@@ -159,3 +164,121 @@ export function knowledgePicker(classifier: Classifier, log?: (text: string) =>
     },
   };
 }
+
+/**
+ * Bookmark selection. The classifier sees bounded catalogue metadata — one
+ * short line per candidate reference, never a knowledge passage — and answers
+ * one yes/no per candidate. Candidates are the lexically best twelve, so the
+ * call is small and bounded; the whole preparation waits at most
+ * `BOOKMARK_DEADLINE_MS` and any failure, disablement or timeout falls back to
+ * the deterministic lexical selection, which never blocks work. Selections are
+ * cached by assignment input and catalogue revision, so unrelated task
+ * activity does not rebuild them.
+ */
+export const BOOKMARK_CANDIDATES = 12;
+const META_LINE_CHARS = 400;
+const CACHE_LIMIT = 64;
+
+/** A candidate reference as the classifier sees it: id, title, kind, agent and a bounded description. */
+export function metaLine(entry: CatalogueEntry): string {
+  const heading = entry.locator.heading ? ` > ${entry.locator.heading}` : "";
+  return clip(`${entry.id} · ${entry.title}${heading} · ${entry.kind} by ${entry.agent} · ${entry.description}`, META_LINE_CHARS);
+}
+
+/** One request that asks about each candidate reference. */
+export function refRequest(assignment: string, metas: readonly string[]): SectionCall {
+  const entries: Record<string, string> = {};
+  const questions: SystemOneRequest["questions"] = {};
+  const keys = new Map<string, number>();
+  metas.forEach((meta, position) => {
+    const key = `r${position + 1}`;
+    entries[key] = meta;
+    questions[key] = noul(`Should reference \`sections.${key}\` be bookmarked for an agent doing \`task\`? Yes when the knowledge, standard, decision or finding it points to bears on the code, files, conventions or choices the task touches; no when it is about something else or only shares words with it.`);
+    keys.set(key, position);
+  });
+  return { request: { state: { task: clip(assignment, 3000), sections: entries }, questions }, keys };
+}
+
+export interface BookmarkPick {
+  ref: string;
+  reason: string;
+  revision: number;
+  /** Who picked it: the classifier judged it, or the lexical fallback did. */
+  source: "classifier" | "lexical";
+}
+
+export interface BookmarkSelectorInput {
+  assignment: string;
+  /** Non-stale catalogue entries this caller may see. */
+  entries: readonly CatalogueEntry[];
+  /** The catalogue revision the entries stand for; it forms the cache key. */
+  catalogueRevision: number;
+  /** Distinguishes parallel selections with the same assignment (task and recipient). */
+  cacheKey?: string;
+  signal?: AbortSignal;
+}
+
+export type BookmarkSource = BookmarkPick["source"];
+
+export interface BookmarkSelector {
+  select(input: BookmarkSelectorInput): Promise<BookmarkPick[]>;
+}
+
+/** The picks the classifier's answers keep: relevant candidates, best first, within the automatic cap. */
+export function picksFromAnswers(relevance: ReadonlyMap<number, number>, candidates: readonly CatalogueEntry[], floor: number): BookmarkPick[] {
+  return [...relevance]
+    .filter(([, value]) => value >= floor)
+    .sort((a, b) => b[1] - a[1] || a[0] - b[0])
+    .slice(0, MAX_AUTO_BOOKMARKS)
+    .map(([index]) => ({ ref: candidates[index]!.id, reason: "judged relevant to this assignment", revision: candidates[index]!.revision, source: "classifier" as const }));
+}
+
+function lexicalPicks(input: BookmarkSelectorInput): BookmarkPick[] {
+  const picks: Selection[] = lexicalBookmarks(input.assignment, input.entries);
+  return picks.map((pick) => ({ ref: pick.ref, reason: pick.reason, revision: pick.revision, source: "lexical" as const }));
+}
+
+/** The cache key: one assignment of one recipient, against one catalogue revision. */
+function cacheKeyOf(input: BookmarkSelectorInput): string {
+ const assignment = createHash("sha1").update(input.assignment).digest("hex").slice(0, 16);
+  return `${input.cacheKey ?? ""}:${assignment}:${input.catalogueRevision}`;
+}
+
+const cache = new Map<string, BookmarkPick[]>();
+
+/** Ask Jev about the lexically best candidates; anything short of an answer falls back to the lexical picks. */
+async function classifierPicks(classifier: Classifier, input: BookmarkSelectorInput, log?: (text: string) => void): Promise<BookmarkPick[]> {
+  const ranked: Selection[] = lexicalBookmarks(input.assignment, input.entries, BOOKMARK_CANDIDATES);
+  if (ranked.length === 0) return [];
+  const byRef = new Map(ranked.map((pick) => [pick.ref, input.entries.find((entry) => entry.id === pick.ref)!]));
+  const candidates = ranked.map((pick) => byRef.get(pick.ref)!);
+  const call = refRequest(input.assignment, candidates.map(metaLine));
+  const result = await classifier.ask("knowledge", call.request, { ...(input.signal ? { signal: input.signal } : {}), timeoutMs: Math.min(classifier.config.timeoutMs, BOOKMARK_DEADLINE_MS) });
+  if (!result) return lexicalPicks(input);
+  const relevance = new Map<number, number>();
+  for (const [key, index] of call.keys) {
+    const value = yesOf(result.answers, key);
+    if (value !== undefined) relevance.set(index, value);
+  }
+  if (relevance.size === 0) return lexicalPicks(input);
+  const picks = picksFromAnswers(relevance, candidates, classifier.config.thresholds.knowledgeRelevantAt);
+  log?.(`bookmarks: kept ${picks.length} of ${candidates.length} catalogue references · ${result.ms} ms`);
+  return picks.length > 0 ? picks : lexicalPicks(input);
+}
+
+/** A bookmark selector on Jev: metadata in, references out, deterministic fallback on any failure. */
+export function bookmarkSelector(classifier: Classifier, log?: (text: string) => void): BookmarkSelector {
+  return {
+    async select(input) {
+      const key = cacheKeyOf(input);
+      const cached = cache.get(key);
+      if (cached) return cached;
+      const picks = !classifier.enabled("knowledge") || !input.assignment.trim()
+        ? lexicalPicks(input)
+        : await classifierPicks(classifier, input, log).catch(() => lexicalPicks(input));
+      if (cache.size >= CACHE_LIMIT) cache.clear();
+      cache.set(key, picks);
+      return picks;
+    },
+  };
+}

package/src/desk/board-client.ts

@@ -1,19 +1,38 @@
 /**
  * The task board inside a worker's pi process: `post_board` adds a typed post
  * (through the desk when one runs, so peers hear about contracts and
- * blockers at once; straight to the board's file otherwise) and `read_board`
- * reads what the task's agents posted, filtered to the reader's role.
+ * blockers at once; straight to the board's file otherwise), `read_board`
+ * reads what the task's agents posted, filtered to the reader's role, and
+ * `ack_board` records the events the worker actually incorporated — reading
+ * alone proves receipt, not incorporation.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { createDeskClient, type DeskClient } from "./ipc.ts";
-import { appendPost, BOARD_ENV, filterPosts, formatPosts, isPostKind, POST_KINDS, readBoard, subscriptionFor, type PostKind } from "./board.ts";
+import { appendPost, BOARD_ENV, formatPosts, isPostKind, POST_KINDS, recentPost, readBoard, subscriptionFor, type BoardPost, type PostKind } from "./board.ts";
+import { ackRelevant, deliveryPath, markDelivered, markHandled, markSeen, provenThrough, readDelivery } from "./delivery.ts";
 import { deskAddress } from "./client-extension.ts";
 
 function text(value: string) {
   return { content: [{ type: "text" as const, text: value }], details: undefined };
 }
 
+/**
+ * A read proves receipt of what its window showed: the delivered cursor grows
+ * only over the posts relevant to the reader that the window included — it
+ * stops at the first one the window omitted — and shown posts beyond that are
+ * recorded out of order. Posts routed only by files wait for the desk that
+ * knows the claims. Nothing is marked handled: receipt is not incorporation.
+ */
+function recordRead(path: string, self: string, kinds: readonly PostKind[], shownPosts: readonly BoardPost[]): void {
+  const statePath = deliveryPath(path);
+  const prior = readDelivery(statePath).recipients[self]?.lastSeq ?? 0;
+  const shown = new Set(shownPosts.map((post) => post.seq));
+  const through = provenThrough(readBoard(path), shown, (post) => ackRelevant(post, self, kinds), prior);
+  if (through > prior) markDelivered(statePath, self, through);
+  for (const post of shownPosts) if (post.seq > through) markSeen(statePath, self, post.seq);
+}
+
 export function registerBoardClient(pi: ExtensionAPI, env: NodeJS.ProcessEnv = process.env, client?: DeskClient): void {
   const path = env[BOARD_ENV];
   if (!path) return;
@@ -27,21 +46,33 @@ export function registerBoardClient(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
     name: "post_board",
     label: "Post to the task board",
     description:
-      "Post a short, typed entry on the task board that every agent on this task can read: `contract` (an interface others build against: a route, a payload shape, a type, an event name), `decision` (a choice others should follow), `blocker` (something stopping you that someone else must change), `question` (open, for the oracle), `done` (a piece is finished and ready to test), `note`. Contracts and blockers reach the other running workers at once. Post facts, not progress chatter.",
+      "Post a short, typed entry on the task board that every agent on this task can read: `contract` (an interface others build against: a route, a payload shape, a type, an event name, file location), `decision` (a choice others should follow), `blocker` (something stopping you that someone else must change), `question` (open, for the oracle), `done` (a piece is finished and ready to test), `note`. Unaddressed contracts and blockers reach the other running workers at once; `to` (worker ids: backend, designer, qa, a child id) or `files` narrows who is pushed it. Post facts, not progress chatter.",
     parameters: Type.Object({
       kind: Type.Union(POST_KINDS.map((kind) => Type.Literal(kind))),
       text: Type.String({ description: "The post: the exact facts, at most a short paragraph" }),
-      files: Type.Optional(Type.Array(Type.String(), { description: "Files the post is about" })),
+      files: Type.Optional(Type.Array(Type.String(), { description: "Files the post is about; pushed to the workers holding them" })),
+      to: Type.Optional(Type.Array(Type.String(), { description: "Recipients the post is addressed to: a domain (`backend`) reaches every worker of that role, an assignment id (`backend:9f2c1e`) that worker alone; pushed only to them" })),
     }),
     async execute(_id, params) {
+      const post = { from: self, kind: params.kind, text: params.text, ...(params.files ? { files: params.files } : {}), ...(params.to ? { to: params.to } : {}) };
       if (desk) {
-        const answer = await desk.request({ op: "post", from: self, kind: params.kind, text: params.text, files: params.files ?? [] });
-        // Only a desk without the board, or one never reached, leaves the post to the file below; any other answer may follow a write.
-        if (answer.ok || !/^This task has no board\.$|^the file desk is unavailable$/.test(answer.text)) return text(answer.text);
+        let answer: { ok: boolean; text: string } | undefined;
+        try {
+          answer = await desk.request({ op: "post", from: self, kind: params.kind, text: params.text, files: params.files ?? [], targets: params.to ?? [] });
+        } catch {
+          // The request failed mid-flight; the post may already be on the board, so a retry must not duplicate it.
+        }
+        if (answer) {
+          // Only a desk without the board, or one never reached, leaves the post to the file below; any other answer may follow a write.
+          if (answer.ok || !/^This task has no board\.$|^the file desk is unavailable$/.test(answer.text)) return text(answer.text);
+        } else {
+          const landed = recentPost(path, self, params.kind, params.text);
+          if (landed) return text(`Posted #${landed.seq} (already on the board).`);
+        }
       }
       try {
-        const post = appendPost(path, { from: self, kind: params.kind, text: params.text, ...(params.files ? { files: params.files } : {}) });
-        return text(`Posted #${post.seq}.`);
+        const stored = appendPost(path, post);
+        return text(`Posted #${stored.seq}.`);
       } catch (error) {
         return text(`Not posted: ${(error as Error).message}`);
       }
@@ -51,15 +82,51 @@ export function registerBoardClient(pi: ExtensionAPI, env: NodeJS.ProcessEnv = p
   pi.registerTool({
     name: "read_board",
     label: "Read the task board",
-    description: "Read the task board. By default you see the kinds your role follows, newest last; pass kinds to see others, or after to see only posts newer than one you have read.",
+    description: "Read the task board. By default you see the kinds your role follows, newest last; pass kinds to see others, or after to see only posts newer than one you have read. Reading is receipt only: acknowledge what you incorporate with ack_board.",
     parameters: Type.Object({
       kinds: Type.Optional(Type.Array(Type.String(), { description: `Any of: ${POST_KINDS.join(", ")}` })),
       after: Type.Optional(Type.Number({ description: "Only posts after this number" })),
     }),
     async execute(_id, params) {
       const kinds: readonly PostKind[] = params.kinds?.filter(isPostKind).length ? params.kinds.filter(isPostKind) : subscriptionFor(self);
-      const posts = filterPosts(readBoard(path), { kinds, ...(params.after ? { after: params.after } : {}), limit: 50 });
+      const matching = readBoard(path)
+        .filter((post) => kinds.includes(post.kind) && (!params.after || post.seq > params.after))
+        .sort((a, b) => a.seq - b.seq);
+      const posts = matching.slice(-50);
+      if (posts.length > 0) recordRead(path, self, kinds, posts);
       return text(posts.length > 0 ? formatPosts(posts) : "Nothing on the board for those kinds yet.");
     },
   });
+
+  pi.registerTool({
+    name: "ack_board",
+    label: "Acknowledge board events",
+    description:
+      "Acknowledge the board events you have actually incorporated into your work: the numbers shown as `#3` (or the posts' ids). Receipt is not acknowledgement — reading or being steered a post does not count; only this does. Out-of-order acknowledgements are kept, and events relevant to you that you have not acknowledged yet stay pending.",
+    parameters: Type.Object({
+      events: Type.Array(Type.Union([Type.String(), Type.Number()]), { description: "The events: `#3`-style numbers, plain numbers, or post ids" }),
+    }),
+    async execute(_id, params) {
+      if (desk) {
+        let answer: { ok: boolean; text: string } | undefined;
+        try {
+          answer = await desk.request({ op: "ack", events: params.events });
+        } catch {
+          // Fall through to the file: acknowledging is idempotent, so a retry cannot double-record.
+        }
+        if (answer && (answer.ok || !/^the file desk is unavailable$|^the file desk closed$/.test(answer.text))) return text(answer.text);
+      }
+      return text(ackText(markHandled(path, self, params.events)));
+    },
+  });
+}
+
+/** The worker-facing result of one acknowledgement, whether anything was recorded or not. */
+export function ackText(result: { acknowledged: { seq: number }[]; unknown: string[]; refused: string[]; state: { handled?: number[] } }): string {
+  if (result.refused.length > 0) return `Not acknowledged: ${result.refused.join(", ")} ${result.refused.length === 1 ? "is" : "are"} outside what your role follows. Nothing was recorded.`;
+  const parts = [`Acknowledged ${result.acknowledged.map((post) => `#${post.seq}`).join(", ")}.`];
+  if (result.unknown.length > 0) parts.push(`No board event matches: ${result.unknown.join(", ")}.`);
+  const pending = result.state.handled ?? [];
+  if (pending.length > 0) parts.push(`${pending.length} earlier event${pending.length === 1 ? "" : "s"} you have not acknowledged still hold${pending.length === 1 ? "s" : ""} your acknowledgement cursor.`);
+  return parts.join(" ");
 }

package/src/desk/board.ts

@@ -7,10 +7,15 @@
  *
  * It lives in the task's directory as `board.jsonl`, so later steps, the QA
  * gate and the oracle read the same record; a worker without a running desk
- * (a single step) appends to the file directly.
+ * (a single step) appends to the file directly. A post may name recipients
+ * (`to`) or files: those route its *delivery* — an addressed post is pushed
+ * only to its targets, a file-named one to the workers holding those files —
+ * while the board itself stays readable to every role.
  */
-import { appendFileSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { LOCK_BUSY, withFileLock } from "./lock.ts";
 
 export const POST_KINDS = ["contract", "decision", "blocker", "question", "done", "note"] as const;
 export type PostKind = (typeof POST_KINDS)[number];
@@ -22,12 +27,16 @@ export function isPostKind(value: unknown): value is PostKind {
 export interface BoardPost {
   /** Order on the board, from 1. */
   seq: number;
-  /** Who posted it: a domain (`backend`, `designer`, `qa`), a child run id, or `oracle`. */
+  /** Stable unique id minted at append; posts written before it exists have none, and stay readable. */
+  id?: string;
+  /** Who posted it: a domain (`backend`, `designer`, `qa`), an assignment id (`backend:9f2c1e`), a child run id, or `oracle`. */
   from: string;
   kind: PostKind;
   text: string;
   /** Repository files the post is about, when it names any. */
   files?: string[];
+  /** Recipients the post is addressed to (worker ids or domains): only they are pushed it; everyone can still read it. */
+  to?: string[];
   at: string;
 }
 
@@ -35,7 +44,7 @@ export interface BoardPost {
 export const BOARD_ENV = "BOT_LOBBY_BOARD";
 
 /** Tools every worker gets when its task has a board. */
-export const BOARD_TOOLS: readonly string[] = ["post_board", "read_board"];
+export const BOARD_TOOLS: readonly string[] = ["post_board", "read_board", "ack_board"];
 
 /**
  * What each role reads by default. A builder needs the contracts and
@@ -51,11 +60,30 @@ export const SUBSCRIPTIONS: Readonly<Record<string, readonly PostKind[]>> = {
 
 const DEFAULT_SUBSCRIPTION: readonly PostKind[] = ["contract", "decision", "blocker"];
 
-/** Kinds a running peer is told about the moment they are posted, not only when it next reads. */
-export const PUSHED_KINDS: ReadonlySet<PostKind> = new Set(["contract", "blocker"]);
+/** Kinds a running peer is told about the moment they are posted, not only when it next reads: the consequential ones, never routine notes. */
+export const PUSHED_KINDS: ReadonlySet<PostKind> = new Set(["contract", "decision", "blocker"]);
 
 export function subscriptionFor(reader: string): readonly PostKind[] {
-  return SUBSCRIPTIONS[reader] ?? DEFAULT_SUBSCRIPTION;
+  return SUBSCRIPTIONS[reader] ?? SUBSCRIPTIONS[roleOf(reader) ?? ""] ?? DEFAULT_SUBSCRIPTION;
+}
+
+/** A recipient named the way posts address it: DEV/design/backend all mean `backend`; anything else (a child run id, `oracle`) is itself. */
+export function recipientId(name: string): string {
+  const key = name.trim().toLowerCase();
+  const ids: Record<string, string> = { dev: "backend", backend: "backend", design: "designer", designer: "designer", qa: "qa", oracle: "oracle" };
+  return ids[key] ?? name.trim();
+}
+
+/** The role a recipient answers to: `backend`, `backend:9f2c1e` and `DEV` are backend; an unrelated id (a bare child run id) has none. */
+export function roleOf(name: string): string | undefined {
+  const [head = ""] = name.trim().split(":", 1);
+  const role = recipientId(head);
+  return SUBSCRIPTIONS[role] ? role : undefined;
+}
+
+/** One assignment's board identity: unique per worker run (`backend:9f2c1e`), so two same-role workers never share delivery state while posts addressed to their role still reach both. */
+export function assignmentId(domain: string): string {
+  return `${recipientId(domain)}:${randomUUID().slice(0, 8)}`;
 }
 
 export const MAX_POST_CHARS = 1500;
@@ -102,61 +130,41 @@ export interface NewPost {
   kind: PostKind;
   text: string;
   files?: readonly string[];
+  /** Recipients the post is addressed to; an addressed post is pushed only to them. */
+  to?: readonly string[];
 }
 
 /** Longest a board path in a post may be. */
 const MAX_FILE_CHARS = 300;
-/** How long a writer waits for another process's append, and when a lock is taken to be left behind. */
-const LOCK_WAIT_MS = 2000;
-const STALE_LOCK_MS = 10_000;
 
-function sleep(ms: number): void {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
+/** Most recipients one post may name. */
+const MAX_TARGETS = 8;
 
-/**
- * Run `write` holding the board's lock (a directory beside it, made
- * atomically), so posts from several processes get distinct sequence
- * numbers. A lock left by a crashed writer is broken once stale; past the
- * wait the post goes in anyway rather than being lost.
- */
-function withLock<T>(path: string, write: () => T): T {
-  const lock = `${path}.lock`;
-  const until = Date.now() + LOCK_WAIT_MS;
-  let held = false;
-  while (!held) {
-    try {
-      mkdirSync(lock);
-      held = true;
-    } catch {
-      try {
-        if (Date.now() - statSync(lock).mtimeMs > STALE_LOCK_MS) rmSync(lock, { recursive: true, force: true });
-      } catch {
-        // Released meanwhile.
-      }
-      if (Date.now() > until) break;
-      sleep(5);
-    }
-  }
-  try {
-    return write();
-  } finally {
-    if (held) rmSync(lock, { recursive: true, force: true });
-  }
-}
-
-/** Append a post and return it as stored. Throws on an empty text, so the caller can tell the agent. */
+/** Append a post and return it as stored. Throws on an empty text or a busy board, so the caller can tell the agent. */
 export function appendPost(path: string, post: NewPost, now = new Date()): BoardPost {
   const text = clean(post.text, MAX_POST_CHARS);
   if (!text) throw new Error("a board post needs text");
   const files = (post.files ?? []).map((file) => clean(file, MAX_FILE_CHARS)).filter(Boolean).slice(0, MAX_FILES);
+  const to = [...new Set((post.to ?? []).map((target) => clean(target, 80)).filter(Boolean))].slice(0, MAX_TARGETS);
   mkdirSync(dirname(path), { recursive: true });
-  return withLock(path, () => {
-    const seq = (readBoard(path).at(-1)?.seq ?? 0) + 1;
-    const stored: BoardPost = { seq, from: post.from, kind: post.kind, text, ...(files.length > 0 ? { files } : {}), at: now.toISOString() };
-    appendFileSync(path, `${JSON.stringify(stored)}\n`, "utf8");
-    return stored;
-  });
+  try {
+    return withFileLock(path, () => {
+      const seq = (readBoard(path).at(-1)?.seq ?? 0) + 1;
+      const stored: BoardPost = { seq, id: randomUUID(), from: post.from, kind: post.kind, text, ...(files.length > 0 ? { files } : {}), ...(to.length > 0 ? { to } : {}), at: now.toISOString() };
+      appendFileSync(path, `${JSON.stringify(stored)}\n`, "utf8");
+      return stored;
+    });
+  } catch (error) {
+    throw new Error((error as Error).message === LOCK_BUSY ? `Not posted: ${LOCK_BUSY}` : (error as Error).message);
+  }
+}
+
+/** The newest post already on the board with this sender, kind and exact text, if one exists: a retry can adopt it instead of duplicating it. */
+export function recentPost(path: string, from: string, kind: PostKind, text: string): BoardPost | undefined {
+  const wanted = clean(text, MAX_POST_CHARS);
+  return readBoard(path)
+    .filter((post) => post.from === from && post.kind === kind && post.text === wanted)
+    .at(-1);
 }
 
 export interface BoardFilter {
@@ -179,13 +187,16 @@ export function filterPosts(posts: readonly BoardPost[], filter: BoardFilter): B
 const NAMES: Record<string, string> = { backend: "DEV", designer: "DESIGN", qa: "QA", oracle: "ORACLE" };
 
 export function posterName(from: string): string {
+  const role = roleOf(from);
+  if (role && from !== role) return `${NAMES[role] ?? role.toUpperCase()}(${from.slice(role.length + 1)})`;
   return NAMES[from] ?? (from.length > 12 ? `child ${from.slice(0, 8)}` : from.toUpperCase());
 }
 
 /** One post on one line: its text is flattened, so a post can never pass for a line of the engine's own. */
 export function formatPost(post: BoardPost): string {
   const files = post.files?.length ? ` (${post.files.join(", ")})` : "";
-  return `#${post.seq} [${post.kind}] ${posterName(post.from)}${files}: ${post.text.replace(/\s+/g, " ")}`;
+  const to = post.to?.length ? ` → ${post.to.map(posterName).join(", ")}` : "";
+  return `#${post.seq} [${post.kind}] ${posterName(post.from)}${to}${files}: ${post.text.replace(/\s+/g, " ")}`;
 }
 
 export function formatPosts(posts: readonly BoardPost[]): string {