@cueloop/daemon 0.1.0-alpha.4 → 0.1.0-alpha.40

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.
@@ -8,15 +8,22 @@
 import {
   SCHEMA_VERSION,
   feedbackForSession,
+  isAddressed,
+  isAgentNote,
+  parseBlocks,
+  registerParticipant,
+  resolveAnchor,
   verdictAllows,
   type Annotation,
   type Artifact,
+  type Identity,
   type ReviewSession,
   type Verdict,
   type VerdictKind,
   type WorkspaceKey,
 } from "@cueloop/schema";
 import { SessionStore } from "./store";
+import { HerdrTabStore, type HerdrTabHandle } from "./herdr-tab-store";
 import { DaemonError } from "./errors";
 
 export type EventName =
@@ -31,10 +38,11 @@ export interface DaemonEvent {
   sessionId: string;
 }
 
-type EventListener = (e: DaemonEvent) => void;
+type EventListener = (event: DaemonEvent) => void;
 
 export class DaemonCore {
   readonly store: SessionStore;
+  readonly herdrTabs: HerdrTabStore;
   private waiters = new Map<string, ((session: ReviewSession) => void)[]>();
   private listeners = new Set<EventListener>();
   private seq = 0;
@@ -42,6 +50,16 @@ export class DaemonCore {
   constructor(home: string) {
     this.store = new SessionStore(home);
     this.store.recover();
+    this.herdrTabs = new HerdrTabStore(home);
+  }
+
+  /** 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 {
@@ -50,12 +68,12 @@ export class DaemonCore {
   }
 
   private emit(event: EventName, sessionId: string): void {
-    for (const l of this.listeners) l({ event, sessionId });
+    for (const listener of this.listeners) listener({ event, sessionId });
   }
 
   /** 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 {
@@ -78,16 +96,21 @@ export class DaemonCore {
   }
 
   sessionGet(id: string): ReviewSession {
-    const s = this.store.get(id);
-    if (!s) throw new DaemonError("not_found", `no session ${id}`);
-    return s;
+    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>;
+  }): ReviewSession[] {
+    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;
     });
   }
@@ -98,16 +121,16 @@ export class DaemonCore {
    * 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);
+    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) => {
@@ -121,73 +144,180 @@ export class DaemonCore {
     });
   }
 
-  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,
+  ): ReviewSession {
+    const session = this.mutable(id);
+    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);
+    if (existing === -1) session.annotations.push(full);
+    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);
-    return s;
+    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);
+    const session = this.mutable(id);
+    session.annotations = session.annotations.filter((candidate) => candidate.id !== annotationId);
+    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);
+    const session = this.mutable(id);
+    if (workingCopy === undefined || workingCopy === session.artifact.content)
+      delete session.workingCopy;
+    else session.workingCopy = workingCopy;
+    this.store.upsert(session);
     this.emit("session.updated", id);
-    return s;
+    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[]): ReviewSession {
+    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;
+  }
+
+  sessionSetShareId(id: string, shareId: string): ReviewSession {
+    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 {
+    if (!this.store.delete(id)) throw new DaemonError("not_found", `no session ${id}`);
+    this.herdrTabs.delete(id);
+    this.emit("inbox.changed", id);
+  }
+
+  /**
+   * Merge a share's collaborator state back into the local session: annotations
+   * union by id with existing ones (the planner's) winning, and the participant
+   * registry union by id with the incoming identity winning (a collaborator is
+   * the authority on their own name). This is how a teammate's name reaches the
+   * planner after a pull, alongside their notes.
+   */
+  sessionMergeShared(
+    id: string,
+    incoming: { annotations: Annotation[]; participants?: Identity[] },
+  ): ReviewSession {
+    const session = this.mutable(id);
+    const known = new Set(session.annotations.map((annotation) => annotation.id));
+    for (const annotation of incoming.annotations)
+      if (!known.has(annotation.id)) session.annotations.push(annotation);
+    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()];
+    }
+    this.store.upsert(session);
+    this.emit("session.updated", id);
+    return session;
   }
 
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): ReviewSession {
-    const s = this.mutable(id);
+    const session = this.mutable(id);
     const verdict: Verdict = {
       kind: verdictKind,
       summary,
-      feedback: feedbackForSession(s, verdictKind, summary),
+      feedback: feedbackForSession(session, verdictKind, summary),
       resolvedAt: new Date().toISOString(),
     };
-    s.verdict = verdict;
-    s.status = "resolved";
-    this.store.upsert(s);
+    session.verdict = verdict;
+    session.status = "resolved";
+    this.store.upsert(session);
     const parked = this.waiters.get(id) ?? [];
     this.waiters.delete(id);
-    for (const w of parked) w(s);
+    for (const parkedWaiter of parked) parkedWaiter(session);
     this.emit("session.resolved", id);
     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[] = [],
+  ): ReviewSession {
+    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);
+    const revisionNumber = session.revisions.length + 1;
+    session.revisions.push({ revision: revisionNumber, content, submittedAt: now });
+    session.artifact = { ...session.artifact, content };
+    delete session.workingCopy;
+    session.verdict = null;
+    session.status = "pending";
+
+    const reportedIds = new Set(addressedAnnotationIds);
+    // drift assist applies to plans only: a diff revision is a whole new
+    // patch, where a vanished quote says nothing about the feedback
+    const revisedBlocks = session.artifact.type === "plan" ? 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 &&
+        resolveAnchor(annotation.anchor, revisedBlocks) === null
+      ) {
+        annotation.resolution = { revision: revisionNumber, source: "drift" };
+      }
+    }
+
+    this.store.upsert(session);
     this.emit("session.revised", id);
     this.emit("inbox.changed", id);
-    return s;
+    return session;
   }
 
   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;
+    const session = this.sessionGet(id);
+    if (session.status === "resolved")
+      throw new DaemonError("resolved", `session ${id} is already resolved`);
+    return session;
   }
 }
 

package/src/capabilities.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { asDaemonRole, roleAllowsMethod } from "./capabilities";
+
+describe("roleAllowsMethod", () => {
+  test("the owner may call every verb", () => {
+    // Assert
+    for (const method of ["session.resolve", "session.submitRevision", "session.delete"])
+      expect(roleAllowsMethod("owner", method)).toBe(true);
+  });
+
+  test("a capped role may read and annotate but not escalate", () => {
+    // Assert - allowed
+    for (const method of ["session.get", "session.list", "session.wait", "session.annotate"])
+      expect(roleAllowsMethod("agent", method)).toBe(true);
+    // Assert - denied
+    for (const method of [
+      "session.resolve",
+      "session.submitRevision",
+      "session.setWorkingCopy",
+      "session.delete",
+      "session.setShareId",
+    ])
+      expect(roleAllowsMethod("agent", method)).toBe(false);
+    expect(roleAllowsMethod("collaborator", "session.resolve")).toBe(false);
+  });
+});
+
+describe("asDaemonRole", () => {
+  test("passes owner and collaborator through and caps anything unknown to agent", () => {
+    // Assert
+    expect(asDaemonRole("owner")).toBe("owner");
+    expect(asDaemonRole("collaborator")).toBe("collaborator");
+    expect(asDaemonRole("agent")).toBe("agent");
+    expect(asDaemonRole("root")).toBe("agent");
+    expect(asDaemonRole(undefined)).toBe("agent");
+  });
+});

package/src/capabilities.ts

@@ -0,0 +1,30 @@
+/**
+ * Daemon role capabilities: which socket methods a connection may call. The
+ * owner (the local planner) may call everything; a collaborator or a review-side
+ * agent is capped to reading the session and adding annotations, so a bring-your-
+ * own agent literally cannot resolve, rewrite, cut, share, or delete (ADR 0009).
+ * This is the single source of truth the server dispatch enforces.
+ */
+
+export type DaemonRole = "owner" | "collaborator" | "agent";
+
+/** Methods a non-owner role may call: read the session and annotate, plus connection plumbing. */
+const NON_OWNER_METHODS = new Set<string>([
+  "daemon.ping",
+  "daemon.hello",
+  "events.subscribe",
+  "session.get",
+  "session.list",
+  "session.wait",
+  "session.annotate",
+]);
+
+/** Whether `role` may call `method`. The owner may call anything; others are capped to read + annotate. */
+export function roleAllowsMethod(role: DaemonRole, method: string): boolean {
+  return role === "owner" || NON_OWNER_METHODS.has(method);
+}
+
+/** Parse an untrusted role string, defaulting unknown values to the capped "agent". */
+export function asDaemonRole(value: unknown): DaemonRole {
+  return value === "owner" || value === "collaborator" ? value : "agent";
+}

package/src/client.ts

@@ -1,38 +1,85 @@
 /**
  * Daemon client: the one library every consumer shares - CLI verbs, the TUI,
- * adapters, and tests. Also owns the lazy-launch story (#14): connect() with
+ * adapters, and tests. Also owns the lazy-launch story: connect() with
  * autostart spawns a detached daemon when the socket is dead, then attaches.
  */
 
 import { existsSync, rmSync } from "node:fs";
-import type { Annotation, Artifact, ReviewSession, VerdictKind, WorkspaceKey } from "@cueloop/schema";
-import { LineBuffer, type EventFrame, type Response } from "./protocol";
+import type {
+  Annotation,
+  Artifact,
+  Identity,
+  ReviewSession,
+  VerdictKind,
+  WorkspaceKey,
+} from "@cueloop/schema";
+import { BackpressureWriter, LineBuffer, type EventFrame, type Response } from "./protocol";
+import type { DaemonRole } from "./capabilities";
+import type { HerdrTabHandle } from "./herdr-tab-store";
 import { cueloopHome, socketPath } from "./paths";
 
+export type { EventFrame } from "./protocol";
+
 export interface ConnectOptions {
   home?: string;
   /** Spawn the daemon when the socket is not alive. */
   autostart?: boolean;
+  /** Capability role for this connection; a review-side agent connects capped. Defaults to owner. */
+  role?: DaemonRole;
 }
 
-type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void };
+type PendingRequest = { resolve: (value: unknown) => void; reject: (error: Error) => void };
 
-export class DaemonClient {
+/**
+ * The session verbs the review controller drives. DaemonClient is the local
+ * implementation (unix socket); the sharing gateway supplies an in-memory,
+ * blob-backed one. Depending on this interface - not DaemonClient - is what
+ * lets the same <App> render a local session or a decrypted share unchanged.
+ */
+export interface SessionClient {
+  onEvent(listener: (event: EventFrame) => void): () => void;
+  subscribe(): Promise<void>;
+  sessionGet(id: string): Promise<ReviewSession>;
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<ReviewSession[]>;
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<ReviewSession>;
+  sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession>;
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession>;
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession>;
+  sessionSetShareId(id: string, shareId: string): Promise<ReviewSession>;
+  sessionMergeShared(
+    id: string,
+    incoming: { annotations: Annotation[]; participants?: Identity[] },
+  ): Promise<ReviewSession>;
+  sessionDelete(id: string): Promise<void>;
+  /** Record the caller's own identity name (collaborator self-naming on a share). */
+  sessionSetSelfName(id: string, name: string): Promise<ReviewSession>;
+  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession>;
+  close(): void;
+}
+
+export class DaemonClient implements SessionClient {
   private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
-  private pending = new Map<number, Pending>();
+  private writer: BackpressureWriter | null = null;
+  private pending = new Map<number, PendingRequest>();
   private nextId = 1;
-  private eventListeners = new Set<(e: EventFrame) => void>();
+  private eventListeners = new Set<(event: EventFrame) => void>();
   private closed = false;
+  private role: DaemonRole = "owner";
 
-  static async connect(opts: ConnectOptions = {}): Promise<DaemonClient> {
-    const home = opts.home ?? cueloopHome();
+  static async connect(options: ConnectOptions = {}): Promise<DaemonClient> {
+    const home = options.home ?? cueloopHome();
     const path = socketPath(home);
     const client = new DaemonClient();
+    client.role = options.role ?? "owner";
     try {
       await client.dial(path);
       return client;
     } catch (err) {
-      if (!opts.autostart) throw err;
+      if (!options.autostart) throw err;
     }
     // Socket dead or absent: clean a stale file and spawn the daemon detached.
     if (existsSync(path)) rmSync(path, { force: true });
@@ -40,47 +87,53 @@ export class DaemonClient {
     // Generous: a cold or loaded machine pays for a runtime start before the
     // socket exists, and giving up early looks to callers like a broken daemon.
     const deadline = Date.now() + Number(process.env.CUELOOP_START_TIMEOUT_MS ?? 30_000);
-    let lastErr: unknown;
+    let lastError: unknown;
     while (Date.now() < deadline) {
       try {
         await client.dial(path);
         return client;
       } catch (err) {
-        lastErr = err;
+        lastError = err;
         await Bun.sleep(50);
       }
     }
-    throw new Error(`daemon did not come up at ${path}: ${String(lastErr)}`);
+    throw new Error(`daemon did not come up at ${path}: ${String(lastError)}`);
   }
 
   private async dial(path: string): Promise<void> {
     const buffer = new LineBuffer();
-    const self = this;
     this.socket = await Bun.connect({
       unix: path,
       socket: {
-        data(_socket, data) {
-          buffer.push(data.toString(), (line) => self.handleFrame(line));
+        data: (_socket, data) => {
+          buffer.push(data.toString(), (line) => this.routeInboundFrame(line));
+        },
+        drain: () => {
+          this.writer?.drain();
         },
-        close() {
-          self.closed = true;
-          for (const p of self.pending.values()) p.reject(new Error("daemon connection closed"));
-          self.pending.clear();
+        close: () => {
+          this.closed = true;
+          for (const pendingRequest of this.pending.values())
+            pendingRequest.reject(new Error("daemon connection closed"));
+          this.pending.clear();
         },
         error() {},
       },
     });
+    this.writer = new BackpressureWriter(this.socket);
     // Verify liveness: a dead socket file accepts connects on some platforms
     // only to fail later, so a ping is the actual handshake.
     await this.request("daemon.ping", {}, 2_000);
+    // Cap this connection's role for the daemon's capability gate (owner is the default).
+    if (this.role !== "owner") await this.request("daemon.hello", { role: this.role }, 2_000);
   }
 
-  onEvent(listener: (e: EventFrame) => void): () => void {
+  onEvent(listener: (event: EventFrame) => void): () => void {
     this.eventListeners.add(listener);
     return () => this.eventListeners.delete(listener);
   }
 
-  private handleFrame(line: string): void {
+  private routeInboundFrame(line: string): void {
     let frame: Response | EventFrame;
     try {
       frame = JSON.parse(line) as Response | EventFrame;
@@ -88,14 +141,15 @@ export class DaemonClient {
       return;
     }
     if ("event" in frame) {
-      for (const l of this.eventListeners) l(frame);
+      for (const listener of this.eventListeners) listener(frame);
       return;
     }
-    const p = this.pending.get(frame.id);
-    if (!p) return;
+    const pendingRequest = this.pending.get(frame.id);
+    if (!pendingRequest) return;
     this.pending.delete(frame.id);
-    if (frame.error) p.reject(new DaemonClientError(frame.error.code, frame.error.message));
-    else p.resolve(frame.result);
+    if (frame.error)
+      pendingRequest.reject(new DaemonClientError(frame.error.code, frame.error.message));
+    else pendingRequest.resolve(frame.result);
   }
 
   request<T = unknown>(method: string, params: unknown, timeoutMs = 30_000): Promise<T> {
@@ -107,16 +161,16 @@ export class DaemonClient {
         reject(new Error(`request ${method} timed out`));
       }, timeoutMs);
       this.pending.set(id, {
-        resolve: (v) => {
+        resolve: (value) => {
           clearTimeout(timer);
-          resolve(v as T);
+          resolve(value as T);
         },
-        reject: (e) => {
+        reject: (error) => {
           clearTimeout(timer);
-          reject(e);
+          reject(error);
         },
       });
-      this.socket!.write(JSON.stringify({ id, method, params }) + "\n");
+      this.writer!.write(JSON.stringify({ id, method, params }) + "\n");
     });
   }
 
@@ -145,8 +199,12 @@ export class DaemonClient {
   sessionWait(id: string, timeoutMs: number): Promise<ReviewSession | null> {
     return this.request("session.wait", { id, timeoutMs }, timeoutMs + 10_000);
   }
-  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): Promise<ReviewSession> {
-    return this.request("session.annotate", { id, annotation });
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<ReviewSession> {
+    return this.request("session.annotate", { id, annotation, authorName });
   }
   sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession> {
     return this.request("session.removeAnnotation", { id, annotationId });
@@ -154,11 +212,41 @@ export class DaemonClient {
   sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession> {
     return this.request("session.setWorkingCopy", { id, workingCopy });
   }
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession> {
+    return this.request("session.setViewed", { id, viewedPaths });
+  }
+  sessionSetShareId(id: string, shareId: string): Promise<ReviewSession> {
+    return this.request("session.setShareId", { id, shareId });
+  }
+  sessionMergeShared(
+    id: string,
+    incoming: { annotations: Annotation[]; participants?: Identity[] },
+  ): Promise<ReviewSession> {
+    return this.request("session.mergeShared", { id, ...incoming });
+  }
+  sessionDelete(id: string): Promise<void> {
+    return this.request("session.delete", { id });
+  }
+  /** Local sessions have no collaborator self-name; the share client owns this. */
+  sessionSetSelfName(id: string, _name: string): Promise<ReviewSession> {
+    return this.sessionGet(id);
+  }
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
     return this.request("session.resolve", { id, verdictKind, summary });
   }
-  sessionSubmitRevision(id: string, content: string): Promise<ReviewSession> {
-    return this.request("session.submitRevision", { id, content });
+  sessionSubmitRevision(
+    id: string,
+    content: string,
+    addressedAnnotationIds: string[] = [],
+  ): Promise<ReviewSession> {
+    return this.request("session.submitRevision", { id, content, addressedAnnotationIds });
+  }
+  /** herdr adapter scratch: the tab opened for a review; local-only, off the SessionClient contract. */
+  herdrGetTab(id: string): Promise<HerdrTabHandle | null> {
+    return this.request("herdr.getTab", { id });
+  }
+  async herdrSetTab(id: string, handle: HerdrTabHandle): Promise<void> {
+    await this.request("herdr.setTab", { id, ...handle });
   }
   shutdown(): Promise<void> {
     return this.request("daemon.shutdown", {});