@cueloop/daemon 0.1.0-alpha.84 → 0.1.0-alpha.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.84",
+  "version": "0.1.0-alpha.86",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.84",
+    "@cueloop/schema": "0.1.0-alpha.86",
     "@pierre/diffs": "^1.4.1",
     "effect": "^4.0.0-rc.115",
     "smol-toml": "^1.8.0",

package/src/api.ts

@@ -65,7 +65,7 @@ import {
 import { HarnessStateStore } from "./harness-state-store";
 import { DiffWatcher } from "./diff-watcher";
 import { PrReviewPoller } from "./pr-poller";
-import { prDiff } from "./gh";
+import { prSnapshot } from "./gh";
 import { workingTreeDiff, workingChangeList, type WorkingTreeDiff } from "./working-tree";
 import { listProjectFiles, readProjectFile } from "./project-files";
 import { resolveWorkspace } from "./thread-review";
@@ -90,6 +90,7 @@ function annotationDeliveryFingerprint(annotation: Annotation | undefined): stri
     target: annotation.target,
     body: annotation.body,
     author: annotation.author,
+    reviewComment: annotation.reviewComment,
     replyTo: annotation.replyTo,
   });
 }
@@ -158,7 +159,9 @@ export class DaemonCore {
       this.ghosttyThreadSurfaces.delete(threadId);
     }
     this.diffWatcher = new DiffWatcher((repoRoot) => void this.refreshDiffsForRepo(repoRoot));
-    this.prPoller = new PrReviewPoller((sessionId) => void this.sessionRefreshPrDiff(sessionId));
+    this.prPoller = new PrReviewPoller((sessionId, refs) =>
+      this.markPrRefreshAvailable(sessionId, refs),
+    );
     // resume hot-reload for diff sessions that survived a daemon restart
     for (const session of this.store.list()) {
       this.trackLiveDiffSession(session);
@@ -1073,31 +1076,72 @@ export class DaemonCore {
 
     if (!session || session.status !== "pending" || session.artifact.type !== "diff")
       return { changed: false };
-    const pr = session.artifact.meta.pr;
+    const pr = session.artifact.meta.prUrl ?? session.artifact.meta.pr;
 
     if (pr === undefined) return { changed: false };
     const generation = (this.diffRefreshGenerations.get(id) ?? 0) + 1;
 
     this.diffRefreshGenerations.set(id, generation);
-    const patch = await prDiff(pr);
+    const snapshot = await prSnapshot(pr);
 
     // gh failed (offline, unauthenticated): keep the diff we have, try again next poll
-    if (patch === null) return { changed: false };
+    if (snapshot === null) return { changed: false };
     // the pull yields the event loop: discard a stale capture or a closed session
     if (this.diffRefreshGenerations.get(id) !== generation) return { changed: false };
     const current = this.store.get(id);
 
     if (!current || current.status !== "pending" || current.artifact.type !== "diff")
       return { changed: false };
-    if (patch === current.artifact.content) return { changed: false };
-    current.artifact = { ...current.artifact, content: patch };
+    const contentChanged = snapshot.patch !== current.artifact.content;
+
+    if (
+      !contentChanged &&
+      snapshot.baseSha === current.artifact.meta.prBaseSha &&
+      snapshot.headSha === current.artifact.meta.prHeadSha &&
+      current.artifact.meta.prRefreshBaseSha === undefined &&
+      current.artifact.meta.prRefreshHeadSha === undefined
+    )
+      return { changed: false };
+    current.artifact = {
+      ...current.artifact,
+      content: snapshot.patch,
+      meta: {
+        ...current.artifact.meta,
+        prBaseSha: snapshot.baseSha,
+        prHeadSha: snapshot.headSha,
+        prRefreshBaseSha: undefined,
+        prRefreshHeadSha: undefined,
+      },
+    };
     const history = withHistory(current).history;
 
-    if (history) current.history = recaptureMainHead(history, patch);
+    if (history && contentChanged) current.history = recaptureMainHead(history, snapshot.patch);
     this.store.upsert(current);
     this.emit("session.updated", id);
 
-    return { changed: true };
+    return { changed: contentChanged };
+  }
+
+  /** Record moved PR refs without replacing the review until the reviewer refreshes it. */
+  private markPrRefreshAvailable(id: string, refs: { baseSha: string; headSha: string }): void {
+    const session = this.store.get(id);
+
+    if (!session || session.status !== "pending" || session.artifact.meta.pr === undefined) return;
+    if (
+      session.artifact.meta.prBaseSha === refs.baseSha &&
+      session.artifact.meta.prHeadSha === refs.headSha
+    )
+      return;
+    session.artifact = {
+      ...session.artifact,
+      meta: {
+        ...session.artifact.meta,
+        prRefreshBaseSha: refs.baseSha,
+        prRefreshHeadSha: refs.headSha,
+      },
+    };
+    this.store.upsert(session);
+    this.emit("session.updated", id);
   }
 
   /** Re-capture every working-tree diff session sharing a repo root (one debounced fs change). */
@@ -1122,7 +1166,16 @@ export class DaemonCore {
     if (isWorkingTreeDiffSession(session))
       this.diffWatcher.trackDiffRepo(session.workspace.repoRoot, session.id);
     else if (isPrReviewSession(session))
-      this.prPoller.trackPr(session.id, session.artifact.meta.pr!);
+      this.prPoller.trackPr(
+        session.id,
+        session.artifact.meta.prUrl ?? session.artifact.meta.pr!,
+        session.artifact.meta.prBaseSha && session.artifact.meta.prHeadSha
+          ? {
+              baseSha: session.artifact.meta.prBaseSha,
+              headSha: session.artifact.meta.prHeadSha,
+            }
+          : null,
+      );
   }
 
   private untrackLiveDiffSession(session: Thread): void {

package/src/client.ts

@@ -142,6 +142,8 @@ export interface ThreadClient {
   repoChanges?(cwd: string): Promise<{ path: string; status: DiffFileStatus }[]>;
   /** The live working-tree diff (patch plus per-file contents) at `cwd`. */
   repoDiff?(cwd: string): Promise<WorkingTreeDiff>;
+  /** Refresh a local diff or explicitly pull a moved PR head. */
+  sessionRefreshDiff?(id: string): Promise<{ changed: boolean }>;
   /** Find-or-create the per-repo workbench thread for `cwd`, so a bare launch's first comment persists. */
   sessionWorkbench?(cwd: string): Promise<Thread>;
   /** Move a branch's tip (the current one, or `branch` after switching to it) back to an entry on its path; a summary records the abandoned segment. */

package/src/diff-hot-reload.test.ts

@@ -5,7 +5,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { DaemonCore } from "./api";
@@ -168,10 +168,17 @@ describe("PR review sessions", () => {
   test("refresh re-pulls the PR diff via gh and never clobbers it with the working tree", async () => {
     // Given a stub gh that reports a PR diff distinct from the local working tree
     const ghStub = join(repo, "gh-stub.sh");
+    const ghLog = join(repo, "gh-stub.log");
 
     writeFileSync(
       ghStub,
-      '#!/bin/sh\ncase "$2" in\n  diff) printf "STUB PR DIFF\\n" ;;\n  view) printf "sha-2\\n" ;;\nesac\n',
+      `#!/bin/sh
+printf '%s\n' "$*" >> '${ghLog}'
+case "$2" in
+  diff) printf "STUB PR DIFF\\n" ;;
+  view) printf '{"baseRefOid":"base-2","headRefOid":"sha-2"}\\n' ;;
+esac
+`,
     );
     chmodSync(ghStub, 0o755);
     const previousGh = process.env.CUELOOP_GH;
@@ -185,7 +192,14 @@ describe("PR review sessions", () => {
         type: "diff",
         content: "OLD PR DIFF\n",
         files: [],
-        meta: { pr: "org/repo#1" },
+        meta: {
+          pr: "1",
+          prUrl: "https://github.com/org/repo/pull/1",
+          prBaseSha: "base-1",
+          prHeadSha: "sha-1",
+          prRefreshBaseSha: "base-2",
+          prRefreshHeadSha: "sha-2",
+        },
       };
       const session = core.sessionCreate({ workspace, artifact });
 
@@ -200,6 +214,11 @@ describe("PR review sessions", () => {
 
       expect(refreshed.artifact.content).toContain("STUB PR DIFF");
       expect(refreshed.artifact.content).not.toContain("export const a = 123;");
+      expect(refreshed.artifact.meta.prBaseSha).toBe("base-2");
+      expect(refreshed.artifact.meta.prHeadSha).toBe("sha-2");
+      expect(refreshed.artifact.meta.prRefreshBaseSha).toBeUndefined();
+      expect(refreshed.artifact.meta.prRefreshHeadSha).toBeUndefined();
+      expect(readFileSync(ghLog, "utf8")).toContain("https://github.com/org/repo/pull/1");
     } finally {
       if (previousGh === undefined) delete process.env.CUELOOP_GH;
       else process.env.CUELOOP_GH = previousGh;

package/src/gh.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { prSnapshot } from "./gh";
+
+describe("prSnapshot", () => {
+  test("retries until the diff and head are one stable snapshot", async () => {
+    const refs = [
+      { baseSha: "base-1", headSha: "head-1" },
+      { baseSha: "base-1", headSha: "head-2" },
+      { baseSha: "base-1", headSha: "head-2" },
+      { baseSha: "base-1", headSha: "head-2" },
+    ];
+    const patches = ["patch-1", "patch-2"];
+
+    const snapshot = await prSnapshot(
+      "https://github.com/org/repo/pull/1",
+      3,
+      async () => refs.shift() ?? null,
+      async () => patches.shift() ?? null,
+    );
+
+    expect(snapshot).toEqual({ patch: "patch-2", baseSha: "base-1", headSha: "head-2" });
+  });
+
+  test("returns no snapshot when the head keeps moving", async () => {
+    let head = 0;
+
+    const snapshot = await prSnapshot(
+      "https://github.com/org/repo/pull/1",
+      2,
+      async () => ({ baseSha: "base", headSha: `head-${head++}` }),
+      async () => "patch",
+    );
+
+    expect(snapshot).toBeNull();
+  });
+
+  test("retries when only the base moves", async () => {
+    const refs = [
+      { baseSha: "base-1", headSha: "head" },
+      { baseSha: "base-2", headSha: "head" },
+      { baseSha: "base-2", headSha: "head" },
+      { baseSha: "base-2", headSha: "head" },
+    ];
+    const patches = ["old-base-patch", "new-base-patch"];
+
+    const snapshot = await prSnapshot(
+      "https://github.com/org/repo/pull/1",
+      3,
+      async () => refs.shift() ?? null,
+      async () => patches.shift() ?? null,
+    );
+
+    expect(snapshot).toEqual({
+      patch: "new-base-patch",
+      baseSha: "base-2",
+      headSha: "head",
+    });
+  });
+});

package/src/gh.ts

@@ -1,5 +1,17 @@
 // gh CLI reads for PR reviews; auth is delegated to the user's gh. Reads only.
 
+import * as v from "valibot";
+
+export interface PullRequestRefs {
+  baseSha: string;
+  headSha: string;
+}
+
+const PullRequestRefsSchema = v.object({
+  baseRefOid: v.pipe(v.string(), v.nonEmpty()),
+  headRefOid: v.pipe(v.string(), v.nonEmpty()),
+});
+
 const ghBinary = (): string => process.env.CUELOOP_GH || "gh";
 
 async function gh(args: string[]): Promise<{ code: number; stdout: string }> {
@@ -9,22 +21,23 @@ async function gh(args: string[]): Promise<{ code: number; stdout: string }> {
   return { code: await process.exited, stdout };
 }
 
-/** The PR head commit sha, or null when gh is absent, unauthenticated, or the call fails. */
-export async function prHeadSha(pr: string): Promise<string | null> {
-  const { code, stdout } = await gh([
-    "pr",
-    "view",
-    pr,
-    "--json",
-    "headRefOid",
-    "-q",
-    ".headRefOid",
-  ]);
+/** The PR base and head commits, or null when gh is absent, unauthenticated, or the call fails. */
+export async function prRefs(pr: string): Promise<PullRequestRefs | null> {
+  const { code, stdout } = await gh(["pr", "view", pr, "--json", "baseRefOid,headRefOid"]);
 
   if (code !== 0) return null;
-  const sha = stdout.trim();
+  let input: unknown;
+
+  try {
+    input = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  const parsed = v.safeParse(PullRequestRefsSchema, input);
+
+  if (!parsed.success) return null;
 
-  return sha.length > 0 ? sha : null;
+  return { baseSha: parsed.output.baseRefOid, headSha: parsed.output.headRefOid };
 }
 
 /** The PR unified diff as gh prints it, or null when the call fails. */
@@ -35,3 +48,27 @@ export async function prDiff(pr: string): Promise<string | null> {
 
   return stdout;
 }
+
+/** A stable PR diff and the exact base/head pair it represents. */
+export async function prSnapshot(
+  pr: string,
+  attempts = 3,
+  readRefs: (reference: string) => Promise<PullRequestRefs | null> = prRefs,
+  readDiff: (reference: string) => Promise<string | null> = prDiff,
+): Promise<{ patch: string; baseSha: string; headSha: string } | null> {
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const before = await readRefs(pr);
+
+    if (before === null) return null;
+    const patch = await readDiff(pr);
+
+    if (patch === null) return null;
+    const after = await readRefs(pr);
+
+    if (after === null) return null;
+    if (before.baseSha === after.baseSha && before.headSha === after.headSha)
+      return { patch, ...after };
+  }
+
+  return null;
+}

package/src/pr-poller.test.ts

@@ -2,27 +2,31 @@ import { describe, expect, test } from "bun:test";
 import { PrReviewPoller } from "./pr-poller";
 
 /** Build a poller whose head sha is controllable, with the timer effectively disabled. */
-function makePoller(initialSha: string | null) {
-  let sha = initialSha;
-  const advanced: string[] = [];
+function refs(baseSha: string, headSha: string) {
+  return { baseSha, headSha };
+}
+
+function makePoller(initialRefs: ReturnType<typeof refs> | null) {
+  let currentRefs = initialRefs;
+  const advanced: Array<{ sessionId: string; refs: ReturnType<typeof refs> }> = [];
   const poller = new PrReviewPoller(
-    (sessionId) => advanced.push(sessionId),
-    async () => sha,
+    (sessionId, nextRefs) => advanced.push({ sessionId, refs: nextRefs }),
+    async () => currentRefs,
     1_000_000,
   );
 
   return {
     poller,
     advanced,
-    setSha: (next: string | null) => {
-      sha = next;
+    setRefs: (next: ReturnType<typeof refs> | null) => {
+      currentRefs = next;
     },
   };
 }
 
 describe("PrReviewPoller", () => {
   test("the first observation is a silent baseline", async () => {
-    const { poller, advanced } = makePoller("sha1");
+    const { poller, advanced } = makePoller(refs("base1", "sha1"));
 
     poller.trackPr("s1", "org/repo#1");
     await poller.refreshHead("s1");
@@ -32,45 +36,67 @@ describe("PrReviewPoller", () => {
   });
 
   test("a moved head fires once; an unchanged head stays quiet", async () => {
-    const { poller, advanced, setSha } = makePoller("sha1");
+    const { poller, advanced, setRefs } = makePoller(refs("base1", "sha1"));
 
     poller.trackPr("s1", "org/repo#1");
     await poller.refreshHead("s1");
 
-    setSha("sha2");
+    setRefs(refs("base1", "sha2"));
     await poller.refreshHead("s1");
     await poller.refreshHead("s1");
 
-    expect(advanced).toEqual(["s1"]);
+    expect(advanced).toEqual([{ sessionId: "s1", refs: refs("base1", "sha2") }]);
+    poller.close();
+  });
+
+  test("a persisted reviewed head exposes a move on the first check after restart", async () => {
+    const { poller, advanced } = makePoller(refs("base1", "sha2"));
+
+    poller.trackPr("s1", "https://github.com/org/repo/pull/1", refs("base1", "sha1"));
+    await poller.refreshHead("s1");
+
+    expect(advanced).toEqual([{ sessionId: "s1", refs: refs("base1", "sha2") }]);
     poller.close();
   });
 
   test("a failed head read never fires and keeps the last baseline", async () => {
-    const { poller, advanced, setSha } = makePoller("sha1");
+    const { poller, advanced, setRefs } = makePoller(refs("base1", "sha1"));
 
     poller.trackPr("s1", "org/repo#1");
     await poller.refreshHead("s1");
 
-    setSha(null);
+    setRefs(null);
     await poller.refreshHead("s1");
-    setSha("sha2");
+    setRefs(refs("base1", "sha2"));
     await poller.refreshHead("s1");
 
-    expect(advanced).toEqual(["s1"]);
+    expect(advanced).toEqual([{ sessionId: "s1", refs: refs("base1", "sha2") }]);
     poller.close();
   });
 
   test("untrack stops further checks", async () => {
-    const { poller, advanced, setSha } = makePoller("sha1");
+    const { poller, advanced, setRefs } = makePoller(refs("base1", "sha1"));
 
     poller.trackPr("s1", "org/repo#1");
     await poller.refreshHead("s1");
     poller.untrackPr("s1");
 
-    setSha("sha2");
+    setRefs(refs("base1", "sha2"));
     await poller.refreshHead("s1");
 
     expect(advanced).toEqual([]);
     poller.close();
   });
+
+  test("a moved base fires while the head stays unchanged", async () => {
+    const { poller, advanced, setRefs } = makePoller(refs("base1", "sha1"));
+
+    poller.trackPr("s1", "org/repo#1");
+    await poller.refreshHead("s1");
+    setRefs(refs("base2", "sha1"));
+    await poller.refreshHead("s1");
+
+    expect(advanced).toEqual([{ sessionId: "s1", refs: refs("base2", "sha1") }]);
+    poller.close();
+  });
 });

package/src/pr-poller.ts

@@ -1,20 +1,18 @@
 /**
- * Polls each open PR review for new commits so the review hot-reloads when the
- * PR head advances. A remote PR has no push signal, so this checks the head sha
- * on an interval - one cheap gh call - and only asks the caller to re-pull the
- * full diff when the head actually moved. Best-effort: a missing or failing gh
- * leaves the last known head in place and never throws.
+ * Polls each open PR review for new commits. A remote PR has no push signal, so
+ * this checks its base/head pair on an interval and only exposes refresh when
+ * either side moved. Best-effort: a missing or failing gh keeps the last refs.
  */
 
-import { prHeadSha } from "./gh";
+import { prRefs, type PullRequestRefs } from "./gh";
 
-/** One cheap head-sha check per interval; the expensive full-diff pull happens only on a move. */
+/** One cheap refs check per interval; the expensive full-diff pull happens only on a move. */
 const PR_POLL_INTERVAL_MS = 30_000;
 
 interface PrPoll {
   pr: string;
-  /** Last head sha seen; null until the baseline check lands, so the first observation never fires. */
-  lastSha: string | null;
+  /** Last refs seen; null until the baseline check lands, so the first observation never fires. */
+  lastRefs: PullRequestRefs | null;
   timer: ReturnType<typeof setInterval>;
 }
 
@@ -22,41 +20,42 @@ export class PrReviewPoller {
   private readonly polls = new Map<string, PrPoll>();
 
   constructor(
-    private readonly onPrAdvance: (sessionId: string) => void,
-    private readonly headSha: (pr: string) => Promise<string | null> = prHeadSha,
+    private readonly onPrAdvance: (sessionId: string, refs: PullRequestRefs) => void,
+    private readonly refs: (pr: string) => Promise<PullRequestRefs | null> = prRefs,
     private readonly intervalMs: number = PR_POLL_INTERVAL_MS,
   ) {}
 
-  /** Start polling a PR review. Idempotent per session; the baseline check runs at once. */
-  trackPr(sessionId: string, pr: string): void {
+  /** Start polling a PR review. Idempotent per session; the persisted reviewed head is the baseline. */
+  trackPr(sessionId: string, pr: string, reviewedRefs: PullRequestRefs | null = null): void {
     if (this.polls.has(sessionId)) return;
     const timer = setInterval(() => void this.refreshHead(sessionId), this.intervalMs);
     // the poll timer must not by itself keep the daemon alive against idle-exit
     timer.unref?.();
-    this.polls.set(sessionId, { pr, lastSha: null, timer });
+    this.polls.set(sessionId, { pr, lastRefs: reviewedRefs, timer });
     void this.refreshHead(sessionId);
   }
 
-  /** Check the PR head once; fire onPrAdvance only when it moved off a known baseline. */
+  /** Check the PR refs once; fire onPrAdvance only when they moved off a known baseline. */
   async refreshHead(sessionId: string): Promise<void> {
     const poll = this.polls.get(sessionId);
 
     if (!poll) return;
-    const sha = await this.headSha(poll.pr).catch(() => null);
+    const refs = await this.refs(poll.pr).catch(() => null);
 
-    if (sha === null) return;
+    if (refs === null) return;
     // the await yields; re-read so an untrack during the call is honoured
     const current = this.polls.get(sessionId);
 
     if (!current) return;
-    if (current.lastSha === null) {
-      current.lastSha = sha;
+    if (current.lastRefs === null) {
+      current.lastRefs = refs;
 
       return;
     }
-    if (sha === current.lastSha) return;
-    current.lastSha = sha;
-    this.onPrAdvance(sessionId);
+    if (refs.baseSha === current.lastRefs.baseSha && refs.headSha === current.lastRefs.headSha)
+      return;
+    current.lastRefs = refs;
+    this.onPrAdvance(sessionId, refs);
   }
 
   untrackPr(sessionId: string): void {

package/src/thread-review.ts

@@ -78,6 +78,10 @@ export interface OpenReviewOptions {
   planPath?: string;
   prototypePath?: string;
   pr?: string;
+  prBrief?: string;
+  prBaseSha?: string;
+  prHeadSha?: string;
+  prUrl?: string;
   herdrPane?: string;
   /**
    * Full file contents per changed file for a working-tree diff, carried onto
@@ -297,6 +301,10 @@ export async function openReview(
       planPath: options.planPath,
       prototypePath: options.prototypePath,
       pr: options.pr,
+      prBrief: options.prBrief,
+      prBaseSha: options.prBaseSha,
+      prHeadSha: options.prHeadSha,
+      prUrl: options.prUrl,
       herdrPane: options.herdrPane,
       title:
         options.title ??

package/src/validate.test.ts

@@ -210,6 +210,12 @@ describe("wire pins", () => {
     planPath: "/repo/plan.md",
     prototypePath: "/repo/proto.html",
     pr: "org/repo#1",
+    prBrief: "# PR",
+    prBaseSha: "base",
+    prHeadSha: "head",
+    prRefreshBaseSha: "next-base",
+    prRefreshHeadSha: "next",
+    prUrl: "https://github.com/org/repo/pull/1",
     herdrPane: "%7",
     title: "Plan",
     workbench: false,
@@ -233,6 +239,17 @@ describe("wire pins", () => {
     body: "b",
     orphan: false,
     author: "SHA256:abc",
+    reviewComment: {
+      severity: "p1",
+      title: "Finding",
+      path: "src/x.ts",
+      line: 1,
+      startLine: 1,
+      startAnchor: fullAnchor,
+      side: "RIGHT",
+      suggestion: "replacement",
+      prompt: "fix it",
+    },
     replyTo: "a0",
     resolution: { revision: 2, source: "agent" },
     createdAt: "now",

package/src/validate.ts

@@ -29,6 +29,8 @@ import {
   type Delivery,
   type PendingDelivery,
   type Revision,
+  REVIEW_SEVERITIES,
+  type ReviewComment,
   type SessionHistory,
   type ShareAccess,
   type ShareLink,
@@ -85,6 +87,12 @@ export const ArtifactMetaSchema = v.object({
   planPath: v.optional(v.string()),
   prototypePath: v.optional(v.string()),
   pr: v.optional(v.string()),
+  prBrief: v.optional(v.string()),
+  prBaseSha: v.optional(NonEmpty),
+  prHeadSha: v.optional(NonEmpty),
+  prRefreshBaseSha: v.optional(NonEmpty),
+  prRefreshHeadSha: v.optional(NonEmpty),
+  prUrl: v.optional(NonEmpty),
   herdrPane: v.optional(v.string()),
   title: v.optional(v.string()),
   workbench: v.optional(v.boolean()),
@@ -135,6 +143,19 @@ export const AnnotationSchema = v.object({
   body: v.string(),
   orphan: v.optional(v.boolean()),
   author: v.optional(v.string()),
+  reviewComment: v.optional(
+    v.object({
+      severity: v.picklist(REVIEW_SEVERITIES),
+      title: NonEmpty,
+      path: NonEmpty,
+      line: v.pipe(v.number(), v.integer(), v.minValue(1)),
+      startLine: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+      startAnchor: v.optional(AnchorSchema),
+      side: v.picklist(["LEFT", "RIGHT"]),
+      suggestion: v.optional(v.string()),
+      prompt: v.optional(v.string()),
+    } satisfies EntriesOf<ReviewComment>),
+  ),
   replyTo: v.optional(NonEmpty),
   resolution: v.optional(
     v.object({