@cueloop/daemon 0.1.0-alpha.33 → 0.1.0-alpha.35

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.33",
+  "version": "0.1.0-alpha.35",
+  "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
+  },
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/daemon"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -10,28 +24,14 @@
     "./herdr-pane": "./src/herdr-pane.ts",
     "./share-blob": "./src/share-blob.ts"
   },
-  "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.33",
-    "valibot": "^1.4.2"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "dependencies": {
+    "@cueloop/schema": "0.1.0-alpha.35",
+    "valibot": "^1.4.2"
+  },
   "engines": {
     "bun": ">=1.3.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mmurakaru/cueloop.git",
-    "directory": "packages/daemon"
-  },
-  "homepage": "https://github.com/mmurakaru/cueloop#readme",
-  "bugs": {
-    "url": "https://github.com/mmurakaru/cueloop/issues"
-  },
-  "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits"
-}
+  }
+}

package/src/api.test.ts

@@ -79,7 +79,10 @@ describe("session lifecycle", () => {
     // Assert
     expect(resolved.verdict!.feedback).toContain("# Review: request changes");
     expect(resolved.verdict!.feedback).toContain("> carefully");
-    expect(verdictResponse(resolved)).toEqual({ allow: false, feedback: resolved.verdict!.feedback });
+    expect(verdictResponse(resolved)).toEqual({
+      allow: false,
+      feedback: resolved.verdict!.feedback,
+    });
 
     // Arrange
     const approved = core.sessionCreate({ workspace: WS, artifact: PLAN });
@@ -98,7 +101,12 @@ describe("session lifecycle", () => {
 
     // Assert
     expect(() =>
-      core.sessionAnnotate(session.id, { id: "a1", kind: "comment", anchor: { quote: "x", prefix: "", suffix: "" }, body: "b" }),
+      core.sessionAnnotate(session.id, {
+        id: "a1",
+        kind: "comment",
+        anchor: { quote: "x", prefix: "", suffix: "" },
+        body: "b",
+      }),
     ).toThrow("already resolved");
   });
 
@@ -166,7 +174,12 @@ describe("session lifecycle", () => {
 
 describe("revision marks addressed annotations", () => {
   const annotate = (sessionId: string, id: string, quote: string, body = "note") =>
-    core.sessionAnnotate(sessionId, { id, kind: "comment", anchor: { quote, prefix: "", suffix: "" }, body });
+    core.sessionAnnotate(sessionId, {
+      id,
+      kind: "comment",
+      anchor: { quote, prefix: "", suffix: "" },
+      body,
+    });
 
   test("ids the agent reports are marked addressed by that revision", () => {
     // Arrange
@@ -190,10 +203,16 @@ describe("revision marks addressed annotations", () => {
     annotate(session.id, "kept", "Context");
 
     // Act: the revision rewrites the "carefully" sentence but keeps the Context heading
-    const revised = core.sessionSubmitRevision(session.id, "# Plan\n\n## Context\n\nDo the thing with tests.\n");
+    const revised = core.sessionSubmitRevision(
+      session.id,
+      "# Plan\n\n## Context\n\nDo the thing with tests.\n",
+    );
 
     // Assert
-    expect(revised.annotations.find((a) => a.id === "gone")!.resolution).toEqual({ revision: 2, source: "drift" });
+    expect(revised.annotations.find((a) => a.id === "gone")!.resolution).toEqual({
+      revision: 2,
+      source: "drift",
+    });
     expect(revised.annotations.find((a) => a.id === "kept")!.resolution).toBeUndefined();
   });
 
@@ -326,10 +345,21 @@ describe("events", () => {
 
     // Act
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    core.sessionAnnotate(session.id, { id: "a1", kind: "comment", anchor: { quote: "thing", prefix: "", suffix: "" }, body: "b" });
+    core.sessionAnnotate(session.id, {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "thing", prefix: "", suffix: "" },
+      body: "b",
+    });
     core.sessionResolve(session.id, "approve", "");
 
     // Assert
-    expect(seen).toEqual(["session.created", "inbox.changed", "session.updated", "session.resolved", "inbox.changed"]);
+    expect(seen).toEqual([
+      "session.created",
+      "inbox.changed",
+      "session.updated",
+      "session.resolved",
+      "inbox.changed",
+    ]);
   });
 });

package/src/api.ts

@@ -88,11 +88,16 @@ export class DaemonCore {
     return session;
   }
 
-  sessionList(filter?: { status?: "pending" | "resolved"; workspace?: Partial<WorkspaceKey> }): ReviewSession[] {
+  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;
+      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;
     });
   }
@@ -131,7 +136,11 @@ export class DaemonCore {
     const existing = session.annotations.findIndex((candidate) => candidate.id === annotation.id);
     const full: Annotation = { ...annotation, createdAt: new Date().toISOString() };
     if (existing === -1) session.annotations.push(full);
-    else session.annotations[existing] = { ...full, createdAt: session.annotations[existing]!.createdAt };
+    else
+      session.annotations[existing] = {
+        ...full,
+        createdAt: session.annotations[existing]!.createdAt,
+      };
     this.store.upsert(session);
     this.emit("session.updated", id);
     return session;
@@ -148,7 +157,8 @@ export class DaemonCore {
   /** The reviewer's working copy; undefined clears it (revert all edits). */
   sessionSetWorkingCopy(id: string, workingCopy: string | undefined): ReviewSession {
     const session = this.mutable(id);
-    if (workingCopy === undefined || workingCopy === session.artifact.content) delete session.workingCopy;
+    if (workingCopy === undefined || workingCopy === session.artifact.content)
+      delete session.workingCopy;
     else session.workingCopy = workingCopy;
     this.store.upsert(session);
     this.emit("session.updated", id);
@@ -190,12 +200,18 @@ export class DaemonCore {
    * 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 {
+  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);
+    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]));
+      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()];
     }
@@ -233,7 +249,11 @@ export class DaemonCore {
    * 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 {
+  sessionSubmitRevision(
+    id: string,
+    content: string,
+    addressedAnnotationIds: string[] = [],
+  ): ReviewSession {
     const session = this.sessionGet(id);
     const now = new Date().toISOString();
     const revisionNumber = session.revisions.length + 1;
@@ -251,7 +271,10 @@ export class DaemonCore {
       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) {
+      } else if (
+        revisedBlocks !== null &&
+        resolveAnchor(annotation.anchor, revisedBlocks) === null
+      ) {
         annotation.resolution = { revision: revisionNumber, source: "drift" };
       }
     }
@@ -264,7 +287,8 @@ export class DaemonCore {
 
   private mutable(id: string): ReviewSession {
     const session = this.sessionGet(id);
-    if (session.status === "resolved") throw new DaemonError("resolved", `session ${id} is already resolved`);
+    if (session.status === "resolved")
+      throw new DaemonError("resolved", `session ${id} is already resolved`);
     return session;
   }
 }

package/src/client.ts

@@ -5,7 +5,14 @@
  */
 
 import { existsSync, rmSync } from "node:fs";
-import type { Annotation, Artifact, Identity, ReviewSession, VerdictKind, WorkspaceKey } from "@cueloop/schema";
+import type {
+  Annotation,
+  Artifact,
+  Identity,
+  ReviewSession,
+  VerdictKind,
+  WorkspaceKey,
+} from "@cueloop/schema";
 import { BackpressureWriter, LineBuffer, type EventFrame, type Response } from "./protocol";
 import { cueloopHome, socketPath } from "./paths";
 
@@ -35,7 +42,10 @@ export interface SessionClient {
   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>;
+  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>;
@@ -82,20 +92,20 @@ export class DaemonClient implements SessionClient {
 
   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.routeInboundFrame(line));
+        data: (_socket, data) => {
+          buffer.push(data.toString(), (line) => this.routeInboundFrame(line));
         },
-        drain() {
-          self.writer?.drain();
+        drain: () => {
+          this.writer?.drain();
         },
-        close() {
-          self.closed = true;
-          for (const pendingRequest of self.pending.values()) pendingRequest.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() {},
       },
@@ -125,7 +135,8 @@ export class DaemonClient implements SessionClient {
     const pendingRequest = this.pending.get(frame.id);
     if (!pendingRequest) return;
     this.pending.delete(frame.id);
-    if (frame.error) pendingRequest.reject(new DaemonClientError(frame.error.code, frame.error.message));
+    if (frame.error)
+      pendingRequest.reject(new DaemonClientError(frame.error.code, frame.error.message));
     else pendingRequest.resolve(frame.result);
   }
 
@@ -191,7 +202,10 @@ export class DaemonClient implements SessionClient {
   sessionSetShareId(id: string, shareId: string): Promise<ReviewSession> {
     return this.request("session.setShareId", { id, shareId });
   }
-  sessionMergeShared(id: string, incoming: { annotations: Annotation[]; participants?: Identity[] }): Promise<ReviewSession> {
+  sessionMergeShared(
+    id: string,
+    incoming: { annotations: Annotation[]; participants?: Identity[] },
+  ): Promise<ReviewSession> {
     return this.request("session.mergeShared", { id, ...incoming });
   }
   sessionDelete(id: string): Promise<void> {
@@ -204,7 +218,11 @@ export class DaemonClient implements SessionClient {
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
     return this.request("session.resolve", { id, verdictKind, summary });
   }
-  sessionSubmitRevision(id: string, content: string, addressedAnnotationIds: string[] = []): Promise<ReviewSession> {
+  sessionSubmitRevision(
+    id: string,
+    content: string,
+    addressedAnnotationIds: string[] = [],
+  ): Promise<ReviewSession> {
     return this.request("session.submitRevision", { id, content, addressedAnnotationIds });
   }
   shutdown(): Promise<void> {

package/src/herdr-pane.test.ts

@@ -54,7 +54,12 @@ describe("openHerdrPane", () => {
     const stub = makeStub("open");
 
     // Act
-    const ok = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath: stub.binPath, label: "Rollout Plan" });
+    const ok = openHerdrPane({
+      sessionId: "ses_abc",
+      cwd: "/repo/work",
+      binPath: stub.binPath,
+      label: "Rollout Plan",
+    });
 
     // Assert
     expect(ok).toBeTrue();
@@ -82,7 +87,10 @@ describe("openHerdrPane", () => {
     // Arrange
     const logPath = join(dir, "nopane.log");
     const binPath = join(dir, "nopane.sh");
-    writeFileSync(binPath, `#!/bin/sh\nprintf '%s\\n' "$*" >> "${logPath}"\nprintf '{"result":{}}'\n`);
+    writeFileSync(
+      binPath,
+      `#!/bin/sh\nprintf '%s\\n' "$*" >> "${logPath}"\nprintf '{"result":{}}'\n`,
+    );
     chmodSync(binPath, 0o755);
 
     // Act

package/src/herdr-pane.ts

@@ -47,13 +47,18 @@ export interface OpenHerdrPaneOptions {
 export function openHerdrPane(options: OpenHerdrPaneOptions): boolean {
   const { sessionId, cwd, binPath, label } = options;
   try {
-    const created = Bun.spawnSync([binPath, "tab", "create", "--cwd", cwd, "--label", label, "--focus"], {
-      stdout: "pipe",
-      stderr: "ignore",
-      timeout: HERDR_SPAWN_TIMEOUT_MS,
-    });
+    const created = Bun.spawnSync(
+      [binPath, "tab", "create", "--cwd", cwd, "--label", label, "--focus"],
+      {
+        stdout: "pipe",
+        stderr: "ignore",
+        timeout: HERDR_SPAWN_TIMEOUT_MS,
+      },
+    );
     if (created.exitCode !== 0) return false;
-    const parsed = JSON.parse(created.stdout.toString()) as { result?: { root_pane?: { pane_id?: string } } };
+    const parsed = JSON.parse(created.stdout.toString()) as {
+      result?: { root_pane?: { pane_id?: string } };
+    };
     const paneId = parsed.result?.root_pane?.pane_id;
     if (!paneId) return false;
     // A fresh tab hosts a plain shell, so the review is typed in like a human.

package/src/main.ts

@@ -2,7 +2,9 @@
 
 import { DaemonServer } from "./server";
 
-const idleExitMs = process.env.CUELOOP_IDLE_EXIT_MS ? Number(process.env.CUELOOP_IDLE_EXIT_MS) : undefined;
+const idleExitMs = process.env.CUELOOP_IDLE_EXIT_MS
+  ? Number(process.env.CUELOOP_IDLE_EXIT_MS)
+  : undefined;
 const server = new DaemonServer({ idleExitMs });
 const path = server.start();
 if (path === null) {

package/src/review.test.ts

@@ -7,7 +7,7 @@ import { join } from "node:path";
 import type { ReviewSession } from "@cueloop/schema";
 import { DaemonServer } from "./server";
 import { DaemonClient } from "./client";
-import { openReview, resolveWorkspace } from "./review";
+import { awaitResolve, openReview, resolveWorkspace } from "./review";
 
 const PLAN = "# Rollout Plan\n\nShip it in two stages.\n";
 
@@ -66,7 +66,12 @@ describe("resolveWorkspace", () => {
 describe("openReview", () => {
   test("shapes the artifact: agent, derived title, cwd", async () => {
     // Act
-    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home, agent: "test-agent" });
+    const review = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      agent: "test-agent",
+    });
 
     // Assert
     const session = review.session;
@@ -80,13 +85,22 @@ describe("openReview", () => {
 
   test("an explicit title wins; diffs never derive one from content", async () => {
     // Act
-    const titled = await openReview(client, { type: "plan", content: PLAN, cwd: home, title: "Custom" });
+    const titled = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      title: "Custom",
+    });
 
     // Assert
     expect(titled.session.artifact.meta.title).toBe("Custom");
 
     // Act
-    const diff = await openReview(client, { type: "diff", content: "# not a heading\n", cwd: home });
+    const diff = await openReview(client, {
+      type: "diff",
+      content: "# not a heading\n",
+      cwd: home,
+    });
 
     // Assert
     expect(diff.session.artifact.meta.title).toBeUndefined();
@@ -97,7 +111,12 @@ describe("openReview", () => {
     const ws = { repoRoot: "/elsewhere", branch: "feature" };
 
     // Act
-    const review = await openReview(client, { type: "diff", content: "d", cwd: home, workspace: ws });
+    const review = await openReview(client, {
+      type: "diff",
+      content: "d",
+      cwd: home,
+      workspace: ws,
+    });
 
     // Assert
     expect(review.session.workspace).toEqual(ws);
@@ -105,7 +124,12 @@ describe("openReview", () => {
 
   test("the same agentSessionId revises instead of opening a new session", async () => {
     // Arrange
-    const first = await openReview(client, { type: "plan", content: PLAN, cwd: home, agentSessionId: "agent-1" });
+    const first = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      agentSessionId: "agent-1",
+    });
 
     // Act
     const second = await openReview(client, {
@@ -121,7 +145,12 @@ describe("openReview", () => {
     expect(second.session.status).toBe("pending");
 
     // Act
-    const other = await openReview(client, { type: "plan", content: PLAN, cwd: home, agentSessionId: "agent-2" });
+    const other = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      agentSessionId: "agent-2",
+    });
 
     // Assert
     expect(other.id).not.toBe(first.id);
@@ -206,7 +235,8 @@ describe("awaitVerdict: chunked loop (the pi shape)", () => {
 
     // Assert
     // give the loop a chunk to observe the annotation before resolving
-    for (let i = 0; i < 100 && !seen.some((snapshot) => snapshot.annotations.length === 1); i++) await Bun.sleep(20);
+    for (let i = 0; i < 100 && !seen.some((snapshot) => snapshot.annotations.length === 1); i++)
+      await Bun.sleep(20);
     expect(seen.some((snapshot) => snapshot.annotations.length === 1)).toBe(true);
 
     // Act
@@ -223,7 +253,11 @@ describe("awaitVerdict: chunked loop (the pi shape)", () => {
     // Arrange
     const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
     const controller = new AbortController();
-    const waiting = review.awaitVerdict({ timeoutMs: Infinity, pollMs: 100, signal: controller.signal });
+    const waiting = review.awaitVerdict({
+      timeoutMs: Infinity,
+      pollMs: 100,
+      signal: controller.signal,
+    });
 
     // Act
     controller.abort();
@@ -241,3 +275,88 @@ describe("awaitVerdict: chunked loop (the pi shape)", () => {
     expect(await review.awaitVerdict({ timeoutMs: 120, pollMs: 50 })).toBe("pending");
   });
 });
+
+describe("awaitResolve: the adapter wake seam (session id only)", () => {
+  test("resolves to the outcome when the verdict lands during the wait", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const waiting = awaitResolve(client, review.id, { pollMs: 100 });
+
+    // Act
+    await client.sessionResolve(review.id, "approve", "Ship it.");
+    const verdict = await waiting;
+
+    // Assert
+    expect(verdict).not.toBeNull();
+    expect(verdict!.allow).toBe(true);
+    expect(verdict!.feedback).toContain("Ship it.");
+    expect(verdict!.session.verdict!.kind).toBe("approve");
+  });
+
+  test("returns the stored verdict immediately when the session already resolved", async () => {
+    // Arrange - a detached waiter that only attaches after the human decided
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    await client.sessionResolve(review.id, "request_changes", "One stage only.");
+
+    // Act
+    const verdict = await awaitResolve(client, review.id);
+
+    // Assert
+    expect(verdict).not.toBeNull();
+    expect(verdict!.allow).toBe(false);
+    expect(verdict!.feedback).toContain("One stage only.");
+  });
+
+  test("returns null when the signal aborts first", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const controller = new AbortController();
+    const waiting = awaitResolve(client, review.id, { pollMs: 100, signal: controller.signal });
+
+    // Act
+    controller.abort();
+
+    // Assert
+    expect(await waiting).toBeNull();
+    expect((await client.sessionGet(review.id)).status).toBe("pending");
+  });
+});
+
+describe("awaitResolve: the held wait keeps the daemon alive", () => {
+  test("a pending session does not idle-exit while a waiter is parked, then the verdict lands", async () => {
+    // Arrange - a daemon with an aggressive idle timer and its own home
+    const idleHome = mkdtempSync(join(tmpdir(), "cueloop-idle-"));
+    let idleExits = 0;
+    const idleServer = new DaemonServer({
+      home: idleHome,
+      idleExitMs: 30,
+      onIdleExit: () => idleExits++,
+    });
+    idleServer.start();
+    const waiterClient = await DaemonClient.connect({ home: idleHome });
+    try {
+      const review = await openReview(waiterClient, { type: "plan", content: PLAN, cwd: idleHome });
+      const waiting = awaitResolve(waiterClient, review.id, { pollMs: 40 });
+
+      // Act - wait well past the idle window while the review is still pending
+      await Bun.sleep(120);
+
+      // Assert - the parked waiter and the pending session both keep it alive
+      expect(idleExits).toBe(0);
+      expect((await waiterClient.ping()).pid).toBe(process.pid);
+
+      // Act - the human returns a verdict; the parked wait collects it
+      const resolver = await DaemonClient.connect({ home: idleHome });
+      await resolver.sessionResolve(review.id, "approve", "Good to go.");
+      resolver.close();
+      const verdict = await waiting;
+
+      // Assert
+      expect(verdict!.allow).toBe(true);
+    } finally {
+      waiterClient.close();
+      idleServer.stop();
+      rmSync(idleHome, { recursive: true, force: true });
+    }
+  }, 15_000);
+});

package/src/review.ts

@@ -7,7 +7,13 @@
  * serializing the decision in its host's contract.
  */
 
-import { newAnnotationId, type ArtifactType, type ReviewSession, type WorkspaceKey } from "@cueloop/schema";
+import {
+  newAnnotationId,
+  type ArtifactType,
+  type DiffFileContents,
+  type ReviewSession,
+  type WorkspaceKey,
+} from "@cueloop/schema";
 import { verdictResponse } from "./api";
 import type { DaemonClient } from "./client";
 
@@ -51,6 +57,11 @@ export interface OpenReviewOptions {
   planPath?: string;
   pr?: string;
   herdrPane?: string;
+  /**
+   * Full file contents per changed file for a working-tree diff, carried onto
+   * the artifact so hunk curation produces an exactly applyable patch.
+   */
+  files?: DiffFileContents[];
   /** Defaults to the plan's first markdown heading; diffs get no derived title. */
   title?: string;
   /**
@@ -69,7 +80,11 @@ export interface ReviewNote {
 }
 
 /** Anchor a note at its file: quote = the path, no context selectors. */
-async function attachNotes(client: DaemonClient, sessionId: string, notes: ReviewNote[]): Promise<void> {
+async function attachNotes(
+  client: DaemonClient,
+  sessionId: string,
+  notes: ReviewNote[],
+): Promise<void> {
   for (const note of notes) {
     await client.sessionAnnotate(sessionId, {
       id: newAnnotationId(),
@@ -100,7 +115,10 @@ export interface VerdictOutcome {
 /** Sentinel distinguishing an abort from any daemon response. */
 const ABORTED = Symbol("aborted");
 
-function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof ABORTED> {
+function raceAbort<T>(
+  promise: Promise<T>,
+  signal: AbortSignal | undefined,
+): Promise<T | typeof ABORTED> {
   if (!signal) return promise;
   if (signal.aborted) {
     promise.catch(() => {});
@@ -169,8 +187,44 @@ function outcome(session: ReviewSession): VerdictOutcome {
   return { ...verdictResponse(session), session };
 }
 
+export interface AwaitResolveOptions {
+  /** Long-poll chunk length; the wait re-arms each chunk until resolved or aborted. Default 30s. */
+  pollMs?: number;
+  /** Abort the wait (the harness session shut down); resolves to null. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Park until a review session resolves, then return the verdict outcome; null
+ * when the signal aborts first. Where ReviewHandle.awaitVerdict needs the handle
+ * that opened the review, this needs only a session id - so a background waiter
+ * that woke on a session it did not open (a detached Claude Code / Codex waiter,
+ * or pi's session_start listener) can collect the same verdict. This is the
+ * wake seam every non-blocking adapter builds on. Loops the daemon long-poll, so
+ * a verdict that lands between chunks is never missed and a session already
+ * resolved returns on the first chunk. The held connection also keeps the daemon
+ * off its idle-exit path for the whole wait.
+ */
+export async function awaitResolve(
+  client: DaemonClient,
+  sessionId: string,
+  options: AwaitResolveOptions = {},
+): Promise<VerdictOutcome | null> {
+  const chunkMs = options.pollMs ?? 30_000;
+  const { signal } = options;
+  for (;;) {
+    if (signal?.aborted) return null;
+    const resolved = await raceAbort(client.sessionWait(sessionId, chunkMs), signal);
+    if (resolved === ABORTED) return null;
+    if (resolved !== null) return outcome(resolved);
+  }
+}
+
 /** Open a review session (or revise the agent session's existing one) and hand back the wait surface. */
-export async function openReview(client: DaemonClient, options: OpenReviewOptions): Promise<ReviewHandle> {
+export async function openReview(
+  client: DaemonClient,
+  options: OpenReviewOptions,
+): Promise<ReviewHandle> {
   const cwd = options.cwd ?? process.cwd();
   const workspace = options.workspace ?? (await resolveWorkspace(cwd));
   // Resubmits from the same agent session become revisions, not new sessions.
@@ -190,6 +244,7 @@ export async function openReview(client: DaemonClient, options: OpenReviewOption
   let session = await client.sessionCreate(workspace, {
     type: options.type,
     content: options.content,
+    files: options.files,
     meta: {
       agent: options.agent,
       agentSessionId: options.agentSessionId,

package/src/server.test.ts

@@ -132,8 +132,21 @@ describe("socket round-trip", () => {
     // When a pull merges an update to the known id, a new collaborator note, and the collaborator's identity
     const merged = await client.sessionMergeShared(session.id, {
       annotations: [
-        { id: "a1", kind: "comment", anchor, body: "should not overwrite", createdAt: "2026-01-01T00:00:00.000Z" },
-        { id: "a2", kind: "comment", anchor, body: "theirs", author: "SHA256:mate", createdAt: "2026-01-01T00:00:00.000Z" },
+        {
+          id: "a1",
+          kind: "comment",
+          anchor,
+          body: "should not overwrite",
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+        {
+          id: "a2",
+          kind: "comment",
+          anchor,
+          body: "theirs",
+          author: "SHA256:mate",
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
       ],
       participants: [{ id: "SHA256:mate", provider: "ssh", name: "Sam" }],
     });
@@ -141,7 +154,9 @@ describe("socket round-trip", () => {
     // Then notes union by id (existing a1 kept), and the participant registry carries the collaborator's name
     expect(merged.annotations.map((annotation) => annotation.id).sort()).toEqual(["a1", "a2"]);
     expect(merged.annotations.find((annotation) => annotation.id === "a1")!.body).toBe("mine");
-    expect(merged.annotations.find((annotation) => annotation.id === "a2")!.author).toBe("SHA256:mate");
+    expect(merged.annotations.find((annotation) => annotation.id === "a2")!.author).toBe(
+      "SHA256:mate",
+    );
     expect(merged.participants).toEqual([{ id: "SHA256:mate", provider: "ssh", name: "Sam" }]);
   });
 
@@ -196,7 +211,8 @@ describe("large payloads survive socket backpressure", () => {
     // mid-line because the write return value was ignored, so the client
     // never saw the frame's newline and every later request wedged too.
     // Arrange
-    const bigContent = "# Big plan\n" + "lorem ipsum dolor sit amet, consectetur adipiscing elit\n".repeat(4000);
+    const bigContent =
+      "# Big plan\n" + "lorem ipsum dolor sit amet, consectetur adipiscing elit\n".repeat(4000);
 
     // Act
     const created = await client.sessionCreate(

package/src/server.ts

@@ -4,7 +4,16 @@
  * permissions are the local auth: the socket and state dir are 0700/0600.
  */
 
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { DaemonCore, type DaemonEvent } from "./api";
 import { DaemonError } from "./errors";
 import { isKnownMethod, parseParams } from "./validate";
@@ -118,20 +127,23 @@ export class DaemonServer {
     // safe now: holding the lock means no live daemon owns this home, so any
     // socket file left behind is stale
     if (existsSync(path)) rmSync(path, { force: true });
-    const self = this;
-    this.server = Bun.listen<{ buffer: LineBuffer; connection: Connection; writer: BackpressureWriter }>({
+    this.server = Bun.listen<{
+      buffer: LineBuffer;
+      connection: Connection;
+      writer: BackpressureWriter;
+    }>({
       unix: path,
       socket: {
-        open(socket) {
+        open: (socket) => {
           const writer = new BackpressureWriter(socket);
           const connection: Connection = { write: (data) => writer.write(data), subscribed: false };
           socket.data = { buffer: new LineBuffer(), connection, writer };
-          self.connections.add(connection);
-          self.scheduleIdleCheck();
+          this.connections.add(connection);
+          this.scheduleIdleCheck();
         },
-        data(socket, data) {
+        data: (socket, data) => {
           socket.data.buffer.push(data.toString(), (line) => {
-            void self.respondToRequestLine(socket.data.connection, line);
+            void this.respondToRequestLine(socket.data.connection, line);
           });
         },
         drain(socket) {
@@ -139,9 +151,9 @@ export class DaemonServer {
           // a throw here would take the whole daemon down with the socket
           socket.data?.writer.drain();
         },
-        close(socket) {
-          self.connections.delete(socket.data.connection);
-          self.scheduleIdleCheck();
+        close: (socket) => {
+          this.connections.delete(socket.data.connection);
+          this.scheduleIdleCheck();
         },
         error() {},
       },
@@ -186,7 +198,10 @@ export class DaemonServer {
     try {
       request = JSON.parse(line) as Request;
     } catch {
-      connection.write(JSON.stringify({ id: -1, error: { code: "bad_json", message: "unparseable request" } }) + "\n");
+      connection.write(
+        JSON.stringify({ id: -1, error: { code: "bad_json", message: "unparseable request" } }) +
+          "\n",
+      );
       return;
     }
     try {
@@ -255,7 +270,10 @@ export class DaemonServer {
       }
       case "session.mergeShared": {
         const params = parseParams("session.mergeShared", request.params);
-        return core.sessionMergeShared(params.id, { annotations: params.annotations, participants: params.participants });
+        return core.sessionMergeShared(params.id, {
+          annotations: params.annotations,
+          participants: params.participants,
+        });
       }
       case "session.resolve": {
         const params = parseParams("session.resolve", request.params);

package/src/share-blob.ts

@@ -34,7 +34,10 @@ export function unpackSessionBlob(bytes: Uint8Array): ReviewSession {
   try {
     json = gunzipSync(bytes, { maxOutputLength: MAX_BLOB_BYTES }).toString("utf8");
   } catch (err) {
-    throw new Error(`blob is not valid gzip or exceeds ${MAX_BLOB_BYTES} bytes: ${err instanceof Error ? err.message : String(err)}`);
+    throw new Error(
+      `blob is not valid gzip or exceeds ${MAX_BLOB_BYTES} bytes: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
   }
   let raw: unknown;
   try {

package/src/store.ts

@@ -49,7 +49,9 @@ export class SessionStore {
   }
 
   list(): ReviewSession[] {
-    return [...this.sessions.values()].sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    return [...this.sessions.values()].sort((left, right) =>
+      left.createdAt.localeCompare(right.createdAt),
+    );
   }
 
   upsert(session: ReviewSession): void {

package/src/validate.test.ts

@@ -77,12 +77,16 @@ describe("parseParams", () => {
   test("defaults and clamps the wait timeout", () => {
     expect(parseParams("session.wait", { id: "ses_1" }).timeoutMs).toBe(60_000);
     expect(() => parseParams("session.wait", { id: "ses_1", timeoutMs: -5 })).toThrow();
-    expect(() => parseParams("session.wait", { id: "ses_1", timeoutMs: 99 * 60 * 60 * 1000 })).toThrow();
+    expect(() =>
+      parseParams("session.wait", { id: "ses_1", timeoutMs: 99 * 60 * 60 * 1000 }),
+    ).toThrow();
   });
 
   test("verdict kinds are closed", () => {
     expect(parseParams("session.resolve", { id: "s", verdictKind: "approve" }).summary).toBe("");
-    expect(() => parseParams("session.resolve", { id: "s", verdictKind: "lgtm" })).toThrow(/verdictKind/);
+    expect(() => parseParams("session.resolve", { id: "s", verdictKind: "lgtm" })).toThrow(
+      /verdictKind/,
+    );
   });
 
   test("annotation kinds stay open (extension kinds are allowed)", () => {
@@ -98,12 +102,14 @@ describe("parseParams", () => {
   });
 
   test("setViewed takes a full path list and rejects non-string entries", () => {
-    expect(parseParams("session.setViewed", { id: "s", viewedPaths: ["src/a.ts", "src/b.ts"] }).viewedPaths).toEqual([
-      "src/a.ts",
-      "src/b.ts",
-    ]);
+    expect(
+      parseParams("session.setViewed", { id: "s", viewedPaths: ["src/a.ts", "src/b.ts"] })
+        .viewedPaths,
+    ).toEqual(["src/a.ts", "src/b.ts"]);
     expect(parseParams("session.setViewed", { id: "s", viewedPaths: [] }).viewedPaths).toEqual([]);
-    expect(() => parseParams("session.setViewed", { id: "s", viewedPaths: [1] })).toThrow(/viewedPaths/);
+    expect(() => parseParams("session.setViewed", { id: "s", viewedPaths: [1] })).toThrow(
+      /viewedPaths/,
+    );
     expect(() => parseParams("session.setViewed", { id: "s" })).toThrow(/viewedPaths/);
   });
 
@@ -166,7 +172,14 @@ describe("wire pins", () => {
     herdrPane: "%7",
     title: "Plan",
   };
-  const fullAnchor: Required<Anchor> = { quote: "q", prefix: "p", suffix: "s", blockIndex: 0, start: 0, end: 1 };
+  const fullAnchor: Required<Anchor> = {
+    quote: "q",
+    prefix: "p",
+    suffix: "s",
+    blockIndex: 0,
+    start: 0,
+    end: 1,
+  };
   const fullAnnotation: Required<Annotation> = {
     id: "a1",
     kind: "comment",
@@ -177,11 +190,26 @@ describe("wire pins", () => {
     resolution: { revision: 2, source: "agent" },
     createdAt: "now",
   };
-  const fullArtifact: Required<Artifact> = { type: "plan", content: "# P", meta: fullMeta };
-  const fullVerdict: Required<Verdict> = { kind: "approve", summary: "", feedback: "", resolvedAt: "now" };
+  const fullArtifact: Required<Artifact> = {
+    type: "plan",
+    content: "# P",
+    meta: fullMeta,
+    files: [{ path: "src/a.ts", oldContents: "old\n", newContents: "new\n", status: "modified" }],
+  };
+  const fullVerdict: Required<Verdict> = {
+    kind: "approve",
+    summary: "",
+    feedback: "",
+    resolvedAt: "now",
+  };
   const fullRevision: Required<Revision> = { revision: 1, content: "# P", submittedAt: "now" };
   const fullWorkspace: Required<WorkspaceKey> = { repoRoot: "/repo", branch: "main" };
-  const fullIdentity: Required<Identity> = { id: "SHA256:abc", provider: "ssh", name: "Al", handle: "abc" };
+  const fullIdentity: Required<Identity> = {
+    id: "SHA256:abc",
+    provider: "ssh",
+    name: "Al",
+    handle: "abc",
+  };
   const fullSession: Required<ReviewSession> = {
     schemaVersion: SCHEMA_VERSION,
     id: "ses_1",

package/src/validate.ts

@@ -16,6 +16,7 @@ import {
   type Annotation,
   type Artifact,
   type ArtifactMeta,
+  type DiffFileContents,
   type Identity,
   type ReviewSession,
   type Revision,
@@ -50,10 +51,18 @@ export const ArtifactMetaSchema = v.object({
   title: v.optional(v.string()),
 } satisfies EntriesOf<ArtifactMeta>);
 
+export const DiffFileContentsSchema = v.object({
+  path: NonEmpty,
+  oldContents: v.string(),
+  newContents: v.string(),
+  status: v.picklist(["added", "modified", "deleted"]),
+} satisfies EntriesOf<DiffFileContents>);
+
 export const ArtifactSchema = v.object({
   type: v.picklist(["plan", "diff"]),
   content: v.string(),
   meta: v.optional(ArtifactMetaSchema, {}),
+  files: v.optional(v.array(DiffFileContentsSchema)),
 } satisfies EntriesOf<Artifact>);
 
 export const AnchorSchema = v.object({
@@ -68,7 +77,7 @@ export const AnchorSchema = v.object({
 /** Wire annotations arrive without createdAt - the daemon stamps it. */
 export const AnnotationSchema = v.object({
   id: NonEmpty,
-  /** Open kind set: built-ins are comment and suggestion. */
+  /** Open kind set: the built-in is comment. */
   kind: NonEmpty,
   anchor: AnchorSchema,
   body: v.string(),
@@ -85,7 +94,10 @@ export const AnnotationSchema = v.object({
 const SessionId = NonEmpty;
 
 /** A stored annotation: the wire shape plus the daemon-stamped createdAt. */
-export const FullAnnotationSchema = v.object({ ...AnnotationSchema.entries, createdAt: v.string() } satisfies EntriesOf<Annotation>);
+export const FullAnnotationSchema = v.object({
+  ...AnnotationSchema.entries,
+  createdAt: v.string(),
+} satisfies EntriesOf<Annotation>);
 
 export const IdentitySchema = v.object({
   id: NonEmpty,
@@ -108,7 +120,10 @@ export const Params = {
   "session.wait": v.object({
     id: SessionId,
     // clamped: a negative or absurd timeout is a client bug, not a daemon one
-    timeoutMs: v.optional(v.pipe(v.number(), v.minValue(0), v.maxValue(24 * 60 * 60 * 1000)), 60_000),
+    timeoutMs: v.optional(
+      v.pipe(v.number(), v.minValue(0), v.maxValue(24 * 60 * 60 * 1000)),
+      60_000,
+    ),
   }),
   "session.annotate": v.object({ id: SessionId, annotation: AnnotationSchema }),
   "session.removeAnnotation": v.object({ id: SessionId, annotationId: NonEmpty }),
@@ -144,12 +159,18 @@ export function isKnownMethod(method: string): method is MethodName {
 }
 
 /** Validate params for a method, or throw a DaemonError the client can read. */
-export function parseParams<M extends MethodName>(method: M, params: unknown): v.InferOutput<(typeof Params)[M]> {
+export function parseParams<M extends MethodName>(
+  method: M,
+  params: unknown,
+): v.InferOutput<(typeof Params)[M]> {
   const result = v.safeParse(Params[method], params ?? {});
   if (!result.success) {
     const issue = result.issues[0]!;
     const path = issue.path?.map((pathSegment) => String(pathSegment.key)).join(".") ?? "";
-    throw new DaemonError("invalid_params", `${method}: ${path ? path + " - " : ""}${issue.message}`);
+    throw new DaemonError(
+      "invalid_params",
+      `${method}: ${path ? path + " - " : ""}${issue.message}`,
+    );
   }
   return result.output;
 }
@@ -185,7 +206,9 @@ export const SessionRecordSchema = v.object({
   participants: v.optional(v.array(IdentitySchema)),
 } satisfies EntriesOf<ReviewSession>);
 
-export function validateSessionRecord(raw: unknown): { ok: true; value: v.InferOutput<typeof SessionRecordSchema> } | { ok: false; error: string } {
+export function validateSessionRecord(
+  raw: unknown,
+): { ok: true; value: v.InferOutput<typeof SessionRecordSchema> } | { ok: false; error: string } {
   const result = v.safeParse(SessionRecordSchema, raw);
   if (result.success) return { ok: true, value: result.output };
   const issue = result.issues[0]!;