@dev.fast/whiteboard 0.3.4 → 0.3.5-preview.20261021.131

package/dist/{thread-state-5pYr6_zM.js → thread-state-BPpvKFwQ.js}

@@ -1,4 +1,4 @@
-import { A as ReviewSelectedDiffSchema, C as ReviewApiSelectionSourceSchema } from "./src-DsM3jO8G.js";
+import { M as ReviewSelectedDiffSchema, T as ReviewApiSelectionSourceSchema } from "./src-DYZLCUP_.js";
 import { z } from "zod";
 /** A semantic selection, independent of comment/thread creation. */
 const AgentSelectionSchema = z.strictObject({
@@ -24,6 +24,10 @@ const AgentSelectionSchema = z.strictObject({
 			startLine: z.number().int().positive(),
 			endLine: z.number().int().positive()
 		}),
+		z.strictObject({
+			kind: z.literal("block"),
+			blockId: z.string().min(1).max(200)
+		}),
 		z.strictObject({ kind: z.literal("review") })
 	]),
 	title: z.string().max(500),
@@ -36,6 +40,7 @@ function selectionMarkdown(selection, sourceExcerpt = "", diffPaths) {
 	const target = selection.target;
 	if (selection.selectedDiff) return `Selected diff:\n${selectedDiffMarkdown(selection.selectedDiff, diffPaths)}`;
 	if (target.kind === "review") return "";
+	if (target.kind === "block") return `Selected block:\n${sourceExcerpt}`;
 	if (target.kind === "text") return `Selected text:\n${target.quote.split(/\r?\n/).map((line) => `> ${line}`).join("\n")}`;
 	return `Selected code:\n${[
 		`## ${selection.title}`,
@@ -374,7 +379,12 @@ const askHistoryEntrySchema = z.object({
 	/** The commit the agent read. */
 	head: z.string(),
 	createdAt: z.string(),
-	updatedAt: z.string()
+	updatedAt: z.string(),
+	/** The board the conversation started on, and the block if it was about one. */
+	anchor: z.object({
+		board: z.string(),
+		block: z.string().optional()
+	}).optional()
 });
 //#endregion
 export { askHistoryEntrySchema as a, askPicksSchema as c, selectionMarkdown as d, askEntrySchema as i, askQuestionSchema as l, askAgentIds as n, askOfferSchema as o, askChoiceKinds as r, askPermissionsSchema as s, applyAskChange as t, AgentSelectionSchema as u };

package/dist/{tool-failure-C9MpbXJJ.js → tool-failure-CQhyLht3.js}

@@ -1,5 +1,6 @@
 import { m as isStringValue, n as isJsonObject } from "./src-X9phtB2j.js";
-import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-BOOi7EUR.js";
+import { l as boardTitle } from "./src-DYZLCUP_.js";
+import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-H53ajvrm.js";
 import { t as ReviewInputError } from "./input-error-OLgB_h31.js";
 //#region src/review-api/public-tools.ts
 function publicDescription(text) {
@@ -38,7 +39,7 @@ function publicResult(value) {
 	if (Array.isArray(value)) return value.map(publicResult);
 	if (!isJsonObject(value)) return value;
 	return Object.fromEntries(Object.entries(value).map(([key, item]) => {
-		return [key === "reviewId" ? "sessionId" : key === "review" ? "session" : key === "reviews" ? "sessions" : key, key === "review" || key === "reviews" ? publicResult(item) : item];
+		return [key === "reviewId" ? "sessionId" : key === "review" ? "session" : key === "reviews" ? "sessions" : key, key === "review" || key === "reviews" ? publicResult(item) : key === "title" && "reviewId" in value && isStringValue(item) ? boardTitle(item) : item];
 	}));
 }
 async function callPublicTool(client, tool, input, signal) {
@@ -47,7 +48,13 @@ async function callPublicTool(client, tool, input, signal) {
 	const fields = { ...rest };
 	if (sessionId !== void 0) fields.reviewId = sessionId;
 	const result = await callAuthoringTool(client, tool, fields, signal);
-	return result instanceof ToolText ? result : publicResult(result);
+	return result instanceof ToolText ? result : withoutRepositoryIds(publicResult(result));
+}
+/** Agents never see repository ids. */
+function withoutRepositoryIds(value) {
+	if (Array.isArray(value)) return value.map(withoutRepositoryIds);
+	if (!isJsonObject(value)) return value;
+	return Object.fromEntries(Object.entries(value).filter(([key]) => key !== "repositoryId").map(([key, item]) => [key, withoutRepositoryIds(item)]));
 }
 //#endregion
 //#region src/review-api/recovery.ts

package/instructions/authoring.md

@@ -1,12 +1,26 @@
 you are writing an interactive rfc-style whiteboard, for consumption by a staff engineer.
 
+**plans and stacks**
+
+Keep plans and their implementation reviews together, and group reviews of an actual PR stack. Create these relationships automatically when supported by the work's history; the user need not request nesting. Choose the board structure before the authoring flow below. Use `session_list` to find the plan governing this work or the overview of this PR stack before creating one.
+
+- Before assigning a parent, identify the plan requirement this change implements or the actual PR stack it belongs to. A plan may be authored by the user or developed with the agent during this work. A PR stack must have established branch or dependency relationships. If the change neither implements part of an established plan nor belongs to an actual PR stack, leave its review top-level.
+- Shared subject matter, repository, conversation, or resemblance to an earlier change is insufficient reason to nest boards. Related follow-ups remain top-level; link to earlier boards for context.
+- For a plan with no changes yet, create a board with `target:{kind:"project", repositoryPath}`. Do not use a worktree or commit target for a plan: those attach code and show the code-board icon.
+- When implementing a plan in several changes, keep the plan as the top-level board. Create one child board per PR or change with `parentId` set to the plan's session ID. Keep the plan's project target; do not replace it with one child's diff.
+- When reviewing an existing PR stack without a plan, create one project-target board for the overview, then one child per PR. Explain the whole change on the overview and each layer's own diff on its child.
+- Set each child's `dependsOn` only to the session IDs it actually builds on, not to impose a convenient reading order. For a linear PR stack, each child after the first depends on the previous child; independent pieces of a plan need no dependencies. `parentId` groups boards; `dependsOn` records dependencies and orders them. Git bases alone do not create these relationships.
+- For commit targets, use the branch below each layer as its `base`. For PR targets, use the PR itself; its GitHub base selects that layer's diff.
+- Nest only one level: plan or overview → change boards. Update existing boards after rebases instead of creating duplicates. If `session_create` returns an existing PR board, preserve its relationships unless the current task establishes a reason to change them. Use `session_set_parent` and `session_set_dependencies` only for the supported relationships above.
+- Link the children from the overview and link the parent from each child with `[label](whiteboard:board/<sessionId>)`. Read the overview and all children back to check their targets, parent, dependency order, and links.
+
 **flow**
-follow these first five steps in order, with no tool calls beyond what they need: loading the tools they use (`session_create`, `session_activity_begin`, `session_edit`, `session_get`, and later `session_activity_update` and `session_activity_end`) and, for a PR, reading its description (`gh pr view`).
+For each board, follow these first five steps in order, with no tool calls beyond what they need: loading the tools they use (`session_create`, `session_activity_begin`, `session_edit`, `session_get`, and later `session_activity_update` and `session_activity_end`) and, for a PR, reading its description (`gh pr view`).
 
-- create the whiteboard, pinned to the commits/pr the user describes, naming the checkout by its `repositoryPath`. if they name none, use a `worktree` target with no `base`: it reviews the checkout, uncommitted work included, against the default branch. for uncommitted work only, pass `base: "HEAD"`. untracked files are left out: run `git add -N <file>` on new files you want reviewed
-- trigger a subagent with this exact instruction: "Call `session_get_instructions({topic:\"file-lenses\"})` and follow it for whiteboard <sessionId>, whose change is `<base>..<head>` in `<repositoryPath>`."
+- create the whiteboard with a `target` naming the checkout by its `repositoryPath`: `{kind:"commits", head, base?}` for commits, `{kind:"pullRequest", pullRequest}` for a PR by URL or number, or `{kind:"project"}` for a plan with no change yet. if they name none, use a `worktree` target with no `base`: it reviews the checkout, uncommitted work included, against the default branch. for uncommitted work only, pass `base: "HEAD"`. untracked files are left out: run `git add -N <file>` on new files you want reviewed
+- for a change board only, trigger a subagent with this exact instruction: "Call `session_get_instructions({topic:\"file-lenses\"})` and follow it for whiteboard <sessionId>, whose change is `<base>..<head>` in `<repositoryPath>`."
 - call `session_activity_begin` and pass its `activityId` on every `session_edit`
-- read the diff with git (or jj) in `repositoryPath`, at the commits `session_create` returned: `git diff <base> <head>`, or for a worktree target `git diff <base>` plus `git status` for untracked files. if it shows no changes, the target is wrong: fix it with `session_set_target` before writing
+- for a project-target plan or overview, read the relevant source or the stack's combined diff; no diff is expected on the project target itself. For a change board, read the diff with git (or jj) in `repositoryPath`, at the commits `session_create` returned: `git diff <base> <head>`, or for a worktree target `git diff <base>` plus `git status` for untracked files. if it shows no changes, the target is wrong: fix it with `session_set_target` before writing
 - immediately after reading the diff (and the PR description) - put down a first pass at the what/why section.
 
 - whiteboard structure - each of these should be written as a top-level `section`, in this order:
@@ -37,4 +51,5 @@ follow these first five steps in order, with no tool calls beyond what they need
 - use `session_activity_update` to provide regular status updates on your area of focus.
 - keep whiteboards short and sweet when possible (esp. for small changes.) feel free to omit sections.
 - when something (a phrase in the prose, diagram node, etc.) describes actual code in the codebase, always default to attaching/hyperlink code.
-- Link repository code as `[label](review-source:head/src/file.ts#L10-L24)`; use `base` for old code. Use repository-relative paths and verified line numbers.
+- Link repository code as `[label](whiteboard:source/head/src/file.ts#L10-L24)`; use `base` for old code. To quote any other commit of the board's repository, as a plan does, put the commit in place of `head`: `[label](whiteboard:source/<commit>/src/file.ts#L10-L24)`. Use repository-relative paths and verified line numbers.
+- Link another whiteboard inline as `[label](whiteboard:board/<sessionId>)`, or one of its blocks as `[label](whiteboard:board/<sessionId>#<blockId>)`, wherever the prose refers to it. The board and block must exist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.fast/whiteboard",
-  "version": "0.3.4",
+  "version": "0.3.5-preview.20261021.131",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -44,11 +44,11 @@
     "@agentclientprotocol/sdk": "1.5.1",
     "@hono/node-server": "2.0.12",
     "@img/sharp-wasm32": "0.35.5",
-    "@modelcontextprotocol/sdk": "1.31.0",
+    "@modelcontextprotocol/sdk": "1.32.0",
     "@parcel/watcher": "2.6.0",
     "commander": "14.0.3",
     "fuzzysort": "4.0.2",
-    "hono": "4.13.7",
+    "hono": "4.13.11",
     "mdast-util-from-markdown": "2.0.3",
     "mdast-util-gfm": "3.1.0",
     "mdast-util-math": "3.0.0",
@@ -88,7 +88,7 @@
     "repo": "devdotfast/review",
     "docs": "packages/review/instructions/authoring.md"
   },
-  "gitHead": "f33bd6620742fe65ccc1d5fef416fbe8254dcf79",
+  "gitHead": "6bf7b672e0c4d566b582d555044a624620c6311f",
   "scripts": {
     "prebuild": "pnpm run build:workspace-deps",
     "build": "node --max-old-space-size=8192 node_modules/tsdown/dist/run.mjs",

package/src/agent-selection.ts

@@ -35,6 +35,10 @@ export const AgentSelectionSchema = z.strictObject({
       startLine: z.number().int().positive(),
       endLine: z.number().int().positive(),
     }),
+    z.strictObject({
+      kind: z.literal("block"),
+      blockId: z.string().min(1).max(200),
+    }),
     /** Nothing in particular: a question about the whole review. */
     z.strictObject({ kind: z.literal("review") }),
   ]),
@@ -61,6 +65,8 @@ export function selectionMarkdown(
 
   if (target.kind === "review") return "";
 
+  if (target.kind === "block") return `Selected block:\n${sourceExcerpt}`;
+
   if (target.kind === "text")
     return `Selected text:\n${target.quote
       .split(/\r?\n/)

package/src/ask/agents.ts

@@ -19,6 +19,7 @@ import {
   type AskPermissions,
   askAgentIds,
 } from "@review/ask/thread-state.js";
+import { ASK_THREAD_ENV } from "@review/review-api/request-origin.js";
 
 /** How Whiteboard runs an agent that speaks ACP on stdio. */
 type AskAgentLaunch =
@@ -247,6 +248,8 @@ export type AskAgentLauncher = (
     /** The MCP servers its sessions are given. */
     mcpServers?: McpServer[];
     env?: NodeJS.ProcessEnv;
+    /** The Ask thread this agent serves. */
+    threadId?: string;
   },
 ) => Promise<AskAgentProcess>;
 
@@ -357,7 +360,12 @@ const STDERR_LIMIT = 8_000;
 export const launchAskAgent: AskAgentLauncher = async (
   agent,
   cwd,
-  { permissions = "read-only", mcpServers = [], env: base = process.env } = {},
+  {
+    permissions = "read-only",
+    mcpServers = [],
+    env: base = process.env,
+    threadId,
+  } = {},
 ) => {
   const spec = askAgents[agent];
   const executable = await findAgent(spec, base);
@@ -369,6 +377,10 @@ export const launchAskAgent: AskAgentLauncher = async (
     ...askAgentSettings(agent, permissions).env,
   };
 
+  // Lets `whiteboard api` calls from the agent's shell name the thread.
+  // The MCP server gets it in its own env, since MCP clients may not pass theirs on.
+  if (threadId) env[ASK_THREAD_ENV] = threadId;
+
   // A server started from inside a Claude Code session must not look nested.
   delete env.CLAUDECODE;
   delete env.CLAUDE_CODE_ENTRYPOINT;

package/src/ask/checkout-files.ts

@@ -1,13 +1,10 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
+import { runVcs } from "@dev.fast/local-vcs";
 
 /** The checkout's files relative to its root: tracked ones, and new ones git
  * does not ignore. None where git cannot list them. */
 export async function checkoutFiles(root: string): Promise<string[]> {
   try {
-    const { stdout } = await execFileAsync(
+    const { stdout } = await runVcs(
       "git",
       [
         "-C",

package/src/ask/thread-state.ts

@@ -375,6 +375,10 @@ export const askHistoryEntrySchema = z.object({
   head: z.string(),
   createdAt: z.string(),
   updatedAt: z.string(),
+  /** The board the conversation started on, and the block if it was about one. */
+  anchor: z
+    .object({ board: z.string(), block: z.string().optional() })
+    .optional(),
 });
 
 export type AskHistoryEntry = z.infer<typeof askHistoryEntrySchema>;

package/src/ask/thread.ts

@@ -88,6 +88,15 @@ const steeringSchema = z.object({
 
 const steerOutcomeSchema = z.object({ outcome: z.string() });
 
+/** A review Codex couldn't run; one it ran has a risk level. */
+const failedReviewSchema = z.object({
+  review: z.object({
+    status: z.literal("denied"),
+    riskLevel: z.null(),
+    rationale: z.string(),
+  }),
+});
+
 /** MCP servers the reviewer's own agent may bring whose tools only read,
  * so their calls run without asking, like the agent reading files. */
 const READ_ONLY_MCP_SERVERS = new Set([
@@ -100,8 +109,6 @@ const READ_ONLY_MCP_SERVERS = new Set([
  * the reviewer. */
 export type AskMcpServers = (threadId: string) => McpServer[];
 
-/** Where a thread saves what happens to it, which moves with the thread
- * when another review adopts it. */
 export interface AskThreadHooks {
   /** The agent created a session: the id a later reopen loads. A new one
    * replaces a session the agent could not reopen. */
@@ -176,6 +183,7 @@ export class AskThread {
   /** The number of changes so far; a snapshot carries the one it includes. */
   private seq = 0;
   private readonly listeners = new Set<(update: AskUpdate) => void>();
+  private readonly statusListeners = new Set<() => void>();
   private readonly closers = new Set<() => void>();
   private readonly decisions = new Map<
     string,
@@ -214,6 +222,8 @@ export class AskThread {
   private needsContext: boolean;
   /** The reviewer changed what the agent may do since it was last told. */
   private permitted = false;
+  /** Why the agent's automatic approval review failed this turn. */
+  private reviewFailure?: string;
   /** The agent could not reopen the session, for a reason signing in would
    * not fix, so trying again starts a new one. */
   private unloadable = false;
@@ -227,9 +237,6 @@ export class AskThread {
   private steerable = false;
   /** Follow-ups waiting for the turn under way to end, oldest first. */
   private queue: { id: string; question: AskQuestion }[] = [];
-  /** The review the thread answers in, and where it saves; adopting moves
-   * both. */
-  private home: AskThreadHooks & { reviewId: string };
 
   constructor(
     private readonly launch: AskAgentLauncher,
@@ -240,15 +247,6 @@ export class AskThread {
     this.id = start.id ?? randomUUID();
     this.mcpServers = mcpServers(this.id);
     this.picks = { ...start.picks };
-    this.home = {
-      reviewId: start.reviewId,
-      onSession: start.onSession,
-      onTurn: start.onTurn,
-      onSave: start.onSave,
-      onPermissions: start.onPermissions,
-      onOffer: start.onOffer,
-      onTitle: start.onTitle,
-    };
     this.state = {
       id: this.id,
       agent: start.agent,
@@ -268,16 +266,7 @@ export class AskThread {
   }
 
   get reviewId() {
-    return this.home.reviewId;
-  }
-
-  /** Moves the thread to another review, as when its agent creates the
-   * review it was asked for, and saves it there as it stands. */
-  adopt(reviewId: string, hooks: AskThreadHooks) {
-    this.home = { reviewId, ...hooks };
-
-    if (this.sessionId) hooks.onSession?.(this.sessionId);
-    hooks.onSave?.(this.state.entries);
+    return this.start.reviewId;
   }
 
   read(): AskThreadState {
@@ -288,6 +277,10 @@ export class AskThread {
     return { seq: this.seq, snapshot: this.state };
   }
 
+  get status() {
+    return this.state.status;
+  }
+
   /** Every change after the current `seq`, in order. */
   subscribe(listener: (update: AskUpdate) => void) {
     this.listeners.add(listener);
@@ -295,6 +288,13 @@ export class AskThread {
     return () => this.listeners.delete(listener);
   }
 
+  /** Calls back when the status changes, without following the thread. */
+  onStatusChange(listener: () => void) {
+    this.statusListeners.add(listener);
+
+    return () => this.statusListeners.delete(listener);
+  }
+
   /** Whether anything follows the thread, as an open panel does. */
   watched() {
     return this.listeners.size > 0;
@@ -506,7 +506,7 @@ export class AskThread {
         this.state.status !== "starting" &&
         this.state.status !== "failed"
       )
-        this.home.onSave?.(settled(this.state.entries));
+        this.start.onSave?.(settled(this.state.entries));
     } finally {
       for (const resolve of this.decisions.values())
         resolve({ outcome: { outcome: "cancelled" } });
@@ -630,6 +630,7 @@ export class AskThread {
     const launched = await this.launch(this.start.agent, this.start.cwd, {
       permissions: this.state.permissions,
       mcpServers: this.mcpServers,
+      threadId: this.id,
     });
 
     // Closed, stopped or given up on while the process started.
@@ -851,7 +852,7 @@ export class AskThread {
     if (commands) offer.commands = commands;
 
     if (accepts) offer.accepts = accepts;
-    this.home.onOffer?.(offer);
+    this.start.onOffer?.(offer);
   }
 
   /** Changes what the agent may do from the next answer: it starts again
@@ -874,7 +875,7 @@ export class AskThread {
 
     this.emit({ type: "set", permissions });
     this.permitted = true;
-    this.home.onPermissions?.(permissions);
+    this.start.onPermissions?.(permissions);
     this.disconnect();
     // Its mode is Whiteboard's change, not one to announce as the agent's.
     this.settings.clear();
@@ -923,7 +924,7 @@ export class AskThread {
       if (this.closed) throw new Error("This conversation has ended.");
 
       this.sessionId = response.sessionId;
-      this.home.onSession?.(response.sessionId);
+      this.start.onSession?.(response.sessionId);
 
       this.greeting = piGreetingSchema.safeParse(
         response._meta,
@@ -1055,6 +1056,20 @@ export class AskThread {
         title: `${this.state.agentName} finished without replying.`,
       });
 
+    // Every action would fail review again; read-only asks Whiteboard instead.
+    const reviewFailed =
+      this.reviewFailure !== undefined && this.state.permissions === "auto";
+
+    if (reviewFailed)
+      this.push({
+        kind: "notice",
+        id: randomUUID(),
+        severity: "warning",
+        title: `${this.state.agentName}'s automatic approval review failed, so this conversation is now read-only. Ask again to continue.`,
+        description: this.reviewFailure,
+      });
+    this.reviewFailure = undefined;
+
     this.emit({
       type: "set",
       status: "idle",
@@ -1065,8 +1080,10 @@ export class AskThread {
             ? `${this.state.agentName} stopped before finishing.`
             : null,
     });
-    this.home.onTurn?.();
-    this.home.onSave?.(this.state.entries);
+    this.start.onTurn?.();
+    this.start.onSave?.(this.state.entries);
+
+    if (reviewFailed) await this.permit("read-only");
     this.askQueued();
   }
 
@@ -1245,6 +1262,7 @@ export class AskThread {
 
       case "tool_call":
         this.noteMcpServer(update);
+        this.noteReview(update);
         this.push({
           kind: "tool",
           id: update.toolCallId,
@@ -1258,6 +1276,7 @@ export class AskThread {
         return;
       case "tool_call_update":
         this.noteMcpServer(update);
+        this.noteReview(update);
 
         // An agent may report a tool call's first state as an update.
         if (
@@ -1340,7 +1359,7 @@ export class AskThread {
 
         if (title && title !== this.state.title) {
           this.emit({ type: "set", title });
-          this.home.onTitle?.(title);
+          this.start.onTitle?.(title);
         }
 
         return true;
@@ -1357,6 +1376,14 @@ export class AskThread {
     if (server) this.mcpCalls.set(update.toolCallId, server);
   }
 
+  private noteReview(update: ToolCallUpdate) {
+    const failed = failedReviewSchema.safeParse(
+      update.rawOutput ?? update.rawInput,
+    ).data;
+
+    if (failed && !this.replaying) this.reviewFailure = failed.review.rationale;
+  }
+
   /**
    * In its read-only mode Claude answers by writing a plan and asking to
    * leave the mode with it. That request is refused, so the plan is shown
@@ -1533,5 +1560,8 @@ export class AskThread {
     const update = { seq: this.seq, change };
 
     for (const listener of this.listeners) listener(update);
+
+    if (change.type === "set" && change.status)
+      for (const listener of this.statusListeners) listener();
   }
 }

package/src/ask/threads.ts

@@ -18,6 +18,7 @@ import {
   type AskThreadStart,
   askThreadLimits,
 } from "@review/ask/thread.js";
+import { ASK_THREAD_ENV } from "@review/review-api/request-origin.js";
 
 /** How long an agent may take to say what it offers. */
 const OFFER_TIMEOUT_MS = 30_000;
@@ -163,7 +164,7 @@ export function cliAskTools(
   ];
 
   return {
-    mcpServers: () => {
+    mcpServers: (threadId) => {
       const cli = cliPath();
 
       return cli
@@ -172,7 +173,9 @@ export function cliAskTools(
               name: "whiteboard",
               command: process.execPath,
               args: [cli, "mcp"],
-              env: env(),
+              // MCP clients may not pass their own env on, so the server
+              // gets the thread it serves in its own.
+              env: [...env(), { name: ASK_THREAD_ENV, value: threadId }],
             },
           ]
         : [];
@@ -218,6 +221,8 @@ export class AskThreads {
 
   private readonly mcpServers: AskMcpServers;
 
+  private readonly statusListeners = new Set<() => void>();
+
   constructor(
     private readonly launch: AskAgentLauncher,
     private readonly tools: AskTools = {},
@@ -249,6 +254,8 @@ export class AskThreads {
     );
 
     this.threads.set(thread.id, thread);
+    thread.onStatusChange(() => this.statusChanged());
+    this.statusChanged();
     void thread.open();
     this.sweeper ??= setInterval(() => this.sweep(), SWEEP_MS);
     this.sweeper.unref?.();
@@ -291,6 +298,19 @@ export class AskThreads {
     }
   }
 
+  /** Calls back when a thread opens, closes or changes its status. */
+  subscribeStatus(listener: () => void) {
+    this.statusListeners.add(listener);
+
+    return () => {
+      this.statusListeners.delete(listener);
+    };
+  }
+
+  private statusChanged() {
+    for (const listener of this.statusListeners) listener();
+  }
+
   get(id: string) {
     return this.threads.get(id);
   }
@@ -313,9 +333,10 @@ export class AskThreads {
 
   close(id: string, save = true) {
     const thread = this.threads.get(id);
-    this.threads.delete(id);
     this.unwatchedSince.delete(id);
     thread?.close(save);
+
+    if (this.threads.delete(id)) this.statusChanged();
   }
 
   closeDeletedReviews(isDeleted: (reviewId: string) => boolean) {

package/src/cli-install.ts

@@ -699,11 +699,16 @@ export async function writePathShim(
   cliPath: string,
   runtimePath: string | undefined,
   devHome: string,
+  previewHome = devHome,
 ): Promise<void> {
   if (process.platform === "win32") {
     await writeFileAtomicAsync(
       shimPath,
-      windowsCliShim(cliPath, runtimePath ?? process.execPath, devHome),
+      windowsCliShim(
+        cliPath,
+        runtimePath ?? process.execPath,
+        devHome === previewHome ? devHome : undefined,
+      ),
       { replaceSymlink: true },
     );
 
@@ -716,6 +721,8 @@ export async function writePathShim(
 FALLBACK_CLI=${shSingleQuote(cliPath)}
 FALLBACK_RUNTIME=${shSingleQuote(runtimePath ?? "")}
 DEFAULT_HOME=${shSingleQuote(devHome)}
+channel="\${DEV_FAST_REVIEW_CHANNEL:-\${DEV_REVIEW_INSTANCE:-}}"
+[ "$channel" = preview ] && DEFAULT_HOME=${shSingleQuote(previewHome)}
 export DEV_REVIEW_HOME="\${DEV_REVIEW_HOME:-$DEFAULT_HOME}"
 DESKTOP="$DEV_REVIEW_HOME/review-desktop"
 
@@ -836,7 +843,11 @@ export async function installReviewCommand(input: {
     shimPath,
     input.cliPath,
     input.cliRuntimePath,
-    devReviewHome(env, homeDir),
+    devReviewHome({ DEV_REVIEW_HOME: env.DEV_REVIEW_HOME }, homeDir),
+    devReviewHome(
+      { DEV_REVIEW_HOME: env.DEV_REVIEW_HOME, DEV_REVIEW_INSTANCE: "preview" },
+      homeDir,
+    ),
   );
 
   if (await traceMachineEnabled({ homeDir, env })) {

package/src/cli-runner.ts

@@ -5,6 +5,7 @@ import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 
+import { boardTitle } from "@dev.fast/review-protocol";
 import {
   REVIEW_CLI_INSTALL_TARGET_LABELS,
   REVIEW_REMOTE_AGENT_IDS,
@@ -836,7 +837,9 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
             : "Whiteboard Desktop is ready in the background. Pass --focus to bring it forward.\n",
       );
     } else {
-      input.stdout.write(`Whiteboard Desktop is showing "${event.title}".\n`);
+      input.stdout.write(
+        `Whiteboard Desktop is showing "${boardTitle(event.title)}".\n`,
+      );
     }
   };
 

package/src/cli.ts

@@ -84,9 +84,12 @@ async function maybeDelegateToDesktopCli(
   // This bootstrap runs before the Node floor check, so it cannot import
   // devReviewHome() from @dev.fast/trace-core: that module graph needs a modern
   // Node. Keep this copy in step with devReviewHome().
+  const channel =
+    env.DEV_FAST_REVIEW_CHANNEL?.trim() || env.DEV_REVIEW_INSTANCE?.trim();
+
   const devHome = env.DEV_REVIEW_HOME?.trim()
     ? path.resolve(env.DEV_REVIEW_HOME.trim())
-    : path.join(os.homedir(), ".dev");
+    : path.join(os.homedir(), channel === "preview" ? ".dev-preview" : ".dev");
 
   let cliPath: string;
   let runtimePath: string | undefined;