@cueloop/daemon 0.1.0-alpha.3 → 0.1.0-alpha.30

package/src/review.test.ts

@@ -0,0 +1,243 @@
+/** The shared review core against a real DaemonServer in a temp home: workspace resolution, title derivation, open-or-revise by agentSessionId, and both awaitVerdict shapes (one long-poll and the chunked loop with progress and abort). */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ReviewSession } from "@cueloop/schema";
+import { DaemonServer } from "./server";
+import { DaemonClient } from "./client";
+import { openReview, resolveWorkspace } from "./review";
+
+const PLAN = "# Rollout Plan\n\nShip it in two stages.\n";
+
+let home: string;
+let server: DaemonServer;
+let client: DaemonClient;
+
+beforeEach(async () => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-review-core-"));
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  client = await DaemonClient.connect({ home });
+});
+afterEach(() => {
+  client.close();
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+function sh(args: string[], cwd: string): void {
+  const gitResult = Bun.spawnSync(args, { cwd, stdout: "ignore", stderr: "ignore" });
+  if (gitResult.exitCode !== 0) throw new Error(`${args.join(" ")} failed`);
+}
+
+describe("resolveWorkspace", () => {
+  test("a git repo resolves to its root and branch", async () => {
+    const repo = mkdtempSync(join(tmpdir(), "cueloop-ws-"));
+    try {
+      // Arrange
+      sh(["git", "init", "-q", "-b", "main"], repo);
+      sh(["git", "config", "user.email", "t@t"], repo);
+      sh(["git", "config", "user.name", "t"], repo);
+      sh(["git", "commit", "-q", "--allow-empty", "-m", "init"], repo);
+
+      // Act
+      const ws = await resolveWorkspace(repo);
+
+      // Assert
+      expect(ws.branch).toBe("main");
+      // macOS tmpdirs can resolve through /private; compare the tail
+      expect(ws.repoRoot.endsWith(repo.split("/").at(-1)!)).toBe(true);
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+    }
+  });
+
+  test("outside a repo the cwd itself is the workspace, branch detached", async () => {
+    // Act
+    const ws = await resolveWorkspace(home);
+
+    // Assert
+    expect(ws).toEqual({ repoRoot: home, branch: "detached" });
+  });
+});
+
+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" });
+
+    // Assert
+    const session = review.session;
+    expect(session.status).toBe("pending");
+    expect(session.artifact.type).toBe("plan");
+    expect(session.artifact.meta.agent).toBe("test-agent");
+    expect(session.artifact.meta.title).toBe("Rollout Plan");
+    expect(session.artifact.meta.cwd).toBe(home);
+    expect(session.workspace).toEqual({ repoRoot: home, branch: "detached" });
+  });
+
+  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" });
+
+    // Assert
+    expect(titled.session.artifact.meta.title).toBe("Custom");
+
+    // Act
+    const diff = await openReview(client, { type: "diff", content: "# not a heading\n", cwd: home });
+
+    // Assert
+    expect(diff.session.artifact.meta.title).toBeUndefined();
+  });
+
+  test("a pre-resolved workspace skips git resolution", async () => {
+    // Arrange
+    const ws = { repoRoot: "/elsewhere", branch: "feature" };
+
+    // Act
+    const review = await openReview(client, { type: "diff", content: "d", cwd: home, workspace: ws });
+
+    // Assert
+    expect(review.session.workspace).toEqual(ws);
+  });
+
+  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" });
+
+    // Act
+    const second = await openReview(client, {
+      type: "plan",
+      content: PLAN + "\nStage three.\n",
+      cwd: home,
+      agentSessionId: "agent-1",
+    });
+
+    // Assert
+    expect(second.id).toBe(first.id);
+    expect(second.session.revisions.length).toBe(2);
+    expect(second.session.status).toBe("pending");
+
+    // Act
+    const other = await openReview(client, { type: "plan", content: PLAN, cwd: home, agentSessionId: "agent-2" });
+
+    // Assert
+    expect(other.id).not.toBe(first.id);
+  });
+
+  test("per-file notes land as note annotations anchored at the file path", async () => {
+    // Act
+    const review = await openReview(client, {
+      type: "diff",
+      content: "d",
+      cwd: home,
+      notes: [
+        { path: "src/a.ts", body: "Renames b and adds c." },
+        { path: "src/b.ts", body: "Swaps the line." },
+      ],
+    });
+
+    // Assert
+    const notes = review.session.annotations;
+    expect(notes.length).toBe(2);
+    expect(notes.every((annotation) => annotation.kind === "note")).toBe(true);
+    expect(notes.map((annotation) => annotation.anchor.quote)).toEqual(["src/a.ts", "src/b.ts"]);
+    expect(notes[0]!.body).toBe("Renames b and adds c.");
+  });
+});
+
+describe("awaitVerdict: one long-poll (the hook shape)", () => {
+  test("times out to pending; a later wait collects the stored verdict", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+
+    // Assert
+    expect(await review.awaitVerdict({ timeoutMs: 50 })).toBe("pending");
+
+    // Act
+    await client.sessionResolve(review.id, "approve", "Fine.");
+    const verdict = await review.awaitVerdict({ timeoutMs: 1_000 });
+
+    // Assert
+    expect(verdict).not.toBe("pending");
+    if (verdict === "pending") throw new Error("unreachable");
+    expect(verdict.allow).toBe(true);
+    expect(verdict.feedback).toContain("Fine.");
+    expect(verdict.session.verdict!.kind).toBe("approve");
+  });
+
+  test("request_changes maps to allow=false with feedback.md attached", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const waiting = review.awaitVerdict({ timeoutMs: 5_000 });
+
+    // Act
+    await client.sessionResolve(review.id, "request_changes", "One stage only.");
+    const verdict = await waiting;
+
+    // Assert
+    if (verdict === "pending") throw new Error("expected a verdict");
+    expect(verdict.allow).toBe(false);
+    expect(verdict.feedback).toContain("# Review: request changes");
+    expect(verdict.feedback).toContain("One stage only.");
+  });
+});
+
+describe("awaitVerdict: chunked loop (the pi shape)", () => {
+  test("onProgress sees fresh sessions between chunks; the verdict ends the loop", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const seen: ReviewSession[] = [];
+    const waiting = review.awaitVerdict({
+      timeoutMs: Infinity,
+      pollMs: 100,
+      onProgress: (progress) => seen.push(progress),
+    });
+
+    // Act
+    await client.sessionAnnotate(review.id, {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "two stages", prefix: "in ", suffix: "." },
+      body: "Name them.",
+    });
+
+    // 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);
+    expect(seen.some((snapshot) => snapshot.annotations.length === 1)).toBe(true);
+
+    // Act
+    await client.sessionResolve(review.id, "request_changes", "Too vague.");
+    const verdict = await waiting;
+
+    // Assert
+    if (verdict === "pending") throw new Error("expected a verdict");
+    expect(verdict.allow).toBe(false);
+    expect(verdict.session.annotations.length).toBe(1);
+  }, 15_000);
+
+  test("abort surfaces as pending and leaves the session collectable", async () => {
+    // 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 });
+
+    // Act
+    controller.abort();
+
+    // Assert
+    expect(await waiting).toBe("pending");
+    expect((await client.sessionGet(review.id)).status).toBe("pending");
+  });
+
+  test("a finite budget runs out to pending", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+
+    // Assert
+    expect(await review.awaitVerdict({ timeoutMs: 120, pollMs: 50 })).toBe("pending");
+  });
+});

package/src/review.ts

@@ -0,0 +1,208 @@
+/**
+ * The shared review core: one open/wait/verdict path for every consumer -
+ * CLI commands and agent adapters. openReview resolves the workspace, shapes
+ * the artifact, and opens-or-revises by agentSessionId; awaitVerdict maps the
+ * wait contract onto the agent contract through verdictResponse. An
+ * adapter keeps only two bespoke parts: parsing its host's event shape and
+ * serializing the decision in its host's contract.
+ */
+
+import { newAnnotationId, type ArtifactType, type ReviewSession, type WorkspaceKey } from "@cueloop/schema";
+import { verdictResponse } from "./api";
+import type { DaemonClient } from "./client";
+
+// Adapters and CLI verbs reach the verdict mapping through this module too,
+// so a session obtained outside a ReviewHandle maps the same way.
+export { verdictResponse };
+
+async function git(args: string[], cwd: string): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore" });
+    const out = await new Response(proc.stdout).text();
+    if ((await proc.exited) !== 0) return null;
+    return out.trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Workspace key resolution: repo root + branch from the cwd. */
+export async function resolveWorkspace(cwd = process.cwd()): Promise<WorkspaceKey> {
+  const repoRoot = (await git(["rev-parse", "--show-toplevel"], cwd)) ?? cwd;
+  const branch = (await git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)) ?? "detached";
+  return { repoRoot, branch };
+}
+
+function firstHeading(markdown: string): string | undefined {
+  const headingMatch = markdown.match(/^#\s+(.+)$/m);
+  return headingMatch?.[1]?.trim();
+}
+
+export interface OpenReviewOptions {
+  type: ArtifactType;
+  content: string;
+  /** Workspace resolution root and meta.cwd; defaults to process.cwd(). */
+  cwd?: string;
+  /** Pre-resolved workspace key; skips git resolution when the caller already has it. */
+  workspace?: WorkspaceKey;
+  agent?: string;
+  /** When set, a resubmit from the same agent session becomes a revision, not a new session. */
+  agentSessionId?: string;
+  planPath?: string;
+  pr?: string;
+  herdrPane?: string;
+  /** Defaults to the plan's first markdown heading; diffs get no derived title. */
+  title?: string;
+  /**
+   * Per-file agent notes for diff sessions: the submitting agent's own
+   * explanation of each file's change, in dead prose. Stored as annotations
+   * with kind "note" anchored at the file path, so they render as regular
+   * rail cards and feed the guided walk's agent-note block.
+   */
+  notes?: ReviewNote[];
+}
+
+/** The note contract: one note per changed file, anchored by the file path. */
+export interface ReviewNote {
+  path: string;
+  body: string;
+}
+
+/** Anchor a note at its file: quote = the path, no context selectors. */
+async function attachNotes(client: DaemonClient, sessionId: string, notes: ReviewNote[]): Promise<void> {
+  for (const note of notes) {
+    await client.sessionAnnotate(sessionId, {
+      id: newAnnotationId(),
+      kind: "note",
+      anchor: { quote: note.path, prefix: "", suffix: "" },
+      body: note.body,
+    });
+  }
+}
+
+export interface AwaitVerdictOptions {
+  /** Total wait budget; Infinity keeps polling until resolved or aborted. */
+  timeoutMs: number;
+  /** Chunk length for the poll loop; between chunks the session is re-read for progress. */
+  pollMs?: number;
+  /** Called with the fresh session after each chunk that is still pending. */
+  onProgress?: (session: ReviewSession) => void;
+  signal?: AbortSignal;
+}
+
+/** A resolved review mapped onto the agent contract, plus the full session. */
+export interface VerdictOutcome {
+  allow: boolean;
+  feedback: string;
+  session: ReviewSession;
+}
+
+/** 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> {
+  if (!signal) return promise;
+  if (signal.aborted) {
+    promise.catch(() => {});
+    return Promise.resolve(ABORTED);
+  }
+  return new Promise<T | typeof ABORTED>((resolve, reject) => {
+    const onAbort = () => {
+      // The daemon request keeps running until the client closes; swallow its
+      // eventual rejection so the abort path never leaks an unhandled error.
+      promise.catch(() => {});
+      resolve(ABORTED);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+export class ReviewHandle {
+  constructor(
+    private readonly client: DaemonClient,
+    readonly session: ReviewSession,
+  ) {}
+
+  get id(): string {
+    return this.session.id;
+  }
+
+  /**
+   * Block on the verdict. "pending" means the budget ran out or the signal
+   * aborted - the session stays open and the verdict is collectable later
+   * (verdicts outlive waits). With only timeoutMs this is one long-poll;
+   * pollMs/onProgress/signal switch to the chunked loop.
+   */
+  async awaitVerdict(options: AwaitVerdictOptions): Promise<VerdictOutcome | "pending"> {
+    const { timeoutMs, pollMs, onProgress, signal } = options;
+    if (pollMs === undefined && onProgress === undefined && signal === undefined) {
+      const resolved = await this.client.sessionWait(this.session.id, timeoutMs);
+      return resolved === null ? "pending" : outcome(resolved);
+    }
+    const chunkMs = pollMs ?? 10_000;
+    const deadline = Number.isFinite(timeoutMs) ? Date.now() + timeoutMs : undefined;
+    for (;;) {
+      const budget = deadline === undefined ? chunkMs : Math.min(chunkMs, deadline - Date.now());
+      if (budget <= 0 || signal?.aborted) return "pending";
+      const resolved = await raceAbort(this.client.sessionWait(this.session.id, budget), signal);
+      if (resolved === ABORTED) return "pending";
+      if (resolved !== null) return outcome(resolved);
+      // Still pending after this chunk: re-read to surface reviewer progress.
+      const current = await raceAbort(this.client.sessionGet(this.session.id), signal);
+      if (current === ABORTED) return "pending";
+      onProgress?.(current);
+    }
+  }
+}
+
+function outcome(session: ReviewSession): VerdictOutcome {
+  return { ...verdictResponse(session), session };
+}
+
+/** 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> {
+  const cwd = options.cwd ?? process.cwd();
+  const workspace = options.workspace ?? (await resolveWorkspace(cwd));
+  // Resubmits from the same agent session become revisions, not new sessions.
+  if (options.agentSessionId !== undefined) {
+    const existing = (await client.sessionList()).find(
+      (candidate) => candidate.artifact.meta.agentSessionId === options.agentSessionId,
+    );
+    if (existing !== undefined) {
+      let revised = await client.sessionSubmitRevision(existing.id, options.content);
+      if (options.notes?.length) {
+        await attachNotes(client, revised.id, options.notes);
+        revised = await client.sessionGet(revised.id);
+      }
+      return new ReviewHandle(client, revised);
+    }
+  }
+  let session = await client.sessionCreate(workspace, {
+    type: options.type,
+    content: options.content,
+    meta: {
+      agent: options.agent,
+      agentSessionId: options.agentSessionId,
+      planPath: options.planPath,
+      pr: options.pr,
+      herdrPane: options.herdrPane,
+      title: options.title ?? (options.type === "plan" ? firstHeading(options.content) : undefined),
+      cwd,
+    },
+  });
+  if (options.notes?.length) {
+    await attachNotes(client, session.id, options.notes);
+    session = await client.sessionGet(session.id);
+  }
+  return new ReviewHandle(client, session);
+}

package/src/server.test.ts

@@ -27,18 +27,27 @@ afterEach(() => {
 
 describe("socket round-trip", () => {
   test("ping and full session flow over the wire", async () => {
+    // Assert
     expect((await client.ping()).pid).toBe(process.pid);
-    const s = await client.sessionCreate(WS, PLAN);
-    expect(s.status).toBe("pending");
-    await client.sessionAnnotate(s.id, {
+
+    // Act
+    const session = await client.sessionCreate(WS, PLAN);
+
+    // Assert
+    expect(session.status).toBe("pending");
+
+    // Act
+    await client.sessionAnnotate(session.id, {
       id: "a1",
       kind: "comment",
       anchor: { quote: "Body text", prefix: "", suffix: "." },
       body: "More detail please.",
     });
-    const wait = client.sessionWait(s.id, 5_000);
-    await client.sessionResolve(s.id, "request_changes", "Expand it.");
+    const wait = client.sessionWait(session.id, 5_000);
+    await client.sessionResolve(session.id, "request_changes", "Expand it.");
     const resolved = (await wait)!;
+
+    // Assert
     expect(resolved.verdict!.kind).toBe("request_changes");
     expect(resolved.verdict!.feedback).toContain("More detail please.");
   });
@@ -47,18 +56,23 @@ describe("socket round-trip", () => {
     expect(client.sessionGet("nope")).rejects.toBeInstanceOf(DaemonClientError);
     try {
       await client.sessionGet("nope");
-    } catch (e) {
-      expect((e as DaemonClientError).code).toBe("not_found");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("not_found");
     }
   });
 
   test("events push to subscribed connections only", async () => {
+    // Arrange
     const observer = await DaemonClient.connect({ home });
     const seen: string[] = [];
-    observer.onEvent((e) => seen.push(e.event));
+    observer.onEvent((event) => seen.push(event.event));
     await observer.subscribe();
-    const s = await client.sessionCreate(WS, PLAN);
-    await client.sessionResolve(s.id, "approve", "");
+
+    // Act
+    const session = await client.sessionCreate(WS, PLAN);
+    await client.sessionResolve(session.id, "approve", "");
+
+    // Assert
     // events are pushed async over the socket; give the loop a beat
     await Bun.sleep(50);
     expect(seen).toContain("session.created");
@@ -71,33 +85,134 @@ describe("socket round-trip", () => {
     try {
       await client.request("session.create", { artifact: { type: "plan", content: "x" } });
       throw new Error("should have thrown");
-    } catch (e) {
-      expect((e as DaemonClientError).code).toBe("invalid_params");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("invalid_params");
     }
     // wrong types
     try {
       await client.request("session.wait", { id: 42 });
       throw new Error("should have thrown");
-    } catch (e) {
-      expect((e as DaemonClientError).code).toBe("invalid_params");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("invalid_params");
     }
     // unknown method
     try {
       await client.request("session.nuke", {});
       throw new Error("should have thrown");
-    } catch (e) {
-      expect((e as DaemonClientError).code).toBe("unknown_method");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("unknown_method");
     }
     // the daemon is still fully alive afterwards
-    const s = await client.sessionCreate(WS, PLAN);
-    expect((await client.sessionGet(s.id)).id).toBe(s.id);
+    const session = await client.sessionCreate(WS, PLAN);
+    expect((await client.sessionGet(session.id)).id).toBe(session.id);
+  });
+
+  test("meta fields survive the wire: herdrPane set on create comes back from get", async () => {
+    // Act
+    const session = await client.sessionCreate(WS, {
+      type: "plan",
+      content: "# P",
+      meta: { agent: "claude-code", herdrPane: "%7" },
+    });
+    const got = await client.sessionGet(session.id);
+
+    // Assert
+    expect(got.artifact.meta.herdrPane).toBe("%7");
+    expect(got.artifact.meta.agent).toBe("claude-code");
+  });
+
+  test("share-sync verbs round-trip: setShareId persists, mergeShared unions notes and identities by id", async () => {
+    // Given a shared session with one local note
+    const session = await client.sessionCreate(WS, PLAN);
+    const anchor = { quote: "Body text", prefix: "", suffix: "." };
+    await client.sessionSetShareId(session.id, "p_abc123xy");
+    await client.sessionAnnotate(session.id, { id: "a1", kind: "comment", anchor, body: "mine" });
+    expect((await client.sessionGet(session.id)).shareId).toBe("p_abc123xy");
+
+    // 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" },
+      ],
+      participants: [{ id: "SHA256:mate", provider: "ssh", name: "Sam" }],
+    });
+
+    // 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.participants).toEqual([{ id: "SHA256:mate", provider: "ssh", name: "Sam" }]);
+  });
+
+  test("mergeShared validates each annotation at the socket boundary", async () => {
+    // Given a session
+    const session = await client.sessionCreate(WS, PLAN);
+    try {
+      // When a malformed annotation is merged
+      // @ts-expect-error intentionally malformed annotation (empty id, missing fields)
+      await client.sessionMergeShared(session.id, { annotations: [{ id: "" }] });
+      throw new Error("should have thrown");
+    } catch (error) {
+      // Then it is rejected at the wire boundary
+      expect((error as DaemonClientError).code).toBe("invalid_params");
+    }
+  });
+
+  test("session.delete removes a session over the wire", async () => {
+    // Given a created session
+    const session = await client.sessionCreate(WS, PLAN);
+
+    // When it is deleted
+    await client.sessionDelete(session.id);
+
+    // Then it is gone, and deleting an unknown id is a not_found error
+    expect(client.sessionGet(session.id)).rejects.toBeInstanceOf(DaemonClientError);
+    try {
+      await client.sessionDelete("ses_missing");
+      throw new Error("should have thrown");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("not_found");
+    }
   });
 
   test("two clients see the same state (thin-renderer model)", async () => {
+    // Arrange
     const second = await DaemonClient.connect({ home });
-    const s = await client.sessionCreate(WS, PLAN);
-    const fromSecond = await second.sessionGet(s.id);
+
+    // Act
+    const session = await client.sessionCreate(WS, PLAN);
+    const fromSecond = await second.sessionGet(session.id);
+
+    // Assert
     expect(fromSecond.artifact.content).toBe(PLAN.content);
     second.close();
   });
 });
+
+describe("large payloads survive socket backpressure", () => {
+  test("a session bigger than the kernel socket buffer round-trips", async () => {
+    // Regression: responses larger than one socket write used to truncate
+    // 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);
+
+    // Act
+    const created = await client.sessionCreate(
+      { repoRoot: "/repo", branch: "main" },
+      { type: "plan", content: bigContent, meta: { title: "big" } },
+    );
+    const fetched = await client.sessionGet(created.id);
+
+    // Assert
+    expect(fetched.artifact.content).toBe(bigContent);
+
+    // Act
+    // the connection must still be usable for the next frame
+    const listed = await client.sessionList();
+
+    // Assert
+    expect(listed.some((session) => session.id === created.id)).toBe(true);
+  }, 15_000);
+});