@cueloop/daemon 0.1.0-alpha.5 → 0.1.0-alpha.50

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,150 @@ 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);
+});

package/src/server.ts

@@ -1,19 +1,31 @@
 /**
  * The socket server: binds DaemonCore's methods to the unix socket, owns the
- * pidfile, stale-socket cleanup, and the idle-exit timer (#14). File
+ * pidfile, stale-socket cleanup, and the idle-exit timer. File
  * 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 { roleAllowsMethod, type DaemonRole } from "./capabilities";
 import { isKnownMethod, parseParams } from "./validate";
-import { LineBuffer, type Request } from "./protocol";
+import { BackpressureWriter, LineBuffer, type Request } from "./protocol";
 import { cueloopHome, lockPath, pidPath, socketPath } from "./paths";
 
-interface Conn {
+interface Connection {
   write(data: string): void;
   subscribed: boolean;
+  /** Capability role for this connection; the owner until a daemon.hello caps it. */
+  role: DaemonRole;
 }
 
 export interface DaemonOptions {
@@ -33,20 +45,20 @@ const HELD_HOMES = new Set<string>();
 export class DaemonServer {
   readonly core: DaemonCore;
   readonly home: string;
-  private conns = new Set<Conn>();
+  private connections = new Set<Connection>();
   private server: ReturnType<typeof Bun.listen> | null = null;
   private idleTimer: ReturnType<typeof setTimeout> | null = null;
   private lockFd: number | null = null;
   private readonly idleExitMs: number;
   private readonly onIdleExit: () => void;
 
-  constructor(opts: DaemonOptions = {}) {
-    this.home = opts.home ?? cueloopHome();
-    this.idleExitMs = opts.idleExitMs ?? 15 * 60 * 1000;
-    this.onIdleExit = opts.onIdleExit ?? (() => process.exit(0));
+  constructor(options: DaemonOptions = {}) {
+    this.home = options.home ?? cueloopHome();
+    this.idleExitMs = options.idleExitMs ?? 15 * 60 * 1000;
+    this.onIdleExit = options.onIdleExit ?? (() => process.exit(0));
     mkdirSync(this.home, { recursive: true, mode: 0o700 });
     this.core = new DaemonCore(this.home);
-    this.core.onEvent((e) => this.broadcast(e));
+    this.core.onEvent((event) => this.broadcast(event));
   }
 
   /**
@@ -118,24 +130,37 @@ 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; conn: Conn }>({
+    this.server = Bun.listen<{
+      buffer: LineBuffer;
+      connection: Connection;
+      writer: BackpressureWriter;
+    }>({
       unix: path,
       socket: {
-        open(socket) {
-          const conn: Conn = { write: (d) => socket.write(d), subscribed: false };
-          socket.data = { buffer: new LineBuffer(), conn };
-          self.conns.add(conn);
-          self.scheduleIdleCheck();
+        open: (socket) => {
+          const writer = new BackpressureWriter(socket);
+          const connection: Connection = {
+            write: (data) => writer.write(data),
+            subscribed: false,
+            role: "owner",
+          };
+          socket.data = { buffer: new LineBuffer(), connection, writer };
+          this.connections.add(connection);
+          this.scheduleIdleCheck();
         },
-        data(socket, data) {
+        data: (socket, data) => {
           socket.data.buffer.push(data.toString(), (line) => {
-            void self.handleLine(socket.data.conn, line);
+            void this.respondToRequestLine(socket.data.connection, line);
           });
         },
-        close(socket) {
-          self.conns.delete(socket.data.conn);
-          self.scheduleIdleCheck();
+        drain(socket) {
+          // drain can fire before open has attached data on some platforms;
+          // a throw here would take the whole daemon down with the socket
+          socket.data?.writer.drain();
+        },
+        close: (socket) => {
+          this.connections.delete(socket.data.connection);
+          this.scheduleIdleCheck();
         },
         error() {},
       },
@@ -147,6 +172,7 @@ export class DaemonServer {
   }
 
   stop(): void {
+    this.core.dispose();
     this.server?.stop(true);
     this.server = null;
     rmSync(socketPath(this.home), { force: true });
@@ -155,9 +181,9 @@ export class DaemonServer {
     this.releaseLock();
   }
 
-  private broadcast(e: DaemonEvent): void {
-    const frame = JSON.stringify(e) + "\n";
-    for (const c of this.conns) if (c.subscribed) c.write(frame);
+  private broadcast(event: DaemonEvent): void {
+    const frame = JSON.stringify(event) + "\n";
+    for (const connection of this.connections) if (connection.subscribed) connection.write(frame);
     this.scheduleIdleCheck();
   }
 
@@ -166,7 +192,7 @@ export class DaemonServer {
     if (this.idleExitMs <= 0) return;
     if (this.idleTimer) clearTimeout(this.idleTimer);
     this.idleTimer = setTimeout(() => {
-      if (this.conns.size === 0 && !this.core.hasPendingSessions()) {
+      if (this.connections.size === 0 && !this.core.hasPendingSessions()) {
         this.stop();
         this.onIdleExit();
       } else {
@@ -175,33 +201,44 @@ export class DaemonServer {
     }, this.idleExitMs);
   }
 
-  private async handleLine(conn: Conn, line: string): Promise<void> {
-    let req: Request;
+  private async respondToRequestLine(connection: Connection, line: string): Promise<void> {
+    let request: Request;
     try {
-      req = JSON.parse(line) as Request;
+      request = JSON.parse(line) as Request;
     } catch {
-      conn.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 {
-      const result = await this.dispatch(conn, req);
-      conn.write(JSON.stringify({ id: req.id, result }) + "\n");
+      const result = await this.dispatch(connection, request);
+      connection.write(JSON.stringify({ id: request.id, result }) + "\n");
     } catch (err) {
       const code = err instanceof DaemonError ? err.code : "internal";
       const message = err instanceof Error ? err.message : String(err);
-      conn.write(JSON.stringify({ id: req.id, error: { code, message } }) + "\n");
+      connection.write(JSON.stringify({ id: request.id, error: { code, message } }) + "\n");
     }
   }
 
-  private async dispatch(conn: Conn, req: Request): Promise<unknown> {
+  private async dispatch(connection: Connection, request: Request): Promise<unknown> {
     // The wire is untrusted JSON: validate before DaemonCore sees anything.
-    if (typeof req.method !== "string" || !isKnownMethod(req.method)) {
-      throw new DaemonError("unknown_method", `unknown method ${String(req.method)}`);
+    if (typeof request.method !== "string" || !isKnownMethod(request.method)) {
+      throw new DaemonError("unknown_method", `unknown method ${String(request.method)}`);
+    }
+    // Capability gate: a capped role (a review-side agent) cannot escalate past
+    // read + annotate, whatever verb it sends.
+    if (!roleAllowsMethod(connection.role, request.method)) {
+      throw new DaemonError("forbidden", `role ${connection.role} cannot call ${request.method}`);
     }
     const core = this.core;
-    switch (req.method) {
+    switch (request.method) {
       case "daemon.ping":
         return { pid: process.pid };
+      case "daemon.hello":
+        connection.role = parseParams("daemon.hello", request.params).role;
+        return {};
       case "daemon.shutdown":
         setTimeout(() => {
           this.stop();
@@ -209,42 +246,72 @@ export class DaemonServer {
         }, 10);
         return {};
       case "events.subscribe":
-        conn.subscribed = true;
+        connection.subscribed = true;
         return {};
       case "session.create": {
-        const p = parseParams("session.create", req.params);
-        return core.sessionCreate({ workspace: p.workspace, artifact: p.artifact });
+        const params = parseParams("session.create", request.params);
+        return core.sessionCreate({ workspace: params.workspace, artifact: params.artifact });
       }
       case "session.get":
-        return core.sessionGet(parseParams("session.get", req.params).id);
+        return core.sessionGet(parseParams("session.get", request.params).id);
       case "session.list":
-        return core.sessionList(parseParams("session.list", req.params).filter);
+        return core.sessionList(parseParams("session.list", request.params).filter);
       case "session.wait": {
-        const p = parseParams("session.wait", req.params);
-        return core.sessionWait(p.id, p.timeoutMs);
+        const params = parseParams("session.wait", request.params);
+        return core.sessionWait(params.id, params.timeoutMs);
       }
       case "session.annotate": {
-        const p = parseParams("session.annotate", req.params);
-        return core.sessionAnnotate(p.id, p.annotation);
+        const params = parseParams("session.annotate", request.params);
+        return core.sessionAnnotate(params.id, params.annotation, params.authorName);
       }
       case "session.removeAnnotation": {
-        const p = parseParams("session.removeAnnotation", req.params);
-        return core.sessionRemoveAnnotation(p.id, p.annotationId);
+        const params = parseParams("session.removeAnnotation", request.params);
+        return core.sessionRemoveAnnotation(params.id, params.annotationId);
       }
       case "session.setWorkingCopy": {
-        const p = parseParams("session.setWorkingCopy", req.params);
-        return core.sessionSetWorkingCopy(p.id, p.workingCopy);
+        const params = parseParams("session.setWorkingCopy", request.params);
+        return core.sessionSetWorkingCopy(params.id, params.workingCopy);
+      }
+      case "session.setViewed": {
+        const params = parseParams("session.setViewed", request.params);
+        return core.sessionSetViewed(params.id, params.viewedPaths);
+      }
+      case "session.refreshDiff": {
+        const params = parseParams("session.refreshDiff", request.params);
+        return core.sessionRefreshDiff(params.id);
+      }
+      case "session.setShareId": {
+        const params = parseParams("session.setShareId", request.params);
+        return core.sessionSetShareId(params.id, params.shareId);
+      }
+      case "session.delete": {
+        core.sessionDelete(parseParams("session.delete", request.params).id);
+        return {};
+      }
+      case "session.mergeShared": {
+        const params = parseParams("session.mergeShared", request.params);
+        return core.sessionMergeShared(params.id, {
+          annotations: params.annotations,
+          participants: params.participants,
+        });
       }
       case "session.resolve": {
-        const p = parseParams("session.resolve", req.params);
-        return core.sessionResolve(p.id, p.verdictKind, p.summary);
+        const params = parseParams("session.resolve", request.params);
+        return core.sessionResolve(params.id, params.verdictKind, params.summary);
       }
       case "session.submitRevision": {
-        const p = parseParams("session.submitRevision", req.params);
-        return core.sessionSubmitRevision(p.id, p.content);
+        const params = parseParams("session.submitRevision", request.params);
+        return core.sessionSubmitRevision(params.id, params.content, params.addressedAnnotationIds);
+      }
+      case "herdr.getTab":
+        return core.herdrGetTab(parseParams("herdr.getTab", request.params).id);
+      case "herdr.setTab": {
+        const params = parseParams("herdr.setTab", request.params);
+        core.herdrSetTab(params.id, { tabId: params.tabId, paneId: params.paneId });
+        return {};
       }
       default:
-        throw new DaemonError("unknown_method", `unknown method ${req.method}`);
+        throw new DaemonError("unknown_method", `unknown method ${request.method}`);
     }
   }
 }

package/src/share-blob.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { gzipSync } from "node:zlib";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Artifact, WorkspaceKey } from "@cueloop/schema";
+import { DaemonCore } from "./api";
+import { MAX_BLOB_BYTES, packSessionBlob, unpackSessionBlob } from "./share-blob";
+
+const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
+const PLAN: Artifact = { type: "plan", content: "# Plan\n\nDo the thing.\n", meta: {} };
+
+let home: string;
+let core: DaemonCore;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-blob-"));
+  core = new DaemonCore(home);
+});
+afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+describe("share blob roundtrip", () => {
+  test("pack then unpack restores the session with its annotations", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const annotated = core.sessionAnnotate(session.id, {
+      id: "a_1",
+      kind: "comment",
+      anchor: { quote: "the thing", prefix: "", suffix: "" },
+      body: "why this?",
+    });
+
+    // Act
+    const restored = unpackSessionBlob(packSessionBlob(annotated));
+
+    // Assert
+    expect(restored).toEqual(annotated);
+  });
+});
+
+describe("unpack rejects bad input", () => {
+  test("caps the decompressed size, so a compression bomb throws", () => {
+    // Arrange: tiny gzip, huge inflation - the decompression-bomb shape
+    const bomb = gzipSync(Buffer.alloc(MAX_BLOB_BYTES + 1, 0x61));
+
+    // Act / Assert
+    expect(() => unpackSessionBlob(bomb)).toThrow(/exceeds|maxOutputLength/i);
+  });
+
+  test("throws on bytes that are not gzip", () => {
+    // Act / Assert
+    expect(() => unpackSessionBlob(Buffer.from("not gzip at all"))).toThrow(/gzip/i);
+  });
+
+  test("throws on a shape that is not a session", () => {
+    // Arrange
+    const notASession = gzipSync(Buffer.from(JSON.stringify({ hello: "world" })));
+
+    // Act / Assert
+    expect(() => unpackSessionBlob(notASession)).toThrow(/not a valid session/i);
+  });
+});

package/src/share-blob.ts

@@ -0,0 +1,51 @@
+/**
+ * The share-blob wire format: how a ReviewSession travels from `cueloop share`
+ * to the gateway. The planner's CLI packs (this is the only thing it can do -
+ * it holds no encryption key); the gateway unpacks, then encrypts for R2.
+ *
+ * Format is gzip(JSON). Unpack is the untrusted boundary - the bytes come off
+ * an SSH channel from anyone who can reach the `share` user - so it caps the
+ * decompressed size (a decompression-bomb guard) and runs the same record
+ * validator the daemon store uses, never trusting the shape.
+ */
+
+import { gzipSync, gunzipSync } from "node:zlib";
+import type { ReviewSession } from "@cueloop/schema";
+import { validateSessionRecord } from "./validate";
+
+/** Decompressed ceiling for one shared session (ADR 0004's payload cap). */
+export const MAX_BLOB_BYTES = 1024 * 1024;
+
+/** The SSH username `cueloop share` connects as to upload; the gateway routes on it. */
+export const SHARE_UPLOAD_USER = "share";
+
+/** Where shares live, in one place: the client uploads here, the gateway prints it. */
+export const DEFAULT_SHARE_HOST = "cueloop.dev";
+export const DEFAULT_SHARE_PORT = 22;
+
+/** Serialise + compress a session for upload. */
+export function packSessionBlob(session: ReviewSession): Buffer {
+  return gzipSync(Buffer.from(JSON.stringify(session), "utf8"));
+}
+
+/** Decompress + validate an uploaded blob, or throw a precise reason. */
+export function unpackSessionBlob(bytes: Uint8Array): ReviewSession {
+  let json: string;
+  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)}`,
+      { cause: err },
+    );
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    throw new Error("blob is not valid JSON");
+  }
+  const parsed = validateSessionRecord(raw);
+  if (!parsed.ok) throw new Error(`blob is not a valid session: ${parsed.error}`);
+  return parsed.value as ReviewSession;
+}