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

package/src/client.ts

@@ -1,122 +1,365 @@
 /**
- * Daemon client: the one library every consumer shares - CLI verbs, the TUI,
- * adapters, and tests. Also owns the lazy-launch story (#14): connect() with
+ * Daemon client: the one library every consumer shares - CLI primitives, the TUI,
+ * 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 { cueloopHome, socketPath } from "./paths";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import * as v from "valibot";
+import type {
+  Annotation,
+  Artifact,
+  DiffFileStatus,
+  HunkRejection,
+  Thread,
+  VerdictKind,
+  WorkspaceKey,
+} from "@cueloop/schema";
+import {
+  BackpressureWriter,
+  LineBuffer,
+  parseInboundFrame,
+  type EventFrame,
+  type Request,
+  type Response,
+} from "./protocol";
+import type { DaemonRole } from "./capabilities";
+import type { HerdrTabHandle } from "./herdr-tab-store";
+import type { SharedMerge } from "./api";
+
+export type { SharedMerge } from "./api";
+import { cueloopHome, ownerTokenPath, socketPath } from "./paths";
+import { Params, ThreadRecordSchema, DiffFileContentsSchema } from "./validate";
+import type { WorkingTreeDiff } from "./working-tree";
+import { DAEMON_VERSION } from "./version";
+
+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;
+  /** The author a non-owner connection acts as; its comments, removals, and name are bound to it. */
+  author?: string;
+}
+
+type PendingRequest = {
+  resolve: (value: Response["result"]) => void;
+  reject: (error: Error) => void;
+};
+
+const EmptyResultSchema = v.object({});
+// version is optional: a daemon from before the handshake carried one reads as
+// undefined, which never equals this build - so it is treated as stale and replaced
+const PingResultSchema = v.object({ pid: v.number(), version: v.optional(v.string()) });
+const RefreshDiffResultSchema = v.object({ changed: v.boolean() });
+const HerdrTabResultSchema = v.nullable(v.object({ tabId: v.string(), paneId: v.string() }));
+
+/**
+ * The session primitives 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<Thread>;
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<Thread[]>;
+  /** Add a comment; the primary annotate method. `sessionAnnotate` is the retained alias. */
+  sessionComment(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<Thread>;
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<Thread>;
+  /** Remove a comment; a non-owner connection removes only the comments of the author it is bound to. */
+  sessionRemoveAnnotation(id: string, annotationId: string): Promise<Thread>;
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<Thread>;
+  /** Cut the `blockIndex`-th block of the working copy. */
+  sessionCutBlock(id: string, blockIndex: number): Promise<Thread>;
+  /** Re-insert the `baseBlockIndex`-th block of the submitted revision before `line` (default: the end). */
+  sessionRestoreBlock(id: string, baseBlockIndex: number, line?: number): Promise<Thread>;
+  /** Replace a diff review's reject decisions; the working copy follows. */
+  sessionCurate(id: string, rejections: HunkRejection[]): Promise<Thread>;
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<Thread>;
+  /** Rename a session's display title; an empty title restores the derived default. */
+  sessionSetTitle(id: string, title: string): Promise<Thread>;
+  /** Tracked, repo-relative file paths for the session's workspace; a client with no local repo (a share) omits it. */
+  projectFiles?(sessionId: string): Promise<string[]>;
+  /** UTF-8 contents of a repo-relative file, or null when it cannot be read safely; omitted by a client with no local repo. */
+  fileContents?(sessionId: string, path: string): Promise<string | null>;
+  /** Tracked, repo-relative paths for the git repo containing `cwd`, for the no-session welcome shell. */
+  repoFiles?(cwd: string): Promise<string[]>;
+  /** UTF-8 contents of a repo-relative file in `cwd`'s repo, or null when unreadable. */
+  repoFileContents?(cwd: string, path: string): Promise<string | null>;
+  /** Changed files (path plus git status) in the working tree at `cwd`. */
+  repoChanges?(cwd: string): Promise<{ path: string; status: DiffFileStatus }[]>;
+  /** The live working-tree diff (patch plus per-file contents) at `cwd`. */
+  repoDiff?(cwd: string): Promise<WorkingTreeDiff>;
+  /** Find-or-create the per-repo workbench thread for `cwd`, so a bare launch's first comment persists. */
+  sessionWorkbench?(cwd: string): Promise<Thread>;
+  /** Move a branch's tip (the current one, or `branch` after switching to it) back to an entry on its path; a summary records the abandoned segment. */
+  sessionNavigate(id: string, entryId: string, summary?: string, branch?: string): Promise<Thread>;
+  /** Start a branch at the current tip and switch to it. */
+  sessionBranch(id: string, name: string): Promise<Thread>;
+  sessionSwitch(id: string, branch: string): Promise<Thread>;
+  /** Name the current tip as a checkpoint. */
+  sessionLabel(id: string, label: string): Promise<Thread>;
+  /** Copy the current path into a new session; returns the fork. */
+  sessionFork(id: string): Promise<Thread>;
+  sessionSetShareId(id: string, shareId: string): 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). */
+  sessionSetSelfName(id: string, name: string): Promise<Thread>;
+  sessionResolve(
+    id: string,
+    verdictKind: VerdictKind,
+    summary: string,
+    actionBodies?: Record<string, string>,
+  ): Promise<Thread>;
+  close(): void;
+}
+
+/** What a connection says about itself: its role, the owner token when it claims ownership, the author it acts as otherwise. */
+interface HelloParams {
+  role: DaemonRole;
+  token?: string;
+  author?: string;
 }
 
-type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void };
+/** The token as the daemon writes it: 32 random bytes in hex. */
+const OwnerTokenSchema = v.pipe(v.string(), v.trim(), v.regex(/^[0-9a-f]{64}$/));
 
-export class DaemonClient {
+/** The owner token in `home`, or undefined when the daemon there never wrote one. */
+function readOwnerToken(home: string): string | undefined {
+  const path = ownerTokenPath(home);
+
+  if (!existsSync(path)) return undefined;
+  const parsed = v.safeParse(OwnerTokenSchema, readFileSync(path, "utf8"));
+
+  if (!parsed.success) {
+    throw new DaemonClientError(
+      "invalid_owner_token",
+      `${path} is not an owner token; restart the daemon to mint a fresh one`,
+    );
+  }
+
+  return parsed.output;
+}
+
+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>();
+  /** The connected daemon's build version and pid, learned from the ping handshake. */
+  private daemonVersion: string | undefined;
+  private daemonPid: number | undefined;
   private nextId = 1;
-  private eventListeners = new Set<(e: EventFrame) => void>();
+  private eventListeners = new Set<(event: EventFrame) => void>();
   private closed = false;
+  private role: DaemonRole = "owner";
+  private author: string | undefined;
+  private home = cueloopHome();
 
-  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";
+    client.author = options.author;
+    client.home = home;
     try {
       await client.dial(path);
-      return client;
+      // A daemon from an earlier build lingers after an upgrade; talking to it
+      // means new client, old behaviour. The owner replaces it so an upgrade
+      // never needs a manual restart; without autostart there is nothing to
+      // replace it with, so the caller hears exactly why.
+      if (client.daemonVersion === DAEMON_VERSION) return client;
+      if (!options.autostart) {
+        client.close();
+        throw new DaemonClientError(
+          "version_mismatch",
+          `daemon is version ${client.daemonVersion ?? "unknown"}, but this client is ${DAEMON_VERSION}; restart the daemon`,
+        );
+      }
+      await client.stopStaleDaemon(path);
     } catch (err) {
-      if (!opts.autostart) throw err;
+      // a live daemon that refused the handshake is not a dead socket: the
+      // caller hears why instead of the client replacing a running daemon
+      if (!options.autostart || err instanceof DaemonClientError) throw err;
     }
-    // Socket dead or absent: clean a stale file and spawn the daemon detached.
+    // Socket dead, absent, or just-replaced: clean a stale file and spawn detached.
+    return client.attachFreshDaemon(home, path);
+  }
+
+  /**
+   * Tear down a daemon from an earlier build so a fresh one can bind: ask it to
+   * shut down (owner-gated) or, failing that, signal its pid, then wait for it to
+   * release the socket. Best-effort - attachFreshDaemon's stale-socket and
+   * stale-lock cleanup recovers even a daemon that never ran its own teardown.
+   */
+  private async stopStaleDaemon(path: string): Promise<void> {
+    const pid = this.daemonPid;
+
+    try {
+      await this.request("daemon.shutdown", {}, EmptyResultSchema, 2_000);
+    } catch {
+      if (pid !== undefined) {
+        try {
+          process.kill(pid);
+        } catch {}
+      }
+    }
+    this.socket?.end();
+    this.resetConnection();
+    // the old daemon removes its socket in stop(); wait so the new one binds cleanly
+    const deadline = Date.now() + 5_000;
+
+    while (Date.now() < deadline && existsSync(path)) await Bun.sleep(50);
+  }
+
+  /** Reset per-connection state so a fresh dial() can reuse this client instance. */
+  private resetConnection(): void {
+    this.socket = null;
+    this.writer = null;
+    this.closed = false;
+    for (const pendingRequest of this.pending.values())
+      pendingRequest.reject(new Error("daemon connection replaced"));
+    this.pending.clear();
+  }
+
+  /** Clean any stale socket, spawn a detached daemon, and dial it until it answers. */
+  private async attachFreshDaemon(home: string, path: string): Promise<DaemonClient> {
     if (existsSync(path)) rmSync(path, { force: true });
     spawnDaemon(home);
     // 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;
+        await this.dial(path);
+
+        return this;
       } 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);
+    // only to fail later, so a ping is the actual handshake. It also carries the
+    // daemon's build version and pid, so connect() can replace a stale daemon.
+    const pong = await this.request("daemon.ping", {}, PingResultSchema, 2_000);
+
+    this.daemonVersion = pong.version;
+    this.daemonPid = pong.pid;
+    // Every connection starts as a collaborator; the owner proves itself with
+    // the token the daemon wrote into the home it serves, which only the home's
+    // user can read. A capped role just names itself.
+    await this.request("daemon.hello", this.helloParams(), EmptyResultSchema, 2_000);
+  }
+
+  private helloParams(): HelloParams {
+    if (this.role !== "owner") {
+      return this.author === undefined
+        ? { role: this.role }
+        : { role: this.role, author: this.author };
+    }
+    const token = readOwnerToken(this.home);
+
+    // a daemon from before owner tokens has no file; it still knows the bare hello
+    return token === undefined ? { role: "owner" } : { role: "owner", token };
   }
 
-  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 {
-    let frame: Response | EventFrame;
+  private routeInboundFrame(line: string): void {
+    let frame;
+
     try {
-      frame = JSON.parse(line) as Response | EventFrame;
+      frame = parseInboundFrame(line);
     } catch {
       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> {
+  request<TOutput>(
+    method: string,
+    params: Request["params"],
+    resultSchema: v.GenericSchema<unknown, TOutput>,
+    timeoutMs = 30_000,
+  ): Promise<TOutput> {
     if (this.closed || !this.socket) return Promise.reject(new Error("not connected"));
     const id = this.nextId++;
-    return new Promise<T>((resolve, reject) => {
+
+    return new Promise<TOutput>((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
         reject(new Error(`request ${method} timed out`));
       }, timeoutMs);
+
       this.pending.set(id, {
-        resolve: (v) => {
+        resolve: (value) => {
           clearTimeout(timer);
-          resolve(v as T);
+          resolve(v.parse(resultSchema, value));
         },
-        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");
     });
   }
 
@@ -125,43 +368,172 @@ export class DaemonClient {
     this.socket?.end();
   }
 
-  // ── typed verbs ─────────────────────────────
+  // ── typed primitives ─────────────────────────────
   ping(): Promise<{ pid: number }> {
-    return this.request("daemon.ping", {});
+    return this.request("daemon.ping", {}, PingResultSchema);
   }
   subscribe(): Promise<void> {
-    return this.request("events.subscribe", {});
+    return this.request("events.subscribe", {}, EmptyResultSchema).then(() => undefined);
   }
-  sessionCreate(workspace: WorkspaceKey, artifact: Artifact): Promise<ReviewSession> {
-    return this.request("session.create", { workspace, artifact });
+  sessionCreate(workspace: WorkspaceKey, artifact: Artifact): Promise<Thread> {
+    return this.request("session.create", { workspace, artifact }, ThreadRecordSchema);
   }
-  sessionGet(id: string): Promise<ReviewSession> {
-    return this.request("session.get", { id });
+  sessionGet(id: string): Promise<Thread> {
+    return this.request("session.get", { id }, ThreadRecordSchema);
   }
-  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<ReviewSession[]> {
-    return this.request("session.list", { filter });
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<Thread[]> {
+    return this.request("session.list", { filter }, v.array(ThreadRecordSchema));
   }
   /** Long-poll; null = still pending after timeoutMs (re-poll to collect). */
-  sessionWait(id: string, timeoutMs: number): Promise<ReviewSession | null> {
-    return this.request("session.wait", { id, timeoutMs }, timeoutMs + 10_000);
+  sessionWait(id: string, timeoutMs: number): Promise<Thread | null> {
+    return this.request(
+      "session.wait",
+      { id, timeoutMs },
+      v.nullable(ThreadRecordSchema),
+      timeoutMs + 10_000,
+    );
+  }
+  sessionComment(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<Thread> {
+    return this.request("session.comment", { id, annotation, authorName }, ThreadRecordSchema);
+  }
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<Thread> {
+    return this.request("session.annotate", { id, annotation, authorName }, ThreadRecordSchema);
+  }
+  sessionRemoveAnnotation(id: string, annotationId: string): Promise<Thread> {
+    return this.request("session.removeAnnotation", { id, annotationId }, ThreadRecordSchema);
+  }
+  /** Register a display name for a participant - a collaborator's or an agent's own, on a share or locally. */
+  sessionSetParticipantName(id: string, author: string, name: string): Promise<Thread> {
+    return this.request("session.setParticipantName", { id, author, name }, ThreadRecordSchema);
+  }
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<Thread> {
+    return this.request("session.setWorkingCopy", { id, workingCopy }, ThreadRecordSchema);
+  }
+  sessionCutBlock(id: string, blockIndex: number): Promise<Thread> {
+    return this.request("session.cutBlock", { id, blockIndex }, ThreadRecordSchema);
+  }
+  sessionNavigate(id: string, entryId: string, summary?: string, branch?: string): Promise<Thread> {
+    const params: v.InferInput<(typeof Params)["session.navigate"]> = { id, entryId };
+
+    if (summary !== undefined) params.summary = summary;
+    if (branch !== undefined) params.branch = branch;
+
+    return this.request("session.navigate", params, ThreadRecordSchema);
+  }
+  sessionBranch(id: string, name: string): Promise<Thread> {
+    return this.request("session.branch", { id, name }, ThreadRecordSchema);
+  }
+  sessionSwitch(id: string, branch: string): Promise<Thread> {
+    return this.request("session.switch", { id, branch }, ThreadRecordSchema);
+  }
+  sessionLabel(id: string, label: string): Promise<Thread> {
+    return this.request("session.label", { id, label }, ThreadRecordSchema);
+  }
+  sessionFork(id: string): Promise<Thread> {
+    return this.request("session.fork", { id }, ThreadRecordSchema);
   }
-  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): Promise<ReviewSession> {
-    return this.request("session.annotate", { id, annotation });
+  sessionRestoreBlock(id: string, baseBlockIndex: number, line?: number): Promise<Thread> {
+    return this.request(
+      "session.restoreBlock",
+      line === undefined ? { id, baseBlockIndex } : { id, baseBlockIndex, line },
+      ThreadRecordSchema,
+    );
   }
-  sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession> {
-    return this.request("session.removeAnnotation", { id, annotationId });
+  sessionCurate(id: string, rejections: HunkRejection[]): Promise<Thread> {
+    return this.request("session.curate", { id, rejections }, ThreadRecordSchema);
   }
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession> {
-    return this.request("session.setWorkingCopy", { id, workingCopy });
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<Thread> {
+    return this.request("session.setViewed", { id, viewedPaths }, ThreadRecordSchema);
   }
-  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
-    return this.request("session.resolve", { id, verdictKind, summary });
+  sessionSetTitle(id: string, title: string): Promise<Thread> {
+    return this.request("session.setTitle", { id, title }, ThreadRecordSchema);
   }
-  sessionSubmitRevision(id: string, content: string): Promise<ReviewSession> {
-    return this.request("session.submitRevision", { id, content });
+  projectFiles(sessionId: string): Promise<string[]> {
+    return this.request("session.projectFiles", { id: sessionId }, v.array(v.string()));
+  }
+  fileContents(sessionId: string, path: string): Promise<string | null> {
+    return this.request("session.fileContents", { id: sessionId, path }, v.nullable(v.string()));
+  }
+  repoFiles(cwd: string): Promise<string[]> {
+    return this.request("repo.files", { cwd }, v.array(v.string()));
+  }
+  repoFileContents(cwd: string, path: string): Promise<string | null> {
+    return this.request("repo.fileContents", { cwd, path }, v.nullable(v.string()));
+  }
+  repoChanges(cwd: string): Promise<{ path: string; status: DiffFileStatus }[]> {
+    return this.request(
+      "repo.changes",
+      { cwd },
+      v.array(v.object({ path: v.string(), status: v.picklist(["added", "modified", "deleted"]) })),
+    );
+  }
+  repoDiff(cwd: string): Promise<WorkingTreeDiff> {
+    return this.request(
+      "repo.diff",
+      { cwd },
+      v.object({ patch: v.string(), files: v.array(DiffFileContentsSchema) }),
+    );
+  }
+  sessionWorkbench(cwd: string): Promise<Thread> {
+    return this.request("session.workbench", { cwd }, ThreadRecordSchema);
+  }
+  /** Re-capture a diff session's working tree; changed=true when the patch moved and an event fired. */
+  sessionRefreshDiff(id: string): Promise<{ changed: boolean }> {
+    return this.request("session.refreshDiff", { id }, RefreshDiffResultSchema);
+  }
+  sessionSetShareId(id: string, shareId: string): Promise<Thread> {
+    return this.request("session.setShareId", { id, shareId }, ThreadRecordSchema);
+  }
+  sessionMergeShared(id: string, incoming: SharedMerge): Promise<Thread> {
+    return this.request("session.mergeShared", { id, ...incoming }, ThreadRecordSchema);
+  }
+  sessionDelete(id: string): Promise<void> {
+    return this.request("session.delete", { id }, EmptyResultSchema).then(() => undefined);
+  }
+  /** Local sessions have no collaborator self-name; the share client owns this. */
+  sessionSetSelfName(id: string, _name: string): Promise<Thread> {
+    return this.sessionGet(id);
+  }
+  sessionResolve(
+    id: string,
+    verdictKind: VerdictKind,
+    summary: string,
+    actionBodies?: Record<string, string>,
+  ): Promise<Thread> {
+    return this.request(
+      "session.resolve",
+      { id, verdictKind, summary, actionBodies },
+      ThreadRecordSchema,
+    );
+  }
+  sessionSubmitRevision(
+    id: string,
+    content: string,
+    addressedAnnotationIds: string[] = [],
+  ): Promise<Thread> {
+    return this.request(
+      "session.submitRevision",
+      { id, content, addressedAnnotationIds },
+      ThreadRecordSchema,
+    );
+  }
+  /** 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 }, HerdrTabResultSchema);
+  }
+  async herdrSetTab(id: string, handle: HerdrTabHandle): Promise<void> {
+    await this.request("herdr.setTab", { id, ...handle }, EmptyResultSchema);
   }
   shutdown(): Promise<void> {
-    return this.request("daemon.shutdown", {});
+    return this.request("daemon.shutdown", {}, EmptyResultSchema).then(() => undefined);
   }
 }
 
@@ -174,9 +546,27 @@ export class DaemonClientError extends Error {
   }
 }
 
+// A compiled binary re-execs `cueloop daemon --autostart` (idle-exits like main.ts,
+// unlike the never-exiting foreground daemon); from source, bun runs main.ts. In
+// dev (CUELOOP_DEV_WATCH=1, source only) it runs under --watch so daemon-code edits
+// reload the daemon without a manual restart - the version handshake only catches
+// release upgrades, not same-version source changes.
+export function daemonSpawnCommand(
+  execPath: string,
+  moduleUrl: string,
+  devWatch = process.env.CUELOOP_DEV_WATCH === "1",
+): string[] {
+  const compiled =
+    moduleUrl.includes("$bunfs") || moduleUrl.includes("~BUN") || moduleUrl.includes("%7EBUN");
+
+  if (compiled) return [execPath, "daemon", "--autostart"];
+  const mainPath = new URL("./main.ts", moduleUrl).pathname;
+
+  return devWatch ? [execPath, "--watch", "run", mainPath] : [execPath, "run", mainPath];
+}
+
 function spawnDaemon(home: string): void {
-  const entry = new URL("./main.ts", import.meta.url).pathname;
-  Bun.spawn([process.execPath, "run", entry], {
+  Bun.spawn(daemonSpawnCommand(process.execPath, import.meta.url), {
     env: { ...process.env, CUELOOP_HOME: home },
     stdio: ["ignore", "ignore", "ignore"],
   }).unref();