@cueloop/daemon 0.1.0-alpha.78 → 0.1.0-alpha.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.78",
+  "version": "0.1.0-alpha.79",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -35,8 +35,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.78",
-    "@pierre/diffs": "^1.3.6",
+    "@cueloop/schema": "0.1.0-alpha.79",
+    "@pierre/diffs": "^1.4.1",
     "effect": "^4.0.0-rc.115",
     "valibot": "^1.4.2"
   },

package/src/api.ts

@@ -36,6 +36,7 @@ import {
   type HunkRejection,
   type NewEntry,
   type Artifact,
+  type ShareLink,
   type Identity,
   type Thread,
   type SessionHistory,
@@ -48,6 +49,8 @@ import { ThreadStore, withHistory } from "./store";
 import { pruneExpiredSessions, resolveCleanupPeriodDays } from "./retention";
 import { HerdrTabStore, type HerdrTabHandle } from "./herdr-tab-store";
 import { DiffWatcher } from "./diff-watcher";
+import { PrReviewPoller } from "./pr-poller";
+import { prDiff } from "./gh";
 import { workingTreeDiff, workingChangeList, type WorkingTreeDiff } from "./working-tree";
 import { listProjectFiles, readProjectFile } from "./project-files";
 import { resolveWorkspace } from "./review";
@@ -85,6 +88,8 @@ export class DaemonCore {
   private seq = 0;
   /** Drives diff hot-reload: watches each live diff session's repo for working-tree changes. */
   private readonly diffWatcher: DiffWatcher;
+  /** Drives PR-review hot-reload: polls each open PR review for a moved head. */
+  private readonly prPoller: PrReviewPoller;
   /**
    * Per-diff-session capture generation. Bumped when a refresh begins; a
    * capture whose generation is stale by the time it finishes discards its
@@ -100,13 +105,15 @@ export class DaemonCore {
     pruneExpiredSessions(this.store, resolveCleanupPeriodDays(), Date.now());
     this.herdrTabs = new HerdrTabStore(home);
     this.diffWatcher = new DiffWatcher((repoRoot) => void this.refreshDiffsForRepo(repoRoot));
+    this.prPoller = new PrReviewPoller((sessionId) => void this.sessionRefreshPrDiff(sessionId));
     // resume hot-reload for diff sessions that survived a daemon restart
-    for (const session of this.store.list()) this.watchIfDiffSession(session);
+    for (const session of this.store.list()) this.trackLiveDiffSession(session);
   }
 
-  /** Release the fs watchers behind diff hot-reload; call on daemon shutdown. */
+  /** Release the watchers and pollers behind diff hot-reload; call on daemon shutdown. */
   dispose(): void {
     this.diffWatcher.close();
+    this.prPoller.close();
   }
 
   /** The herdr tab opened for a review, if any (adapter scratch, not on the session). */
@@ -152,7 +159,7 @@ export class DaemonCore {
 
     session.history = historyFromLinear(session);
     this.store.upsert(session);
-    this.watchIfDiffSession(session);
+    this.trackLiveDiffSession(session);
     this.emit("session.created", session.id);
     this.emit("inbox.changed", session.id);
 
@@ -432,6 +439,21 @@ export class DaemonCore {
     return session;
   }
 
+  /** Replace the thread's share links; the legacy single-share fields are dropped once shares[] is authoritative. */
+  sessionSetShares(id: string, shares: ShareLink[]): Thread {
+    const session = this.mutable(id);
+
+    session.shares = shares;
+    delete session.shareId;
+    delete session.access;
+    delete session.owner;
+    delete session.shareBranch;
+    this.store.upsert(session);
+    this.emit("session.updated", id);
+
+    return session;
+  }
+
   /** Set the private-share allowlist of GitHub logins; presence marks the share private. */
   sessionSetAccess(id: string, githubLogins: string[]): Thread {
     const session = this.mutable(id);
@@ -448,7 +470,7 @@ export class DaemonCore {
     const session = this.store.get(id);
 
     if (!this.store.delete(id)) throw new DaemonError("not_found", `no session ${id}`);
-    if (session) this.unwatchIfDiffSession(session);
+    if (session) this.untrackLiveDiffSession(session);
     this.diffRefreshGenerations.delete(id);
     this.herdrTabs.delete(id);
     this.emit("inbox.changed", id);
@@ -612,7 +634,7 @@ export class DaemonCore {
     });
     this.store.upsert(session);
     // a resolved diff review is frozen; stop hot-reloading its working tree
-    this.unwatchIfDiffSession(session);
+    this.untrackLiveDiffSession(session);
     const parked = this.waiters.get(id) ?? [];
 
     this.waiters.delete(id);
@@ -789,7 +811,7 @@ export class DaemonCore {
     if (source.participants)
       fork.participants = source.participants.map((identity) => ({ ...identity }));
     this.store.upsert(fork);
-    this.watchIfDiffSession(fork);
+    this.trackLiveDiffSession(fork);
     this.emit("session.created", fork.id);
     this.emit("inbox.changed", fork.id);
 
@@ -801,6 +823,8 @@ export class DaemonCore {
     const session = this.mutable(id);
 
     if (session.artifact.type !== "diff") return { changed: false };
+    // a PR review has no local working tree; re-pull it from the PR instead of clobbering it
+    if (session.artifact.meta.pr !== undefined) return this.sessionRefreshPrDiff(id);
     const generation = (this.diffRefreshGenerations.get(id) ?? 0) + 1;
 
     this.diffRefreshGenerations.set(id, generation);
@@ -827,11 +851,50 @@ export class DaemonCore {
     return { changed: true };
   }
 
-  /** Re-capture every live diff session sharing a repo root (one debounced fs change). */
+  /**
+   * Re-pull a PR review's diff when its head moved; broadcasts session.updated
+   * only when the patch text changed. A PR review has no local working tree, so
+   * it never runs workingTreeDiff - the diff comes from gh.
+   */
+  async sessionRefreshPrDiff(id: string): Promise<{ changed: boolean }> {
+    const session = this.store.get(id);
+
+    if (!session || session.status !== "pending" || session.artifact.type !== "diff")
+      return { changed: false };
+    const pr = 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);
+
+    // gh failed (offline, unauthenticated): keep the diff we have, try again next poll
+    if (patch === 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 history = withHistory(current).history;
+
+    if (history) current.history = recaptureMainHead(history, patch);
+    this.store.upsert(current);
+    this.emit("session.updated", id);
+
+    return { changed: true };
+  }
+
+  /** Re-capture every working-tree diff session sharing a repo root (one debounced fs change). */
   private async refreshDiffsForRepo(repoRoot: string): Promise<void> {
     const live = this.store
       .list()
-      .filter((session) => isLiveDiffSession(session) && session.workspace.repoRoot === repoRoot);
+      .filter(
+        (session) => isWorkingTreeDiffSession(session) && session.workspace.repoRoot === repoRoot,
+      );
 
     for (const session of live) {
       // a session resolved or deleted between the change and this tick just skips
@@ -843,14 +906,17 @@ export class DaemonCore {
     }
   }
 
-  private watchIfDiffSession(session: Thread): void {
-    if (isLiveDiffSession(session))
+  private trackLiveDiffSession(session: Thread): void {
+    if (isWorkingTreeDiffSession(session))
       this.diffWatcher.trackDiffRepo(session.workspace.repoRoot, session.id);
+    else if (isPrReviewSession(session))
+      this.prPoller.trackPr(session.id, session.artifact.meta.pr!);
   }
 
-  private unwatchIfDiffSession(session: Thread): void {
-    if (session.artifact.type === "diff")
-      this.diffWatcher.untrackDiffRepo(session.workspace.repoRoot, session.id);
+  private untrackLiveDiffSession(session: Thread): void {
+    if (session.artifact.type !== "diff") return;
+    this.diffWatcher.untrackDiffRepo(session.workspace.repoRoot, session.id);
+    this.prPoller.untrackPr(session.id);
   }
 
   /**
@@ -975,9 +1041,22 @@ function forkedAnnotation(annotation: Annotation, source: Thread, fork: Thread):
     : { ...annotation, resolution: { ...resolution, revision: inFork.revision } };
 }
 
-/** A pending diff session: the state that warrants hot-reload watching of its working tree. */
-function isLiveDiffSession(session: Thread): boolean {
-  return session.status === "pending" && session.artifact.type === "diff";
+/** A pending diff of the local working tree: hot-reloads by watching its repo. A PR review is excluded. */
+function isWorkingTreeDiffSession(session: Thread): boolean {
+  return (
+    session.status === "pending" &&
+    session.artifact.type === "diff" &&
+    session.artifact.meta.pr === undefined
+  );
+}
+
+/** A pending review of a remote PR: hot-reloads by polling the PR head, never by watching a working tree. */
+function isPrReviewSession(session: Thread): boolean {
+  return (
+    session.status === "pending" &&
+    session.artifact.type === "diff" &&
+    session.artifact.meta.pr !== undefined
+  );
 }
 
 /** Convenience for adapters: map a resolved session to the agent contract. */

package/src/capabilities.ts

@@ -55,6 +55,7 @@ const PRIMITIVE_ROLES = {
   "session.fork": "owner",
   "session.refreshDiff": "owner",
   "session.setShareId": "owner",
+  "session.setShares": "owner",
   "session.delete": "owner",
   "session.mergeShared": "owner",
   "session.resolve": "owner",

package/src/client.ts

@@ -11,6 +11,7 @@ import type {
   Artifact,
   DiffFileStatus,
   HunkRejection,
+  ShareLink,
   Thread,
   VerdictKind,
   WorkspaceKey,
@@ -117,6 +118,7 @@ export interface SessionClient {
   /** Copy the current path into a new session; returns the fork. */
   sessionFork(id: string): Promise<Thread>;
   sessionSetShareId(id: string, shareId: string): Promise<Thread>;
+  sessionSetShares(id: string, shares: ShareLink[]): Promise<Thread>;
   sessionMergeShared(id: string, incoming: SharedMerge): Promise<Thread>;
   sessionDelete(id: string): Promise<void>;
   /** Record the caller's own identity name (collaborator self-naming on a share). */
@@ -497,6 +499,10 @@ export class DaemonClient implements SessionClient {
   sessionSetShareId(id: string, shareId: string): Promise<Thread> {
     return this.request("session.setShareId", { id, shareId }, ThreadRecordSchema);
   }
+
+  sessionSetShares(id: string, shares: ShareLink[]): Promise<Thread> {
+    return this.request("session.setShares", { id, shares }, ThreadRecordSchema);
+  }
   sessionMergeShared(id: string, incoming: SharedMerge): Promise<Thread> {
     return this.request("session.mergeShared", { id, ...incoming }, ThreadRecordSchema);
   }

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

@@ -5,7 +5,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { DaemonCore } from "./api";
@@ -164,6 +164,49 @@ describe("session.refreshDiff", () => {
   });
 });
 
+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");
+
+    writeFileSync(
+      ghStub,
+      '#!/bin/sh\ncase "$2" in\n  diff) printf "STUB PR DIFF\\n" ;;\n  view) printf "sha-2\\n" ;;\nesac\n',
+    );
+    chmodSync(ghStub, 0o755);
+    const previousGh = process.env.CUELOOP_GH;
+
+    process.env.CUELOOP_GH = ghStub;
+
+    try {
+      // Given a PR review over the same repo root, and a local working-tree change present
+      const workspace = await resolveWorkspace(repo);
+      const artifact: Artifact = {
+        type: "diff",
+        content: "OLD PR DIFF\n",
+        files: [],
+        meta: { pr: "org/repo#1" },
+      };
+      const session = core.sessionCreate({ workspace, artifact });
+
+      writeFileSync(join(repo, "a.ts"), "export const a = 123;\n");
+
+      // When the diff is refreshed
+      const result = await core.sessionRefreshDiff(session.id);
+
+      // Then it carries the PR diff from gh, not the local working-tree change
+      expect(result.changed).toBe(true);
+      const refreshed = core.sessionGet(session.id);
+
+      expect(refreshed.artifact.content).toContain("STUB PR DIFF");
+      expect(refreshed.artifact.content).not.toContain("export const a = 123;");
+    } finally {
+      if (previousGh === undefined) delete process.env.CUELOOP_GH;
+      else process.env.CUELOOP_GH = previousGh;
+    }
+  });
+});
+
 describe("the fs watcher drives hot-reload", () => {
   test("a working-tree change under a live diff session refreshes it in place", async () => {
     // Given a live diff session whose repo the daemon is watching
@@ -183,4 +226,47 @@ describe("the fs watcher drives hot-reload", () => {
     }
     expect(content).toContain("+export const a = 42;");
   }, 12_000);
+
+  test("watches a directory created after open, so a change inside it refreshes", async () => {
+    // Given an open diff session over a repo that had no such directory
+    const session = await openDiffSession();
+
+    // When a new directory appears, the watcher extends into it (a recursive watch got this free)
+    mkdirSync(join(repo, "pkg"));
+    await Bun.sleep(500);
+    writeFileSync(join(repo, "pkg", "inside.ts"), "export const inside = 1;\n");
+
+    // Then a change inside the new directory drives a re-capture
+    const deadline = Date.now() + 8_000;
+    let content = core.sessionGet(session.id).artifact.content;
+
+    while (!content.includes("+export const inside = 1;") && Date.now() < deadline) {
+      await Bun.sleep(100);
+      content = core.sessionGet(session.id).artifact.content;
+    }
+    expect(content).toContain("+export const inside = 1;");
+  }, 12_000);
+
+  test("a commit refreshes the diff even though no working-tree file changed", async () => {
+    // Given an open diff session showing an uncommitted change to a.ts
+    writeFileSync(join(repo, "a.ts"), "export const a = 5;\n");
+    const session = await openDiffSession();
+
+    expect(core.sessionGet(session.id).artifact.content).toContain("+export const a = 5;");
+
+    // When the change is committed - moving refs/HEAD, touching no working-tree file -
+    // the working tree now equals HEAD, so `git diff HEAD` is empty
+    git(["add", "a.ts"], repo);
+    git(["commit", "-qm", "land a"], repo);
+
+    // Then the git-metadata watch drives a re-capture and the diff empties out
+    const deadline = Date.now() + 8_000;
+    let content = core.sessionGet(session.id).artifact.content;
+
+    while (content.includes("+export const a = 5;") && Date.now() < deadline) {
+      await Bun.sleep(100);
+      content = core.sessionGet(session.id).artifact.content;
+    }
+    expect(content).not.toContain("+export const a = 5;");
+  }, 12_000);
 });

package/src/diff-watcher.ts

@@ -2,32 +2,101 @@
  * Watches a diff session's repository for working-tree changes and drives the
  * hot-reload: on any change under a repo root that a live diff session tracks,
  * the daemon re-captures that session's diff so the open review updates in place.
- * One recursive fs watcher per repo root - many diff sessions can share a repo -
- * with a debounce so a burst of file writes triggers a single re-capture.
+ * One watcher per non-ignored directory (not a recursive watch), so churn under
+ * `.git`, `node_modules`, or a .gitignored path never registers a watch at all -
+ * that keeps idle cost near zero on Linux, where a recursive watch would open an
+ * inotify descriptor per directory. A debounce collapses a burst into one
+ * re-capture. Many diff sessions can share a repo.
  */
 
-import { watch, type FSWatcher } from "node:fs";
-import { sep } from "node:path";
+import { watch, readdirSync, statSync, type Dirent, type FSWatcher } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
 
 /** Debounce window: a save or a checkout writes many files in a burst; collapse them into one re-capture. */
 const DIFF_REFRESH_DEBOUNCE_MS = 300;
 
 /**
- * Paths whose churn must never trigger a diff refresh. git rewrites `.git`
- * metadata (the index, lock files) on every read `cueloop diff` itself runs, so
- * watching it would loop; `node_modules` churns on installs and is never review
- * content.
+ * Directory names never worth a watch, whatever .gitignore says. `.git` is
+ * watched narrowly elsewhere (HEAD, refs, packed-refs) so its own read churn (the
+ * index, lock files) cannot loop; `node_modules` churns on installs and is never
+ * review content.
  */
-function isIgnoredWatchPath(relativePath: string): boolean {
-  const segments = relativePath.split(sep);
+const ALWAYS_IGNORED_DIRS = new Set([".git", "node_modules"]);
 
-  return segments.includes(".git") || segments.includes("node_modules");
+/**
+ * Absolute paths of the directories git ignores under a repo root, resolved once
+ * at watch time from `git ls-files` so a .gitignored tree (dist, build output)
+ * never gets a watcher. Empty when git is unavailable - the name check still
+ * skips the churny defaults.
+ */
+function ignoredDirectories(repoRoot: string): Set<string> {
+  const ignored = new Set<string>();
+  const result = spawnGit(
+    ["ls-files", "--others", "--ignored", "--exclude-standard", "--directory"],
+    repoRoot,
+  );
+
+  if (!result || result.exitCode !== 0) return ignored;
+  for (const line of result.stdout.toString().split("\n")) {
+    const relative = line.trim().replace(/\/$/, "");
+
+    if (relative.length > 0) ignored.add(join(repoRoot, relative));
+  }
+
+  return ignored;
+}
+
+/** Whether git ignores a single path; used for a directory created after the initial walk. */
+function isGitIgnored(repoRoot: string, path: string): boolean {
+  return spawnGit(["check-ignore", "-q", path], repoRoot)?.exitCode === 0;
+}
+
+/** Run a git command in `cwd`, or null when git is missing or the cwd is gone (spawn throws ENOENT). */
+function spawnGit(args: string[], cwd: string): { exitCode: number; stdout: Buffer } | null {
+  try {
+    const result = Bun.spawnSync(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore" });
+
+    return { exitCode: result.exitCode ?? 1, stdout: result.stdout };
+  } catch {
+    return null;
+  }
+}
+
+/** The git-metadata filenames whose change means `git diff HEAD` moved: a checkout, a commit, or a reset. */
+function isRefChange(filename: string): boolean {
+  return filename === "HEAD" || filename === "packed-refs";
+}
+
+/**
+ * A repo's git dir (HEAD and the index live here) and common dir (refs and
+ * packed-refs live here). They differ inside a linked worktree. Null when the
+ * root is not a git repo or git is unavailable.
+ */
+function resolveGitDirs(repoRoot: string): { gitDir: string; commonDir: string } | null {
+  const result = spawnGit(["rev-parse", "--absolute-git-dir", "--git-common-dir"], repoRoot);
+
+  if (!result || result.exitCode !== 0) return null;
+  const [gitDir, commonRaw] = result.stdout.toString().trim().split("\n");
+
+  if (!gitDir) return null;
+  const commonDir = commonRaw
+    ? isAbsolute(commonRaw)
+      ? commonRaw
+      : join(repoRoot, commonRaw)
+    : gitDir;
+
+  return { gitDir, commonDir };
 }
 
 interface RepoWatch {
-  handle: FSWatcher;
+  /** One watcher per watched working-tree directory plus the narrow git-metadata watches; all close together. */
+  handles: FSWatcher[];
   /** Live diff session ids sharing this repo root; the watch closes when the last one leaves. */
   sessionIds: Set<string>;
+  /** Absolute paths git ignores under the root, so the walk skips them. */
+  ignored: Set<string>;
+  /** Directories already watched, so a runtime-created dir is not watched twice. */
+  watchedDirs: Set<string>;
   debounce: ReturnType<typeof setTimeout> | null;
 }
 
@@ -51,21 +120,124 @@ export class DiffWatcher {
 
       return;
     }
-    let handle: FSWatcher;
+    const repoWatch: RepoWatch = {
+      handles: [],
+      sessionIds: new Set([sessionId]),
+      ignored: ignoredDirectories(repoRoot),
+      watchedDirs: new Set(),
+      debounce: null,
+    };
 
-    try {
-      handle = watch(repoRoot, { recursive: true }, (_event, filename) => {
-        if (filename !== null && isIgnoredWatchPath(filename.toString())) return;
-        this.scheduleRepoRefresh(repoRoot);
+    this.repoWatches.set(repoRoot, repoWatch);
+
+    // one watcher per non-ignored working-tree directory; a tracked-file change re-captures
+    if (!this.watchTree(repoRoot, repoRoot)) {
+      // repo root gone or not watchable on this platform: skip, no hot-reload here
+      this.repoWatches.delete(repoRoot);
+
+      return;
+    }
+
+    // git metadata: a commit, checkout, or reset moves `git diff HEAD` without
+    // touching any working-tree file, so those never reach the tree watch above.
+    const gitDirs = resolveGitDirs(repoRoot);
+
+    if (gitDirs) {
+      // HEAD and packed-refs sit beside the index; the index rewrites on our own
+      // reads, so only HEAD/packed-refs here - watching the index would loop
+      this.watchInto(repoWatch.handles, gitDirs.gitDir, { recursive: false }, (filename) => {
+        if (isRefChange(filename)) this.scheduleRepoRefresh(repoRoot);
       });
+      // a commit or reset updates refs/heads/<branch>; any ref move re-captures
+      this.watchInto(repoWatch.handles, join(gitDirs.commonDir, "refs"), { recursive: true }, () =>
+        this.scheduleRepoRefresh(repoRoot),
+      );
+      if (gitDirs.commonDir !== gitDirs.gitDir)
+        this.watchInto(repoWatch.handles, gitDirs.commonDir, { recursive: false }, (filename) => {
+          if (isRefChange(filename)) this.scheduleRepoRefresh(repoRoot);
+        });
+    }
+  }
+
+  /**
+   * Watch `dir` (non-recursive) and every non-ignored directory under it, adding
+   * each to the repo's handles. Returns whether `dir` itself got a watcher, so
+   * the caller can tell a dead root from a merely-skipped subtree. A skipped
+   * (ignored or already-watched) directory counts as watched, not a failure.
+   */
+  private watchTree(repoRoot: string, dir: string): boolean {
+    const repoWatch = this.repoWatches.get(repoRoot);
+
+    if (!repoWatch) return false;
+    if (repoWatch.watchedDirs.has(dir)) return true;
+    if (ALWAYS_IGNORED_DIRS.has(basename(dir)) || repoWatch.ignored.has(dir)) return true;
+
+    const opened = this.watchInto(repoWatch.handles, dir, { recursive: false }, (filename) => {
+      this.scheduleRepoRefresh(repoRoot);
+      // a newly created subdirectory needs its own watch (a recursive watch got this for free)
+      this.extendWatch(repoRoot, join(dir, filename));
+    });
+
+    if (!opened) return false;
+    repoWatch.watchedDirs.add(dir);
+
+    let entries: Dirent[];
+
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
     } catch {
-      // repo root gone or not watchable on this platform: skip, no hot-reload here
+      return true;
+    }
+    for (const entry of entries) {
+      // a symlinked directory is skipped so the walk cannot loop
+      if (entry.isDirectory() && !entry.isSymbolicLink())
+        this.watchTree(repoRoot, join(dir, entry.name));
+    }
+
+    return true;
+  }
+
+  /**
+   * After a change names a new path, watch it (and its subtree) when it is a
+   * directory git does not ignore. The point-in-time ignored set cannot know a
+   * directory created after the walk, so a fresh dir is checked against git live.
+   */
+  private extendWatch(repoRoot: string, path: string): void {
+    try {
+      if (!statSync(path).isDirectory()) return;
+    } catch {
+      // the path is already gone (a transient temp dir); nothing to watch
       return;
     }
-    // a watcher error (the root is deleted mid-review) must not take down the
-    // daemon; the inherited EventEmitter `on` is absent from Bun's FSWatcher type
-    handle.on("error", () => {});
-    this.repoWatches.set(repoRoot, { handle, sessionIds: new Set([sessionId]), debounce: null });
+    if (ALWAYS_IGNORED_DIRS.has(basename(path))) return;
+    if (isGitIgnored(repoRoot, path)) return;
+    this.watchTree(repoRoot, path);
+  }
+
+  /**
+   * Open one watcher and add it to `handles`; returns whether it opened. A
+   * watcher error (the path is deleted mid-review) is swallowed - hot-reload is
+   * best-effort and must never take down the daemon. The inherited EventEmitter
+   * `on` is absent from Bun's FSWatcher type.
+   */
+  private watchInto(
+    handles: FSWatcher[],
+    path: string,
+    options: { recursive: boolean },
+    onFile: (filename: string) => void,
+  ): boolean {
+    try {
+      const handle = watch(path, options, (_event, filename) => {
+        if (filename !== null) onFile(filename.toString());
+      });
+
+      handle.on("error", () => {});
+      handles.push(handle);
+
+      return true;
+    } catch {
+      return false;
+    }
   }
 
   /** Drop one diff session; close the repo watch once no diff session tracks it. */
@@ -76,7 +248,7 @@ export class DiffWatcher {
     repoWatch.sessionIds.delete(sessionId);
     if (repoWatch.sessionIds.size > 0) return;
     if (repoWatch.debounce !== null) clearTimeout(repoWatch.debounce);
-    repoWatch.handle.close();
+    for (const handle of repoWatch.handles) handle.close();
     this.repoWatches.delete(repoRoot);
   }
 
@@ -95,7 +267,7 @@ export class DiffWatcher {
   close(): void {
     for (const repoWatch of this.repoWatches.values()) {
       if (repoWatch.debounce !== null) clearTimeout(repoWatch.debounce);
-      repoWatch.handle.close();
+      for (const handle of repoWatch.handles) handle.close();
     }
     this.repoWatches.clear();
   }

package/src/gh.ts

@@ -0,0 +1,37 @@
+// gh CLI reads for PR reviews; auth is delegated to the user's gh. Reads only.
+
+const ghBinary = (): string => process.env.CUELOOP_GH || "gh";
+
+async function gh(args: string[]): Promise<{ code: number; stdout: string }> {
+  const process = Bun.spawn([ghBinary(), ...args], { stdout: "pipe", stderr: "ignore" });
+  const stdout = await new Response(process.stdout).text();
+
+  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",
+  ]);
+
+  if (code !== 0) return null;
+  const sha = stdout.trim();
+
+  return sha.length > 0 ? sha : null;
+}
+
+/** The PR unified diff as gh prints it, or null when the call fails. */
+export async function prDiff(pr: string): Promise<string | null> {
+  const { code, stdout } = await gh(["pr", "diff", pr]);
+
+  if (code !== 0) return null;
+
+  return stdout;
+}

package/src/pr-poller.test.ts

@@ -0,0 +1,76 @@
+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[] = [];
+  const poller = new PrReviewPoller(
+    (sessionId) => advanced.push(sessionId),
+    async () => sha,
+    1_000_000,
+  );
+
+  return {
+    poller,
+    advanced,
+    setSha: (next: string | null) => {
+      sha = next;
+    },
+  };
+}
+
+describe("PrReviewPoller", () => {
+  test("the first observation is a silent baseline", async () => {
+    const { poller, advanced } = makePoller("sha1");
+
+    poller.trackPr("s1", "org/repo#1");
+    await poller.refreshHead("s1");
+
+    expect(advanced).toEqual([]);
+    poller.close();
+  });
+
+  test("a moved head fires once; an unchanged head stays quiet", async () => {
+    const { poller, advanced, setSha } = makePoller("sha1");
+
+    poller.trackPr("s1", "org/repo#1");
+    await poller.refreshHead("s1");
+
+    setSha("sha2");
+    await poller.refreshHead("s1");
+    await poller.refreshHead("s1");
+
+    expect(advanced).toEqual(["s1"]);
+    poller.close();
+  });
+
+  test("a failed head read never fires and keeps the last baseline", async () => {
+    const { poller, advanced, setSha } = makePoller("sha1");
+
+    poller.trackPr("s1", "org/repo#1");
+    await poller.refreshHead("s1");
+
+    setSha(null);
+    await poller.refreshHead("s1");
+    setSha("sha2");
+    await poller.refreshHead("s1");
+
+    expect(advanced).toEqual(["s1"]);
+    poller.close();
+  });
+
+  test("untrack stops further checks", async () => {
+    const { poller, advanced, setSha } = makePoller("sha1");
+
+    poller.trackPr("s1", "org/repo#1");
+    await poller.refreshHead("s1");
+    poller.untrackPr("s1");
+
+    setSha("sha2");
+    await poller.refreshHead("s1");
+
+    expect(advanced).toEqual([]);
+    poller.close();
+  });
+});

package/src/pr-poller.ts

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+
+import { prHeadSha } from "./gh";
+
+/** One cheap head-sha 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;
+  timer: ReturnType<typeof setInterval>;
+}
+
+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 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 {
+    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 });
+    void this.refreshHead(sessionId);
+  }
+
+  /** Check the PR head once; fire onPrAdvance only when it 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);
+
+    if (sha === 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;
+
+      return;
+    }
+    if (sha === current.lastSha) return;
+    current.lastSha = sha;
+    this.onPrAdvance(sessionId);
+  }
+
+  untrackPr(sessionId: string): void {
+    const poll = this.polls.get(sessionId);
+
+    if (!poll) return;
+    clearInterval(poll.timer);
+    this.polls.delete(sessionId);
+  }
+
+  close(): void {
+    for (const poll of this.polls.values()) clearInterval(poll.timer);
+    this.polls.clear();
+  }
+}

package/src/server.ts

@@ -430,6 +430,11 @@ export class DaemonServer {
 
       return this.core.sessionSetShareId(params.id, params.shareId);
     },
+    "session.setShares": (_connection, request) => {
+      const params = parseParams("session.setShares", request.params);
+
+      return this.core.sessionSetShares(params.id, params.shares);
+    },
     "session.delete": (_connection, request) => {
       this.core.sessionDelete(parseParams("session.delete", request.params).id);
 

package/src/store.ts

@@ -24,7 +24,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { historyFromLinear, type Thread } from "@cueloop/schema";
+import { historyFromLinear, withShareLinks, type Thread } from "@cueloop/schema";
 import { migratedSessionsDir, sessionsDir, threadBucket, threadsDir } from "./paths";
 import { validateThreadRecord } from "./validate";
 
@@ -55,9 +55,12 @@ export interface ThreadRepository {
  * reading without a history - migration never loses a record.
  */
 export function withHistory(session: Thread): Thread {
-  if (session.history || session.revisions.length === 0) return session;
+  // migrate a legacy single share into shares[] on the same read that fills history
+  const migrated = withShareLinks(session);
 
-  return { ...session, history: historyFromLinear(session) };
+  if (migrated.history || migrated.revisions.length === 0) return migrated;
+
+  return { ...migrated, history: historyFromLinear(migrated) };
 }
 
 /** Records in the order `list()` promises: oldest first. */

package/src/validate.test.ts

@@ -279,6 +279,16 @@ describe("wire pins", () => {
     verdict: fullVerdict,
     status: "pending",
     createdAt: "now",
+    shares: [
+      {
+        id: "p_abc123xy",
+        name: "review link",
+        requireAuth: true,
+        allowlist: ["octocat"],
+        owner: "SHA256:owner",
+        shareBranch: "main",
+      },
+    ],
     shareId: "p_abc123xy",
     owner: "SHA256:owner",
     access: { githubLogins: ["octocat"] },

package/src/validate.ts

@@ -25,6 +25,7 @@ import {
   type Revision,
   type SessionHistory,
   type ShareAccess,
+  type ShareLink,
   validateHistory,
   type Verdict,
   type WorkspaceKey,
@@ -131,6 +132,15 @@ export const IdentitySchema = v.object({
   handle: v.optional(v.string()),
 } satisfies EntriesOf<Identity>);
 
+export const ShareLinkSchema = v.object({
+  id: NonEmpty,
+  name: v.optional(v.string()),
+  requireAuth: v.boolean(),
+  allowlist: v.array(NonEmpty),
+  owner: v.optional(v.string()),
+  shareBranch: v.optional(v.string()),
+} satisfies EntriesOf<ShareLink>);
+
 export const Params = {
   "session.create": v.object({ workspace: WorkspaceSchema, artifact: ArtifactSchema }),
   "session.get": v.object({ id: SessionId }),
@@ -205,6 +215,7 @@ export const Params = {
   "session.fork": v.object({ id: SessionId }),
   "session.refreshDiff": v.object({ id: SessionId }),
   "session.setShareId": v.object({ id: SessionId, shareId: NonEmpty }),
+  "session.setShares": v.object({ id: SessionId, shares: v.array(ShareLinkSchema) }),
   "session.setAccess": v.object({ id: SessionId, githubLogins: v.array(NonEmpty) }),
   "session.delete": v.object({ id: SessionId }),
   "session.mergeShared": v.object({
@@ -348,6 +359,7 @@ export const ThreadRecordSchema = v.object({
   createdAt: v.string(),
   shelvedAnnotations: v.optional(v.array(FullAnnotationSchema)),
   parentSessionId: v.optional(v.string()),
+  shares: v.optional(v.array(ShareLinkSchema)),
   shareId: v.optional(v.string()),
   shareBranch: v.optional(v.string()),
   owner: v.optional(v.string()),