@cueloop/daemon 0.1.0-alpha.11 → 0.1.0-alpha.110

package/src/client.ts

@@ -1,171 +1,868 @@
 /**
- * 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 { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+import * as v from "valibot";
+import type {
+  Annotation,
+  Artifact,
+  DiffFileStatus,
+  DiffFileContents,
+  HunkRejection,
+  ShareLink,
+  Thread,
+  HarnessBinding,
+  Delivery,
+  PendingDelivery,
+  MessageOutcome,
+  WorkspaceKey,
+  TextCut,
+} from "@cueloop/schema";
+import {
+  BackpressureWriter,
+  LineBuffer,
+  parseInboundFrame,
+  type EventFrame,
+  type Request,
+  type Response,
+} from "./protocol";
+import type { DaemonRole } from "./capabilities";
+import type { HerdrThreadSurfaceHandle } from "./herdr-thread-surface-store";
+import type { GhosttyThreadSurfaceHandle } from "./ghostty-thread-surface-store";
+import type { SharedMerge } from "./api";
+
+export type { SharedMerge } from "./api";
+import { cueloopHome, ownerTokenPath, socketPath } from "./paths";
+import {
+  Params,
+  ThreadRecordSchema,
+  DiffFileContentsSchema,
+  HarnessBindingSchema,
+  DeliverySchema,
+  PendingDeliverySchema,
+} from "./validate";
+import type { WorkingTreeDiff } from "./working-tree";
+import { DaemonTransportError, type DaemonRequestOptions } from "./client-errors";
+export { DaemonTransportError, type DaemonRequestOptions } from "./client-errors";
+import { DAEMON_VERSION } from "./version";
+import { ThreadAgentSchema } from "./thread-agent-validation";
+import type { AgentComment, ThreadAgentState, AgentPromptRequest } from "@cueloop/schema";
+
+export type { EventFrame } from "./protocol";
 
 export interface ConnectOptions {
   home?: string;
-  /** Spawn the daemon when the socket is not alive. */
   autostart?: boolean;
+  role?: DaemonRole;
+  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.
+const PingResultSchema = v.object({
+  pid: v.number(),
+  version: v.optional(v.string()),
+  agentHarness: v.optional(v.string()),
+});
+const RefreshDiffResultSchema = v.object({ changed: v.boolean() });
+const HerdrThreadSurfaceResultSchema = v.nullable(
+  v.object({
+    tabId: v.string(),
+    paneId: v.string(),
+    mode: v.optional(v.picklist(["tab", "pane"])),
+    layout: v.optional(v.literal("pair")),
+  }),
+);
+const GhosttyThreadSurfaceResultSchema = v.nullable(v.object({ terminalId: 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 ThreadClient {
+  onEvent(listener: (event: EventFrame) => void): () => void;
+  subscribe(): Promise<void>;
+  sessionGet(id: string): Promise<Thread>;
+  sessionCreate?(workspace: WorkspaceKey, artifact: Artifact): Promise<Thread>;
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<Thread[]>;
+  sessionComment(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<Thread>;
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<Thread>;
+  sessionRemoveAnnotation(id: string, annotationId: string): Promise<Thread>;
+  sessionSetWorkingCopy(
+    id: string,
+    workingCopy: string | undefined,
+    textCuts?: TextCut[],
+  ): Promise<Thread>;
+  sessionCutBlock(id: string, blockIndex: number): Promise<Thread>;
+  sessionRestoreBlock(id: string, baseBlockIndex: number, line?: number): Promise<Thread>;
+  sessionCurate(id: string, rejections: HunkRejection[]): Promise<Thread>;
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<Thread>;
+  sessionSetTitle(id: string, title: string): Promise<Thread>;
+  agentGet?(id: string): Promise<ThreadAgentState>;
+  projectFiles?(sessionId: string): Promise<string[]>;
+  fileContents?(sessionId: string, path: string): Promise<string | null>;
+  repoFiles?(cwd: string): Promise<string[]>;
+  repoFileContents?(cwd: string, path: string): Promise<string | null>;
+  repoChanges?(cwd: string): Promise<{ path: string; status: DiffFileStatus }[]>;
+  repoDiff?(cwd: string, vcs?: string): Promise<WorkingTreeDiff>;
+  sessionRefreshDiff?(id: string): Promise<{ changed: boolean }>;
+  sessionWorkbench?(cwd: string): Promise<Thread>;
+  sessionNavigate(id: string, entryId: string, summary?: string, branch?: string): Promise<Thread>;
+  sessionBranch(id: string, name: string): Promise<Thread>;
+  sessionSwitch(id: string, branch: string): Promise<Thread>;
+  sessionLabel(id: string, label: string): Promise<Thread>;
+  sessionFork(id: string): Promise<Thread>;
+  sessionSetShares(id: string, shares: ShareLink[]): Promise<Thread>;
+  sessionMergeShared(id: string, incoming: SharedMerge): Promise<Thread>;
+  sessionDelete(id: string): Promise<void>;
+  sessionSetSelfName(id: string, name: string): Promise<Thread>;
+  sessionSendMessage(
+    id: string,
+    outcome: MessageOutcome,
+    summary: string,
+    actionBodies?: Record<string, string>,
+  ): Promise<Thread>;
+  harnessBind?(
+    threadId: string,
+    harness: string,
+    harnessSessionId: string,
+  ): Promise<HarnessBinding>;
+  harnessGetBinding?(bindingId: string): Promise<HarnessBinding>;
+  harnessBindingsForSession?(harness: string, harnessSessionId: string): Promise<HarnessBinding[]>;
+  harnessConsumeApprovedRetry?(
+    bindingId: string,
+    messageId: string,
+    content: string,
+  ): Promise<boolean>;
+  deliveryPending?(bindingId: string): Promise<PendingDelivery[]>;
+  deliveryAcknowledge?(deliveryId: string): Promise<Delivery>;
+  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;
+  clientVersion: string;
+  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}$/));
+
+/** 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;
 
-export class DaemonClient {
-  private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
-  private pending = new Map<number, Pending>();
+  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 ThreadClient {
+  private socket: { end(): void } | null = null;
+  private writer: BackpressureWriter | null = null;
+  private connectionEpoch = 0;
+  private pending = new Map<number, PendingRequest>();
+  /** The connected daemon's build version, learned from the ping handshake. */
+  private daemonVersion: string | undefined;
   private nextId = 1;
-  private eventListeners = new Set<(e: EventFrame) => void>();
+  private eventListeners = new Set<(event: EventFrame) => void>();
+  private disconnectListeners = new Set<(reason: DaemonTransportError) => void>();
+  private disconnectReason: DaemonTransportError | undefined;
   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;
+
+      if (client.daemonVersion === DAEMON_VERSION) return client;
+
+      const daemonVersion = client.daemonVersion ?? "unknown";
+
+      client.close();
+      throw new DaemonClientError(
+        "version_mismatch",
+        `daemon is version ${daemonVersion}, but this client is ${DAEMON_VERSION}; align cueloop versions before restarting the daemon`,
+      );
     } catch (err) {
-      if (!opts.autostart) throw err;
+      // Autostart repairs an unavailable socket, never a live incompatible daemon.
+      if (!options.autostart || err instanceof DaemonClientError) {
+        client.close();
+
+        throw err instanceof DaemonClientError || err instanceof DaemonTransportError
+          ? err
+          : new DaemonTransportError(
+              "connection",
+              "Daemon connection failed",
+              "not_sent",
+              undefined,
+              { cause: err },
+            );
+      }
     }
-    // Socket dead or absent: clean a stale file and spawn the daemon detached.
-    if (existsSync(path)) rmSync(path, { force: true });
-    spawnDaemon(home);
+
+    // Socket dead or absent: let the new daemon own stale socket cleanup.
+    return client.attachFreshDaemon(home, path);
+  }
+
+  /** Reset per-connection state so a fresh dial() can reuse this client instance. */
+  private resetConnection(): void {
+    this.connectionEpoch += 1;
+    this.socket = null;
+    this.writer = null;
+    this.closed = false;
+    for (const pendingRequest of this.pending.values())
+      pendingRequest.reject(
+        new DaemonTransportError("connection", "daemon connection replaced", "unknown"),
+      );
+    this.pending.clear();
+  }
+
+  /** Spawn a detached daemon and dial the lock owner until it answers. */
+  private async attachFreshDaemon(home: string, path: string): Promise<DaemonClient> {
+    const startupLogPath = 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;
-    while (Date.now() < deadline) {
-      try {
-        await client.dial(path);
-        return client;
-      } catch (err) {
-        lastErr = err;
-        await Bun.sleep(50);
+    let lastError: unknown;
+
+    try {
+      while (Date.now() < deadline) {
+        try {
+          await this.dial(path);
+
+          if (this.daemonVersion !== DAEMON_VERSION) {
+            this.close();
+
+            if (typeof Bun === "undefined") {
+              throw new DaemonClientError(
+                "version_mismatch",
+                `installed cueloop is ${this.daemonVersion ?? "unknown"}, but this adapter is ${DAEMON_VERSION}; run cueloop update`,
+              );
+            }
+
+            throw new Error("daemon autostarted an older build");
+          }
+
+          return this;
+        } catch (err) {
+          if (err instanceof DaemonClientError) throw err;
+
+          this.socket?.end();
+          this.resetConnection();
+          lastError = err;
+          await sleep(50);
+        }
       }
+      const output = readFileSync(startupLogPath, "utf8").trim();
+      const detail = output ? `\ndaemon startup output:\n${output.slice(-4_096)}` : "";
+
+      throw new DaemonTransportError(
+        "connection",
+        `Daemon startup failed at ${path}: ${String(lastError)}${detail}`,
+        "not_sent",
+      );
+    } finally {
+      rmSync(startupLogPath, { force: true });
     }
-    throw new Error(`daemon did not come up at ${path}: ${String(lastErr)}`);
   }
 
   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));
+
+    this.disconnectReason = undefined;
+    const epoch = ++this.connectionEpoch;
+
+    const close = () => {
+      if (this.connectionEpoch !== epoch) return;
+
+      this.closed = true;
+      for (const pendingRequest of this.pending.values())
+        pendingRequest.reject(
+          new DaemonTransportError("connection", "daemon connection closed", "unknown"),
+        );
+      this.pending.clear();
+      const reason =
+        this.disconnectReason ??
+        new DaemonTransportError("connection", "daemon connection closed", "unknown");
+
+      for (const listener of this.disconnectListeners) listener(reason);
+    };
+
+    if (typeof Bun !== "undefined") {
+      const socket = await Bun.connect({
+        unix: path,
+        socket: {
+          data: (_socket, data) => {
+            buffer.push(data.toString(), (line) => this.routeInboundFrame(line));
+          },
+          drain: () => this.writer?.drain(),
+          close,
+          error() {},
         },
-        close() {
-          self.closed = true;
-          for (const p of self.pending.values()) p.reject(new Error("daemon connection closed"));
-          self.pending.clear();
+      });
+
+      this.socket = socket;
+      this.writer = new BackpressureWriter(socket);
+    } else {
+      const socket = createConnection(path);
+
+      await new Promise<void>((resolve, reject) => {
+        socket.once("connect", resolve);
+        socket.once("error", reject);
+      });
+      socket.on("data", (data) => {
+        buffer.push(data.toString(), (line) => this.routeInboundFrame(line));
+      });
+      socket.on("close", close);
+      socket.on("error", () => {});
+      this.socket = socket;
+      // Node queues the complete Buffer internally when write returns false.
+      this.writer = new BackpressureWriter({
+        write(data) {
+          socket.write(data);
+
+          return data.length;
         },
-        error() {},
-      },
-    });
+      });
+    }
+
     // 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, so connect() can reject incompatible clients.
+    const pong = await this.request("daemon.ping", {}, PingResultSchema, 2_000);
+
+    this.daemonVersion = pong.version;
+    // 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, clientVersion: DAEMON_VERSION }
+        : { role: this.role, clientVersion: DAEMON_VERSION, 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", clientVersion: DAEMON_VERSION }
+      : { role: "owner", clientVersion: DAEMON_VERSION, 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;
+  /** Notify an adapter when its daemon socket closes so it can reconnect and replay Messages. */
+  onDisconnect(listener: (reason: DaemonTransportError) => void): () => void {
+    this.disconnectListeners.add(listener);
+
+    return () => this.disconnectListeners.delete(listener);
+  }
+
+  private routeInboundFrame(line: string): void {
+    let frame;
+
     try {
-      frame = JSON.parse(line) as Response | EventFrame;
-    } catch {
+      frame = parseInboundFrame(line);
+    } catch (cause) {
+      this.disconnectReason = new DaemonTransportError(
+        "protocol",
+        "daemon sent a malformed frame",
+        "unknown",
+        undefined,
+        { cause },
+      );
+      for (const pendingRequest of this.pending.values())
+        pendingRequest.reject(
+          new DaemonTransportError(
+            "protocol",
+            "daemon sent a malformed frame",
+            "unknown",
+            undefined,
+            { cause },
+          ),
+        );
+      this.pending.clear();
+      this.close();
+
       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> {
-    if (this.closed || !this.socket) return Promise.reject(new Error("not connected"));
+  request<TOutput>(
+    method: string,
+    params: Request["params"],
+    resultSchema: v.GenericSchema<unknown, TOutput>,
+    options: number | DaemonRequestOptions = 30_000,
+  ): Promise<TOutput> {
+    const { timeoutMs = 30_000, signal } = v.is(v.number(), options)
+      ? { timeoutMs: options }
+      : options;
+
+    if (signal?.aborted)
+      return Promise.reject(
+        new DaemonTransportError("cancelled", `request ${method} cancelled`, "not_sent", method),
+      );
+
+    if (this.closed || !this.socket)
+      return Promise.reject(
+        new DaemonTransportError("connection", "not connected", "not_sent", method),
+      );
+
     const id = this.nextId++;
-    return new Promise<T>((resolve, reject) => {
-      const timer = setTimeout(() => {
+
+    return new Promise<TOutput>((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
         this.pending.delete(id);
-        reject(new Error(`request ${method} timed out`));
+      };
+      const fail = (error: Error) => {
+        cleanup();
+        reject(error);
+      };
+      const abort = () =>
+        fail(
+          new DaemonTransportError("cancelled", `request ${method} cancelled`, "unknown", method),
+        );
+      const timer = setTimeout(() => {
+        fail(new DaemonTransportError("timeout", `request ${method} timed out`, "unknown", method));
       }, timeoutMs);
+
       this.pending.set(id, {
-        resolve: (v) => {
-          clearTimeout(timer);
-          resolve(v as T);
-        },
-        reject: (e) => {
-          clearTimeout(timer);
-          reject(e);
+        resolve: (value) => {
+          cleanup();
+          try {
+            const parsed = v.safeParse(resultSchema, value);
+
+            if (!parsed.success)
+              throw new DaemonTransportError(
+                "protocol",
+                `request ${method} returned an invalid result`,
+                "unknown",
+                method,
+                { cause: parsed.issues },
+              );
+
+            resolve(parsed.output);
+          } catch (cause) {
+            reject(
+              cause instanceof DaemonTransportError
+                ? cause
+                : new DaemonTransportError(
+                    "protocol",
+                    `request ${method} returned an invalid result`,
+                    "unknown",
+                    method,
+                    { cause },
+                  ),
+            );
+          }
         },
+        reject: fail,
       });
-      this.socket!.write(JSON.stringify({ id, method, params }) + "\n");
+      signal?.addEventListener("abort", abort, { once: true });
+      try {
+        this.writer!.write(JSON.stringify({ id, method, params }) + "\n");
+      } catch (cause) {
+        fail(
+          new DaemonTransportError(
+            "connection",
+            `request ${method} could not be written`,
+            "unknown",
+            method,
+            { cause },
+          ),
+        );
+      }
     });
   }
 
   close(): void {
     this.closed = true;
+    for (const pendingRequest of this.pending.values())
+      pendingRequest.reject(
+        new DaemonTransportError("connection", "daemon connection closed", "unknown"),
+      );
+    this.pending.clear();
     this.socket?.end();
   }
 
-  // ── typed verbs ─────────────────────────────
-  ping(): Promise<{ pid: number }> {
-    return this.request("daemon.ping", {});
+  // ── typed primitives ─────────────────────────────
+  /** Read the agent transcript without starting a model request. */
+  agentGet(id: string, options?: DaemonRequestOptions): Promise<ThreadAgentState> {
+    return this.request("agent.get", { id }, ThreadAgentSchema, options);
+  }
+  /** Submit a question and optional selected passage to the daemon-owned agent. */
+  agentPrompt(
+    params: AgentPromptRequest,
+    options?: DaemonRequestOptions,
+  ): Promise<ThreadAgentState> {
+    return this.request("agent.prompt", params, ThreadAgentSchema, options);
+  }
+  /** Cancel the active turn; the daemon retains partial output. */
+  agentCancel(id: string): Promise<ThreadAgentState> {
+    return this.request("agent.cancel", { id }, ThreadAgentSchema);
+  }
+  /** Save quote-primary feedback on a finalized agent answer. */
+  agentComment(params: { id: string; comment: AgentComment }): Promise<ThreadAgentState> {
+    return this.request("agent.comment", params, ThreadAgentSchema);
+  }
+  /** Configure only an option advertised by the current harness. */
+  agentConfigure(params: {
+    id: string;
+    configId?: string;
+    value?: string;
+  }): Promise<ThreadAgentState> {
+    return this.request("agent.configure", params, ThreadAgentSchema);
+  }
+
+  /** Select an option from the active agent permission card. */
+  agentPermission(params: {
+    id: string;
+    requestId: string;
+    optionId: string;
+  }): Promise<ThreadAgentState> {
+    return this.request("agent.permission", params, ThreadAgentSchema);
+  }
+  ping(): Promise<{ pid: number; agentHarness?: string }> {
+    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,
+    textCuts?: TextCut[],
+  ): Promise<Thread> {
+    return this.request(
+      "session.setWorkingCopy",
+      { id, workingCopy, textCuts },
+      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);
+  }
+  sessionRestoreBlock(id: string, baseBlockIndex: number, line?: number): Promise<Thread> {
+    return this.request(
+      "session.restoreBlock",
+      line === undefined ? { id, baseBlockIndex } : { id, baseBlockIndex, line },
+      ThreadRecordSchema,
+    );
+  }
+  sessionCurate(id: string, rejections: HunkRejection[]): Promise<Thread> {
+    return this.request("session.curate", { id, rejections }, ThreadRecordSchema);
+  }
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<Thread> {
+    return this.request("session.setViewed", { id, viewedPaths }, ThreadRecordSchema);
+  }
+  sessionSetTitle(id: string, title: string): Promise<Thread> {
+    return this.request("session.setTitle", { id, title }, ThreadRecordSchema);
+  }
+  projectFiles(sessionId: string): Promise<string[]> {
+    return this.request("session.projectFiles", { id: sessionId }, v.array(v.string()));
   }
-  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): Promise<ReviewSession> {
-    return this.request("session.annotate", { id, annotation });
+  fileContents(sessionId: string, path: string): Promise<string | null> {
+    return this.request("session.fileContents", { id: sessionId, path }, v.nullable(v.string()));
   }
-  sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession> {
-    return this.request("session.removeAnnotation", { id, annotationId });
+  repoFiles(cwd: string): Promise<string[]> {
+    return this.request("repo.files", { cwd }, v.array(v.string()));
   }
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession> {
-    return this.request("session.setWorkingCopy", { id, workingCopy });
+  repoFileContents(cwd: string, path: string): Promise<string | null> {
+    return this.request("repo.fileContents", { cwd, path }, v.nullable(v.string()));
   }
-  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
-    return this.request("session.resolve", { id, verdictKind, summary });
+  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"]) })),
+    );
   }
-  sessionSubmitRevision(id: string, content: string): Promise<ReviewSession> {
-    return this.request("session.submitRevision", { id, content });
+  repoDiff(
+    cwd: string,
+    vcs?: string,
+  ): Promise<
+    WorkingTreeDiff & { vcs?: string; source?: { changeId?: string; revisionId: string } }
+  > {
+    return this.request(
+      "repo.diff",
+      { cwd, vcs },
+      v.object({
+        patch: v.string(),
+        files: v.array(DiffFileContentsSchema),
+        vcs: v.optional(v.string()),
+        source: v.optional(v.object({ changeId: v.optional(v.string()), revisionId: v.string() })),
+      }),
+    );
+  }
+  sessionWorkbench(cwd: string): Promise<Thread> {
+    return this.request("session.workbench", { cwd }, ThreadRecordSchema);
+  }
+  /** Open a workbench with the diff snapshot used for its first frame. */
+  workbenchReview(cwd: string): Promise<{ session: Thread; diff: WorkingTreeDiff }> {
+    return this.request(
+      "session.workbenchReview",
+      { cwd },
+      v.object({
+        session: ThreadRecordSchema,
+        diff: v.object({
+          patch: v.string(),
+          files: v.array(DiffFileContentsSchema),
+          vcs: v.string(),
+          source: v.optional(
+            v.object({ changeId: v.optional(v.string()), revisionId: v.string() }),
+          ),
+        }),
+      }),
+    );
+  }
+  /** 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);
+  }
+
+  sessionSetShares(id: string, shares: ShareLink[]): Promise<Thread> {
+    return this.request("session.setShares", { id, shares }, ThreadRecordSchema);
+  }
+  sessionMergeShared(id: string, incoming: SharedMerge): Promise<Thread> {
+    return this.request("session.mergeShared", { id, ...incoming }, ThreadRecordSchema);
+  }
+  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);
+  }
+  sessionSendMessage(
+    id: string,
+    outcome: MessageOutcome,
+    summary: string,
+    actionBodies?: Record<string, string>,
+    operationId?: string,
+    options?: DaemonRequestOptions,
+  ): Promise<Thread> {
+    return this.request(
+      "session.sendMessage",
+      { id, outcome, summary, actionBodies, operationId },
+      ThreadRecordSchema,
+      options,
+    );
+  }
+  harnessBind(
+    threadId: string,
+    harness: string,
+    harnessSessionId: string,
+  ): Promise<HarnessBinding> {
+    return this.request(
+      "harness.bind",
+      { threadId, harness, harnessSessionId },
+      HarnessBindingSchema,
+    );
+  }
+  harnessGetBinding(bindingId: string): Promise<HarnessBinding> {
+    return this.request("harness.getBinding", { bindingId }, HarnessBindingSchema);
+  }
+  harnessBindingsForSession(harness: string, harnessSessionId: string): Promise<HarnessBinding[]> {
+    return this.request(
+      "harness.bindingsForSession",
+      { harness, harnessSessionId },
+      v.array(HarnessBindingSchema),
+    );
+  }
+  harnessConsumeApprovedRetry(
+    bindingId: string,
+    messageId: string,
+    content: string,
+  ): Promise<boolean> {
+    return this.request(
+      "harness.consumeApprovedRetry",
+      { bindingId, messageId, content },
+      v.boolean(),
+    );
+  }
+  deliveryPending(bindingId: string): Promise<PendingDelivery[]> {
+    return this.request("delivery.pending", { bindingId }, v.array(PendingDeliverySchema));
+  }
+  deliveryAcknowledge(deliveryId: string): Promise<Delivery> {
+    return this.request("delivery.acknowledge", { deliveryId }, DeliverySchema);
+  }
+  sessionSubmitRevision(
+    id: string,
+    content: string,
+    addressedAnnotationIds: string[] = [],
+    files?: DiffFileContents[],
+    source?: import("@cueloop/schema").DiffSource,
+  ): Promise<Thread> {
+    return this.request(
+      "session.submitRevision",
+      { id, content, addressedAnnotationIds, files, source },
+      ThreadRecordSchema,
+    );
+  }
+  /** Read Herdr's local Thread surface handle, outside the ThreadClient contract. */
+  herdrGetThreadSurface(id: string): Promise<HerdrThreadSurfaceHandle | null> {
+    return this.request("herdr.getThreadSurface", { id }, HerdrThreadSurfaceResultSchema);
+  }
+  async herdrSetThreadSurface(id: string, handle: HerdrThreadSurfaceHandle): Promise<void> {
+    await this.request("herdr.setThreadSurface", { id, ...handle }, EmptyResultSchema);
+  }
+  ghosttyGetThreadSurface(id: string): Promise<GhosttyThreadSurfaceHandle | null> {
+    return this.request("ghostty.getThreadSurface", { id }, GhosttyThreadSurfaceResultSchema);
+  }
+  async ghosttySetThreadSurface(id: string, handle: GhosttyThreadSurfaceHandle): Promise<void> {
+    await this.request("ghostty.setThreadSurface", { id, ...handle }, EmptyResultSchema);
+  }
+  ghosttyClaimThreadSurface(id: string): Promise<boolean> {
+    return this.request("ghostty.claimThreadSurface", { id }, v.boolean());
+  }
+  async ghosttyReleaseThreadSurface(id: string): Promise<void> {
+    await this.request("ghostty.releaseThreadSurface", { id }, EmptyResultSchema);
   }
   shutdown(): Promise<void> {
-    return this.request("daemon.shutdown", {});
+    return this.request("daemon.shutdown", {}, EmptyResultSchema).then(() => undefined);
   }
 }
 
 export class DaemonClientError extends Error {
+  readonly _tag = "DaemonClientError";
   constructor(
     readonly code: string,
     message: string,
@@ -174,10 +871,62 @@ export class DaemonClientError extends Error {
   }
 }
 
-function spawnDaemon(home: string): void {
-  const entry = new URL("./main.ts", import.meta.url).pathname;
-  Bun.spawn([process.execPath, "run", entry], {
-    env: { ...process.env, CUELOOP_HOME: home },
-    stdio: ["ignore", "ignore", "ignore"],
-  }).unref();
+// A compiled binary re-execs `cueloop daemon --autostart` (idle-exits like main.ts,
+// unlike the never-exiting foreground daemon); source also uses the CLI composition root. 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",
+  entry = process.env.CUELOOP_DAEMON_ENTRY,
+): string[] {
+  const compiled =
+    moduleUrl.includes("$bunfs") || moduleUrl.includes("~BUN") || moduleUrl.includes("%7EBUN");
+
+  if (compiled) return [execPath, "daemon", "--autostart"];
+
+  const mainPath = entry ?? new URL("./main.ts", moduleUrl).pathname;
+
+  const args = entry ? ["daemon", "--autostart"] : [];
+
+  return devWatch
+    ? [execPath, "--watch", "run", mainPath, ...args]
+    : [execPath, "run", mainPath, ...args];
+}
+
+function spawnDaemon(home: string): string {
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  const startupLogPath = join(
+    home,
+    `daemon-startup-${process.pid}-${randomBytes(6).toString("hex")}.log`,
+  );
+  const logFd = openSync(startupLogPath, "wx", 0o600);
+
+  try {
+    if (typeof Bun === "undefined") {
+      const child = spawn(process.env.CUELOOP_EXECUTABLE ?? "cueloop", ["daemon", "--autostart"], {
+        env: { ...process.env, CUELOOP_HOME: home },
+        stdio: ["ignore", logFd, logFd],
+        detached: true,
+      });
+
+      child.on("error", (error) => appendFileSync(startupLogPath, `${String(error)}\n`));
+      child.unref();
+    } else {
+      Bun.spawn(daemonSpawnCommand(process.execPath, import.meta.url), {
+        env: { ...process.env, CUELOOP_HOME: home },
+        stdio: ["ignore", logFd, logFd],
+      }).unref();
+    }
+  } finally {
+    closeSync(logFd);
+  }
+
+  return startupLogPath;
+}
+
+function sleep(durationMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, durationMs));
 }