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

package/src/review-api/http.ts

@@ -1,23 +1,11 @@
-import {
-  type JsonObject,
-  type JsonValue,
-  isJsonObject,
-  isStringValue,
-} from "@dev.fast/json";
-import { defaultBranch, resolveRepoContextSync } from "@dev.fast/local-vcs";
+import { type JsonObject, isJsonObject } from "@dev.fast/json";
 import {
   REVIEW_CLIENT_HEADER,
   REVIEW_CLIENT_REMOTE,
-  type ReviewApiSummary,
-  type ReviewBoardPlace,
-  type ReviewProjectThreads,
   type ReviewRemoteLanguageEnvironment,
   type ReviewRemoteNavigatorAnswer,
   type ReviewStreamLine,
   type ReviewStructuralDiffEvent,
-  type ReviewThreadBoard,
-  boardIconKind,
-  boardTitle,
 } from "@dev.fast/review-protocol";
 import { errorMessage } from "@dev.fast/trace-core";
 import {
@@ -63,13 +51,12 @@ import { anchorQuotes } from "./anchor-quotes.js";
 import type { AskRecord } from "./ask-history.js";
 import { authoringTools } from "./authoring-tools.js";
 import { documentText } from "./document-text.js";
+import { ReviewInputError } from "./document.js";
 import {
-  ReviewInputError,
-  type ReviewTarget,
-  boardLinks,
-  boardRepositoryId,
-} from "./document.js";
-import { instructionsQuerySchema, renderInstructions } from "./instructions.js";
+  instructionsQuerySchema,
+  renderInstructions,
+  scratchpadAvailable,
+} from "./instructions.js";
 import type { LocalReviewData } from "./local-data.js";
 import { registerOnboardingRoutes } from "./onboarding.js";
 import {
@@ -78,8 +65,6 @@ import {
   readQuerySchemas,
 } from "./read-schemas.js";
 import {
-  REVIEW_PERSON_HEADER,
-  REVIEW_THREAD_HEADER,
   type ReviewRequestVia,
   reviewRequestOrigin,
 } from "./request-origin.js";
@@ -92,9 +77,8 @@ import {
   uncategorizedReport,
 } from "./review-progress.js";
 import {
-  type Author,
-  type PlacedBoard,
   type ReviewStore,
+  SCRATCHPAD_ID,
   type Snapshot,
   commandSchema,
   inspectSnapshot,
@@ -158,8 +142,13 @@ const askDecisionSchema = z.strictObject({
 export interface AuthoringCapabilities {
   desktopAvailable: boolean;
   softwareMapEnabled: boolean;
+  /** Off, the host neither makes nor lists the scratchpad, and refuses its id. */
+  scratchpadEnabled: boolean;
 }
 
+const SCRATCHPAD_DISABLED =
+  "The scratchpad is off. Turn it on in Whiteboard Desktop Settings.";
+
 /**
  * What the host reports about reviews, for telemetry. `onReviewCreated` fires
  * again for a replayed create command; consumers dedupe by review id.
@@ -167,6 +156,7 @@ export interface AuthoringCapabilities {
 export interface ReviewApiHooks {
   onReviewCreated?: (event: {
     reviewId: string;
+    kind: "review" | "scratchpad";
     blocks: number;
     via: ReviewRequestVia;
     agentKind?: ReviewSessionAgent;
@@ -174,14 +164,6 @@ export interface ReviewApiHooks {
   sharing?: SharingHostEvents;
 }
 
-/** A person's save carries the whole board, which edits one at a time can
- * grow past the size of a single command. */
-const PERSON_EDIT_MAX_BYTES = 16 * 1024 * 1024;
-
-/** A request the gateway forwarded from another machine. */
-const remoteCaller = (context: Context) =>
-  context.req.header(REVIEW_CLIENT_HEADER) === REVIEW_CLIENT_REMOTE;
-
 /** Both hosts mount this behind their token authentication. */
 export function createReviewApi(
   store: ReviewStore,
@@ -192,11 +174,14 @@ export function createReviewApi(
   }) => Promise<{ softwareMapEnabled: boolean }>,
   shared?: SharedReviewStore,
   capabilities: () =>
-    | AuthoringCapabilities
-    | Promise<AuthoringCapabilities> = () => ({
+    | Omit<AuthoringCapabilities, "scratchpadEnabled">
+    | Promise<Omit<AuthoringCapabilities, "scratchpadEnabled">> = () => ({
     desktopAvailable: Boolean(open),
     softwareMapEnabled: false,
   }),
+  // Synchronous because the catalog is read inside watch callbacks. The host
+  // keeps it current from its preferences file.
+  scratchpadEnabled: () => boolean = () => false,
   // Read per request: capture can change from outside this server.
   traceEnabled: () => Promise<boolean> = async () => false,
   /** Which server this is, for whiteboard_status. */
@@ -267,7 +252,23 @@ export function createReviewApi(
     operation: z.object({ reviewId: z.string().optional() }),
   });
 
+  // The host that can show the scratchpad keeps it: Desktop, while the
+  // preference is on. Headless servers never make one, and a pad made earlier
+  // stays in the store while it is off.
+  const ensureScratchpad = async (id?: string) => {
+    if (open && scratchpadEnabled() && (!id || id === SCRATCHPAD_ID))
+      await store.ensureScratchpad();
+  };
+
+  const refuseDisabledScratchpad = (id?: string) => {
+    if (id === SCRATCHPAD_ID && !scratchpadEnabled())
+      throw new ReviewInputError(SCRATCHPAD_DISABLED, 409);
+  };
+
   const sharedGuard: MiddlewareHandler = async (context, next) => {
+    refuseDisabledScratchpad(context.req.param("id"));
+    await ensureScratchpad(context.req.param("id"));
+
     const id = context.req.param("id");
 
     if (!id || !isShared(id)) return next();
@@ -299,68 +300,22 @@ export function createReviewApi(
     return snapshot;
   };
 
-  /** Adds a PR board's state, as this host last read it from GitHub. */
-  const withPullRequestState = <
-    Board extends {
-      pullRequestUrl?: string;
-      origin?: { pullRequestUrl?: string };
-    },
-  >(
-    board: Board,
-  ) => {
-    const state = data?.pullRequestState(
-      board.origin?.pullRequestUrl ?? board.pullRequestUrl,
-    );
+  const catalog = () => {
+    const local = store.list();
 
-    return state ? { ...board, pullRequestState: state } : board;
+    return [
+      ...(scratchpadEnabled()
+        ? local
+        : local.filter((summary) => summary.kind !== "scratchpad")),
+      ...(shared?.list() ?? []),
+    ];
   };
 
-  const catalog = () => [
-    ...store.list().map(withPullRequestState),
-    ...(shared?.list() ?? []),
-  ];
-
-  /** Where a board sits among its project's, and its PR's facts, for the
-   * board's header. */
-  const placeOf = (id: string): ReviewBoardPlace => {
-    if (isShared(id) || !store.has(id)) return { siblings: [] };
-
-    const { board, parent, siblings, children } = store.place(id);
-    const url = board.origin?.pullRequestUrl;
-    const state = data?.pullRequestState(url);
-    const baseBranch = url && data?.pullRequestBaseBranch(url);
-    const headBranch = url && data?.pullRequestHeadBranch(url);
-
-    const place = ({ reviewId, title, target }: PlacedBoard) => ({
-      reviewId,
-      title,
-      icon: boardIconKind(target),
-    });
-
-    const listed = (child: PlacedBoard) => {
-      const childState = data?.pullRequestState(child.origin?.pullRequestUrl);
+  app.get("/", async (context) => {
+    await ensureScratchpad();
 
-      return {
-        ...place(child),
-        ...(child.origin?.pullRequestNumber && {
-          pullRequestNumber: child.origin.pullRequestNumber,
-        }),
-        ...(childState && { pullRequestState: childState }),
-      };
-    };
-
-    return {
-      ...(state && { pullRequestState: state }),
-      ...(baseBranch && { baseBranch }),
-      ...(headBranch && { headBranch }),
-      board: place(board),
-      ...(parent && { parent: place(parent) }),
-      siblings: siblings.map(listed),
-      ...(children?.length && { children: children.map(listed) }),
-    };
-  };
-
-  app.get("/", (context) => context.json(catalog()));
+    return context.json(catalog());
+  });
 
   app.get("/feedback-eligibility", (context) =>
     context.json({ eligible: store.feedbackEligible() }),
@@ -369,13 +324,20 @@ export function createReviewApi(
   // Server-owned state only: asking the Desktop canvas would let a stalled
   // renderer block tool listing and the first instructions call.
   const instructionContext = async () => ({
+    desktopAvailable: Boolean(open),
+    scratchpadEnabled: scratchpadEnabled(),
     traceEnabled: await traceEnabled(),
   });
 
   app.get("/authoring", async (context) => {
     const instructions = await instructionContext();
 
-    return context.json(authoringTools(instructions.traceEnabled));
+    return context.json(
+      authoringTools(
+        scratchpadAvailable(instructions),
+        instructions.traceEnabled,
+      ),
+    );
   });
   app.get("/instructions", async (context) => {
     const { topic } = instructionsQuerySchema.parse(context.req.query());
@@ -506,7 +468,10 @@ export function createReviewApi(
   );
 
   app.get("/capabilities", async (context) =>
-    context.json(await capabilities()),
+    context.json({
+      ...(await capabilities()),
+      scratchpadEnabled: scratchpadEnabled(),
+    }),
   );
 
   app.get("/:id/activity", (context) => {
@@ -538,27 +503,6 @@ export function createReviewApi(
         );
       },
     );
-  // The person's canvas, never an agent tool: a save of the whole board,
-  // the block in focus, and discarding a board left untouched.
-  app.post("/:id/person-edit", async (context) =>
-    context.json(
-      await store.personEdit(
-        context.req.param("id"),
-        await readBoundedRequestJson(context.req.raw, PERSON_EDIT_MAX_BYTES),
-      ),
-    ),
-  );
-  app.post("/:id/focus", async (context) =>
-    context.json(
-      store.focus(
-        context.req.param("id"),
-        await readBoundedRequestJson(context.req.raw),
-      ),
-    ),
-  );
-  app.post("/:id/discard", async (context) =>
-    context.json(await store.discard(context.req.param("id"))),
-  );
   app.get("/watch", (context) => {
     let input: unknown;
 
@@ -586,36 +530,6 @@ export function createReviewApi(
     let dirtyList = lists;
     const dirtyReviews = new Set(reviewIds);
     let sentList: string | undefined;
-    // Bumped when a board a review links to changes, so its links reload.
-    const linksRevision = new Map<string, number>();
-
-    // The PR states its links show: only a change to one of them sends the
-    // review again. GitHub answers for every PR on launch, a few at a time.
-    const linksKey = (id: string) => {
-      if (!data || isShared(id) || !store.has(id)) return "";
-      const { outgoing, backlinks } = store.links(id);
-
-      return JSON.stringify(
-        [...outgoing, ...backlinks].map(
-          (link) =>
-            link.pullRequestUrl &&
-            data.pullRequestState(link.pullRequestUrl, { seen: false }),
-        ),
-      );
-    };
-
-    const linksKeys = new Map(
-      [...reviewIds].map((reviewId) => [reviewId, linksKey(reviewId)] as const),
-    );
-
-    // Bumped when a review's parent or siblings change, so its header
-    // reloads them.
-    const placeRevision = new Map<string, number>();
-    const placeKey = (id: string) => JSON.stringify(placeOf(id));
-
-    const placeKeys = new Map(
-      [...reviewIds].map((reviewId) => [reviewId, placeKey(reviewId)] as const),
-    );
 
     const readReviewLine = (reviewId: string): ReviewStreamLine<Snapshot> => {
       try {
@@ -626,8 +540,6 @@ export function createReviewApi(
             ...readReview(reviewId),
             activity: store.activity.read(reviewId),
             coverageRevision: data?.coverageRevision ?? 0,
-            linksRevision: linksRevision.get(reviewId) ?? 0,
-            placeRevision: placeRevision.get(reviewId) ?? 0,
           },
         };
       } catch (error) {
@@ -672,22 +584,6 @@ export function createReviewApi(
       return true;
     };
 
-    /** Bumps the place of each board whose place changed. */
-    const refreshPlaces = () => {
-      let marked = false;
-
-      for (const [id, key] of placeKeys) {
-        const next = placeKey(id);
-
-        if (next === key) continue;
-        placeKeys.set(id, next);
-        placeRevision.set(id, (placeRevision.get(id) ?? 0) + 1);
-        marked = markReview(id) || marked;
-      }
-
-      return marked;
-    };
-
     const markLists = () => {
       dirtyList ||= lists;
 
@@ -702,14 +598,7 @@ export function createReviewApi(
           notify();
         }) ?? (() => {}),
         store.subscribe((result) => {
-          let marked = markReview(result.reviewId);
-
-          for (const from of store.linkingBoards(result.reviewId)) {
-            linksRevision.set(from, (linksRevision.get(from) ?? 0) + 1);
-            marked = markReview(from) || marked;
-          }
-
-          if (marked) notify();
+          if (markReview(result.reviewId)) notify();
         }),
         store.activity.subscribe((id) => {
           if (markReview(id)) notify();
@@ -717,31 +606,11 @@ export function createReviewApi(
         store.activity.subscribeWorking(() => {
           if (markLists()) notify();
         }),
-        // A PR's state shows on its board in the list, on links to it, and
-        // with its branches in its board's header.
-        data?.subscribePullRequestStates(() => {
-          let marked = markLists();
-
-          marked = refreshPlaces() || marked;
-
-          for (const reviewId of reviewIds) {
-            const next = linksKey(reviewId);
-
-            if (next === linksKeys.get(reviewId)) continue;
-            linksKeys.set(reviewId, next);
-            linksRevision.set(reviewId, (linksRevision.get(reviewId) ?? 0) + 1);
-            marked = markReview(reviewId) || marked;
-          }
-
-          if (marked) notify();
-        }) ?? (() => {}),
         shared?.subscribe(() => {
           if (markLists()) notify();
         }) ?? (() => {}),
         store.subscribeCatalog(() => {
-          const marked = refreshPlaces();
-
-          if (markLists() || marked) notify();
+          if (markLists()) notify();
         }),
       ];
 
@@ -815,15 +684,21 @@ export function createReviewApi(
     });
 
     // Traces are stored beside the review's own repository.
-    const tracePins = async (id: string, version?: number) => {
-      const snapshot = readReview(id, version);
+    const tracePins = (id: string, version?: number) => {
+      const { pins } = readReview(id, version);
 
-      return snapshot.pins ?? (await data.documentPins(snapshot));
+      if (!pins)
+        throw new ReviewInputError(
+          "This document has no source pins of its own.",
+          409,
+        );
+
+      return pins;
     };
 
     app.get("/:id/agent-traces", async (context) => {
       const query = traceQuery.parse(context.req.query());
-      const pins = await tracePins(context.req.param("id"), query.version);
+      const pins = tracePins(context.req.param("id"), query.version);
 
       return context.json(
         await listPinnedTraces(
@@ -835,7 +710,7 @@ export function createReviewApi(
     });
     app.get("/:id/agent-traces/:sessionId", async (context) => {
       const query = traceQuery.parse(context.req.query());
-      const pins = await tracePins(context.req.param("id"), query.version);
+      const pins = tracePins(context.req.param("id"), query.version);
 
       const result = await readStoredTrace(
         store.repositoryPath(pins.repositoryId),
@@ -914,27 +789,13 @@ export function createReviewApi(
 
       return context.json(await data!.register(input.path));
     });
-    app.post("/resources", async (context) => {
-      const body = await readBoundedRequestJson(
-        context.req.raw,
-        8 * 1024 * 1024,
-      );
-
-      // Agents send a checkout path; swap it for a repository id.
-      const named = z
-        .looseObject({ repositoryPath: z.string().min(1) })
-        .safeParse(body);
-
-      if (!named.success) return context.json(await data!.upload(body));
-      const { repositoryPath, ...upload } = named.data;
-
-      return context.json(
-        await data!.upload({
-          ...upload,
-          repositoryId: (await data!.register(repositoryPath)).id,
-        }),
-      );
-    });
+    app.post("/resources", async (context) =>
+      context.json(
+        await data!.upload(
+          await readBoundedRequestJson(context.req.raw, 8 * 1024 * 1024),
+        ),
+      ),
+    );
     app.get("/:id/resources/:resourceId", async (context) => {
       const id = context.req.param("id");
       const snapshot = readReview(id);
@@ -1135,20 +996,6 @@ export function createReviewApi(
 
       return context.json(await data.changes(pins));
     });
-    // A commit a quote is read at, in the board's repository.
-    app.get("/:id/commit/:commit", async (context) => {
-      const repositoryId = boardRepositoryId(
-        readReview(context.req.param("id")),
-      );
-
-      if (!repositoryId)
-        throw new ReviewInputError("This board has no repository.", 404);
-
-      return context.json(
-        await data.commitInfo(repositoryId, context.req.param("commit")),
-      );
-    });
-
     app.get("/:id/commits", async (context) => {
       const input = readQuerySchemas.commits.parse(context.req.query());
 
@@ -1238,7 +1085,7 @@ export function createReviewApi(
     );
 
     return [
-      `Whiteboard: ${boardTitle(snapshot.title)}`,
+      `Whiteboard: ${snapshot.title}`,
       `Session ID: ${snapshot.reviewId}`,
       `Version: ${snapshot.version}`,
       ...(selection.apiSource?.commit
@@ -1246,6 +1093,7 @@ export function createReviewApi(
         : []),
       ...(selection.apiSource?.pins
         ? [
+            `Selected repository ID: ${selection.apiSource.pins.repositoryId}`,
             ...(selection.apiSource.pins.base
               ? [`Selected base: ${selection.apiSource.pins.base}`]
               : []),
@@ -1254,6 +1102,7 @@ export function createReviewApi(
         : []),
       ...(snapshot.pins
         ? [
+            `Repository ID: ${snapshot.pins.repositoryId}`,
             `Session base: ${snapshot.pins.base}`,
             `Session head: ${snapshot.pins.head}`,
           ]
@@ -1267,15 +1116,10 @@ export function createReviewApi(
   }
 
   if (ask && data) {
-    const projectOf = (reviewId: string) =>
-      isShared(reviewId) || !store.has(reviewId)
-        ? undefined
-        : store.projectOf(reviewId);
-
     const readThread = (reviewId: string, threadId: string) => {
       const thread = ask.threads.get(threadId);
 
-      if (!thread)
+      if (!thread || thread.reviewId !== reviewId)
         throw new ReviewInputError("This conversation has ended.", 404);
 
       return thread;
@@ -1354,7 +1198,7 @@ export function createReviewApi(
       const { reviewId } = snapshot;
 
       return [
-        `A reviewer is reading "${boardTitle(snapshot.title)}" in Whiteboard and has a question about ${selection.target.kind === "review" ? "it" : "a selection"}.`,
+        `A reviewer is reading "${snapshot.title}" in Whiteboard and has a question about ${selection.target.kind === "review" ? "it" : "a selection"}.`,
         checkout.live
           ? "Your working directory is the repository the review describes."
           : `Your working directory is a checkout of the review's head commit, ${checkout.head}. Answer from this code, not from other branches.`,
@@ -1482,9 +1326,6 @@ export function createReviewApi(
 
       assertWritable(reviewId);
 
-      // Asked on screen: seen from the start.
-      store.askHistory.markViewed(id, createdAt);
-
       const thread = ask.threads.open({
         id,
         reviewId,
@@ -1493,10 +1334,7 @@ export function createReviewApi(
         // replaces a session the agent could not reopen.
         ...historyHooks({
           id,
-          anchor:
-            target.kind === "text" && target.anchor
-              ? { board: reviewId, block: target.anchor.blockId }
-              : { board: reviewId },
+          reviewId,
           agent: input.agent,
           version: snapshot.version,
           head: checkout.head,
@@ -1522,109 +1360,12 @@ export function createReviewApi(
       return context.json({ threadId: thread.id });
     });
 
-    /** Every project's threads for the sidebar: who runs them, where they
-     * started and live, and which boards they changed. */
-    const projectThreads = (reviewId: string): ReviewProjectThreads => {
-      const entries = store.askHistory.listAll();
-
-      const ids = entries.map((entry) => entry.id);
-      const edited = store.boardsChangedByThreads(ids);
-      const viewed = store.askHistory.viewedAt(ids);
-
-      const boards = new Map<string, ReviewThreadBoard>();
-
-      const board = (id: string) => {
-        let found = boards.get(id);
-
-        if (!found) {
-          found = store.has(id)
-            ? store.boardFace(id)
-            : { reviewId: id, icon: boardIconKind(undefined) };
-          boards.set(id, found);
-        }
-
-        return found;
-      };
-
-      const project = projectOf(reviewId);
-
-      return {
-        board: reviewId,
-        ...(project && { project }),
-        threads: entries.map((entry) => {
-          const anchor = entry.anchor ?? { board: reviewId };
-          const status = ask.threads.get(entry.id)?.status;
-          const viewedAt = viewed.get(entry.id);
-
-          // A turn finished since the reviewer last saw the thread.
-          const unread =
-            status !== "starting" &&
-            status !== "running" &&
-            status !== "waiting" &&
-            viewedAt !== undefined &&
-            entry.updatedAt > viewedAt;
-
-          return {
-            id: entry.id,
-            ...(entry.projectId && { projectId: entry.projectId }),
-            ...(store.has(anchor.board) && {
-              place: store.boardPlace(anchor.board),
-            }),
-            agent: entry.agent,
-            agentName: askAgents[entry.agent].name,
-            opening: entry.question ?? entry.title,
-            pinned:
-              entry.selection.target.kind === "text" &&
-              entry.selection.target.anchor !== undefined,
-            ...(status && { status }),
-            ...(unread && { unread }),
-            updatedAt: entry.updatedAt,
-            anchor: {
-              board: board(anchor.board),
-              ...(anchor.block && { block: anchor.block }),
-            },
-            edited: edited.get(entry.id) ?? [],
-          };
-        }),
-      };
-    };
-
     app.get("/:id/ask/threads", (context) => {
       const reviewId = context.req.param("id");
 
       readReview(reviewId);
 
-      if (context.req.query("watch") !== undefined) {
-        // Sent again only when it reads differently.
-        let sent = "";
-
-        return watch(
-          () => {
-            const line = JSON.stringify(projectThreads(reviewId));
-
-            if (line === sent) return [];
-            sent = line;
-
-            return [line];
-          },
-          (notify) => {
-            const stops = [
-              store.askHistory.subscribe(notify),
-              ask.threads.subscribeStatus(notify),
-              // An edit, title or target of any board a thread may show; a
-              // deleted board may have been a thread's anchor.
-              store.subscribe(() => notify()),
-            ];
-
-            return () => stops.forEach((stop) => stop());
-          },
-        );
-      }
-
-      return context.json({
-        threads: store.askHistory.list(reviewId, projectOf(reviewId)),
-        board: reviewId,
-      });
+      return context.json({ threads: store.askHistory.list(reviewId) });
     });
 
     // The threads of every open Ask in a review, over one connection. Before
@@ -1643,32 +1384,20 @@ export function createReviewApi(
           threads.map((threadId) => {
             const thread = ask.threads.get(threadId);
 
-            return [threadId, thread];
+            return [
+              threadId,
+              thread?.reviewId === reviewId ? thread : undefined,
+            ];
           }),
         ),
       );
     });
 
-    // The boards a thread changed: titles from any project, so only for a
-    // local caller.
-    app.get("/:id/ask/:threadId/boards", (context) => {
-      const threadId = context.req.param("threadId");
-      const record = store.askHistory.get(threadId);
-
-      const anchor =
-        record?.anchor.board ?? ask.threads.get(threadId)?.reviewId;
-
-      if (remoteCaller(context) || !anchor)
-        throw new ReviewInputError("This conversation was not found.", 404);
-
-      return context.json({ boards: store.boardsChangedBy(threadId) });
-    });
-
     // A saved conversation, without starting its agent.
     app.get("/:id/ask/:threadId", (context) => {
       const record = store.askHistory.get(context.req.param("threadId"));
 
-      if (!record)
+      if (record?.reviewId !== context.req.param("id"))
         throw new ReviewInputError("This conversation was not found.", 404);
       const target = record.selection.target;
 
@@ -1700,19 +1429,17 @@ export function createReviewApi(
         const threadId = context.req.param("threadId");
         const live = ask.threads.get(threadId);
 
-        if (live) return context.json({ threadId });
+        if (live?.reviewId === reviewId) return context.json({ threadId });
         const record = store.askHistory.get(threadId);
 
         const { picks } = askOpenSchema.parse(
           await readBoundedRequestJson(context.req.raw, undefined, {}),
         );
 
-        if (!record)
+        if (record?.reviewId !== reviewId)
           throw new ReviewInputError("This conversation was not found.", 404);
 
-        // The thread runs in the checkout of the board it started on.
-        const anchor = record.anchor.board;
-        const snapshot = readReview(anchor, record.version);
+        const snapshot = readReview(reviewId, record.version);
         const checkout = await data.agentCheckout(snapshot);
         const target = record.selection.target;
 
@@ -1728,7 +1455,7 @@ export function createReviewApi(
         assertWritable(reviewId);
         ask.threads.open({
           id: record.id,
-          reviewId: anchor,
+          reviewId,
           agent: record.agent,
           cwd: checkout.rootPath,
           head: checkout.head,
@@ -1920,16 +1647,6 @@ export function createReviewApi(
       },
     );
 
-    app.post("/:id/ask/:threadId/viewed", (context) => {
-      const threadId = context.req.param("threadId");
-
-      if (!ask.threads.get(threadId) && !store.askHistory.get(threadId))
-        throw new ReviewInputError("This conversation was not found.", 404);
-      store.askHistory.markViewed(threadId);
-
-      return context.json({ ok: true });
-    });
-
     // Closing an Ask ends its agent; the conversation stays saved. A tab
     // switched away from or a reload leaves it running, to come back to.
     app.post("/:id/ask/:threadId/close", reviewAccess("read"), (context) => {
@@ -1947,29 +1664,17 @@ export function createReviewApi(
       const reviewId = context.req.param("id");
       const threadId = context.req.param("threadId");
 
-      const record = store.askHistory.get(threadId);
-
-      if (!record)
+      if (store.askHistory.get(threadId)?.reviewId !== reviewId)
         throw new ReviewInputError("This conversation was not found.", 404);
 
-      if (ask.threads.get(threadId)) ask.threads.close(threadId);
+      if (ask.threads.get(threadId)?.reviewId === reviewId)
+        ask.threads.close(threadId);
       store.askHistory.delete(threadId);
 
       return context.json({ ok: true });
     });
   }
 
-  app.get("/:id/place", (context) => {
-    const id = context.req.param("id");
-
-    if (!isShared(id)) store.assertExists(id);
-
-    return context.json(placeOf(id));
-  });
-
-  // The board's branch stack: its GitHub stack, else the reviews chained
-  // through the bases they name, bottom first. Apart from its place among
-  // boards.
   app.get("/:id/stack", async (context) => {
     const query = readQuerySchemas.get.parse(context.req.query());
     const id = context.req.param("id");
@@ -1977,94 +1682,14 @@ export function createReviewApi(
 
     if (isShared(id) || !snapshot.pins) return context.json({ layers: [] });
 
-    const repositoryPath = store
-      .repositories()
-      .find(
-        (repository) => repository.id === snapshot.pins!.repositoryId,
-      )?.path;
-
     const layers = await resolveReviewStackLayers(snapshot, store.list(), {
-      repositoryPath,
-    });
-
-    // The branch the stack sits on: the repository's default branch.
-    const trunk =
-      layers.length > 1 && repositoryPath
-        ? await defaultBranch(repositoryPath).catch(() => null)
-        : null;
-
-    return context.json({
-      layers: layers.map((layer) => {
-        const state = data?.pullRequestState(layer.pullRequestUrl ?? undefined);
-
-        return state ? { ...layer, pullRequestState: state } : layer;
-      }),
-      ...(trunk && { base: trunk.ref.replace(/^origin\//, "") }),
+      repositoryPath: store
+        .repositories()
+        .find((repository) => repository.id === snapshot.pins!.repositoryId)
+        ?.path,
     });
-  });
-
-  // The board's project and its whiteboards, for the board's sidebar.
-  app.get("/:id/project", (context) => {
-    const id = context.req.param("id");
-
-    if (isShared(id)) return context.json({ project: null, boards: [] });
-
-    const project = store.summary(id)?.project ?? null;
-
-    return context.json({
-      project,
-      boards: project
-        ? store
-            .list()
-            .filter(
-              (board) => board.project?.id === project.id && !board.trashedAt,
-            )
-            .map(withPullRequestState)
-        : [],
-    });
-  });
-  app.get("/:id/links", (context) => {
-    const id = context.req.param("id");
-
-    // A shared board's links name boards on the sender's machine: shown,
-    // but not followed.
-    if (isShared(id))
-      return context.json({
-        outgoing: boardLinks(id, readReview(id).document).map(
-          ({ from, to }) => ({ from, to, missing: true, elsewhere: true }),
-        ),
-        backlinks: [],
-      });
-
-    const { version } = readQuerySchemas.get
-      .pick({ version: true })
-      .parse({ version: context.req.query("version") });
-
-    const { outgoing, backlinks } = store.links(id, version);
-
-    return context.json({
-      outgoing: outgoing.map(withPullRequestState),
-      backlinks: backlinks.map(withPullRequestState),
-    });
-  });
-  // A link's hover card, read when it opens.
-  app.get("/:id/links/peek", (context) => {
-    const id = context.req.param("id");
 
-    if (isShared(id)) return context.json({});
-
-    const { version } = readQuerySchemas.get
-      .pick({ version: true })
-      .parse({ version: context.req.query("version") });
-
-    const board = context.req.query("board");
-    const block = context.req.query("block");
-
-    if (!board) throw new ReviewInputError("Name the linked board.", 400);
-
-    return context.json(
-      store.linkPeek(id, { board, ...(block && { block }) }, version),
-    );
+    return context.json({ layers });
   });
 
   app.get("/:id/history", (context) => {
@@ -2078,44 +1703,9 @@ export function createReviewApi(
         version: snapshot.version,
         title: snapshot.title,
         createdAt: snapshot.createdAt,
-        author: "agent",
       },
     ]);
   });
-
-  /** A board's relations as session_list reports them: only those it has. */
-  const listedRelations = ({
-    parentId,
-    children,
-    dependsOn,
-  }: ReturnType<typeof store.relations>) => {
-    const listed: Partial<ReturnType<typeof store.relations>> = {};
-
-    if (parentId) listed.parentId = parentId;
-
-    if (children.length) listed.children = children;
-
-    if (dependsOn.length) listed.dependsOn = dependsOn;
-
-    return listed;
-  };
-
-  /** A board's relations, each board named by its title. */
-  const relatedBoards = (id: string) => {
-    const { parentId, children, dependsOn } = store.relations(id);
-
-    const named = (board: string) => ({
-      id: board,
-      title: store.read(board).title,
-    });
-
-    return {
-      ...(parentId && { parent: named(parentId) }),
-      children: children.map(named),
-      dependsOn: dependsOn.map(named),
-    };
-  };
-
   app.get("/:id/inspect", (context) => {
     const query = inspectQuerySchema.parse(context.req.query());
     const id = context.req.param("id");
@@ -2123,19 +1713,12 @@ export function createReviewApi(
 
     return context.json(
       query.format === "text"
-        ? documentText(
-            snapshot,
-            query.targetId,
-            Boolean(query.full),
-            isShared(id) ? undefined : relatedBoards(id),
-          )
+        ? documentText(snapshot, query.targetId, Boolean(query.full))
         : query.targetId !== undefined
           ? inspectSnapshot(snapshot, query.targetId)
-          : {
-              ...(query.full ? snapshot : inspectSnapshot(snapshot)),
-              // Its place among the project's boards, as session_list has it.
-              ...(!isShared(id) && listedRelations(store.relations(id))),
-            },
+          : query.full
+            ? snapshot
+            : inspectSnapshot(snapshot),
     );
   });
   app.get("/:id", async (context) => {
@@ -2195,32 +1778,27 @@ export function createReviewApi(
       await readBoundedRequestJson(context.req.raw),
     );
 
-    // Without local data (a bare store), a path is recorded as it is.
-    const register = async (path: string) =>
-      data ? data.register(path) : store.registerRepository(path);
-
-    const request = withBoardRepository(
-      await locateRepositories(
-        await pullRequestTargets(
-          body,
-          register,
-          (url, repositoryId) => {
-            if (!data)
-              throw new ReviewInputError("Repositories are unavailable.");
+    const request = await locateRepositories(body, (path) => {
+      if (!data) throw new ReviewInputError("Repositories are unavailable.");
 
-            return data.resolvePullRequest(url, { id: repositoryId });
-          },
-          (id) => store.read(id),
-        ),
-        register,
-      ),
-      (id) => (store.has(id) ? store.read(id) : undefined),
-    );
+      return data.register(path);
+    });
 
     const input = commandSchema.parse(request);
 
     const command = sharedCommandSchema.safeParse(input);
 
+    if (command.success) {
+      refuseDisabledScratchpad(command.data.operation.reviewId);
+      await ensureScratchpad(command.data.operation.reviewId);
+    }
+
+    if (
+      input.operation.type === "create" &&
+      input.operation.kind === "scratchpad"
+    )
+      refuseDisabledScratchpad(SCRATCHPAD_ID);
+
     if (
       command.success &&
       command.data.operation.reviewId?.startsWith("shared-")
@@ -2269,23 +1847,7 @@ export function createReviewApi(
       throw new ReviewInputError("Shared reviews are read-only.", 409);
     }
 
-    // Who is writing, trusted only from local callers: a person from
-    // Desktop or the canvas, or an agent, perhaps a thread's. The store
-    // keeps each author's rules.
-    const threadId = remoteCaller(context)
-      ? undefined
-      : context.req.header(REVIEW_THREAD_HEADER)?.trim() || undefined;
-
-    const author: Author =
-      !remoteCaller(context) &&
-      context.req.header(REVIEW_PERSON_HEADER) !== undefined
-        ? { kind: "person" }
-        : {
-            kind: "agent",
-            ...(threadId && { threadId }),
-          };
-
-    const result = await store.execute(input, undefined, author);
+    const result = await store.execute(input);
 
     if (
       result.deleted ||
@@ -2331,6 +1893,7 @@ export function createReviewApi(
     if (result.created !== false)
       hooks.onReviewCreated?.({
         reviewId: result.reviewId,
+        kind: input.operation.kind === "scratchpad" ? "scratchpad" : "review",
         blocks: store.read(result.reviewId).document.length,
         ...reviewRequestOrigin(context.req.raw.headers),
       });
@@ -2416,148 +1979,6 @@ async function locateRepositories(
   };
 }
 
-/** Turns an agent's pullRequest target into what the store takes: a create
- * from pullRequestUrl, or for set_target the PR's resolved commits. */
-async function pullRequestTargets(
-  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Request body boundary: commandSchema parses the result.
-  body: unknown,
-  register: (path: string) => Promise<{ id: string }>,
-  resolve: (
-    url: string,
-    repositoryId: string,
-  ) => Promise<{ target: ReviewTarget }>,
-  board: (id: string) => void,
-) {
-  const target = z.strictObject({
-    kind: z.literal("pullRequest"),
-    repositoryPath: z.string().min(1),
-    pullRequest: z.union([z.string().min(1), z.number().int().positive()]),
-  });
-
-  // A set_target is checked whole before anything is registered or fetched.
-  const located = z
-    .looseObject({
-      operation: z.discriminatedUnion("type", [
-        z.looseObject({ type: z.literal("create"), target }),
-        z.strictObject({
-          type: z.literal("set_target"),
-          reviewId: z.string().min(1),
-          target,
-        }),
-      ]),
-    })
-    .safeParse(body);
-
-  if (!located.success) return body;
-  const { target: pullRequest, ...operation } = located.data.operation;
-
-  if (operation.type === "set_target") board(operation.reviewId);
-  const { id: repositoryId } = await register(pullRequest.repositoryPath);
-
-  const url = pullRequestAt(
-    pullRequest.repositoryPath,
-    pullRequest.pullRequest,
-  );
-
-  if (operation.type === "create")
-    return {
-      ...located.data,
-      operation: { ...operation, pullRequestUrl: url, repositoryId },
-    };
-
-  return {
-    ...located.data,
-    operation: {
-      ...operation,
-      target: (await resolve(url, repositoryId)).target,
-      pullRequestUrl: url,
-    },
-  };
-}
-
-/** A PR's URL: as given, or its number on the checkout's GitHub repository. */
-function pullRequestAt(repositoryPath: string, pullRequest: string | number) {
-  if (isStringValue(pullRequest) && !/^\d+$/.test(pullRequest))
-    return pullRequest;
-
-  const slug = resolveRepoContextSync(repositoryPath)?.githubSlug;
-
-  if (!slug)
-    throw new ReviewInputError(
-      "This checkout has no GitHub remote to find the PR number in; pass the PR's URL.",
-    );
-
-  return `https://github.com/${slug}/pull/${pullRequest}`;
-}
-
-/** A pins object as an edit spells it: commits, with no other fields. A
- * diagram may key its own data `pins`, and that is left alone. */
-/** Pins as an agent writes them: the board's repository is the host's to
- * add. */
-const agentPinsSchema = z.strictObject({
-  head: z.string().min(1),
-  base: z.string().min(1).optional(),
-});
-
-/** An object an agent meant as pins: one naming a head, base or repository.
- * Content may have a field called `pins` that is nothing of the kind. */
-const meantAsPins = (value: JsonValue): value is JsonObject =>
-  isJsonObject(value) &&
-  ["head", "base", "repositoryId"].some((key) => key in value);
-
-/** Sets every pins object in an edit to the board's own repository. */
-function withBoardRepository(
-  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Request body boundary: commandSchema parses the result.
-  body: unknown,
-  board: (id: string) => Snapshot | undefined,
-) {
-  const located = z
-    .looseObject({
-      operation: z.looseObject({
-        type: z.enum(["edit", "lens_edit"]),
-        reviewId: z.string(),
-        edit: z.json(),
-      }),
-    })
-    .safeParse(body);
-
-  if (!located.success) return body;
-  const snapshot = board(located.data.operation.reviewId);
-
-  const repositoryId = snapshot ? boardRepositoryId(snapshot) : undefined;
-
-  const edit = JSON.parse(
-    JSON.stringify(located.data.operation.edit),
-    (key, value: JsonValue) => {
-      if (key !== "pins" || !meantAsPins(value)) return value;
-
-      // Checked as the agent wrote them, so a mistake names head or base,
-      // never the repository the host adds.
-      const { repositoryId: _ignored, ...written } = value;
-      const pins = agentPinsSchema.safeParse(written);
-
-      if (!pins.success)
-        throw new ReviewInputError(
-          `Write pins as {head, base?}, each a commit: ${pins.error.issues
-            .map((issue) => `pins.${issue.path.join(".")}: ${issue.message}`)
-            .join("; ")}.`,
-        );
-
-      if (!repositoryId)
-        throw new ReviewInputError(
-          "This whiteboard has no repository for its pins to name commits of.",
-        );
-
-      return { ...pins.data, repositoryId };
-    },
-  );
-
-  return {
-    ...located.data,
-    operation: { ...located.data.operation, edit },
-  };
-}
-
 function watch(
   lines: () => string[],
   subscribe: (notify: () => void) => () => void,