@dev.fast/whiteboard 0.3.3 → 0.3.4-preview.20261019.126

package/src/lens-selection.ts

@@ -24,8 +24,23 @@ const sameSideAnchor = /^(head|base)\/(.+)#L(\d+)(?:-L(\d+))?$/;
 
 const crossSideAnchor = /^diff\/(.+)#([LR])(\d+)-([LR])(\d+)$/;
 
+const commitLinkAnchor = /^([0-9a-f]{7,40})\/(.+#L\d+(?:-L\d+)?)$/i;
+
+/** A source link's commit form, "<sha>/path#L10-L24" (without its
+ * `whiteboard:source/` prefix): lines of that commit of the board's own
+ * repository, read as their head side. Undefined for any other form. */
+export function commitLinkTarget(
+  target: string,
+): { commit: string; anchor: Anchor } | undefined {
+  const match = commitLinkAnchor.exec(target);
+
+  return match
+    ? { commit: match[1]!.toLowerCase(), anchor: `head/${match[2]!}` }
+    : undefined;
+}
+
 /** An anchor's selection, as markdown source links write it too (without
- * their `review-source:` scheme). Undefined when it isn't one. */
+ * their `whiteboard:source/` prefix). Undefined when it isn't one. */
 export function parseAnchor(text: string): DiffSelection | undefined {
   const same = sameSideAnchor.exec(text);
 
@@ -195,6 +210,26 @@ export function sourceAnchor(source: LensSource): FileLineRange {
   return sourceAnchors(source)[0]!;
 }
 
+/** Why a selection cannot be resolved at its pins, as telemetry reports it. */
+export const SELECTION_UNAVAILABLE_REASONS = [
+  "missing_file",
+  "no_alignment",
+  "outside_lines",
+  "other",
+] as const;
+
+export type SelectionUnavailableReason =
+  (typeof SELECTION_UNAVAILABLE_REASONS)[number];
+
+export class SelectionUnavailableError extends Error {
+  constructor(
+    readonly reason: SelectionUnavailableReason,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
 /** Resolve once against the renderer's rows. No matching or context expansion. */
 export function resolveDiffSelection(
   source: LensSource,
@@ -210,7 +245,8 @@ export function resolveDiffSelection(
   const end = locate(source.end);
 
   if (start < 0 || end < start)
-    throw new Error(
+    throw new SelectionUnavailableError(
+      "outside_lines",
       "Lens endpoints do not identify an ordered interval in this diff.",
     );
   const selected = rows.slice(start, end + 1);

package/src/review-api/README.md

@@ -17,6 +17,7 @@ catalog. Tests inject the native store and source-data provider.
 - `repositories`: server-only local paths; clients receive an ID and display name.
 - `resources`: immutable image, trace and software-map bytes, scoped to a repository.
 - `review_attention`: viewed/trashed timestamps, separate from document history.
+- `board_relations`: where a board sits in its project, outside its versions: a child's `parent` (one per board) and a board's `depends_on` edges.
 
 One host-owned store serializes writes, including asynchronous validation.
 Presences show who is working across database connections and never block a
@@ -51,11 +52,14 @@ All paths below are relative to `/reviews-api`.
 | `GET /:id?targetId=step-3`                                    | Full block, sequence step, flow node or flow edge                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `GET /:id?full=true`                                          | Full snapshot                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `GET /:id?version=2&full=true`                                | Historical snapshot                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `GET /:id/history`                                            | Saved versions with titles and timestamps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `GET /:id/history`                                            | Saved versions with titles, timestamps and `author`: `"you"` for a person's save, else `"agent"` with the Ask `threadId` when one made it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `GET /:id/inspect`                                            | Agent reading view: nested text outline with IDs; `targetId` reads one component completely, `full=true` includes all content, `version` selects history. `format=json` returns raw data instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `POST /:id/open`                                              | Open the review in the attached Desktop; report an error when none is attached                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `POST /commands`                                              | Apply one command; return review ID, version, and for an edit the target ID, its `type`, and — after an insert or replace — `children`: its first-level children as `{id,type}` (a container's blocks; a diagram's steps, or nodes then edges), so new components are addressable without a read. A `create` with `pullRequestUrl` returns the newest existing review for that PR instead (owner/repository matched case-insensitively) unless `operation.reuseExisting` is `false`: `created:false`, a `note`, its stored `target`, `headMoved`, and `working`/`otherReviewIds` when they apply; its target is never moved. A new review reports `created:true`. Either way the result carries `review`, the review's `GET /` catalog entry (target, origin, repository name and path). An interactive `create` also opens the new review in an attached Desktop unless `operation.open` is `false`, and reports `opened` with the open result or an `openError`; the review is saved either way |
 | `POST /commands {operation:{type:"lens_edit",reviewId,edit}}` | Write one file lens, credited to `activityId` when given: `insert {title,targets,afterId?}` (host id `lens-N`), `update {targetId,title?,targets?}` or `remove {targetId}`. Returns `{targetId, type:"lens", uncategorized}`, where `uncategorized` lists changed files and ranges no lens covers yet (at most 50 files)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `POST /:id/person-edit {baseVersion,title,document}`          | Save a person's whole board as their version; return `{reviewId,version,ids}`. See Person edits                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `POST /:id/focus {clientId,blockId}`                          | Lease the board open on a canvas, and the block a person is in (`blockId`, or null), for 15 s; `open:false` lets go. Returns `{ok:true}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `POST /:id/discard`                                           | Delete the board only if it has no title (it reads "Untitled") and no blocks and no child boards, no canvas holds it open and no agent is working on it; waits up to 15 s for a closing canvas to let go. Returns `{deleted}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `GET /:id/lenses`                                             | The current version's file lenses with each one's file count, plus the same `uncategorized` report                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `POST /repositories {path}`                                   | Register a local Git/jj repository; return ID/name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `POST /resources`                                             | Upload an image, trace, or map; return resource ID/kind/MIME type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -89,10 +93,17 @@ The canvas continues to use the JSON snapshot routes above.
 }
 ```
 
-Commands: `create {title,target,pullRequestUrl?,reuseExisting?}` or `create {pullRequestUrl,title?,repositoryId?,reuseExisting?}`, `set_target {reviewId,target,pullRequestUrl?}`, `edit {reviewId,edit}`, `rename {reviewId,title}`,
-`restore {reviewId,version}`. A review's pins, `{repositoryId,base,head}`, are its target resolved to immutable commits.
-Agents name the checkout by `repositoryPath` in a target, or on a create from a PR alone; `/commands` registers the path and passes the store its id. Retargeting preserves content and component IDs. Restore restores title, target, PR identity, and content. Live targets still read the current checkout.
-PR URLs must be canonical `https://github.com/owner/repository/pull/123` URLs. The PR number is derived from the URL; identity is metadata alongside immutable pins, not a moving source reference. A `create` with a target keeps that target and treats the URL as identity only. A `create` with the URL and no target resolves the PR when accepted: it reads the PR with `gh pr view` (falling back to the public GitHub API), picks the registered checkout named by `repositoryId`, else the checkout of the PR's existing review, else the first registered checkout with a remote whose configured URL is `github.com/owner/repository`, and fetches `refs/pull/N/head` and the base branch from that remote into `refs/review/github/owner/repository/pull/N/*`, never moving branches or bookmarks (a jj repository indexes the commits through a transient tag). It pins that head and its merge base with the base branch; for a PR absorbed by a merge commit it uses the merge base with GitHub's frozen base commit instead. The title defaults to the PR title. A repeat resolves the PR again, so `headMoved` compares the existing review with the PR's current head. `set_target` preserves the document and component IDs, including when source commits change. Its response reports retained source ranges to verify, those in files the new commits changed, and resources that no longer match the pins; agents repair these with `edit`. Existing versions keep their original pins and content. It preserves omitted PR identity within one repository, clears it when switching repositories, and accepts an explicit URL or null.
+Commands: `create {title?,target,reuseExisting?,open?}`, `set_target {reviewId,target}`, `edit {reviewId,edit}`, `rename {reviewId,title}`,
+`restore {reviewId,version}`. A target names its checkout by `repositoryPath` (see Review targets). A PR is a `pullRequest` target. A review's pins are its target resolved to immutable commits. Agents write pins as `{head,base?}`, and the host adds the board's repository.
+`/commands` registers the path and passes its id to the store. Agent tools never show repository ids, and `/commands` sets every pins object in an edit to the board's own repository. Retargeting preserves content and component IDs. Restore restores title, target, PR identity, and content. Live targets still read the current checkout.
+PR URLs must be canonical `https://github.com/owner/repository/pull/123` URLs. The PR number is derived from the URL; identity is metadata alongside immutable pins, not a moving source reference. A `pullRequest` target names the PR by URL or by number (a number is looked up on the checkout's GitHub remote) and resolves it when accepted: it reads the PR with `gh pr view` (falling back to the public GitHub API) and fetches `refs/pull/N/head` and the base branch from the checkout named by `repositoryPath` into `refs/review/github/owner/repository/pull/N/*`, never moving branches or bookmarks (a jj repository indexes the commits through a transient tag). It pins that head and its merge base with the base branch; for a PR absorbed by a merge commit it uses the merge base with GitHub's frozen base commit instead. The title defaults to the PR title. A repeat resolves the PR again, so `headMoved` compares the existing review with the PR's current head. `set_target` preserves the document and component IDs, including when source commits change. Its response reports retained source ranges to verify, those in files the new commits changed, and resources that no longer match the pins; agents repair these with `edit`. Existing versions keep their original pins and content. It preserves omitted PR identity within one repository, clears it when switching repositories, and accepts an explicit URL or null.
+
+`set_parent {reviewId,parentId}` nests a board one level under a top-level
+board of its project; `null` makes it top-level. `set_dependencies
+{reviewId,dependsOn}` replaces what it builds on, and refuses a cycle.
+`create` takes both. Neither saves a version. Summaries list `parentId`,
+`children` (in sibling order) and `dependsOn`. Deleting a parent moves its
+children to top level.
 
 `attention {reviewId,action:"view"}` records viewing without changing lifecycle or document history.
 `lifecycle {reviewId,state:"active"|"trash"}` moves a whiteboard to Trash or restores it.
@@ -110,8 +121,7 @@ the same version and side through the API, without a client-side checkout path.
 
 Edits: `insert {content,parentId?,afterId?}`, `update {targetId,changes}`,
 `move {targetId,parentId?,afterId?}`, `remove {targetId}`,
-`replace {targetId,content}`. Omitted placement appends to the root; on the
-scratchpad it prepends instead, so the pad reads newest first. Diagram
+`replace {targetId,content}`. Omitted placement appends to the root. Diagram
 units (a `step` in a sequence, a `flow_node` or `flow_edge` in a flow diagram)
 require their diagram as the parent and can move within it, but not between
 diagrams; removing a flow node removes the edges that touched it. A new
@@ -138,10 +148,35 @@ There is no expected-version parameter. Later same-field edits win. A command
 whose response was lost may or may not have applied; read the review before
 retrying.
 
+## Person edits
+
+The canvas saves a person's edits with `POST /:id/person-edit`, never through
+an agent tool. The body is the whole board: `title`, and `document` with each
+block as stored. A new block has no `id` and may carry a `clientKey`; the host
+gives it a fresh id and returns `ids: {clientKey: id}`. Ids must be unique; an id
+from an earlier version may come back. The save is checked like an agent edit.
+If `baseVersion` is not the current version, nothing is saved and the request
+fails with 409: "The board changed since version N; it is now at version M.
+Merge the latest version and save again." A save that changes nothing returns
+the current version and saves none. The version carries `personEdit: {changed}`,
+the ids of blocks added, removed or changed, and no `lastEdit`, so no courier
+draws it.
+
+While a person edits a block, the canvas posts `POST /:id/focus` about every
+5 s. Each lease expires 15 s after its last post. An agent `edit` that adds,
+removes or changes a leased block fails with 409: "The user is editing this
+block (ID). Edit another block, or try again after they move on." Nothing is
+saved. A section or callout changes only when its own fields do, and a block
+moved unchanged does not change. A lease never refuses a person's edit or
+restore, only an agent's. A board in Trash refuses every change, a person's
+included, until it is restored.
+
 ## Validation and remaining work
 
-Markdown source links use `[label](review-source:head/src/save.ts#L10-L24)`
-(or `base`, or `#L10` for one line). Paths are repository-relative and URL-encoded
+Markdown source links use `[label](whiteboard:source/head/src/save.ts#L10-L24)`
+(or `base`, or `#L10` for one line), or `whiteboard:source/<commit>/src/save.ts#L10-L24`
+to quote any commit of the board's own repository; a short commit is saved in full,
+and one the repository lacks rejects the edit. Paths are repository-relative and URL-encoded
 where needed. Inline and reference-style links open the existing native side peek.
 The same Markdown parser feeds the host's source checks and the renderer, so code
 examples and unused definitions do not become source requests. Invalid paths or
@@ -163,9 +198,10 @@ working-copy files. It checks code ranges and resource ownership before saving.
 Images are fully decoded to PNG; traces retain supplied text with an explicit
 client-supplied provenance label. Map uploads use the existing nested map format,
 with a JSON shape check followed by the existing relationship/coverage validator
-and pinned source-range checks. Uploads take `{id,repositoryId,kind,...}` with
+and pinned source-range checks. Uploads take `{id,repositoryPath,kind,...}` with
 `base64` for images, `trace:{label,events:[{id,role,text}]}` for traces, or
-`pins,side,model` for maps. Reusing an upload ID requires identical content.
+`pins,side,model` for maps, whose pins still name `{repositoryId,head,base}`
+(no agent tool uploads maps). Reusing an upload ID requires identical content.
 
 The canvas preserves React identities during updates. The stream coalesces
 updates when a reader falls behind; reconnecting starts with the current saved
@@ -277,8 +313,11 @@ commands are local and are never authored into review documents.
 
 ## Review targets
 
-`target` is either `{kind:"worktree",repositoryId,base?}` or
-`{kind:"commits",repositoryId,head,base?}`. Commit revisions resolve on acceptance.
+`target` names its checkout by path and is one of `{kind:"project",repositoryPath}`
+(a plan in that repository's project, with no change), `{kind:"worktree",repositoryPath,base?}`,
+`{kind:"commits",repositoryPath,head,base?}` or
+`{kind:"pullRequest",repositoryPath,pullRequest}` (stored as commits plus the PR
+origin). Commit revisions resolve on acceptance.
 Omitted commit base means source at head with no diff, exactly as base=head;
 supply its parent to review the changes introduced by a single commit.
 

package/src/review-api/activity.ts

@@ -68,12 +68,9 @@ export class ReviewActivity {
     private readonly db: DatabaseSync,
     private readonly assertReview?: (reviewId: string) => void,
   ) {
-    // Presences replace the per-scope leases; both last minutes, so the old
-    // table is dropped rather than migrated.
     db.exec(`CREATE TABLE IF NOT EXISTS authoring_presences(
       activity_id TEXT PRIMARY KEY, review_id TEXT NOT NULL, slot INTEGER NOT NULL,
-      started_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, focus TEXT, surface TEXT);
-      DROP TABLE IF EXISTS authoring_sessions;`);
+      started_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, focus TEXT, surface TEXT);`);
 
     for (const row of db
       .prepare(

package/src/review-api/agent-cli.ts

@@ -20,7 +20,12 @@ import { type ReviewApiClient, ReviewApiError } from "./client.js";
 import { exitOnInstallUpdate } from "./install-update.js";
 import { callPublicTool, publicTool } from "./public-tools.js";
 import { RECOVERY } from "./recovery.js";
-import { REVIEW_AGENT_HEADER, REVIEW_VIA_HEADER } from "./request-origin.js";
+import {
+  ASK_THREAD_ENV,
+  REVIEW_AGENT_HEADER,
+  REVIEW_THREAD_HEADER,
+  REVIEW_VIA_HEADER,
+} from "./request-origin.js";
 import { toolFailure } from "./tool-failure.js";
 
 interface AgentCliInput {
@@ -64,9 +69,12 @@ export async function runReviewAgentCli(input: AgentCliInput): Promise<number> {
     if (extra.length || (mode === "mcp" && name))
       throw new Error("Unexpected arguments. Use whiteboard api --help.");
 
+    const thread = env[ASK_THREAD_ENV]?.trim();
+
     const headers = Object.fromEntries([
       [REVIEW_VIA_HEADER, mode === "mcp" ? "mcp" : "api"],
       [REVIEW_AGENT_HEADER, reviewSessionAgent(env)],
+      [REVIEW_THREAD_HEADER, thread ?? ""],
     ]);
 
     if (mode === "mcp") {

package/src/review-api/anchor-quotes.ts

@@ -4,7 +4,12 @@ import {
   selectionKey,
 } from "@review/lens-selection.js";
 
-import { type Pins, anchorPins, selectionReferences } from "./document.js";
+import {
+  type Pins,
+  anchorPins,
+  boardRepositoryId,
+  selectionReferences,
+} from "./document.js";
 import type { Snapshot } from "./store.js";
 
 export interface AnchorQuote {
@@ -40,15 +45,17 @@ export async function anchorQuotes(
 
   const known = new Set(
     before
-      ? selectionReferences(before.document, { tolerant: true }).map(
-          ({ id, source }) => key(id, source),
-        )
+      ? selectionReferences(before.document, {
+          tolerant: true,
+          repositoryId: boardRepositoryId(before),
+        }).map(({ id, source }) => key(id, source))
       : [],
   );
 
-  const added = selectionReferences(after.document, { tolerant: true }).filter(
-    ({ id, source }) => !known.has(key(id, source)),
-  );
+  const added = selectionReferences(after.document, {
+    tolerant: true,
+    repositoryId: boardRepositoryId(after),
+  }).filter(({ id, source }) => !known.has(key(id, source)));
 
   const quotes = await Promise.all(
     added

package/src/review-api/ask-history.ts

@@ -17,7 +17,11 @@ import { ReviewInputError } from "./document.js";
 
 /** A saved Ask conversation: its history entry, and how to reopen it. */
 export const askRecordSchema = askHistoryEntrySchema.extend({
-  reviewId: z.string(),
+  /** The board the conversation started on, and the block if any. */
+  anchor: z.object({ board: z.string(), block: z.string().optional() }),
+  /** The project of the board it started on, read from that board, or its
+   * tombstone once deleted; absent for a shared board. */
+  projectId: z.string().optional(),
   /** The ACP session the agent keeps the transcript under. */
   sessionId: z.string(),
   /** The review version asked about; its pins recreate the checkout. */
@@ -34,7 +38,9 @@ export type AskRecord = z.infer<typeof askRecordSchema>;
 const rowSchema = z
   .object({
     id: z.string(),
-    review_id: z.string(),
+    anchor_board: z.string(),
+    anchor_block: z.string().nullable(),
+    project_id: z.string().nullable(),
     agent: z.string(),
     session_id: z.string(),
     version: z.number(),
@@ -51,7 +57,11 @@ const rowSchema = z
   .transform((row) =>
     askRecordSchema.parse({
       id: row.id,
-      reviewId: row.review_id,
+      anchor:
+        row.anchor_block === null
+          ? { board: row.anchor_board }
+          : { board: row.anchor_board, block: row.anchor_block },
+      projectId: row.project_id ?? undefined,
       agent: row.agent,
       sessionId: row.session_id,
       version: row.version,
@@ -68,17 +78,36 @@ const rowSchema = z
     }),
   );
 
-/** Saved Ask conversations, per review. Shared reviews are not in
- * `reviews`, so there is no foreign key; deleting a review deletes its rows. */
+/** A thread's project: its anchor board's, or a deleted board's from its
+ * tombstone. The one place a thread's project comes from, so it can never
+ * disagree with its board's. */
+const THREAD_PROJECT_SQL = `COALESCE(
+  (SELECT project_id FROM reviews WHERE reviews.id=ask_conversations.anchor_board),
+  (SELECT project_id FROM deleted_boards WHERE deleted_boards.id=ask_conversations.anchor_board))`;
+
+/** Every column of a thread, with its project. */
+const THREAD_COLUMNS = `ask_conversations.*, ${THREAD_PROJECT_SQL} AS project_id`;
+
+/** Saved Ask conversations by project, each anchored on the board it started
+ * on. No foreign key on the anchor: shared reviews are not in `reviews`.
+ * So deleting a board removes its threads by hand (removeReview). */
 export class AskHistory {
+  private readonly listeners = new Set<() => void>();
+
   private externalWriteGuard?: (reviewId: string) => void;
   setExternalWriteGuard(guard: (reviewId: string) => void) {
     this.externalWriteGuard = guard;
   }
-  constructor(private readonly db: DatabaseSync) {
+  constructor(
+    private readonly db: DatabaseSync,
+    /** The store's rule for writing about a board: one in Trash is
+     * read-only. */
+    private readonly writable: (reviewId: string) => void = () => {},
+  ) {
     db.exec(`CREATE TABLE IF NOT EXISTS ask_conversations(
       id TEXT PRIMARY KEY,
-      review_id TEXT NOT NULL,
+      anchor_board TEXT NOT NULL,
+      anchor_block TEXT,
       agent TEXT NOT NULL,
       session_id TEXT NOT NULL,
       version INTEGER NOT NULL,
@@ -91,25 +120,12 @@ export class AskHistory {
       entries TEXT,
       bypass INTEGER NOT NULL DEFAULT 0,
       permissions TEXT,
-      UNIQUE(agent, session_id));
-    CREATE INDEX IF NOT EXISTS ask_conversations_review ON ask_conversations(review_id, updated_at);`);
-
-    // Conversations saved before bypassing permissions, or before auto mode,
-    // lack its column.
-    const columns = new Set(
-      db
-        .prepare("PRAGMA table_info(ask_conversations)")
-        .all()
-        .map((column) => String(column.name)),
-    );
+      viewed_at TEXT,
+      UNIQUE(agent, session_id));`);
 
-    if (!columns.has("bypass"))
-      db.exec(
-        "ALTER TABLE ask_conversations ADD COLUMN bypass INTEGER NOT NULL DEFAULT 0",
-      );
-
-    if (!columns.has("permissions"))
-      db.exec("ALTER TABLE ask_conversations ADD COLUMN permissions TEXT");
+    db.exec(
+      "CREATE INDEX IF NOT EXISTS ask_conversations_review ON ask_conversations(anchor_board, updated_at)",
+    );
 
     // What each agent offered last, so a new question can pick a model and
     // effort, and a command, before its agent starts.
@@ -122,34 +138,46 @@ export class AskHistory {
     );
   }
 
-  private assertWritable(reviewId: string) {
-    if (reviewId.startsWith("shared-")) this.externalWriteGuard?.(reviewId);
+  /** Calls back when a conversation is saved, renamed, used or deleted. */
+  subscribe(listener: () => void) {
+    this.listeners.add(listener);
 
-    const row = this.db
-      .prepare("SELECT deleted_at FROM review_attention WHERE review_id=?")
-      .get(reviewId);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
 
-    if (row?.deleted_at)
-      throw new ReviewInputError(
-        `This whiteboard was moved to Trash on ${new Date(String(row.deleted_at)).toLocaleDateString("en-US", { month: "short", day: "numeric" })}. Restore it with session_lifecycle({"sessionId":"${reviewId}","state":"active"}) to continue.`,
-        409,
-      );
+  private changed() {
+    for (const listener of this.listeners) listener();
+  }
+
+  private assertWritable(reviewId: string) {
+    if (reviewId.startsWith("shared-")) this.externalWriteGuard?.(reviewId);
+    else this.writable(reviewId);
   }
+
   private assertThreadWritable(id: string) {
     const record = this.get(id);
 
-    if (record) this.assertWritable(record.reviewId);
+    if (record) this.assertWritable(record.anchor.board);
   }
   save(record: AskRecord) {
-    this.assertWritable(record.reviewId);
+    this.assertWritable(record.anchor.board);
     this.db
       .prepare(
-        `INSERT OR REPLACE INTO ask_conversations(id,review_id,agent,session_id,version,head,cwd,selection,title,created_at,updated_at,bypass,permissions)
-        VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+        // Its columns, not the row: when it was last seen, and what the
+        // panel showed, stay.
+        `INSERT INTO ask_conversations(id,anchor_board,anchor_block,agent,session_id,version,head,cwd,selection,title,created_at,updated_at,bypass,permissions)
+        VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+        ON CONFLICT(id) DO UPDATE SET anchor_board=excluded.anchor_board, anchor_block=excluded.anchor_block,
+          agent=excluded.agent, session_id=excluded.session_id, version=excluded.version, head=excluded.head,
+          cwd=excluded.cwd, selection=excluded.selection, title=excluded.title, created_at=excluded.created_at,
+          updated_at=excluded.updated_at, bypass=excluded.bypass, permissions=excluded.permissions`,
       )
       .run(
         record.id,
-        record.reviewId,
+        record.anchor.board,
+        record.anchor.block ?? null,
         record.agent,
         record.sessionId,
         record.version,
@@ -162,6 +190,7 @@ export class AskHistory {
         record.permissions === "bypass" ? 1 : 0,
         record.permissions ?? null,
       );
+    this.changed();
   }
 
   /** What the agent may do without asking when the conversation reopens. */
@@ -189,6 +218,7 @@ export class AskHistory {
     this.db
       .prepare("UPDATE ask_conversations SET entries=? WHERE id=?")
       .run(JSON.stringify(entries), id);
+    this.changed();
   }
 
   /** The agent's name for the conversation, which the list shows. */
@@ -197,6 +227,7 @@ export class AskHistory {
     this.db
       .prepare("UPDATE ask_conversations SET title=? WHERE id=?")
       .run(title.slice(0, 200), id);
+    this.changed();
   }
 
   saveOffer(agent: AskAgentId, offer: AskOffer) {
@@ -245,50 +276,105 @@ export class AskHistory {
     this.db
       .prepare("UPDATE ask_conversations SET updated_at=? WHERE id=?")
       .run(at, id);
+    this.changed();
+  }
+
+  /** Conversations in a board's project, or started on the board when it
+   * has none. Newest first. */
+  list(board: string, projectId?: string) {
+    // The project's boards by their index on project_id, then their
+    // threads by ask_conversations_review.
+    return this.entries(
+      "anchor_board=? OR anchor_board IN (SELECT id FROM reviews WHERE project_id=? UNION ALL SELECT id FROM deleted_boards WHERE project_id=?)",
+      board,
+      projectId ?? null,
+      projectId ?? null,
+    );
   }
 
-  /** Newest first. */
-  list(reviewId: string): AskHistoryEntry[] {
+  /** Every project's conversations, newest first. */
+  listAll() {
+    return this.entries("1");
+  }
+
+  private entries(
+    where: string,
+    ...params: (string | null)[]
+  ): (AskHistoryEntry & { projectId?: string })[] {
+    // A transcript can be long: SQLite finds its first question, and the
+    // rest of it is left unread.
     return this.db
       .prepare(
-        "SELECT * FROM ask_conversations WHERE review_id=? ORDER BY updated_at DESC",
+        `SELECT id, anchor_board, anchor_block, ${THREAD_PROJECT_SQL} AS project_id, agent, session_id, version, head, cwd, selection, title,
+          created_at, updated_at, NULL AS entries, bypass, permissions,
+          (SELECT json_extract(value,'$.text') FROM json_each(entries)
+            WHERE json_extract(value,'$.kind')='user' LIMIT 1) AS question
+        FROM ask_conversations WHERE ${where} ORDER BY updated_at DESC`,
       )
-      .all(reviewId)
+      .all(...params)
       .map((row) => {
         const {
-          reviewId: _reviewId,
+          anchor,
           sessionId: _sessionId,
           version: _version,
           cwd: _cwd,
-          entries,
+          entries: _entries,
           permissions: _permissions,
           ...entry
         } = rowSchema.parse(row);
 
-        const question = entries?.find((entry) => entry.kind === "user")?.text;
+        const question = z.string().nullable().parse(row.question) ?? "";
 
-        if (question?.trim()) entry.question = question;
+        if (question.trim()) entry.question = question;
 
-        return entry;
+        return { ...entry, anchor };
       });
   }
 
   get(id: string): AskRecord | undefined {
     const row = this.db
-      .prepare("SELECT * FROM ask_conversations WHERE id=?")
+      .prepare(`SELECT ${THREAD_COLUMNS} FROM ask_conversations WHERE id=?`)
       .get(id);
 
     return row ? rowSchema.parse(row) : undefined;
   }
 
+  /** The reviewer saw the thread, on screen with the app focused. Only
+   * when it was seen changes: not its order, nor when it was used. */
+  markViewed(id: string, at = new Date().toISOString()) {
+    this.db
+      .prepare("UPDATE ask_conversations SET viewed_at=? WHERE id=?")
+      .run(at, id);
+    this.changed();
+  }
+
+  /** When each of these threads was last viewed, where it ever was.
+   * Threads from before views were kept have none, and none is unread. */
+  viewedAt(ids: readonly string[]): Map<string, string> {
+    const select = this.db.prepare(
+      "SELECT viewed_at FROM ask_conversations WHERE id=? AND viewed_at IS NOT NULL",
+    );
+
+    return new Map(
+      ids.flatMap((id) => {
+        const row = select.get(id);
+
+        return row ? [[id, String(row.viewed_at)] as const] : [];
+      }),
+    );
+  }
+
+  /** Forgets the threads that started on a board gone for good. */
   removeReview(reviewId: string) {
     this.db
-      .prepare("DELETE FROM ask_conversations WHERE review_id=?")
+      .prepare("DELETE FROM ask_conversations WHERE anchor_board=?")
       .run(reviewId);
+    this.changed();
   }
 
   delete(id: string) {
     this.assertThreadWritable(id);
     this.db.prepare("DELETE FROM ask_conversations WHERE id=?").run(id);
+    this.changed();
   }
 }