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

package/THIRD_PARTY_NOTICES.md

@@ -4,12 +4,13 @@
 
 The web UI's look (colours, radii, shadows, control and dialog styles, the
 sidebar rail, the chat rows, the work log, the composer (its surface, footer controls and send button), the select
-fields and drop-down lists, the loading and status animations and the
-built-in colour themes), and the third-party harness support (the model
+fields and drop-down lists, the loading and status animations, the code
+viewer with its diff mode and the built-in colour themes), and the third-party harness support (the model
 manifest, CLI flags, prompt injection and ACP handling behind Settings >
 Harnesses), is adapted from T3 Code,
 https://github.com/pingdotgg/t3code. No T3 Code package is a
-dependency; the styles and markup below were ported into this repository and
+dependency (the code viewer uses the same diff and highlighting library T3
+Code does, `@pierre/diffs`, as an ordinary npm dependency); the styles and markup below were ported into this repository and
 rewired to bot-lobby's own data layer. Each adapted file starts with a comment
 naming the file it came from.
 
@@ -38,6 +39,9 @@ naming the file it came from.
 | `webui/src/app/Composer.tsx` | `apps/web/src/components/chat/ComposerSurface.tsx`, `ChatComposer.tsx`, `ComposerPrimaryActions.tsx`, `ComposerControl.tsx` |
 | `webui/src/app/composer/ComposerCommandMenu.tsx` | `apps/web/src/components/chat/ComposerCommandMenu.tsx`, `ComposerBanner.tsx` (the attached drawer surface), `composer-logic.ts` (the `/` and `@` trigger) |
 | `webui/src/app/TerminalDrawer.tsx` | `apps/web/src/components/ThreadTerminalDrawer.tsx` (the drawer, its floating toolbar and terminal list) |
+| `webui/src/app/code/CodeViewer.tsx` | `apps/web/src/components/DiffPanel.tsx`, `DiffPanelShell.tsx` (diff layout and wrap toggles), `components/diffs/DiffFileTree.tsx` (changed files list), `components/files/FilePreviewPanel.tsx` (file header) |
+| `webui/src/app/code/CodeSurface.tsx` | `apps/web/src/components/files/FilePreviewPanel.tsx` (`EditableFileSurface`), `components/files/ReadOnlySourcePreview.tsx`, `components/DiffPanel.tsx` |
+| `webui/src/app/code/codeRendering.ts` | `apps/web/src/lib/diffRendering.ts` (`DIFF_SURFACE_THEME_UNSAFE_CSS`, `resolveDiffThemeName`), `lib/syntaxHighlighting.ts` (`PREFERRED_HIGHLIGHTER`), `components/diffs/StyledDiffCodeView.tsx`, `components/files/fileSurfaceChrome.tsx` |
 | `webui/src/tabs/lobby/InlineActivity.tsx` | `apps/web/src/components/chat/WorkLog.tsx` |
 | `src/webui/palette-core.ts` (the built-in themes) | `packages/shared/src/themePalettes.ts` (Blossom is their T3 Chat theme, renamed) |
 | `src/harness/model-manifest.json` (copied as is) | `apps/server/src/provider/model-manifest.json` |
@@ -88,3 +92,12 @@ Jakarta Sans Project Authors), Figtree (The Figtree Project Authors), Outfit
 Grotesk (The Space Grotesk Project Authors), Source Sans 3 and Source Code Pro
 (Adobe), Fira Code (The Fira Code Project Authors) and Roboto Mono (The Roboto
 Mono Project Authors).
+
+## Code viewer libraries
+
+The code viewer's chunks in `webui/dist/assets` bundle `@pierre/diffs`,
+`@pierre/theming` and `@pierre/theme` (The Pierre Computer Company, Apache
+License 2.0, https://www.apache.org/licenses/LICENSE-2.0), Shiki and its
+grammars (`shiki`, `@shikijs/*`, Pine Wu and Anthony Fu, MIT; each grammar
+keeps its own licence, listed in `@shikijs/langs`) and `diff` (Kevin Decker,
+BSD 3-Clause).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.6.58",
+  "version": "0.6.60",
   "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",
@@ -73,7 +73,12 @@
     "@fontsource-variable/source-code-pro": "^5.3.1",
     "@fontsource-variable/source-sans-3": "^5.3.1",
     "@fontsource-variable/space-grotesk": "^5.3.0",
+    "@pierre/diffs": "^1.5.2",
     "@playwright/test": "1.62.0",
+    "@shikijs/core": "^4.5.0",
+    "@shikijs/engine-javascript": "^4.5.0",
+    "@shikijs/engine-oniguruma": "^4.5.0",
+    "@shikijs/langs": "^4.5.0",
     "@tailwindcss/vite": "4.3.3",
     "@types/node": "^22.10.0",
     "@types/react": "19.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(" ");
 }