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

package/dist/sharing/index.d.ts

@@ -46,6 +46,44 @@ declare const shareManifestSchema: z.ZodObject<{
 }, z.core.$strict>;
 type ShareManifest = z.infer<typeof shareManifestSchema>;
 //#endregion
+//#region ../local-vcs/src/exec.d.ts
+/** A value from outside the code, given to git, jj or gh as an operand. */
+type Operand =
+/** A full commit id. */
+{
+  commit: string;
+} |
+/** A revision expression: a commit, ref, `HEAD~1`, `a..b`. */
+{
+  rev: string;
+} |
+/** A ref or branch name. */
+{
+  ref: string;
+} |
+/** `[+]<from>:<to>`, each a commit id or ref. */
+{
+  refspec: {
+    from: string;
+    to: string;
+    force?: boolean;
+  };
+} |
+/** A path in a checkout; always after `--`. */
+{
+  path: string;
+} |
+/** A remote's name or URL. */
+{
+  remote: string;
+} |
+/** Any other value: a message, a search, a PR number. */
+{
+  value: string;
+};
+/** An argument: a flag or subcommand written in the code, or an operand. */
+type VcsArg = string | Operand;
+//#endregion
 //#region ../local-vcs/src/vcs.d.ts
 interface LocalVcsDiffFileSummary {
   path: string;
@@ -205,19 +243,16 @@ type StructuralLineCounts = {
   removed: number;
 };
 //#endregion
+//#region ../review-protocol/src/board-icons.d.ts
+/** "code" for a board with code attached, "board" for one without. */
+type BoardIconKind = "board" | "code";
+//#endregion
 //#region ../review-protocol/src/review-api-client.d.ts
 /** List metadata for the authenticated local catalog; document contents stay in snapshots. */
 interface ReviewApiSummary {
   reviewId: string;
   version: number;
   title: string;
-  /** Absent for a review. The one scratchpad has no pins or lifecycle. */
-  kind?: "scratchpad";
-  /** What is on the scratchpad, for its Home card; absent for a review. */
-  contents?: {
-    blocks: number;
-    diagrams: number;
-  };
   /** Absent for a document whose references all carry their own pins. */
   pins?: {
     repositoryId: string;
@@ -226,6 +261,9 @@ interface ReviewApiSummary {
     worktreeRevision?: string;
   };
   target?: {
+    kind: "project";
+    repositoryId: string;
+  } | {
     kind: "worktree";
     repositoryId: string;
     base?: string;
@@ -248,14 +286,17 @@ interface ReviewApiSummary {
     pullRequestTitle?: string;
     revision?: string;
   };
+  /** The PR's state on GitHub, when the host has read it. */
+  pullRequestState?: PullRequestState;
   /** Shared imports have separate local checkouts but retain their remote identity. */
   shared?: {
     cloneUrl?: string;
   };
-  /** Display grouping only; source pins remain bound to their own checkout. */
-  repositoryGroup?: {
-    key: string;
-    label: string;
+  /** The project the board belongs to; absent for a share with no
+   * repository here. */
+  project?: {
+    id: string;
+    name: string;
   };
   repositoryName: string;
   repositoryPath?: string;
@@ -266,6 +307,8 @@ interface ReviewApiSummary {
   } | null;
   viewedAt: string | null;
   trashedAt: string | null;
+  /** A version was saved after viewedAt, or the board was never viewed. */
+  changed?: boolean;
   /** An agent holds a live lease; absent on shared reviews. */
   working?: boolean;
   host?: string;
@@ -276,6 +319,12 @@ interface ReviewApiSummary {
     reason?: string;
     pending?: true;
   };
+  /** The board this one is nested under; absent at top level. */
+  parentId?: string;
+  /** The boards nested under this one, in sibling order. */
+  children?: string[];
+  /** The boards in its project this one builds on. */
+  dependsOn?: string[];
 }
 interface ReviewSourceEntry {
   path: string;
@@ -283,6 +332,8 @@ interface ReviewSourceEntry {
 }
 //#endregion
 //#region ../review-protocol/src/contracts.d.ts
+declare const PULL_REQUEST_STATES: readonly ["open", "draft", "merged", "closed"];
+type PullRequestState = (typeof PULL_REQUEST_STATES)[number];
 /** Workspace attachment identity is independent of the displayed source generation. */
 interface ReviewLanguageEnvironment {
   /** Absent for a caller on another machine. */
@@ -356,8 +407,8 @@ type SourcePins = z.infer<typeof sourcePinsSchema>;
  * Authored document attachments use DiffSelection instead. */
 declare const fileLineRangeSchema: z.ZodObject<{
   side: z.ZodDefault<z.ZodEnum<{
-    head: "head";
     base: "base";
+    head: "head";
   }>>;
   file: z.ZodString;
   fromLine: z.ZodNumber;
@@ -709,6 +760,9 @@ type Pins = z.infer<typeof pinsSchema> & {
   worktreeRevision?: string;
 };
 declare const reviewTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  kind: z.ZodLiteral<"project">;
+  repositoryId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
   kind: z.ZodLiteral<"worktree">;
   repositoryId: z.ZodString;
   base: z.ZodOptional<z.ZodString>;
@@ -723,6 +777,15 @@ type ReviewTarget = z.infer<typeof reviewTargetSchema>;
 type Element = Block | Step | FlowDiagramNode | FlowDiagramEdge;
 /** A diagram unit: addressed on its own, but only ever inside its diagram. */
 type Unit = Step | FlowDiagramNode | FlowDiagramEdge;
+/** Names a block from outside its board. Block ids are unique only within a board. */
+type BlockRef = {
+  board: string;
+  block: string;
+};
+type BoardRef = BlockRef | {
+  board: string;
+  block?: undefined;
+};
 declare const editSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   parentId: z.ZodOptional<z.ZodString>;
   afterId: z.ZodOptional<z.ZodString>;
@@ -1031,6 +1094,8 @@ interface EditSummary {
   units?: string[];
   /** The agent whose courier draws this edit, when the host could tell. */
   activityId?: string;
+  /** The Ask thread that made this edit, if any. */
+  threadId?: string;
 }
 /** A component an edit wrote, named so the author can address it. */
 interface WrittenComponent {
@@ -1048,8 +1113,10 @@ interface ComparisonCoverage {
 }
 //#endregion
 //#region src/review-api/pull-request.d.ts
-/** Runs one subprocess and resolves its stdout; rejects on failure or timeout. */
-type RunCommand = (file: string, args: string[], options: {
+/** Runs one subprocess and resolves its stdout; rejects on failure or
+ * timeout. git, jj and gh go through the VCS runner; Azure DevOps's az (by
+ * way of cmd.exe on Windows) gets its operands checked the same way. */
+type RunCommand = (file: "git" | "jj" | "gh" | "az" | "cmd.exe", args: VcsArg[], options: {
   cwd?: string;
   timeoutMs: number;
 }) => Promise<string>;
@@ -1215,37 +1282,29 @@ declare const askPermissionsSchema: z.ZodEnum<{
 }>;
 type AskPermissions = z.infer<typeof askPermissionsSchema>;
 type AskEntry = z.infer<typeof askEntrySchema>;
-/** A saved conversation, as the history list shows it. The transcript stays
- * with the agent; Whiteboard keeps what it needs to find and reopen it. */
-declare const askHistoryEntrySchema: z.ZodObject<{
-  id: z.ZodString;
-  agent: z.ZodEnum<{
-    claude: "claude";
-    codex: "codex";
-    cursor: "cursor";
-    opencode: "opencode";
-    pi: "pi";
-  }>;
-  title: z.ZodString;
-  question: z.ZodOptional<z.ZodString>;
-  selection: any;
-  head: z.ZodString;
-  createdAt: z.ZodString;
-  updatedAt: z.ZodString;
-}, z.core.$strip>;
-type AskHistoryEntry = z.infer<typeof askHistoryEntrySchema>;
 //#endregion
 //#region src/review-api/ask-history.d.ts
 /** A saved Ask conversation: its history entry, and how to reopen it. */
 declare const askRecordSchema: any;
 type AskRecord = z.infer<typeof askRecordSchema>;
-/** Saved Ask conversations, per review. Shared reviews are not in
- * `reviews`, so there is no foreign key; deleting a review deletes its rows. */
+/** Saved Ask conversations by project, each anchored on the board it started
+ * on. No foreign key on the anchor: shared reviews are not in `reviews`.
+ * So deleting a board removes its threads by hand (removeReview). */
 declare class AskHistory {
   private readonly db;
+  /** The store's rule for writing about a board: one in Trash is
+   * read-only. */
+  private readonly writable;
+  private readonly listeners;
   private externalWriteGuard?;
   setExternalWriteGuard(guard: (reviewId: string) => void): void;
-  constructor(db: DatabaseSync);
+  constructor(db: DatabaseSync,
+  /** The store's rule for writing about a board: one in Trash is
+   * read-only. */
+  writable?: (reviewId: string) => void);
+  /** Calls back when a conversation is saved, renamed, used or deleted. */
+  subscribe(listener: () => void): () => void;
+  private changed;
   private assertWritable;
   private assertThreadWritable;
   save(record: AskRecord): void;
@@ -1265,14 +1324,62 @@ declare class AskHistory {
   /** What the agent offered last, or last with the model given. */
   offer(agent: AskAgentId, model?: string): AskOffer | undefined;
   touch(id: string, at?: string): void;
-  /** Newest first. */
-  list(reviewId: string): AskHistoryEntry[];
+  /** Conversations in a board's project, or started on the board when it
+   * has none. Newest first. */
+  list(board: string, projectId?: string): any[];
+  /** Every project's conversations, newest first. */
+  listAll(): any[];
+  private entries;
   get(id: string): AskRecord | undefined;
+  /** The reviewer saw the thread, on screen with the app focused. Only
+   * when it was seen changes: not its order, nor when it was used. */
+  markViewed(id: string, at?: string): void;
+  /** When each of these threads was last viewed, where it ever was.
+   * Threads from before views were kept have none, and none is unread. */
+  viewedAt(ids: readonly string[]): Map<string, string>;
+  /** Forgets the threads that started on a board gone for good. */
   removeReview(reviewId: string): void;
   delete(id: string): void;
 }
 //#endregion
+//#region src/review-api/link-preview.d.ts
+/** What a board link's hover card shows of the board or block it links to. */
+interface BoardLinkPreview {
+  /** A block link: the title of the section the block is in. */
+  section?: string;
+  /** Markdown paragraphs, opening the board or block. */
+  prose?: string[];
+  /** A block link to code: its language and first lines. */
+  code?: {
+    language: string;
+    lines: string[];
+  };
+  /** A block link to a diagram or other figure: its kind and title. */
+  figure?: {
+    type: string;
+    title: string;
+  };
+}
+//#endregion
 //#region src/review-api/store.d.ts
+/** What a person's save wrote: the version, and the id each new block got
+ * by its clientKey. */
+interface PersonEditResult {
+  reviewId: string;
+  version: number;
+  ids: Record<string, string>;
+}
+/** One row of a board's history. */
+interface HistoryEntry {
+  version: number;
+  title: string;
+  createdAt: string;
+  /** "you" for a version a person saved from the canvas; absent for one
+   * saved before Whiteboard recorded who wrote it. */
+  author?: "you" | "agent";
+  /** The Ask thread whose edit made this version, if any. */
+  threadId?: string;
+}
 /** Source identity displayed in the review header and Home, alongside immutable pins. */
 interface SnapshotOrigin {
   branch?: string;
@@ -1297,8 +1404,6 @@ interface Snapshot {
   reviewId: string;
   version: number;
   title: string;
-  /** Absent for a review. The scratchpad has no pins, target or lifecycle. */
-  kind?: "scratchpad";
   /** The default pins for references that name none. A document whose
    * references all carry their own pins has neither pins nor target. */
   pins?: Pins;
@@ -1314,7 +1419,28 @@ interface Snapshot {
   /** The edit that produced this version, when one did; absent for a
    * rename, set_target, restore or import, which the canvas does not draw. */
   lastEdit?: EditSummary;
+  /** The Ask thread that caused this version when it made no edit to
+   * name it on: a create, rename, retarget or restore. */
+  threadId?: string;
+  /** A person saved this version from the canvas: the blocks they added,
+   * removed or changed. Absent on every other version. */
+  personEdit?: {
+    changed: string[];
+    ids?: Record<string, string>;
+  };
 }
+/** Who is writing: the rules a write keeps depend on it. */
+type Author =
+/** An agent, through the API; a thread's agent stamps its versions
+ * with the thread. */
+{
+  kind: "agent";
+  threadId?: string;
+} |
+/** A person, from Desktop or the canvas. */
+{
+  kind: "person";
+};
 interface Result {
   /** Create only: false when an existing review for the same PR came back. */
   created?: boolean;
@@ -1338,8 +1464,24 @@ interface Result {
   attention?: true;
   lifecycle?: true;
   deleted?: true;
+  /** After set_parent or set_dependencies: the board's relations. */
+  relations?: BoardRelations;
   warnings?: string[];
 }
+/** A board as its place in a project shows it. */
+interface PlacedBoard {
+  reviewId: string;
+  title: string;
+  target?: ReviewTarget;
+  origin?: SnapshotOrigin;
+}
+/** Where a board sits among its project's boards. Kept outside its versions. */
+interface BoardRelations {
+  parentId: string | null;
+  /** In sibling order. */
+  children: string[];
+  dependsOn: string[];
+}
 /** A PR's current comparison: GitHub's head and diff base, fetched locally. */
 interface ResolvedPullRequest {
   target: ReviewTarget;
@@ -1352,11 +1494,9 @@ interface ResolvedPullRequest {
 interface ReviewProviders {
   headBranch?(pins: Pins, headRef?: string): Promise<string | undefined>;
   projectSource?(snapshot: Snapshot, pins: Pins): Promise<Snapshot>;
-  /** Fetch a PR into a registered checkout: the named one, else the first
-   * preferred one that still matches, else any whose remote is the PR's. */
+  /** Fetch a PR into the registered checkout the caller names. */
   resolvePullRequest?(url: string, repository: {
-    id?: string;
-    preferred?: string;
+    id: string;
   }): Promise<ResolvedPullRequest>;
   /** Undefined when the forge can't be read. */
   pullRequestTitle?(url: string): Promise<string | undefined>;
@@ -1370,6 +1510,8 @@ interface ReviewProviders {
   /** Ids of references whose own pins no longer name a usable checkout. */
   unavailableAnchors?(snapshot: Snapshot): Promise<string[]>;
   validatePins(pins: Pins): Promise<void>;
+  /** The full commit a commit ID or its prefix names, if any. */
+  resolveCommit?(repositoryId: string, commit: string): Promise<string | undefined>;
   /** The files each side's commit changed from one set of pins to another,
    * or undefined when they can't be diffed commit to commit. */
   filesChangedBetween?(from: Pins, to: Pins): Promise<{
@@ -1380,6 +1522,8 @@ interface ReviewProviders {
     peek: boolean;
   }): Promise<void>;
   validateResource(pins: Pins | undefined, block: Block): Promise<void>;
+  /** A PR's base branch, as last read from GitHub; undefined until read. */
+  pullRequestBaseBranch?(url: string): string | undefined;
 }
 /** One instance owned by the desktop server. All writers go through execute().
  * The queue includes async validation; SQLite transactions contain only writes.
@@ -1387,6 +1531,8 @@ interface ReviewProviders {
  */
 declare class ReviewStore {
   private readonly providers;
+  /** How the checkouts group, if `groupCheckoutsAhead` worked it out. */
+  private readonly checkoutOwners?;
   readonly activity: ReviewActivity;
   readonly askHistory: AskHistory;
   private readonly db;
@@ -1416,10 +1562,29 @@ declare class ReviewStore {
   private observedVersions;
   private observedDeletions;
   subscribeCatalog(listener: () => void): () => void;
-  /** For a host whose listing changed without the store: a preference flip. */
-  invalidateCatalog(): void;
   subscribe(listener: (result: Result) => void): () => void;
-  constructor(databasePath: string, providers: ReviewProviders);
+  constructor(databasePath: string, providers: ReviewProviders,
+  /** How the checkouts group, if `groupCheckoutsAhead` worked it out. */
+  checkoutOwners?: ReadonlyMap<string, string> | undefined);
+  /** Saves a version over what it was; the current one re-indexes its
+   * board's links, as every written version does. */
+  private rewriteVersion;
+  /** The project of a registered checkout, made on first use. Checkouts of
+   * one repository (worktrees, or clones of one GitHub repository) share it. */
+  projectOfRepository(repositoryId: string): string;
+  /** For a board with no repository: the project of the board opened last,
+   * else of the first registered checkout, else one with no repository. */
+  private fallbackProject;
+  private firstRepositoryProject;
+  /** A checkout's project, as the catalog lists it; undefined once the
+   * checkout is unregistered. */
+  checkoutProject(repositoryId: string): ReviewApiSummary["project"] | undefined;
+  /** Undefined when the file can't be read. */
+  private fileAtCommit;
+  /** A checkout's name as its project labels it, else its folder. */
+  private repositoryName;
+  /** A board's project. */
+  projectOf(id: string): string;
   private dataVersion;
   private currentVersions;
   private currentDeletions;
@@ -1434,13 +1599,19 @@ declare class ReviewStore {
     fingerprint: string;
     scope: Coverage;
   }[], viewed: boolean): void;
-  private readonly repositoryGroups;
+  private checkoutGroups;
+  /** How the store's checkouts group into projects, kept for the open. */
+  private get checkouts();
   private repositoryGroup;
   registerRepository(root: string): {
     id: string;
     name: string;
   };
-  unregisterRepository(id: string): void;
+  /** Forgets a checkout no board uses, after every write queued before it,
+   * so a board being made with it keeps it. */
+  unregisterRepository(id: string): Promise<void>;
+  /** Checkouts whose remote is cloneUrl, most recently used first. */
+  checkoutsOf(cloneUrl: string): string[];
   /** Registered checkouts, oldest registration first. */
   repositories(): {
     id: string;
@@ -1465,32 +1636,31 @@ declare class ReviewStore {
   resetServerId(): string;
   /** The 404 check alone, without loading a snapshot. */
   assertExists(id: string): void;
+  /** A board that exists and isn't in Trash: the one rule every write
+   * about a board keeps. */
   assertWritable(id: string): void;
+  /** Refuses a board in Trash, which is read-only until it is restored. */
+  assertOutOfTrash(id: string): void;
   private trashTime;
+  /** Removes a board for good, from Delete… or Trash's purge. Links into
+   * it stay, and show it as deleted. */
   private removePermanently;
+  /** Deletes the boards 30 days in Trash, each as Delete… would. */
   private purgeExpired;
   read(id: string, version?: number): Snapshot;
   setDiffStats(pins: Pins, stats: NonNullable<ReviewApiSummary["diffStats"]>): void;
-  /** Reviews of the tutorial earlier versions shipped, for their removal. */
-  legacyTutorialIds(): string[];
+  /** Deletes the tutorial earlier versions shipped. Like any board, each
+   * goes to Trash first, then is deleted from there. */
+  removeLegacyTutorials(): Promise<void>;
   list(): ReviewApiSummary[];
   /** One review's catalog entry, as review_list shows it. */
   summary(id: string): ReviewApiSummary | undefined;
   private summaries;
   /** Local and imported summaries use the same persisted counts. */
   withDiffStats<T extends ReviewApiSummary>(reviews: T[]): T[];
-  /** What the pad holds, for its Home card: blocks, and the diagrams among them. */
-  private scratchpadContents;
-  /** The one scratchpad, made on first use. A host that loses the race to
-   * another on the same home finds it made. */
-  ensureScratchpad(): Promise<void>;
   /** Two saved board/day pairs in the last fourteen days. */
   feedbackEligible(now?: number): boolean;
-  history(id: string): {
-    version: number;
-    title: string;
-    createdAt: string;
-  }[];
+  history(id: string): HistoryEntry[];
   inspect(id: string, targetId?: string, version?: number): Element | {
     id: string | undefined;
     type: "image" | "code" | "markdown" | "divider" | "code_peek" | "sequence" | "step" | "call_stack_diff" | "database_lens" | "trace_quote" | "software_map" | "flow_diagram" | "flow_node" | "flow_edge" | "section" | "callout";
@@ -1500,7 +1670,191 @@ declare class ReviewStore {
   execute(input: unknown, initial?: {
     document: Block[];
     origin: SnapshotOrigin;
-  }): Promise<Result>;
+  }, author?: Author): Promise<Result>;
+  /**
+   * Commits a board's next version: the one place a version is written.
+   * Whoever writes it, it keeps the same rules:
+   *  - an agent may not change a block a person holds;
+   *  - the version names its author: a thread's names the thread, a
+   *    person's is theirs and never inherits a thread;
+   *  - only a change of repository moves a board to another project, and an
+   *    existing board never takes the project of the board opened last;
+   *  - only links the change adds are checked;
+   *  - the version, its link index, the board's project and its relations
+   *    are written together, and only if the board is still at the version
+   *    read and the rules still hold.
+   * Runs inside the write queue.
+   */
+  private commitVersion;
+  /** The project a version puts its board in: a new board's repository's,
+   * or, for a board that has one, its own unless the version moves it to
+   * another registered repository. */
+  private projectFor;
+  private currentVersion;
+  /** Runs one write after every write queued before it. */
+  private enqueue;
+  /** Respells a document's links and resolves its commit links, as every
+   * save does. A changed reference is no longer stale. */
+  private normalizeDocument;
+  /** Checks a candidate version and numbers it. A worktree board's version
+   * may come back with its live source projected. */
+  private prepareVersion;
+  /** Writes a version; call inside commitCommand. */
+  private saveVersion;
+  /** Deletes a board and its history, if it is still at the version read
+   * and passes `guard`: Delete… from Trash, Trash's purge and a discarded
+   * empty board all end here. An agent can't delete a board while a person
+   * holds a block in it. */
+  private deleteBoard;
+  /** Writes what a board is outside its versions: its parent or what it
+   * depends on, Trash or back, or that it was viewed. No version is saved,
+   * but the rules are a version's: a board in Trash takes nothing but a
+   * restore, and an agent can't put a board a person is in to Trash. */
+  private commitBoardFacts;
+  /** Deletes a board the person made and left as it was: with no title
+   * (it reads "Untitled"), no blocks and no child boards. A title typed as
+   * "Untitled" is a title. A board still open on a canvas, or
+   * one an agent is working on, is kept. A closing canvas saves, then lets
+   * go of the board, so the discard waits for that first. */
+  discard(reviewId: string): Promise<{
+    deleted: boolean;
+  }>;
+  /** Each board's canvas leases by client: the board is open there, and
+   * `blockId` is the block the person is in, if any. In memory: a lease
+   * outlives neither its renewals nor the host. */
+  private readonly leases;
+  /** Whether a canvas still holds the board open. */
+  private leased;
+  /** Records the block a person's canvas has focus in (null for none), or
+   * with `open: false` that the canvas closed the board. */
+  focus(reviewId: string, input: unknown): {
+    ok: true;
+  };
+  /** Refuses an agent's change to a board while a person holds any block
+   * in it. */
+  private assertUnheld;
+  /** Refuses an agent's edit to a block a person is editing. */
+  private assertUnleased;
+  /** Saves a person's whole board as their own version, against the version
+   * they started from. Blocks without ids get fresh ones. */
+  personEdit(reviewId: string, input: unknown): Promise<PersonEditResult>;
+  /** Where a board sits: its parent, and the parent's children in order,
+   * each with what its header shows. */
+  place(id: string): {
+    children?: PlacedBoard[] | undefined;
+    siblings: PlacedBoard[];
+    parent?: PlacedBoard | undefined;
+    board: PlacedBoard;
+  };
+  /** The siblings Home and the sidebar list, which a board's place counts
+   * among: all but those in Trash, and the board itself. */
+  private listedSiblings;
+  /** A board's parent, its children in sibling order, and what it depends on. */
+  relations(id: string): BoardRelations;
+  /** Parents, children and dependencies. A board in Trash is out of them
+   * until it is restored, its rows kept; only its own place sees it. */
+  private relationGraph;
+  /** Drops a board's parent, children and dependencies in other projects,
+   * after it moved to `projectId`. Whether it dropped any. */
+  private dropRelationsOutside;
+  private orderChildren;
+  private siblingFacts;
+  /** Commits never change, so a definite answer is kept. */
+  private readonly ancestry;
+  /** When git was last asked, for questions with no answer yet. */
+  private readonly ancestryAsked;
+  /** Whether `ancestor` is an ancestor of `of`, as far as is known. git is
+   * asked in the background, never on the server thread: until it answers,
+   * or when it fails, the answer is no, and a yes re-sorts the catalog. */
+  private isAncestor;
+  private readonly ancestryQueue;
+  private ancestryRunning;
+  private askNextAncestry;
+  private knowAncestry;
+  private catalogChanged;
+  private boardName;
+  /** The other board exists and is in the same project. */
+  private checkRelated;
+  /** One parent, one level: a parent is top-level and a child has no
+   * children. Null makes the board top-level. */
+  private setParent;
+  private setDependencies;
+  /** New links must point at a board and block that exist. Saved links are
+   * not rechecked, since their target may have been deleted. */
+  private checkBoardLinks;
+  private wasDeleted;
+  /** The boards that link to a board or its blocks. */
+  linkingBoards(id: string): string[];
+  /** Rebuilds the board_links rows for one board. */
+  private indexBoardLinks;
+  /** Link previews by board, version and block; a version never changes. */
+  private readonly linkPreviews;
+  private linkPreview;
+  /** What a link's hover card shows of the board or block it links to,
+   * read when the card opens rather than with every link. Only for a link
+   * the version has. */
+  linkPeek(id: string, to: {
+    board: string;
+    block?: string;
+  }, version?: number): BoardLinkPreview;
+  /** "owner / repo" for a board in a GitHub repository, else its folder. */
+  private repositoryLabel;
+  /** A version's outgoing links and the board's current backlinks. Links to a
+   * deleted board or block are marked missing. */
+  links(id: string, version?: number): {
+    outgoing: {
+      title?: string | undefined;
+      deletedAt?: string | undefined;
+      missing: boolean;
+      updatedAt?: string | undefined;
+      pullRequestNumber?: number | undefined;
+      pullRequestUrl?: string | undefined;
+      repository?: string | undefined;
+      icon?: BoardIconKind | undefined;
+      from: BlockRef;
+      to: BoardRef;
+    }[];
+    backlinks: {
+      pullRequestNumber?: number | undefined;
+      pullRequestUrl?: string | undefined;
+      icon?: BoardIconKind | undefined;
+      from: {
+        board: string;
+        block: string;
+      };
+      to: {
+        board: string;
+        block?: undefined;
+      } | {
+        board: string;
+        block: string;
+      };
+      title: string;
+    }[];
+  };
+  /** Boards edited by an Ask thread, most recent first. */
+  boardsChangedBy(threadId: string): {
+    reviewId: string;
+    title: string;
+    icon: BoardIconKind;
+    blockId?: string;
+  }[];
+  /** The boards each thread changed, newest first, for many threads in one
+   * query. */
+  /** A board's title and icon, read without its document. */
+  /** Where a board lives, as Recent names it: its checkout's folder, else
+   * its project's name. */
+  boardPlace(reviewId: string): string;
+  boardFace(reviewId: string): {
+    reviewId: string;
+    title: string;
+    icon: BoardIconKind;
+  };
+  boardsChangedByThreads(threadIds: readonly string[]): Map<string, {
+    reviewId: string;
+    title: string;
+    icon: BoardIconKind;
+  }[]>;
   /** Resolve a target-less PR create before it queues, when it will need it. */
   private startPullRequest;
   private startPullRequestTitle;
@@ -1516,6 +1870,10 @@ declare class ReviewStore {
   /** Viewing a review in Trash does not restore it. */
   trashedIds(): string[];
   has(reviewId: string): boolean;
+  /** Saves each new commit link's commit in full, resolved in the board's
+   * repository; one it does not have rejects the edit, as pins do. A link the
+   * board already had stays as it was saved, even if its commit is gone. */
+  private resolveCommitLinks;
   private validateExternal;
 }
 //#endregion
@@ -1571,6 +1929,8 @@ declare class ReviewWorkspaces {
   remove(reviewId: string): Promise<void>;
   private lease;
   private leasedElsewhere;
+  /** The holder may release its lease after `claim` fails. */
+  private ownedElsewhere;
   /** Takes the review's lease unless another live Desktop holds it. */
   private claim;
   private all;
@@ -1648,8 +2008,11 @@ declare class LocalReviewData {
     filePath?: string;
     rootPath: string;
   }>;
-  /** A document read that needs default pins; 409 when the document has none. */
+  /** A document read that needs default pins: its own, or for a plan its
+   * repository's live checkout with base at head; 409 when it has neither. */
   documentPins(snapshot: Snapshot): Promise<Pins>;
+  /** A checkout's current state, base at head: what a plan reads. */
+  private livePins;
   /** Pins a reference names itself, checked against the registered checkout. */
   anchorSourcePins(anchor: SourcePins): Promise<Pins>;
   /** References whose own repository is unregistered or gone from disk.
@@ -1667,6 +2030,8 @@ declare class LocalReviewData {
     subscribe?: typeof subscribe;
     /** gh, git and GitHub API access for pull request targets. */
     pullRequests?: PullRequestDeps;
+    /** Read PR states from GitHub for the catalog. */
+    pullRequestStates?: boolean;
   });
   structuralChanges({ reviewId, pins, signal, file }: {
     reviewId: string;
@@ -1705,10 +2070,33 @@ declare class LocalReviewData {
   }>;
   /** The fork point from `ref`, by default the repository's default branch. */
   private worktreeBase;
+  /** Each PR's state, by URL, as last read. */
+  private readonly pullRequestStates;
+  private readonly pullRequestStateListeners;
+  private pullRequestStateTimer;
+  private readonly pullRequestStateQueue;
+  private pullRequestStateReads;
+  /** While GitHub rate-limits, no state is read. */
+  private pullRequestStatesPausedUntil;
+  /** Calls back when a PR's state changes. While anyone listens, every PR
+   * still shown is read again once its state is a few minutes old. */
+  subscribePullRequestStates(listener: () => void): () => void;
+  /** A PR's state as last read from GitHub; a read older than a few minutes
+   * queues another in the background. Undefined until the first read lands,
+   * and a failed read keeps the last state. A merged or closed PR is not
+   * read again. */
+  pullRequestState(url: string | undefined, { seen }?: {
+    seen?: boolean;
+  }): PullRequestState | undefined;
+  /** Reads queued PR states a few at a time. */
+  private readPullRequestStates;
+  /** The branch a PR merges into, as last read with its state. */
+  pullRequestBaseBranch(url: string): string | undefined;
+  /** A PR's own branch, as last read with its state. */
+  pullRequestHeadBranch(url: string): string | undefined;
   /** The PR's current comparison, fetched into a registered checkout of its repository. */
   resolvePullRequest(url: string, repository: {
-    id?: string;
-    preferred?: string;
+    id: string;
   }): Promise<ResolvedPullRequest>;
   pullRequestTitle(url: string): Promise<string | undefined>;
   /** A registered checkout with a remote for host/owner/repo, and that remote. */
@@ -1720,6 +2108,22 @@ declare class LocalReviewData {
     base: Set<string>;
     head: Set<string>;
   } | undefined>;
+  /** What a commit is, for a quote read at it: its subject, author and
+   * date, and how far behind the default branch's tip it is when both are
+   * known. */
+  commitInfo(repositoryId: string, commit: string): Promise<{
+    commit: string;
+    subject: string;
+    author: string;
+    authoredAt: string;
+    behind?: {
+      count: number;
+      branch: string;
+    };
+  }>;
+  /** The full commit a commit ID or its prefix names in the repository,
+   * or undefined when it names none. */
+  resolveCommit(repositoryId: string, commit: string): Promise<string | undefined>;
   validatePins(pins: Pins): Promise<void>;
   file(pins: Pins, side: "base" | "head", file: string, allowBinary?: boolean): Promise<{
     file: string;
@@ -1826,11 +2230,16 @@ declare class ShareClient {
 }
 //#endregion
 //#region src/sharing/repository.d.ts
-/** Recipients need complete history; publication only checks that the commits exist. */
-declare function fetchPinnedRepository(root: string, url: string, pins: Pick<Pins, "base" | "head">, publishing?: boolean): Promise<void>;
-declare function verifyShareRepository(root: string, pins: Pins, repository?: {
+/** Recipients need complete history; publication only checks that the commits exist.
+ * `commits` are other commits the board's references read at; a plan has
+ * only those. */
+declare function fetchPinnedRepository(root: string, url: string, pins: Pick<Pins, "base" | "head"> | undefined, publishing?: boolean, commits?: readonly string[]): Promise<void>;
+/** A managed clone of a repository's default branch, for a shared board
+ * with no pins whose repository the receiver has no checkout of. */
+declare function cloneSharedRepository(root: string, url: string): Promise<void>;
+declare function verifyShareRepository(root: string, pins: Pins | undefined, repository?: {
   cloneUrl: string;
-}): Promise<{
+}, commits?: readonly string[]): Promise<{
   cloneUrl: string;
 }>;
 //#endregion
@@ -1910,6 +2319,7 @@ declare function sharedReviewId(origin: string, shareId: string): string;
 declare class SharedReviewStore {
   readonly root: string;
   private readonly fetchRepository;
+  private readonly cloneRepository;
   private readonly loaded;
   private readonly validated;
   private readonly attention;
@@ -1924,7 +2334,7 @@ declare class SharedReviewStore {
   private readonly repositories;
   private readonly jobs;
   private readonly states;
-  constructor(root: string, fetchRepository?: typeof fetchPinnedRepository);
+  constructor(root: string, fetchRepository?: typeof fetchPinnedRepository, cloneRepository?: typeof cloneSharedRepository);
   private purgeExpired;
   connect(store: ReviewStore, data: LocalReviewData): void;
   has(id: string): boolean;
@@ -1936,6 +2346,12 @@ declare class SharedReviewStore {
   repositoryRoot(id: string): string;
   prepare(id: string): Promise<void>;
   private prepareRepository;
+  /** Reads each of a shared board's references at its own commits, in the
+   * checkout of its repository. */
+  private validateReferences;
+  /** Files an unpinned board under a local checkout of its repository,
+   * else a managed clone. */
+  private prepareUnpinned;
   assertReady(id: string): Promise<void>;
   subscribe(listener: () => void): () => void;
   load(): Promise<void>;