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

package/dist/{thread-state-5pYr6_zM.js → thread-state-D6MlnGv7.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-CyYCvVHx.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-C9MpbXJJ.js → tool-failure-_makh_Sr.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-CyYCvVHx.js";
+import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-D2RmE9NL.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,24 @@
 you are writing an interactive rfc-style whiteboard, for consumption by a staff engineer.
 
+**plans and stacks**
+
+Organize related work automatically; do not wait for the user to request grouping, child boards, or dependency order. Choose the board structure before the authoring flow below. Use `session_list` to find an existing plan or stack overview in this project before creating one.
+
+- 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` to the session IDs it builds on. For a linear stack, each child after the first depends on the previous child. `parentId` groups boards; `dependsOn` 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, use `session_set_parent` and `session_set_dependencies` to set its relationships.
+- 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 +49,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.20261020.130",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -48,7 +48,7 @@
     "@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",
@@ -74,11 +74,11 @@
     "tsx": "4.21.0",
     "typescript": "6.0.3",
     "vitest": "4.1.11",
-    "@dev.fast/json": "0.0.0",
     "@dev.fast/review-share-protocol": "0.1.2",
     "@dev.fast/trace-core": "0.0.0",
-    "@dev.fast/trace-protocol": "0.5.0",
-    "@dev.fast/review-protocol": "0.0.0"
+    "@dev.fast/json": "0.0.0",
+    "@dev.fast/review-protocol": "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": "f33bd6620742fe65ccc1d5fef416fbe8254dcf79",
+  "gitHead": "e4fb75564bd27f464cf214a4b3a9a75ada3d54a3",
   "scripts": {
     "prebuild": "pnpm run build:workspace-deps",
     "build": "node --max-old-space-size=8192 node_modules/tsdown/dist/run.mjs",

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

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

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