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

package/dist/{thread-state-5pYr6_zM.js → thread-state-Do5LX10I.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-BiWNbcF_.js";
 import { z } from "zod";
 /** A semantic selection, independent of comment/thread creation. */
 const AgentSelectionSchema = z.strictObject({
@@ -374,7 +374,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-BFt2xj9i.js → tool-failure-C9J3r7KD.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-BRBzv3AV.js";
+import { l as boardTitle } from "./src-BiWNbcF_.js";
+import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-G4KxB8zB.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

@@ -3,7 +3,7 @@ you are writing an interactive rfc-style whiteboard, for consumption by a staff
 **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`).
 
-- 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
+- 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
 - 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
@@ -37,4 +37,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.3",
+  "version": "0.3.4-preview.20261019.125",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -77,8 +77,8 @@
     "@dev.fast/json": "0.0.0",
     "@dev.fast/review-protocol": "0.0.0",
     "@dev.fast/review-share-protocol": "0.1.2",
-    "@dev.fast/trace-protocol": "0.5.0",
-    "@dev.fast/trace-core": "0.0.0"
+    "@dev.fast/trace-core": "0.0.0",
+    "@dev.fast/trace-protocol": "0.5.0"
   },
   "engines": {
     "node": ">=24 <25"
@@ -88,7 +88,7 @@
     "repo": "devdotfast/review",
     "docs": "packages/review/instructions/authoring.md"
   },
-  "gitHead": "710b08c0dcb2166b8088ded6af639dd9598288c9",
+  "gitHead": "fc51298c9ea617b6624dcbf7416793fa22451afc",
   "scripts": {
     "prebuild": "pnpm run build:workspace-deps",
     "build": "node --max-old-space-size=8192 node_modules/tsdown/dist/run.mjs",

package/src/agent-connect.ts

@@ -9,7 +9,7 @@ import type {
   ReviewConnectResult,
 } from "@dev.fast/review-protocol";
 
-import { findExecutable } from "./ask/agents.js";
+import { executableCommand, findExecutable } from "./ask/agents.js";
 import {
   type McpLaunch,
   WHITEBOARD_PLUGIN as PLUGIN,
@@ -72,12 +72,18 @@ export type ConnectRun = (
   args: string[],
 ) => Promise<{ code: number; output: string }>;
 
-const runProcess: ConnectRun = (file, args) =>
+const runProcess: ConnectRun = (executable, executableArgs) =>
   new Promise((resolve) => {
+    const { file, args, windowsVerbatimArguments } = executableCommand(
+      executable,
+      executableArgs,
+    );
+
     execFile(
       file,
       args,
       {
+        windowsVerbatimArguments,
         timeout: STEP_TIMEOUT_MS,
         maxBuffer: 4 * 1024 * 1024,
         // A plugin install must never wait on a prompt nobody can see.

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 =
@@ -113,6 +114,7 @@ export const askAgents: Record<AskAgentId, AskAgentSpec> = {
   claude: {
     name: "Claude Code",
     commands: ["claude"],
+    installDirs: [".claude/local", ".local/bin"],
     launch: {
       adapter: "@agentclientprotocol/claude-agent-acp/dist/index.js",
       executableEnv: "CLAUDE_CODE_EXECUTABLE",
@@ -246,34 +248,62 @@ 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>;
 
+/** Windows can't run the extensionless sh shims npm puts beside `.cmd`s. */
+const WINDOWS_EXTENSIONS = [".exe", ".cmd"];
+
 /** Desktop inherits the login shell's PATH, so this sees what a terminal sees.
  * Package-manager bin directories are skipped: the adapters' own dependencies
  * put `codex` there, and that is not the user's install. */
 export async function findExecutable(
   command: string,
   env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
 ): Promise<string | undefined> {
+  const names =
+    platform === "win32"
+      ? WINDOWS_EXTENSIONS.map((extension) => command + extension)
+      : [command];
+
   for (const directory of (env.PATH ?? "").split(path.delimiter)) {
     if (!directory || directory.split(path.sep).includes("node_modules"))
       continue;
-    const candidate = path.join(directory, command);
 
-    try {
-      if (!(await stat(candidate)).isFile()) continue;
-      await access(candidate, constants.X_OK);
+    for (const name of names) {
+      const candidate = path.join(directory, name);
+
+      try {
+        if (!(await stat(candidate)).isFile()) continue;
+        await access(candidate, constants.X_OK);
 
-      return candidate;
-    } catch {
-      /* Not in this directory. */
+        return candidate;
+      } catch {
+        /* Not in this directory. */
+      }
     }
   }
 
   return undefined;
 }
 
+/** Windows runs a `.cmd` only through cmd.exe. */
+export function executableCommand(executable: string, args: string[]) {
+  if (process.platform !== "win32" || !/\.cmd$/i.test(executable))
+    return { file: executable, args, windowsVerbatimArguments: false };
+
+  const line = [executable, ...args].map((arg) => `"${arg}"`).join(" ");
+
+  return {
+    file: "cmd.exe",
+    args: ["/d", "/s", "/c", `"${line}"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
 /** The user's install of an agent's CLI: on PATH, else where its installer
  * puts it. */
 async function findAgent(
@@ -330,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);
@@ -342,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;
@@ -364,10 +403,13 @@ export const launchAskAgent: AskAgentLauncher = async (
     args = [createRequire(import.meta.url).resolve(launch.adapter)];
   } else args = launch.args;
 
-  const child = spawn(command, args, {
+  const start = executableCommand(command, args);
+
+  const child = spawn(start.file, start.args, {
     cwd,
     env,
     stdio: ["pipe", "pipe", "pipe"],
+    windowsVerbatimArguments: start.windowsVerbatimArguments,
   });
 
   let stderr = "";

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

@@ -176,6 +176,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,
@@ -288,6 +289,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 +300,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;
@@ -630,6 +642,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.
@@ -1533,5 +1546,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-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/diff-selection-migration.ts

@@ -1,4 +1,5 @@
 import {
+  type JsonObject,
   type JsonValue,
   isJsonObject,
   isNumberValue,
@@ -14,50 +15,63 @@ export function migrateDiffSelections(input: unknown): JsonValue {
   return migrateNode(jsonValueSchema.parse(input));
 }
 
+/** Keys whose values held retired attachments. */
+export const ATTACHMENT_KEYS = [
+  "source",
+  "peek",
+  "sources",
+  "contextSources",
+  "callSite",
+];
+
+/** A retired attachment as a selection, or undefined for anything else. */
+export function retiredSelection(value: JsonObject): JsonObject | undefined {
+  if (!isStringValue(value.file)) return undefined;
+
+  if (isNumberValue(value.fromLine) && isNumberValue(value.toLine)) {
+    const side = value.side ?? value.graph ?? "head";
+
+    return {
+      file: value.file,
+      start: { side, line: value.fromLine },
+      end: { side, line: value.toLine },
+    };
+  }
+
+  if (
+    isJsonObject(value.start) &&
+    isJsonObject(value.end) &&
+    "baseLine" in value.start
+  ) {
+    const endpoint = (row: JsonObject) =>
+      isNumberValue(row.headLine)
+        ? { side: "head", line: row.headLine }
+        : { side: "base", line: row.baseLine ?? null };
+
+    return {
+      file: value.file,
+      start: endpoint(value.start),
+      end: endpoint(value.end),
+    };
+  }
+
+  return undefined;
+}
+
 function migrateNode(value: JsonValue, attachment = false): JsonValue {
   if (Array.isArray(value))
     return value.map((child) => migrateNode(child, attachment));
 
   if (!isJsonObject(value)) return value;
 
-  if (attachment && isStringValue(value.file)) {
-    if (isNumberValue(value.fromLine) && isNumberValue(value.toLine)) {
-      const side = value.side ?? value.graph ?? "head";
-
-      return {
-        file: value.file,
-        start: { side, line: value.fromLine },
-        end: { side, line: value.toLine },
-      };
-    }
-
-    if (
-      isJsonObject(value.start) &&
-      isJsonObject(value.end) &&
-      "baseLine" in value.start
-    ) {
-      const endpoint = (row: typeof value.start) =>
-        isNumberValue(row.headLine)
-          ? { side: "head", line: row.headLine }
-          : { side: "base", line: row.baseLine };
-
-      return {
-        file: value.file,
-        start: endpoint(value.start),
-        end: endpoint(value.end),
-      };
-    }
-  }
+  const selection = attachment ? retiredSelection(value) : undefined;
+
+  if (selection) return selection;
 
   return Object.fromEntries(
     Object.entries(value).map(([key, child]) => [
       key,
-      migrateNode(
-        child,
-        ["source", "peek", "sources", "contextSources", "callSite"].includes(
-          key,
-        ),
-      ),
+      migrateNode(child, ATTACHMENT_KEYS.includes(key)),
     ]),
   );
 }

package/src/heading-anchors.ts

@@ -0,0 +1,42 @@
+import { slugify, uniqueId } from "./slug.js";
+
+// A board's headings, as the server publishes them and the editor shows
+// them: one rule for both, so a heading's anchor is the same in each.
+
+/** Whether a Markdown heading with this many `#`s is one of the board's
+ * headings, with an anchor and a Contents row: `##` and `###`. */
+export function isBoardHeading(hashes: number | undefined): boolean {
+  return hashes === 2 || hashes === 3;
+}
+
+/** Hands out heading anchors in document order: `slugify(text)`, made
+ * unique, so imported `#fragment` links still land. */
+export function headingAnchors(): (text: string) => string {
+  const used = new Set<string>();
+
+  return (text) => {
+    const id = uniqueId(slugify(text) || "section", used);
+
+    used.add(id);
+
+    return id;
+  };
+}
+
+/**
+ * A Markdown heading's depth in Contents: one step under its section,
+ * whose blocks sit at `base`, and under the block's bigger headings before
+ * it. `open` holds those headings by `#` count, and takes this one.
+ */
+export function markdownHeadingDepth(
+  open: number[],
+  hashes: number,
+  base: number,
+): number {
+  while (open.length && open.at(-1)! >= hashes) open.pop();
+  const depth = base + open.length;
+
+  open.push(hashes);
+
+  return depth;
+}

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);