@cueloop/daemon 0.1.0-alpha.7 → 0.1.0-alpha.70

package/src/api.ts

@@ -1,5 +1,5 @@
 /**
- * The daemon's method surface (#14). Transport-independent: the socket
+ * The daemon's method surface. Transport-independent: the socket
  * server and the in-process test harness both call these handlers.
  * The wait contract: verdicts outlive waits - session.wait long-polls,
  * and a verdict resolved while nobody waited is delivered on next contact.
@@ -7,18 +7,60 @@
 
 import {
   SCHEMA_VERSION,
+  appendEntry,
+  applyPathView,
+  createBranch,
+  cutBlock,
   feedbackForSession,
+  forkHistory,
+  historyFromLinear,
+  HistoryError,
+  labelTip,
+  navigateTo,
+  recaptureMainHead,
+  viewOfPath,
+  isAddressed,
+  isAgentNote,
+  annotationTarget,
+  isMarkdownArtifact,
+  MAIN_BRANCH,
+  parseBlocks,
+  registerParticipant,
+  resolveAnchor,
+  isBlockCut,
+  restoreBlock,
+  switchBranch,
   verdictAllows,
   type Annotation,
+  type DiffFileStatus,
+  type HunkRejection,
+  type NewEntry,
   type Artifact,
-  type ReviewSession,
+  type Identity,
+  type Thread,
+  type SessionHistory,
   type Verdict,
   type VerdictKind,
   type WorkspaceKey,
 } from "@cueloop/schema";
-import { SessionStore } from "./store";
+import { curateDiff } from "./curate";
+import { ThreadStore, withHistory } from "./store";
+import { pruneExpiredSessions, resolveCleanupPeriodDays } from "./retention";
+import { HerdrTabStore, type HerdrTabHandle } from "./herdr-tab-store";
+import { DiffWatcher } from "./diff-watcher";
+import { workingTreeDiff, workingChangeList, type WorkingTreeDiff } from "./working-tree";
+import { listProjectFiles, readProjectFile } from "./project-files";
+import { resolveWorkspace } from "./review";
 import { DaemonError } from "./errors";
 
+/** What a share hands back: the notes and names it collected, and the removals it recorded. */
+export interface SharedMerge {
+  annotations: Annotation[];
+  participants?: Identity[];
+  /** Removal entries by id; a merge applies each once and never rewrites what it already holds. */
+  removals?: Array<{ id: string; annotationId: string; createdAt: string }>;
+}
+
 export type EventName =
   | "session.created"
   | "session.updated"
@@ -29,40 +71,76 @@ export type EventName =
 export interface DaemonEvent {
   event: EventName;
   sessionId: string;
+  /** The history entry the change appended, when it appended one. */
+  entryId?: string;
 }
 
-type EventListener = (e: DaemonEvent) => void;
+type EventListener = (event: DaemonEvent) => void;
 
 export class DaemonCore {
-  readonly store: SessionStore;
-  private waiters = new Map<string, ((session: ReviewSession) => void)[]>();
+  readonly store: ThreadStore;
+  readonly herdrTabs: HerdrTabStore;
+  private waiters = new Map<string, ((session: Thread) => void)[]>();
   private listeners = new Set<EventListener>();
   private seq = 0;
+  /** Drives diff hot-reload: watches each live diff session's repo for working-tree changes. */
+  private readonly diffWatcher: DiffWatcher;
+  /**
+   * Per-diff-session capture generation. Bumped when a refresh begins; a
+   * capture whose generation is stale by the time it finishes discards its
+   * result, so overlapping captures never write an older patch over a newer one.
+   */
+  private readonly diffRefreshGenerations = new Map<string, number>();
+  /** In-flight workbench creations keyed by project, so concurrent bare launches share one thread. */
+  private readonly workbenchCreation = new Map<string, Promise<Thread>>();
 
   constructor(home: string) {
-    this.store = new SessionStore(home);
+    this.store = new ThreadStore(home);
     this.store.recover();
+    pruneExpiredSessions(this.store, resolveCleanupPeriodDays(), Date.now());
+    this.herdrTabs = new HerdrTabStore(home);
+    this.diffWatcher = new DiffWatcher((repoRoot) => void this.refreshDiffsForRepo(repoRoot));
+    // resume hot-reload for diff sessions that survived a daemon restart
+    for (const session of this.store.list()) this.watchIfDiffSession(session);
+  }
+
+  /** Release the fs watchers behind diff hot-reload; call on daemon shutdown. */
+  dispose(): void {
+    this.diffWatcher.close();
+  }
+
+  /** The herdr tab opened for a review, if any (adapter scratch, not on the session). */
+  herdrGetTab(sessionId: string): HerdrTabHandle | null {
+    return this.herdrTabs.get(sessionId);
+  }
+
+  herdrSetTab(sessionId: string, handle: HerdrTabHandle): void {
+    this.herdrTabs.set(sessionId, handle);
   }
 
   onEvent(listener: EventListener): () => void {
     this.listeners.add(listener);
+
     return () => this.listeners.delete(listener);
   }
 
-  private emit(event: EventName, sessionId: string): void {
-    for (const l of this.listeners) l({ event, sessionId });
+  private emit(event: EventName, sessionId: string, entryId?: string): void {
+    const frame: DaemonEvent =
+      entryId === undefined ? { event, sessionId } : { event, sessionId, entryId };
+
+    for (const listener of this.listeners) listener(frame);
   }
 
   /** True when nothing awaits a verdict - drives idle-exit. */
   hasPendingSessions(): boolean {
-    return this.store.list().some((s) => s.status === "pending");
+    return this.store.list().some((session) => session.status === "pending");
   }
 
-  sessionCreate(params: { workspace: WorkspaceKey; artifact: Artifact }): ReviewSession {
+  sessionCreate(params: { workspace: WorkspaceKey; artifact: Artifact }): Thread {
     const now = new Date().toISOString();
-    const session: ReviewSession = {
+    const session: Thread = {
       schemaVersion: SCHEMA_VERSION,
-      id: `ses_${now.replace(/\D/g, "").slice(0, 14)}_${(++this.seq).toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+      id: this.newSessionId(now),
       workspace: params.workspace,
       artifact: params.artifact,
       revisions: [{ revision: 1, content: params.artifact.content, submittedAt: now }],
@@ -71,23 +149,39 @@ export class DaemonCore {
       status: "pending",
       createdAt: now,
     };
+
+    session.history = historyFromLinear(session);
     this.store.upsert(session);
+    this.watchIfDiffSession(session);
     this.emit("session.created", session.id);
     this.emit("inbox.changed", session.id);
+
     return session;
   }
 
-  sessionGet(id: string): ReviewSession {
-    const s = this.store.get(id);
-    if (!s) throw new DaemonError("not_found", `no session ${id}`);
-    return s;
+  private newSessionId(now: string): string {
+    return `ses_${now.replace(/\D/g, "").slice(0, 14)}_${(++this.seq).toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+  }
+
+  sessionGet(id: string): Thread {
+    const session = this.store.get(id);
+
+    if (!session) throw new DaemonError("not_found", `no session ${id}`);
+
+    return session;
   }
 
-  sessionList(filter?: { status?: "pending" | "resolved"; workspace?: Partial<WorkspaceKey> }): ReviewSession[] {
-    return this.store.list().filter((s) => {
-      if (filter?.status && s.status !== filter.status) return false;
-      if (filter?.workspace?.repoRoot && s.workspace.repoRoot !== filter.workspace.repoRoot) return false;
-      if (filter?.workspace?.branch && s.workspace.branch !== filter.workspace.branch) return false;
+  sessionList(filter?: {
+    status?: "pending" | "resolved";
+    workspace?: Partial<WorkspaceKey>;
+  }): Thread[] {
+    return this.store.list().filter((session) => {
+      if (filter?.status && session.status !== filter.status) return false;
+      if (filter?.workspace?.repoRoot && session.workspace.repoRoot !== filter.workspace.repoRoot)
+        return false;
+      if (filter?.workspace?.branch && session.workspace.branch !== filter.workspace.branch)
+        return false;
+
       return true;
     });
   }
@@ -97,104 +191,787 @@ export class DaemonCore {
    * otherwise parks until sessionResolve fires or timeoutMs elapses (null =
    * still pending - the caller re-polls later; the verdict is never lost).
    */
-  sessionWait(id: string, timeoutMs: number): Promise<ReviewSession | null> {
-    const s = this.sessionGet(id);
-    if (s.status === "resolved") return Promise.resolve(s);
+  sessionWait(id: string, timeoutMs: number): Promise<Thread | null> {
+    const current = this.sessionGet(id);
+
+    if (current.status === "resolved") return Promise.resolve(current);
+
     return new Promise((resolve) => {
       const list = this.waiters.get(id) ?? [];
       let done = false;
       const timer = setTimeout(() => {
         if (done) return;
         done = true;
-        const idx = list.indexOf(waiter);
-        if (idx !== -1) list.splice(idx, 1);
+        const waiterIndex = list.indexOf(waiter);
+
+        if (waiterIndex !== -1) list.splice(waiterIndex, 1);
         resolve(null);
       }, timeoutMs);
-      const waiter = (session: ReviewSession) => {
+      const waiter = (session: Thread) => {
         if (done) return;
         done = true;
         clearTimeout(timer);
         resolve(session);
       };
+
       list.push(waiter);
       this.waiters.set(id, list);
     });
   }
 
-  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): ReviewSession {
-    const s = this.mutable(id);
-    const existing = s.annotations.findIndex((a) => a.id === annotation.id);
+  /**
+   * `authorName` registers the annotation's author in the participant registry;
+   * a bare author id (no name) keeps its short-handle fallback instead.
+   */
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Thread {
+    const session = this.mutable(id);
+    // a welcome-playground note is ephemeral by design: never persisted, so never fed back
+    if (annotationTarget(annotation).kind === "welcome") return session;
+    const existing = session.annotations.findIndex((candidate) => candidate.id === annotation.id);
     const full: Annotation = { ...annotation, createdAt: new Date().toISOString() };
-    if (existing === -1) s.annotations.push(full);
-    else s.annotations[existing] = { ...full, createdAt: s.annotations[existing]!.createdAt };
-    this.store.upsert(s);
-    this.emit("session.updated", id);
-    return s;
+
+    let entryId: string | undefined;
+
+    if (existing === -1) {
+      session.annotations.push(full);
+      entryId = this.record(session, {
+        type: "comment",
+        annotationId: full.id,
+        createdAt: full.createdAt,
+      });
+    } else
+      session.annotations[existing] = {
+        ...full,
+        createdAt: session.annotations[existing]!.createdAt,
+      };
+    if (annotation.author && authorName)
+      session.participants = registerParticipant(
+        session,
+        annotation.author,
+        authorName,
+      ).participants;
+    this.store.upsert(session);
+    this.emit("session.updated", id, entryId);
+
+    return session;
+  }
+
+  /**
+   * Remove a comment. With `onBehalfOf`, the caller is a collaborator or an
+   * agent acting as that author and may remove only that author's comments;
+   * the owner (no `onBehalfOf`) may remove any.
+   */
+  sessionRemoveAnnotation(id: string, annotationId: string, onBehalfOf?: string): Thread {
+    const session = this.mutable(id);
+    const target = session.annotations.find((candidate) => candidate.id === annotationId);
+
+    if (onBehalfOf !== undefined && target !== undefined && target.author !== onBehalfOf) {
+      throw new DaemonError("forbidden", `${onBehalfOf} cannot remove another author's comment`);
+    }
+    session.annotations = session.annotations.filter((candidate) => candidate.id !== annotationId);
+    let entryId: string | undefined;
+
+    if (target !== undefined) {
+      // nothing is deleted: a navigate back before the removal shows it again
+      session.shelvedAnnotations = [...(session.shelvedAnnotations ?? []), target];
+      entryId = this.record(session, {
+        type: "comment-removed",
+        annotationId,
+        createdAt: new Date().toISOString(),
+      });
+    }
+
+    this.store.upsert(session);
+    this.emit("session.updated", id, entryId);
+
+    return session;
   }
 
-  sessionRemoveAnnotation(id: string, annotationId: string): ReviewSession {
-    const s = this.mutable(id);
-    s.annotations = s.annotations.filter((a) => a.id !== annotationId);
-    this.store.upsert(s);
+  /** Register a display name for a participant; how a collaborator or an agent names itself. */
+  sessionSetParticipantName(id: string, author: string, name: string): Thread {
+    const session = this.mutable(id);
+
+    session.participants = registerParticipant(session, author, name).participants;
+    this.store.upsert(session);
     this.emit("session.updated", id);
-    return s;
+
+    return session;
   }
 
   /** The reviewer's working copy; undefined clears it (revert all edits). */
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): ReviewSession {
-    const s = this.mutable(id);
-    if (workingCopy === undefined || workingCopy === s.artifact.content) delete s.workingCopy;
-    else s.workingCopy = workingCopy;
-    this.store.upsert(s);
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Thread {
+    const session = this.mutable(id);
+    const entryId = this.applyWorkingCopy(session, workingCopy);
+
+    this.store.upsert(session);
+    this.emit("session.updated", id, entryId);
+
+    return session;
+  }
+
+  /**
+   * The guided walk's viewed marks. Merge-additive: walking only ever adds
+   * marks, so concurrent or stale clients converge instead of overwriting
+   * each other. An empty array is the explicit reset.
+   */
+  sessionSetViewed(id: string, viewedPaths: string[]): Thread {
+    const session = this.mutable(id);
+
+    if (viewedPaths.length === 0) delete session.viewedPaths;
+    else session.viewedPaths = [...new Set([...(session.viewedPaths ?? []), ...viewedPaths])];
+    this.store.upsert(session);
+    this.emit("session.updated", id);
+
+    return session;
+  }
+
+  /** Rename a session's display title; an empty title clears it back to the derived default. */
+  sessionSetTitle(id: string, title: string): Thread {
+    const session = this.mutable(id);
+    const trimmed = title.trim();
+
+    if (trimmed.length === 0) delete session.artifact.meta.title;
+    else session.artifact.meta.title = trimmed;
+    this.store.upsert(session);
+    // the title shows in the Threads sidebar, so a rename is an inbox change, not just a content edit
+    this.emit("inbox.changed", id);
+
+    return session;
+  }
+
+  /** Tracked, repo-relative file paths for the session's workspace; [] when it has no repo. */
+  projectFiles(id: string): Promise<string[]> {
+    return listProjectFiles(this.sessionGet(id).workspace.repoRoot);
+  }
+
+  /** UTF-8 contents of a repo-relative file in the session's workspace, or null when it cannot be read safely. */
+  fileContents(id: string, path: string): Promise<string | null> {
+    return readProjectFile(this.sessionGet(id).workspace.repoRoot, path);
+  }
+
+  /** Tracked, repo-relative file paths for the git repo containing `cwd`; [] when it is not a repo. Owner-only. */
+  async repoFiles(cwd: string): Promise<string[]> {
+    return listProjectFiles((await resolveWorkspace(cwd)).repoRoot);
+  }
+
+  /** UTF-8 contents of a repo-relative file in the repo containing `cwd`, or null when unreadable. Owner-only. */
+  async repoFileContents(cwd: string, path: string): Promise<string | null> {
+    return readProjectFile((await resolveWorkspace(cwd)).repoRoot, path);
+  }
+
+  /** Changed files (repo-relative path plus git status) in the working tree at `cwd`. Owner-only. */
+  repoChanges(cwd: string): Promise<{ path: string; status: DiffFileStatus }[]> {
+    return workingChangeList(cwd);
+  }
+
+  /**
+   * The live working-tree diff (HEAD vs working tree, untracked included) at `cwd`:
+   * the same unified patch plus full per-file contents a `cueloop diff` captures,
+   * so the Changes navigator renders a real diff for any thread. Owner-only.
+   */
+  repoDiff(cwd: string): Promise<WorkingTreeDiff> {
+    return workingTreeDiff(cwd);
+  }
+
+  /**
+   * The per-repo workbench thread for `cwd`: a self-initiated review of the current checkout, keyed by
+   * the repo's root-commit identity (a standalone bucket when there is none). Returns the existing one
+   * or lazily creates it with the working-tree diff as its artifact, so a bare launch persists its
+   * first comment without an agent submission. Owner-only.
+   */
+  async workbenchSession(cwd: string): Promise<Thread> {
+    const workspace = await resolveWorkspace(cwd);
+    const key = workspace.rootCommit ?? "_standalone";
+    // an open workbench is reused; a resolved one is immutable and would reject the note, so a fresh
+    // one is created past it
+    const open = this.store
+      .list()
+      .find(
+        (session) =>
+          session.artifact.meta.workbench === true &&
+          session.status !== "resolved" &&
+          (session.workspace.rootCommit ?? "_standalone") === key,
+      );
+
+    if (open) return open;
+    // serialize concurrent bare launches for the same repo onto one creation, so they share a thread
+    const inFlight = this.workbenchCreation.get(key);
+
+    if (inFlight) return inFlight;
+    const creation = workingTreeDiff(cwd).then((diff) =>
+      this.sessionCreate({
+        workspace,
+        artifact: {
+          type: "diff",
+          content: diff.patch,
+          files: diff.files,
+          meta: { workbench: true, title: "Workbench", cwd },
+        },
+      }),
+    );
+
+    this.workbenchCreation.set(key, creation);
+    try {
+      return await creation;
+    } finally {
+      this.workbenchCreation.delete(key);
+    }
+  }
+
+  sessionSetShareId(id: string, shareId: string): Thread {
+    const session = this.mutable(id);
+
+    session.shareId = shareId;
+    this.store.upsert(session);
+    this.emit("session.updated", id);
+
+    return session;
+  }
+
+  /** Remove a session for good (inbox delete); resolved or pending, both go. */
+  sessionDelete(id: string): void {
+    const session = this.store.get(id);
+
+    if (!this.store.delete(id)) throw new DaemonError("not_found", `no session ${id}`);
+    if (session) this.unwatchIfDiffSession(session);
+    this.diffRefreshGenerations.delete(id);
+    this.herdrTabs.delete(id);
+    this.emit("inbox.changed", id);
+  }
+
+  /**
+   * Cut one block of the reviewer's working copy - the `blockIndex`-th block
+   * of the working text - so it serializes into the diff the agent receives.
+   */
+  sessionCutBlock(id: string, blockIndex: number): Thread {
+    const session = this.mutable(id);
+    const working = session.workingCopy ?? session.artifact.content;
+    const block = parseBlocks(working)[blockIndex];
+
+    if (!block)
+      throw new DaemonError("invalid_params", `no block ${blockIndex} in the working copy`);
+    const entryId = this.applyWorkingCopy(session, cutBlock(working, block));
+
+    this.store.upsert(session);
+    this.emit("session.updated", id, entryId);
+
+    return session;
+  }
+
+  /**
+   * Re-insert a cut block - the `baseBlockIndex`-th block of the submitted
+   * revision - into the working copy before `line` (default: the end). A copy
+   * that reads as the submitted revision again is dropped, not stored.
+   */
+  sessionRestoreBlock(id: string, baseBlockIndex: number, line?: number): Thread {
+    const session = this.mutable(id);
+    const base = session.artifact.content;
+    const block = parseBlocks(base)[baseBlockIndex];
+
+    if (!block) {
+      throw new DaemonError(
+        "invalid_params",
+        `no block ${baseBlockIndex} in the submitted revision`,
+      );
+    }
+    const working = session.workingCopy ?? base;
+
+    if (!isBlockCut(base, working, block)) {
+      throw new DaemonError(
+        "invalid_params",
+        `block ${baseBlockIndex} of the submitted revision is present in the working copy`,
+      );
+    }
+    const beforeLine = Math.min(line ?? working.split("\n").length, working.split("\n").length);
+    const entryId = this.applyWorkingCopy(session, restoreBlock(base, working, block, beforeLine));
+
+    this.store.upsert(session);
+    this.emit("session.updated", id, entryId);
+
+    return session;
+  }
+
+  /**
+   * Replace a diff review's reject decisions; the working copy becomes the
+   * patch they leave, or clears when nothing is rejected. Needs the full file
+   * contents a working-tree diff carries; a PR diff cannot be curated.
+   */
+  sessionCurate(id: string, rejections: HunkRejection[]): Thread {
+    const session = this.mutable(id);
+
+    if (session.artifact.type !== "diff") {
+      throw new DaemonError("invalid_params", "only a diff review is curated by hunk");
+    }
+    if (!session.artifact.files) {
+      throw new DaemonError("invalid_params", "hunk curation needs full file contents");
+    }
+    if (rejections.length === 0) delete session.curation;
+    else session.curation = rejections;
+    const entryId = this.applyWorkingCopy(
+      session,
+      rejections.length === 0 ? undefined : curateDiff(session.artifact.files, rejections),
+    );
+
+    this.store.upsert(session);
+    this.emit("session.updated", id, entryId);
+
+    return session;
+  }
+
+  /**
+   * Merge a share's state back into the local session. Comments union by
+   * annotation id with existing ones (the planner's) winning; removals union by
+   * entry id, each shelving its comment once; the participant registry unions
+   * by id with the incoming identity winning (a collaborator is the authority
+   * on their own name). Everything lands on the branch the share follows, and
+   * the record then shows its current path again, wherever the owner stands.
+   */
+  sessionMergeShared(id: string, incoming: SharedMerge): Thread {
+    const session = this.mutable(id);
+    const branch = this.shareBranchOf(session);
+    const known = new Set(
+      [...session.annotations, ...(session.shelvedAnnotations ?? [])].map(
+        (annotation) => annotation.id,
+      ),
+    );
+    let changed = false;
+
+    for (const annotation of incoming.annotations) {
+      if (known.has(annotation.id)) continue;
+      known.add(annotation.id);
+      session.annotations.push(annotation);
+      this.recordOn(session, branch, {
+        type: "comment",
+        annotationId: annotation.id,
+        createdAt: annotation.createdAt,
+      });
+      changed = true;
+    }
+    const recorded = new Set((session.history?.entries ?? []).map((entry) => entry.id));
+
+    for (const removal of incoming.removals ?? []) {
+      if (recorded.has(removal.id) || !known.has(removal.annotationId)) continue;
+      this.recordOn(session, branch, {
+        id: removal.id,
+        type: "comment-removed",
+        annotationId: removal.annotationId,
+        createdAt: removal.createdAt,
+      });
+      changed = true;
+    }
+    if (incoming.participants?.length) {
+      const registry = new Map(
+        (session.participants ?? []).map((participant) => [participant.id, participant]),
+      );
+
+      for (const participant of incoming.participants) registry.set(participant.id, participant);
+      session.participants = [...registry.values()];
+    }
+    if (changed && session.history) this.refreshView(session, session.history);
+    else this.store.upsert(session);
     this.emit("session.updated", id);
-    return s;
+
+    return session;
   }
 
-  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): ReviewSession {
-    const s = this.mutable(id);
+  sessionResolve(
+    id: string,
+    verdictKind: VerdictKind,
+    summary: string,
+    actionBodies?: Record<string, string>,
+  ): Thread {
+    const session = this.mutable(id);
     const verdict: Verdict = {
       kind: verdictKind,
       summary,
-      feedback: feedbackForSession(s, verdictKind, summary),
+      feedback: feedbackForSession(session, verdictKind, summary, actionBodies),
       resolvedAt: new Date().toISOString(),
     };
-    s.verdict = verdict;
-    s.status = "resolved";
-    this.store.upsert(s);
+
+    session.verdict = verdict;
+    session.status = "resolved";
+    const entryId = this.record(session, {
+      type: "verdict",
+      verdict,
+      createdAt: verdict.resolvedAt,
+    });
+    this.store.upsert(session);
+    // a resolved diff review is frozen; stop hot-reloading its working tree
+    this.unwatchIfDiffSession(session);
     const parked = this.waiters.get(id) ?? [];
+
     this.waiters.delete(id);
-    for (const w of parked) w(s);
-    this.emit("session.resolved", id);
+    for (const parkedWaiter of parked) parkedWaiter(session);
+    this.emit("session.resolved", id, entryId);
     this.emit("inbox.changed", id);
-    return s;
+
+    return session;
   }
 
-  /** Agent resubmits: new revision becomes the artifact, session reopens. */
-  sessionSubmitRevision(id: string, content: string): ReviewSession {
-    const s = this.sessionGet(id);
+  /**
+   * Agent resubmits: new revision becomes the artifact, session reopens.
+   * Annotations the agent reports as acted on (by id) are marked addressed,
+   * and for plan revisions any still-open annotation whose quoted text no
+   * longer resolves is marked addressed too ("drift" - the line it pointed at
+   * was rewritten). Addressed is a marker, never a delete: the reviewer's
+   * rail hides them behind a count, and the next feedback document omits them.
+   * Unknown ids are ignored, so a stale id in the agent's list never fails
+   * the resubmit.
+   */
+  sessionSubmitRevision(
+    id: string,
+    content: string,
+    addressedAnnotationIds: string[] = [],
+  ): Thread {
+    const session = this.sessionGet(id);
     const now = new Date().toISOString();
-    s.revisions.push({ revision: s.revisions.length + 1, content, submittedAt: now });
-    s.artifact = { ...s.artifact, content };
-    delete s.workingCopy;
-    s.verdict = null;
-    s.status = "pending";
-    this.store.upsert(s);
-    this.emit("session.revised", id);
+    const revisionNumber = session.revisions.length + 1;
+
+    session.revisions.push({ revision: revisionNumber, content, submittedAt: now });
+    session.artifact = { ...session.artifact, content };
+    // the agent's revision lands on main wherever its tip sits; the artifact
+    // shows the head of the branch the reviewer is on
+    const entryId = this.recordOnMain(session, {
+      type: "revision",
+      by: "agent",
+      content,
+      createdAt: now,
+    });
+    delete session.workingCopy;
+    session.verdict = null;
+    session.status = "pending";
+
+    // a reported root comment addresses its whole discussion: replies are
+    // never listed on their own in the feedback document
+    const reportedIds = new Set(addressedAnnotationIds);
+
+    for (const annotation of session.annotations) {
+      if (annotation.replyTo !== undefined && reportedIds.has(annotation.replyTo)) {
+        reportedIds.add(annotation.id);
+      }
+    }
+    // drift assist applies to markdown artifacts (plan, reply) only: a diff
+    // revision is a whole new patch, where a vanished quote says nothing about
+    // the feedback
+    const revisedBlocks = isMarkdownArtifact(session.artifact.type) ? parseBlocks(content) : null;
+
+    for (const annotation of session.annotations) {
+      if (isAddressed(annotation) || isAgentNote(annotation)) continue;
+      if (reportedIds.has(annotation.id)) {
+        annotation.resolution = { revision: revisionNumber, source: "agent" };
+      } else if (
+        revisedBlocks !== null &&
+        // only a note on the artifact drifts against the artifact's revision; a selector-anchored
+        // pixel element or a file-targeted Changes-diff note anchors elsewhere
+        annotationTarget(annotation).kind === "artifact" &&
+        !annotation.anchor.selector &&
+        resolveAnchor(annotation.anchor, revisedBlocks) === null
+      ) {
+        annotation.resolution = { revision: revisionNumber, source: "drift" };
+      }
+    }
+
+    this.store.upsert(session);
+    this.emit("session.revised", id, entryId);
     this.emit("inbox.changed", id);
-    return s;
+
+    return session;
+  }
+
+  /**
+   * Move a branch's tip back to an entry on its path - the current branch, or
+   * `branch` after switching to it. The entries after it stay in the tree; a
+   * summary records them as a branch-summary entry at the target. The view
+   * follows the path: on `main`, the agent's next revision lands there.
+   */
+  sessionNavigate(id: string, entryId: string, summary?: string, branch?: string): Thread {
+    const session = this.mutable(id);
+    const moved = this.tree(id, () => {
+      const history = this.historyOf(session);
+      const standing = branch === undefined ? history : switchBranch(history, branch);
+
+      return navigateTo(standing, entryId, summary === undefined ? {} : { summary });
+    });
+
+    this.refreshView(session, moved);
+    const tip = moved.tips[moved.branch];
+
+    this.emit("session.updated", id, tip === entryId ? undefined : tip);
+
+    return session;
+  }
+
+  /** Start a branch at the current tip and switch to it; `main` stays where it is. */
+  sessionBranch(id: string, name: string): Thread {
+    const session = this.mutable(id);
+
+    this.refreshView(
+      session,
+      this.tree(id, () => createBranch(this.historyOf(session), name)),
+    );
+    this.emit("session.updated", id);
+
+    return session;
+  }
+
+  sessionSwitch(id: string, branch: string): Thread {
+    const session = this.mutable(id);
+
+    this.refreshView(
+      session,
+      this.tree(id, () => switchBranch(this.historyOf(session), branch)),
+    );
+    this.emit("session.updated", id);
+
+    return session;
+  }
+
+  /** Name the current tip as a checkpoint to navigate back to. */
+  sessionLabel(id: string, label: string): Thread {
+    const session = this.mutable(id);
+
+    session.history = labelTip(this.historyOf(session), label);
+    this.store.upsert(session);
+    this.emit("session.updated", id);
+
+    return session;
+  }
+
+  /**
+   * Copy the current path into a new pending session: its revisions, open
+   * comments, labels, and participant names travel; verdicts, edits, and the
+   * share do not. A resolved session can be forked.
+   */
+  sessionFork(id: string): Thread {
+    const source = this.sessionGet(id);
+    const history = this.tree(id, () => forkHistory(this.historyOf(source)));
+    const now = new Date().toISOString();
+    const known = [...source.annotations, ...(source.shelvedAnnotations ?? [])];
+    const view = viewOfPath(history, known);
+    const fork: Thread = {
+      schemaVersion: SCHEMA_VERSION,
+      id: this.newSessionId(now),
+      workspace: source.workspace,
+      artifact: { ...source.artifact, content: view.content },
+      revisions: history.entries
+        .filter((entry) => entry.type === "revision")
+        .map((entry, index) => ({
+          revision: index + 1,
+          content: entry.content,
+          submittedAt: entry.createdAt,
+        })),
+      annotations: [],
+      history,
+      verdict: null,
+      status: "pending",
+      createdAt: now,
+      parentSessionId: id,
+    };
+
+    fork.annotations = view.annotations.map((annotation) =>
+      forkedAnnotation(annotation, source, fork),
+    );
+    if (source.participants)
+      fork.participants = source.participants.map((identity) => ({ ...identity }));
+    this.store.upsert(fork);
+    this.watchIfDiffSession(fork);
+    this.emit("session.created", fork.id);
+    this.emit("inbox.changed", fork.id);
+
+    return fork;
+  }
+
+  /** Re-capture a diff session's working tree; broadcasts session.updated only when the patch moved. */
+  async sessionRefreshDiff(id: string): Promise<{ changed: boolean }> {
+    const session = this.mutable(id);
+
+    if (session.artifact.type !== "diff") return { changed: false };
+    const generation = (this.diffRefreshGenerations.get(id) ?? 0) + 1;
+
+    this.diffRefreshGenerations.set(id, generation);
+    const diff = await workingTreeDiff(session.workspace.repoRoot);
+
+    // The capture yields the event loop: a newer refresh may have started, or a
+    // concurrent resolve/delete may have closed the session. Discard a stale
+    // capture, and re-read so a resolved review is never mutated and a deleted
+    // one is never revived by this upsert.
+    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 (diff.patch === current.artifact.content) return { changed: false };
+    current.artifact = { ...current.artifact, content: diff.patch, files: diff.files };
+    // the history keeps showing the same revision, re-captured, so a later tree move derives this patch
+    const history = withHistory(current).history;
+
+    if (history) current.history = recaptureMainHead(history, diff.patch);
+    this.store.upsert(current);
+    this.emit("session.updated", id);
+
+    return { changed: true };
+  }
+
+  /** Re-capture every live 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);
+
+    for (const session of live) {
+      // a session resolved or deleted between the change and this tick just skips
+      try {
+        await this.sessionRefreshDiff(session.id);
+      } catch {
+        // no-op: the session is gone or already resolved
+      }
+    }
+  }
+
+  private watchIfDiffSession(session: Thread): void {
+    if (isLiveDiffSession(session))
+      this.diffWatcher.trackDiffRepo(session.workspace.repoRoot, session.id);
+  }
+
+  private unwatchIfDiffSession(session: Thread): void {
+    if (session.artifact.type === "diff")
+      this.diffWatcher.untrackDiffRepo(session.workspace.repoRoot, session.id);
+  }
+
+  /**
+   * Set or clear the working copy and, when the reviewer's text changed, record
+   * it as a reviewer revision on the current branch. Returns that entry's id.
+   */
+  private applyWorkingCopy(session: Thread, workingCopy: string | undefined): string | undefined {
+    const before = session.workingCopy ?? session.artifact.content;
+    const next =
+      workingCopy === undefined || workingCopy === session.artifact.content
+        ? undefined
+        : workingCopy;
+
+    if (next === undefined) delete session.workingCopy;
+    else session.workingCopy = next;
+    const after = next ?? session.artifact.content;
+
+    if (after === before) return undefined;
+
+    return this.record(session, {
+      type: "revision",
+      by: "reviewer",
+      content: after,
+      createdAt: new Date().toISOString(),
+    });
+  }
+
+  /** The session's history; a record without a revision has none and cannot be moved through. */
+  private historyOf(session: Thread): SessionHistory {
+    const history = withHistory(session).history;
+
+    if (!history) throw new DaemonError("invalid_params", `session ${session.id} has no history`);
+
+    return history;
   }
 
-  private mutable(id: string): ReviewSession {
-    const s = this.sessionGet(id);
-    if (s.status === "resolved") throw new DaemonError("resolved", `session ${id} is already resolved`);
-    return s;
+  /** Run a tree operation; a refused move is the caller's mistake, not the daemon's. */
+  private tree(id: string, operation: () => SessionHistory): SessionHistory {
+    try {
+      return operation();
+    } catch (error) {
+      if (error instanceof HistoryError) throw new DaemonError("invalid_params", error.message);
+      throw error;
+    }
+  }
+
+  /** Store a moved history and make the record show its active path. */
+  private refreshView(session: Thread, history: SessionHistory): void {
+    session.history = history;
+    applyPathView(
+      session,
+      viewOfPath(history, [...session.annotations, ...(session.shelvedAnnotations ?? [])]),
+    );
+    this.store.upsert(session);
+  }
+
+  /** Append an entry on the session's current branch; a session without a head has no history to extend. */
+  private record(session: Thread, entry: NewEntry): string | undefined {
+    const history = withHistory(session).history;
+
+    if (!history) return undefined;
+    const appended = appendEntry(history, entry);
+
+    session.history = appended.history;
+
+    return appended.entry.id;
+  }
+
+  /** Append an entry on main, leaving the reviewer's current branch where it is. */
+  private recordOnMain(session: Thread, entry: NewEntry): string | undefined {
+    return this.recordOn(session, MAIN_BRANCH, entry);
+  }
+
+  /** Append an entry on a named branch, leaving the reviewer's current branch where it is. */
+  private recordOn(session: Thread, branch: string, entry: NewEntry): string | undefined {
+    const history = withHistory(session).history;
+
+    if (!history) return undefined;
+    const appended = appendEntry(switchBranch(history, branch), entry);
+
+    session.history = { ...appended.history, branch: history.branch };
+
+    return appended.entry.id;
+  }
+
+  /** The branch a share follows; a share made before branches existed follows main. */
+  private shareBranchOf(session: Thread): string {
+    const branch = session.shareBranch ?? MAIN_BRANCH;
+
+    return session.history?.tips[branch] === undefined ? MAIN_BRANCH : branch;
+  }
+
+  private mutable(id: string): Thread {
+    const session = this.sessionGet(id);
+
+    if (session.status === "resolved")
+      throw new DaemonError("resolved", `session ${id} is already resolved`);
+
+    return session;
   }
 }
 
 export { DaemonError };
 
+/**
+ * A comment as the fork carries it. An addressed mark names a revision by the
+ * source's numbering; the fork numbers its own, so the mark follows the
+ * revision's text, and a comment addressed by a revision off the fork's path
+ * is open again.
+ */
+function forkedAnnotation(annotation: Annotation, source: Thread, fork: Thread): Annotation {
+  const { resolution, ...open } = annotation;
+
+  if (resolution === undefined) return { ...annotation };
+  const addressedBy = source.revisions.find(
+    (revision) => revision.revision === resolution.revision,
+  );
+  const inFork = fork.revisions.find((revision) => revision.content === addressedBy?.content);
+
+  return inFork === undefined
+    ? open
+    : { ...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";
+}
+
 /** Convenience for adapters: map a resolved session to the agent contract. */
-export function verdictResponse(session: ReviewSession): { allow: boolean; feedback: string } {
+export function verdictResponse(session: Thread) {
   if (!session.verdict) throw new DaemonError("pending", "session has no verdict");
+
   return { allow: verdictAllows(session.verdict.kind), feedback: session.verdict.feedback };
 }