@cueloop/daemon 0.1.0-alpha.21 → 0.1.0-alpha.23

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.23",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client.ts",
     "./review": "./src/review.ts",
-    "./herdr-pane": "./src/herdr-pane.ts"
+    "./herdr-pane": "./src/herdr-pane.ts",
+    "./share-blob": "./src/share-blob.ts"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.21",
+    "@cueloop/schema": "0.1.0-alpha.23",
     "valibot": "^1.4.2"
   },
   "publishConfig": {

package/src/api.test.ts

@@ -24,7 +24,10 @@ afterEach(() => rmSync(home, { recursive: true, force: true }));
 
 describe("session lifecycle", () => {
   test("create → get → list", () => {
+    // Act
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    // Assert
     expect(session.status).toBe("pending");
     expect(session.revisions.length).toBe(1);
     expect(core.sessionGet(session.id).id).toBe(session.id);
@@ -32,7 +35,10 @@ describe("session lifecycle", () => {
   });
 
   test("annotate upserts by id; remove deletes", () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    // Act
     core.sessionAnnotate(session.id, {
       id: "a1",
       kind: "comment",
@@ -45,13 +51,20 @@ describe("session lifecycle", () => {
       anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
       body: "Define carefully.",
     });
+
+    // Assert
     expect(core.sessionGet(session.id).annotations.length).toBe(1);
     expect(core.sessionGet(session.id).annotations[0]!.body).toBe("Define carefully.");
+
+    // Act
     core.sessionRemoveAnnotation(session.id, "a1");
+
+    // Assert
     expect(core.sessionGet(session.id).annotations.length).toBe(0);
   });
 
   test("resolve produces feedback.md and maps to the agent contract", () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
     core.sessionAnnotate(session.id, {
       id: "a1",
@@ -59,50 +72,90 @@ describe("session lifecycle", () => {
       anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
       body: "Spell out the steps.",
     });
+
+    // Act
     const resolved = core.sessionResolve(session.id, "request_changes", "Needs detail.");
+
+    // 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 });
+
+    // Arrange
     const approved = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    // Act
     core.sessionResolve(approved.id, "approve", "LGTM");
+
+    // Assert
     expect(verdictResponse(core.sessionGet(approved.id)).allow).toBe(true);
   });
 
   test("mutating a resolved session throws", () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
     core.sessionResolve(session.id, "approve", "");
+
+    // Assert
     expect(() =>
       core.sessionAnnotate(session.id, { id: "a1", kind: "comment", anchor: { quote: "x", prefix: "", suffix: "" }, body: "b" }),
     ).toThrow("already resolved");
   });
 
   test("working copy stores edits and clears on revert or no-op", () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    // Act
     core.sessionSetWorkingCopy(session.id, PLAN.content.replace("carefully", "very carefully"));
+
+    // Assert
     expect(core.sessionGet(session.id).workingCopy).toContain("very carefully");
+
+    // Act
     core.sessionSetWorkingCopy(session.id, PLAN.content);
+
+    // Assert
     expect(core.sessionGet(session.id).workingCopy).toBeUndefined();
   });
 
   test("viewed paths merge, dedupe, clear on empty, and survive a daemon restart", () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    // Act
     core.sessionSetViewed(session.id, ["src/a.ts", "src/b.ts", "src/a.ts"]);
+
+    // Assert
     expect(core.sessionGet(session.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts"]);
+
+    // Act
     // merge-additive: a stale client sending only its own new mark loses nothing
     core.sessionSetViewed(session.id, ["src/c.ts"]);
+
+    // Assert
     expect(core.sessionGet(session.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
     // a resumed review reads its progress back after a daemon restart
     const reborn = new DaemonCore(home);
     expect(reborn.sessionGet(session.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
+
+    // Act
     core.sessionSetViewed(session.id, []);
+
+    // Assert
     expect(core.sessionGet(session.id).viewedPaths).toBeUndefined();
   });
 
   test("revision reopens the session and resets working copy + verdict", () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
     core.sessionSetWorkingCopy(session.id, PLAN.content + "\nedit");
     core.sessionResolve(session.id, "request_changes", "redo");
+
+    // Act
     const revised = core.sessionSubmitRevision(session.id, "# Plan v2\n");
+
+    // Assert
     expect(revised.status).toBe("pending");
     expect(revised.verdict).toBeNull();
     expect(revised.workingCopy).toBeUndefined();
@@ -111,47 +164,154 @@ 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 });
+
+  test("ids the agent reports are marked addressed by that revision", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    annotate(session.id, "a1", "carefully");
+    annotate(session.id, "a2", "Context");
+
+    // Act: the revision keeps both quoted texts, so only the reported id resolves
+    const revised = core.sessionSubmitRevision(session.id, PLAN.content + "\nMore.\n", ["a1"]);
+
+    // Assert
+    const [first, second] = revised.annotations;
+    expect(first!.resolution).toEqual({ revision: 2, source: "agent" });
+    expect(second!.resolution).toBeUndefined();
+  });
+
+  test("a plan annotation whose quoted text vanished is drift-addressed; a surviving quote stays open", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    annotate(session.id, "gone", "carefully");
+    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");
+
+    // Assert
+    expect(revised.annotations.find((a) => a.id === "gone")!.resolution).toEqual({ revision: 2, source: "drift" });
+    expect(revised.annotations.find((a) => a.id === "kept")!.resolution).toBeUndefined();
+  });
+
+  test("an unknown reported id is ignored, and an already-addressed annotation keeps its first resolution", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    annotate(session.id, "a1", "carefully");
+    core.sessionSubmitRevision(session.id, PLAN.content, ["a1"]);
+
+    // Act: a second revision reports a stale id and re-reports the settled one
+    const revised = core.sessionSubmitRevision(session.id, PLAN.content, ["a1", "a_never_existed"]);
+
+    // Assert
+    expect(revised.annotations[0]!.resolution).toEqual({ revision: 2, source: "agent" });
+    expect(revised.revisions.length).toBe(3);
+  });
+
+  test("a diff revision never drift-addresses - a new patch says nothing about the feedback", () => {
+    // Arrange
+    const diffArtifact: Artifact = { type: "diff", content: "+++ b/a.ts\n+new line\n", meta: {} };
+    const session = core.sessionCreate({ workspace: WS, artifact: diffArtifact });
+    annotate(session.id, "d1", "new line");
+
+    // Act: the revised patch no longer contains the quoted text
+    const revised = core.sessionSubmitRevision(session.id, "+++ b/b.ts\n+other\n");
+
+    // Assert
+    expect(revised.annotations[0]!.resolution).toBeUndefined();
+  });
+
+  test("the next feedback document omits addressed annotations and teaches the addressed-ids call", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    annotate(session.id, "settled", "carefully");
+    annotate(session.id, "open", "Context", "needs a diagram");
+    core.sessionSubmitRevision(session.id, PLAN.content, ["settled"]);
+
+    // Act
+    const resolved = core.sessionResolve(session.id, "request_changes", "one left");
+
+    // Assert
+    expect(resolved.verdict!.feedback).not.toContain("settled");
+    expect(resolved.verdict!.feedback).toContain("annotation id: `open`");
+    expect(resolved.verdict!.feedback).toContain(`submit-revision ${session.id}`);
+    expect(resolved.verdict!.feedback).toContain("--addressed");
+  });
+});
+
 describe("the wait contract: verdicts outlive waits", () => {
   test("wait resolves when the verdict arrives", async () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
     const wait = core.sessionWait(session.id, 5_000);
+
+    // Act
     core.sessionResolve(session.id, "approve", "");
     const resolved = await wait;
+
+    // Assert
     expect(resolved!.verdict!.kind).toBe("approve");
   });
 
   test("wait times out to null; a later wait collects the stored verdict", async () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    // Act
     const first = await core.sessionWait(session.id, 30);
+
+    // Assert
     expect(first).toBeNull();
+
+    // Act
     core.sessionResolve(session.id, "request_changes", "later");
     const second = await core.sessionWait(session.id, 30);
+
+    // Assert
     expect(second!.verdict!.summary).toBe("later");
   });
 
   test("multiple waiters all resolve", async () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
     const waits = [core.sessionWait(session.id, 5_000), core.sessionWait(session.id, 5_000)];
+
+    // Act
     core.sessionResolve(session.id, "approve", "");
     const results = await Promise.all(waits);
+
+    // Assert
     expect(results.every((result) => result?.status === "resolved")).toBe(true);
   });
 });
 
 describe("persistence and recovery", () => {
   test("sessions survive a daemon restart", () => {
+    // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
     core.sessionResolve(session.id, "approve", "done");
+
+    // Act
     const reborn = new DaemonCore(home);
     const recovered = reborn.sessionGet(session.id);
+
+    // Assert
     expect(recovered.verdict!.summary).toBe("done");
   });
 
   test("corrupt records are skipped, not fatal, and never deleted", async () => {
+    // Arrange
     core.sessionCreate({ workspace: WS, artifact: PLAN });
     await Bun.write(join(home, "sessions", "broken.json"), "{ not json");
     const store = new SessionStore(home);
+
+    // Act
     const report = store.recover();
+
+    // Assert
     expect(report.recovered.length).toBe(1);
     expect(report.skipped.length).toBe(1);
     expect(await Bun.file(join(home, "sessions", "broken.json")).exists()).toBe(true);
@@ -160,11 +320,16 @@ describe("persistence and recovery", () => {
 
 describe("events", () => {
   test("lifecycle events fire in order", () => {
+    // Arrange
     const seen: string[] = [];
     core.onEvent((event) => seen.push(event.event));
+
+    // 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.sessionResolve(session.id, "approve", "");
+
+    // Assert
     expect(seen).toEqual(["session.created", "inbox.changed", "session.updated", "session.resolved", "inbox.changed"]);
   });
 });

package/src/api.ts

@@ -8,6 +8,10 @@
 import {
   SCHEMA_VERSION,
   feedbackForSession,
+  isAddressed,
+  isAgentNote,
+  parseBlocks,
+  resolveAnchor,
   verdictAllows,
   type Annotation,
   type Artifact,
@@ -183,15 +187,39 @@ export class DaemonCore {
     return session;
   }
 
-  /** Agent resubmits: new revision becomes the artifact, session reopens. */
-  sessionSubmitRevision(id: string, content: string): ReviewSession {
+  /**
+   * Agent resubmits: new revision becomes the artifact, session reopens.
+   * Annotations the agent reports as acted on (by id) are marked addressed,
+   * and for plan revisions any still-open annotation whose quoted text no
+   * longer resolves is marked addressed too ("drift" - the line it pointed at
+   * was rewritten). Addressed is a marker, never a delete: the reviewer's
+   * rail hides them behind a count, and the next feedback document omits them.
+   * 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 {
     const session = this.sessionGet(id);
     const now = new Date().toISOString();
-    session.revisions.push({ revision: session.revisions.length + 1, content, submittedAt: now });
+    const revisionNumber = session.revisions.length + 1;
+    session.revisions.push({ revision: revisionNumber, content, submittedAt: now });
     session.artifact = { ...session.artifact, content };
     delete session.workingCopy;
     session.verdict = null;
     session.status = "pending";
+
+    const reportedIds = new Set(addressedAnnotationIds);
+    // drift assist applies to plans only: a diff revision is a whole new
+    // patch, where a vanished quote says nothing about the feedback
+    const revisedBlocks = session.artifact.type === "plan" ? parseBlocks(content) : null;
+    for (const annotation of session.annotations) {
+      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) {
+        annotation.resolution = { revision: revisionNumber, source: "drift" };
+      }
+    }
+
     this.store.upsert(session);
     this.emit("session.revised", id);
     this.emit("inbox.changed", id);

package/src/client.ts

@@ -9,6 +9,8 @@ import type { Annotation, Artifact, ReviewSession, VerdictKind, WorkspaceKey } f
 import { BackpressureWriter, LineBuffer, type EventFrame, type Response } from "./protocol";
 import { cueloopHome, socketPath } from "./paths";
 
+export type { EventFrame } from "./protocol";
+
 export interface ConnectOptions {
   home?: string;
   /** Spawn the daemon when the socket is not alive. */
@@ -17,7 +19,26 @@ export interface ConnectOptions {
 
 type PendingRequest = { resolve: (value: unknown) => void; reject: (error: Error) => void };
 
-export class DaemonClient {
+/**
+ * The session verbs the review controller drives. DaemonClient is the local
+ * implementation (unix socket); the sharing gateway supplies an in-memory,
+ * blob-backed one. Depending on this interface - not DaemonClient - is what
+ * lets the same <App> render a local session or a decrypted share unchanged.
+ */
+export interface SessionClient {
+  onEvent(listener: (event: EventFrame) => void): () => void;
+  subscribe(): Promise<void>;
+  sessionGet(id: string): Promise<ReviewSession>;
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<ReviewSession[]>;
+  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): Promise<ReviewSession>;
+  sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession>;
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession>;
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession>;
+  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession>;
+  close(): void;
+}
+
+export class DaemonClient implements SessionClient {
   private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
   private writer: BackpressureWriter | null = null;
   private pending = new Map<number, PendingRequest>();
@@ -165,8 +186,8 @@ export class DaemonClient {
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
     return this.request("session.resolve", { id, verdictKind, summary });
   }
-  sessionSubmitRevision(id: string, content: string): Promise<ReviewSession> {
-    return this.request("session.submitRevision", { id, content });
+  sessionSubmitRevision(id: string, content: string, addressedAnnotationIds: string[] = []): Promise<ReviewSession> {
+    return this.request("session.submitRevision", { id, content, addressedAnnotationIds });
   }
   shutdown(): Promise<void> {
     return this.request("daemon.shutdown", {});

package/src/herdr-pane.test.ts

@@ -1,11 +1,4 @@
-/**
- * Creation-side herdr pane opener tests. The herdr binary is stubbed by a
- * script that both records its argv to a log file and, for `tab create`,
- * prints the JSON the helper reads to learn the new pane id. The gating
- * wrapper is exercised for its three outcomes: no-op outside herdr, no-op for
- * a revision (the open pane is reused), and a full open for a genuinely new
- * session.
- */
+/** Creation-side herdr pane opener: a stubbed herdr binary logs its argv, and the gating wrapper is checked for its three outcomes (no-op outside herdr, no-op on revision, full open for a new session). */
 
 import { afterAll, describe, expect, test } from "bun:test";
 import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -18,15 +11,18 @@ const dir = mkdtempSync(join(tmpdir(), "cueloop-herdr-pane-"));
 
 /**
  * A stub herdr binary. It appends its argv to logPath and, when the verb is
- * `tab create`, prints a JSON result carrying paneId on stdout so the helper
- * can drive send-text and send-keys.
+ * `tab create`, prints a JSON result carrying the pane id on stdout so the
+ * helper can drive send-text and send-keys. The printed shape mirrors the
+ * REAL herdr `tab create` output ({ result: { root_pane: { pane_id } } },
+ * verified against herdr 0.8.0) - an earlier stub invented a different shape
+ * and let a parser that never matched real herdr pass the suite.
  */
 function makeStub(name: string, paneId = "w1:p2"): { binPath: string; logPath: string } {
   const logPath = join(dir, `${name}.log`);
   const binPath = join(dir, `${name}.sh`);
   writeFileSync(
     binPath,
-    `#!/bin/sh\nprintf '%s\\n' "$*" >> "${logPath}"\nif [ "$1" = "tab" ] && [ "$2" = "create" ]; then\n  printf '{"result":{"pane":{"id":"${paneId}"}}}'\nfi\n`,
+    `#!/bin/sh\nprintf '%s\\n' "$*" >> "${logPath}"\nif [ "$1" = "tab" ] && [ "$2" = "create" ]; then\n  printf '{"result":{"root_pane":{"pane_id":"${paneId}"}}}'\nfi\n`,
   );
   chmodSync(binPath, 0o755);
   return { binPath, logPath };
@@ -54,8 +50,13 @@ function newSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
 
 describe("openHerdrPane", () => {
   test("creates a focused tab, types the cueloop command, and presses enter", () => {
+    // Arrange
     const stub = makeStub("open");
+
+    // Act
     const ok = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath: stub.binPath, label: "Rollout Plan" });
+
+    // Assert
     expect(ok).toBeTrue();
     expect(readLines(stub.logPath)).toEqual([
       "tab create --cwd /repo/work --label Rollout Plan --focus",
@@ -65,21 +66,29 @@ describe("openHerdrPane", () => {
   });
 
   test("returns false and never throws on a broken binary", () => {
+    // Act
     const ok = openHerdrPane({
       sessionId: "ses_abc",
       cwd: "/repo/work",
       binPath: join(dir, "missing-bin"),
       label: "x",
     });
+
+    // Assert
     expect(ok).toBeFalse();
   });
 
   test("bails out when tab create yields no pane id - no send-text, no send-keys", () => {
+    // Arrange
     const logPath = join(dir, "nopane.log");
     const binPath = join(dir, "nopane.sh");
     writeFileSync(binPath, `#!/bin/sh\nprintf '%s\\n' "$*" >> "${logPath}"\nprintf '{"result":{}}'\n`);
     chmodSync(binPath, 0o755);
+
+    // Act
     const ok = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath, label: "x" });
+
+    // Assert
     expect(ok).toBeFalse();
     expect(readLines(logPath)).toEqual(["tab create --cwd /repo/work --label x --focus"]);
   });
@@ -87,9 +96,14 @@ describe("openHerdrPane", () => {
 
 describe("openHerdrPaneForReview", () => {
   test("opens a pane for a genuinely new session inside herdr", () => {
+    // Arrange
     const stub = makeStub("gated-new");
     const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+
+    // Act
     openHerdrPaneForReview(newSession({ id: "ses_xyz" }), env);
+
+    // Assert
     expect(readLines(stub.logPath)).toEqual([
       "tab create --cwd /repo/work --label Rollout Plan --focus",
       "pane send-text w1:p2 cueloop ses_xyz",
@@ -98,12 +112,18 @@ describe("openHerdrPaneForReview", () => {
   });
 
   test("no-op outside herdr - no herdr process is spawned", () => {
+    // Arrange
     const stub = makeStub("gated-outside");
+
+    // Act
     openHerdrPaneForReview(newSession(), { HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath });
+
+    // Assert
     expect(existsSync(stub.logPath)).toBeFalse();
   });
 
   test("no-op for a revision - the already open pane is reused, not spammed", () => {
+    // Arrange
     const stub = makeStub("gated-revision");
     const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
     const revised = newSession({
@@ -112,7 +132,11 @@ describe("openHerdrPaneForReview", () => {
         { revision: 2, content: "# P2", submittedAt: "now" },
       ],
     });
+
+    // Act
     openHerdrPaneForReview(revised, env);
+
+    // Assert
     expect(existsSync(stub.logPath)).toBeFalse();
   });
 });

package/src/herdr-pane.ts

@@ -38,8 +38,9 @@ export interface OpenHerdrPaneOptions {
 
 /**
  * Open a herdr tab that renders the review. `tab create` prints a JSON result
- * shaped like `{ result: { pane: { id } } }` - the same `result.pane` nesting
- * focusHerdrPane reads - and the pane id drives the two follow-up steps.
+ * shaped like `{ result: { root_pane: { pane_id } } }` (verified against
+ * herdr 0.8.0; `pane get` uses a different `result.pane` nesting, which is
+ * what focusHerdrPane reads). The pane id drives the two follow-up steps.
  * Returns true when the full open-and-launch sequence completed, false on any
  * best-effort bail-out.
  */
@@ -52,8 +53,8 @@ export function openHerdrPane(options: OpenHerdrPaneOptions): boolean {
       timeout: HERDR_SPAWN_TIMEOUT_MS,
     });
     if (created.exitCode !== 0) return false;
-    const parsed = JSON.parse(created.stdout.toString()) as { result?: { pane?: { id?: string } } };
-    const paneId = parsed.result?.pane?.id;
+    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.
     const typed = Bun.spawnSync([binPath, "pane", "send-text", paneId, `cueloop ${sessionId}`], {

package/src/review.test.ts

@@ -1,9 +1,4 @@
-/**
- * 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).
- */
+/** 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";
@@ -41,11 +36,16 @@ 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);
@@ -55,14 +55,20 @@ describe("resolveWorkspace", () => {
   });
 
   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");
@@ -73,34 +79,56 @@ 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" });
+
+    // 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",
@@ -110,6 +138,8 @@ describe("openReview", () => {
         { 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);
@@ -120,10 +150,17 @@ describe("openReview", () => {
 
 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);
@@ -132,10 +169,15 @@ describe("awaitVerdict: one long-poll (the hook shape)", () => {
   });
 
   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");
@@ -145,6 +187,7 @@ describe("awaitVerdict: one long-poll (the hook shape)", () => {
 
 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({
@@ -152,33 +195,49 @@ describe("awaitVerdict: chunked loop (the pi shape)", () => {
       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/server.test.ts

@@ -27,9 +27,16 @@ afterEach(() => {
 
 describe("socket round-trip", () => {
   test("ping and full session flow over the wire", async () => {
+    // Assert
     expect((await client.ping()).pid).toBe(process.pid);
+
+    // Act
     const session = await client.sessionCreate(WS, PLAN);
+
+    // Assert
     expect(session.status).toBe("pending");
+
+    // Act
     await client.sessionAnnotate(session.id, {
       id: "a1",
       kind: "comment",
@@ -39,6 +46,8 @@ describe("socket round-trip", () => {
     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.");
   });
@@ -53,12 +62,17 @@ describe("socket round-trip", () => {
   });
 
   test("events push to subscribed connections only", async () => {
+    // Arrange
     const observer = await DaemonClient.connect({ home });
     const seen: string[] = [];
     observer.onEvent((event) => seen.push(event.event));
     await observer.subscribe();
+
+    // 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");
@@ -94,20 +108,28 @@ describe("socket round-trip", () => {
   });
 
   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("two clients see the same state (thin-renderer model)", async () => {
+    // Arrange
     const second = await DaemonClient.connect({ home });
+
+    // 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();
   });
@@ -118,15 +140,24 @@ describe("large payloads survive socket backpressure", () => {
     // 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

@@ -251,7 +251,7 @@ export class DaemonServer {
       }
       case "session.submitRevision": {
         const params = parseParams("session.submitRevision", request.params);
-        return core.sessionSubmitRevision(params.id, params.content);
+        return core.sessionSubmitRevision(params.id, params.content, params.addressedAnnotationIds);
       }
       default:
         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,48 @@
+/**
+ * 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)}`);
+  }
+  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;
+}

package/src/single-instance.test.ts

@@ -35,21 +35,27 @@ function server(): DaemonServer {
 
 describe("one daemon per home", () => {
   test("the second start is refused instead of stealing the socket", () => {
+    // Arrange
     const first = server();
     const path = first.start();
     expect(path).toBe(socketPath(home));
     const second = server();
+
+    // Assert
     expect(second.start()).toBeNull();
     // the winner's socket survives untouched
     expect(existsSync(path!)).toBe(true);
   });
 
   test("clients keep talking to the one live daemon after a refused start", async () => {
+    // Arrange
     const first = server();
     first.start();
     const created = first.core.sessionCreate({ workspace: WS, artifact: PLAN });
     server().start(); // refused
     const client = await DaemonClient.connect({ home });
+
+    // Assert
     try {
       // no split brain: the session created on the winner is visible
       expect((await client.sessionGet(created.id)).id).toBe(created.id);
@@ -60,29 +66,40 @@ describe("one daemon per home", () => {
   });
 
   test("a stale lock from a crashed daemon is reclaimed", () => {
+    // Arrange
     // a pid that cannot be running (init is never a cueloop daemon, and this
     // simulates the record a crashed process leaves behind)
     writeFileSync(lockPath(home), "999999");
     const daemonServer = server();
+
+    // Assert
     expect(daemonServer.start()).toBe(socketPath(home));
   });
 
   test("stopping releases the lock so a restart works", () => {
+    // Arrange
     const first = server();
     first.start();
+
+    // Act
     first.stop();
+
+    // Assert
     expect(existsSync(lockPath(home))).toBe(false);
     const second = server();
     expect(second.start()).toBe(socketPath(home));
   });
 
   test("concurrent autostarts converge on a single daemon", async () => {
+    // Act
     // several clients race to autostart; all must end up on the same daemon
     const clients = await Promise.all([
       DaemonClient.connect({ home, autostart: true }),
       DaemonClient.connect({ home, autostart: true }),
       DaemonClient.connect({ home, autostart: true }),
     ]);
+
+    // Assert
     try {
       const pids = await Promise.all(clients.map((client) => client.ping()));
       const unique = new Set(pids.map((ping) => ping.pid));

package/src/validate.test.ts

@@ -38,10 +38,13 @@ describe("method allowlist", () => {
 
 describe("parseParams", () => {
   test("accepts a well-formed create and defaults meta", () => {
+    // Act
     const params = parseParams("session.create", {
       workspace: { repoRoot: "/repo", branch: "main" },
       artifact: { type: "plan", content: "# P" },
     });
+
+    // Assert
     expect(params.artifact.meta).toEqual({});
   });
 
@@ -81,10 +84,13 @@ describe("parseParams", () => {
   });
 
   test("annotation kinds stay open (extension kinds are allowed)", () => {
+    // Act
     const params = parseParams("session.annotate", {
       id: "s",
       annotation: { id: "a1", kind: "praise", anchor: { quote: "x" }, body: "nice" },
     });
+
+    // Assert
     expect(params.annotation.kind).toBe("praise");
     expect(params.annotation.anchor.prefix).toBe("");
   });
@@ -122,13 +128,19 @@ describe("validateSessionRecord", () => {
   });
 
   test("rejects a foreign schema version with a readable reason", () => {
+    // Act
     const result = validateSessionRecord({ ...record, schemaVersion: "99" });
+
+    // Assert
     expect(result.ok).toBe(false);
     if (!result.ok) expect(result.error).toContain("schemaVersion");
   });
 
   test("rejects a structurally broken record", () => {
+    // Act
     const result = validateSessionRecord({ ...record, revisions: "nope" });
+
+    // Assert
     expect(result.ok).toBe(false);
   });
 });
@@ -159,6 +171,8 @@ describe("wire pins", () => {
     anchor: fullAnchor,
     body: "b",
     orphan: false,
+    author: "SHA256:abc",
+    resolution: { revision: 2, source: "agent" },
     createdAt: "now",
   };
   const fullArtifact: Required<Artifact> = { type: "plan", content: "# P", meta: fullMeta };
@@ -198,12 +212,17 @@ describe("wire pins", () => {
   test("a fully-populated meta survives validation and DaemonCore unchanged", () => {
     const home = mkdtempSync(join(tmpdir(), "cueloop-val-"));
     try {
+      // Arrange
       const params = parseParams("session.create", {
         workspace: fullWorkspace,
         artifact: { type: "plan", content: "# P", meta: fullMeta },
       });
       const core = new DaemonCore(home);
+
+      // Act
       const created = core.sessionCreate(params);
+
+      // Assert
       expect(core.sessionGet(created.id).artifact.meta).toEqual(fullMeta);
     } finally {
       rmSync(home, { recursive: true, force: true });

package/src/validate.ts

@@ -72,6 +72,13 @@ export const AnnotationSchema = v.object({
   anchor: AnchorSchema,
   body: v.string(),
   orphan: v.optional(v.boolean()),
+  author: v.optional(v.string()),
+  resolution: v.optional(
+    v.object({
+      revision: v.number(),
+      source: v.picklist(["agent", "drift"]),
+    }),
+  ),
 } satisfies EntriesOf<Omit<Annotation, "createdAt">>);
 
 const SessionId = NonEmpty;
@@ -101,7 +108,12 @@ export const Params = {
     verdictKind: v.picklist(["comment", "approve", "request_changes"]),
     summary: v.optional(v.string(), ""),
   }),
-  "session.submitRevision": v.object({ id: SessionId, content: v.string() }),
+  "session.submitRevision": v.object({
+    id: SessionId,
+    content: v.string(),
+    /** Annotation ids the agent acted on; each is marked addressed. */
+    addressedAnnotationIds: v.optional(v.array(NonEmpty), []),
+  }),
   "events.subscribe": v.object({}),
   "daemon.ping": v.object({}),
   "daemon.shutdown": v.object({}),