@cueloop/daemon 0.1.0-alpha.15 → 0.1.0-alpha.17

package/src/review.ts

@@ -2,12 +2,12 @@
  * 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 (#14) onto the agent contract through verdictResponse. An
+ * 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 type { ArtifactType, ReviewSession, WorkspaceKey } from "@cueloop/schema";
+import { newAnnotationId, type ArtifactType, type ReviewSession, type WorkspaceKey } from "@cueloop/schema";
 import { verdictResponse } from "./api";
 import type { DaemonClient } from "./client";
 
@@ -26,16 +26,16 @@ async function git(args: string[], cwd: string): Promise<string | null> {
   }
 }
 
-/** Workspace key resolution (#9): repo root + branch from the cwd. */
+/** 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(md: string): string | undefined {
-  const m = md.match(/^#\s+(.+)$/m);
-  return m?.[1]?.trim();
+function firstHeading(markdown: string): string | undefined {
+  const headingMatch = markdown.match(/^#\s+(.+)$/m);
+  return headingMatch?.[1]?.trim();
 }
 
 export interface OpenReviewOptions {
@@ -53,6 +53,31 @@ export interface OpenReviewOptions {
   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 {
@@ -90,13 +115,13 @@ function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Pro
     };
     signal.addEventListener("abort", onAbort, { once: true });
     promise.then(
-      (v) => {
+      (value) => {
         signal.removeEventListener("abort", onAbort);
-        resolve(v);
+        resolve(value);
       },
-      (e) => {
+      (error) => {
         signal.removeEventListener("abort", onAbort);
-        reject(e);
+        reject(error);
       },
     );
   });
@@ -115,11 +140,11 @@ export class ReviewHandle {
   /**
    * 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, #14). With only timeoutMs this is one long-poll;
+   * (verdicts outlive waits). With only timeoutMs this is one long-poll;
    * pollMs/onProgress/signal switch to the chunked loop.
    */
-  async awaitVerdict(opts: AwaitVerdictOptions): Promise<VerdictOutcome | "pending"> {
-    const { timeoutMs, pollMs, onProgress, signal } = opts;
+  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);
@@ -145,30 +170,39 @@ function outcome(session: ReviewSession): VerdictOutcome {
 }
 
 /** Open a review session (or revise the agent session's existing one) and hand back the wait surface. */
-export async function openReview(client: DaemonClient, opts: OpenReviewOptions): Promise<ReviewHandle> {
-  const cwd = opts.cwd ?? process.cwd();
-  const workspace = opts.workspace ?? (await resolveWorkspace(cwd));
+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 (opts.agentSessionId !== undefined) {
+  if (options.agentSessionId !== undefined) {
     const existing = (await client.sessionList()).find(
-      (s) => s.artifact.meta.agentSessionId === opts.agentSessionId,
+      (candidate) => candidate.artifact.meta.agentSessionId === options.agentSessionId,
     );
     if (existing !== undefined) {
-      return new ReviewHandle(client, await client.sessionSubmitRevision(existing.id, opts.content));
+      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);
     }
   }
-  const session = await client.sessionCreate(workspace, {
-    type: opts.type,
-    content: opts.content,
+  let session = await client.sessionCreate(workspace, {
+    type: options.type,
+    content: options.content,
     meta: {
-      agent: opts.agent,
-      agentSessionId: opts.agentSessionId,
-      planPath: opts.planPath,
-      pr: opts.pr,
-      herdrPane: opts.herdrPane,
-      title: opts.title ?? (opts.type === "plan" ? firstHeading(opts.content) : undefined),
+      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

@@ -28,16 +28,16 @@ afterEach(() => {
 describe("socket round-trip", () => {
   test("ping and full session flow over the wire", async () => {
     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, {
+    const session = await client.sessionCreate(WS, PLAN);
+    expect(session.status).toBe("pending");
+    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)!;
     expect(resolved.verdict!.kind).toBe("request_changes");
     expect(resolved.verdict!.feedback).toContain("More detail please.");
@@ -47,18 +47,18 @@ 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 () => {
     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", "");
+    const session = await client.sessionCreate(WS, PLAN);
+    await client.sessionResolve(session.id, "approve", "");
     // events are pushed async over the socket; give the loop a beat
     await Bun.sleep(50);
     expect(seen).toContain("session.created");
@@ -71,43 +71,43 @@ 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 () => {
-    const s = await client.sessionCreate(WS, {
+    const session = await client.sessionCreate(WS, {
       type: "plan",
       content: "# P",
       meta: { agent: "claude-code", herdrPane: "%7" },
     });
-    const got = await client.sessionGet(s.id);
+    const got = await client.sessionGet(session.id);
     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 () => {
     const second = await DaemonClient.connect({ home });
-    const s = await client.sessionCreate(WS, PLAN);
-    const fromSecond = await second.sessionGet(s.id);
+    const session = await client.sessionCreate(WS, PLAN);
+    const fromSecond = await second.sessionGet(session.id);
     expect(fromSecond.artifact.content).toBe(PLAN.content);
     second.close();
   });

package/src/server.ts

@@ -1,6 +1,6 @@
 /**
  * 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.
  */
 
@@ -11,7 +11,7 @@ import { isKnownMethod, parseParams } from "./validate";
 import { BackpressureWriter, LineBuffer, type Request } from "./protocol";
 import { cueloopHome, lockPath, pidPath, socketPath } from "./paths";
 
-interface Conn {
+interface Connection {
   write(data: string): void;
   subscribed: boolean;
 }
@@ -33,20 +33,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));
   }
 
   /**
@@ -119,19 +119,19 @@ export class DaemonServer {
     // socket file left behind is stale
     if (existsSync(path)) rmSync(path, { force: true });
     const self = this;
-    this.server = Bun.listen<{ buffer: LineBuffer; conn: Conn; writer: BackpressureWriter }>({
+    this.server = Bun.listen<{ buffer: LineBuffer; connection: Connection; writer: BackpressureWriter }>({
       unix: path,
       socket: {
         open(socket) {
           const writer = new BackpressureWriter(socket);
-          const conn: Conn = { write: (data) => writer.write(data), subscribed: false };
-          socket.data = { buffer: new LineBuffer(), conn, writer };
-          self.conns.add(conn);
+          const connection: Connection = { write: (data) => writer.write(data), subscribed: false };
+          socket.data = { buffer: new LineBuffer(), connection, writer };
+          self.connections.add(connection);
           self.scheduleIdleCheck();
         },
         data(socket, data) {
           socket.data.buffer.push(data.toString(), (line) => {
-            void self.handleLine(socket.data.conn, line);
+            void self.respondToRequestLine(socket.data.connection, line);
           });
         },
         drain(socket) {
@@ -140,7 +140,7 @@ export class DaemonServer {
           socket.data?.writer.drain();
         },
         close(socket) {
-          self.conns.delete(socket.data.conn);
+          self.connections.delete(socket.data.connection);
           self.scheduleIdleCheck();
         },
         error() {},
@@ -161,9 +161,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();
   }
 
@@ -172,7 +172,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 {
@@ -181,31 +181,31 @@ 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)}`);
     }
     const core = this.core;
-    switch (req.method) {
+    switch (request.method) {
       case "daemon.ping":
         return { pid: process.pid };
       case "daemon.shutdown":
@@ -215,42 +215,46 @@ 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);
       }
       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.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);
       }
       default:
-        throw new DaemonError("unknown_method", `unknown method ${req.method}`);
+        throw new DaemonError("unknown_method", `unknown method ${request.method}`);
     }
   }
 }

package/src/single-instance.test.ts

@@ -1,5 +1,5 @@
 /**
- * Single-instance guarantee (#14): one daemon per home. Two daemons over one
+ * Single-instance guarantee: one daemon per home. Two daemons over one
  * state directory means divergent in-memory sessions and clients seeing
  * whichever half they connect to.
  */
@@ -23,14 +23,14 @@ beforeEach(() => {
   home = mkdtempSync(join(tmpdir(), "cueloop-lock-"));
 });
 afterEach(() => {
-  for (const s of servers.splice(0)) s.stop();
+  for (const runningServer of servers.splice(0)) runningServer.stop();
   rmSync(home, { recursive: true, force: true });
 });
 
 function server(): DaemonServer {
-  const s = new DaemonServer({ home, idleExitMs: 0 });
-  servers.push(s);
-  return s;
+  const daemonServer = new DaemonServer({ home, idleExitMs: 0 });
+  servers.push(daemonServer);
+  return daemonServer;
 }
 
 describe("one daemon per home", () => {
@@ -63,8 +63,8 @@ describe("one daemon per home", () => {
     // 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 s = server();
-    expect(s.start()).toBe(socketPath(home));
+    const daemonServer = server();
+    expect(daemonServer.start()).toBe(socketPath(home));
   });
 
   test("stopping releases the lock so a restart works", () => {
@@ -84,12 +84,12 @@ describe("one daemon per home", () => {
       DaemonClient.connect({ home, autostart: true }),
     ]);
     try {
-      const pids = await Promise.all(clients.map((c) => c.ping()));
-      const unique = new Set(pids.map((p) => p.pid));
+      const pids = await Promise.all(clients.map((client) => client.ping()));
+      const unique = new Set(pids.map((ping) => ping.pid));
       expect(unique.size).toBe(1);
       // and state is shared: one client's session is visible to the others
-      const s = await clients[0]!.sessionCreate(WS, PLAN);
-      expect((await clients[2]!.sessionGet(s.id)).id).toBe(s.id);
+      const session = await clients[0]!.sessionCreate(WS, PLAN);
+      expect((await clients[2]!.sessionGet(session.id)).id).toBe(session.id);
     } finally {
       for (const c of clients) c.close();
       // the autostarted daemon is not one of `servers` - shut it down

package/src/store.ts

@@ -1,5 +1,5 @@
 /**
- * Session persistence (#14): one JSON document per session, every write
+ * Session persistence: one JSON document per session, every write
  * through a temp file + atomic rename so a crash mid-write can never leave
  * a corrupt record. Recovery is a read-only scan; records that fail to
  * parse are skipped and reported, never deleted.
@@ -49,15 +49,15 @@ export class SessionStore {
   }
 
   list(): ReviewSession[] {
-    return [...this.sessions.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    return [...this.sessions.values()].sort((left, right) => left.createdAt.localeCompare(right.createdAt));
   }
 
   upsert(session: ReviewSession): void {
     this.sessions.set(session.id, session);
     const path = join(this.dir, `${session.id}.json`);
-    const tmp = path + ".tmp";
-    writeFileSync(tmp, JSON.stringify(session, null, 2));
-    renameSync(tmp, path);
+    const tempPath = path + ".tmp";
+    writeFileSync(tempPath, JSON.stringify(session, null, 2));
+    renameSync(tempPath, path);
   }
 
   delete(id: string): boolean {

package/src/validate.test.ts

@@ -38,11 +38,11 @@ describe("method allowlist", () => {
 
 describe("parseParams", () => {
   test("accepts a well-formed create and defaults meta", () => {
-    const p = parseParams("session.create", {
+    const params = parseParams("session.create", {
       workspace: { repoRoot: "/repo", branch: "main" },
       artifact: { type: "plan", content: "# P" },
     });
-    expect(p.artifact.meta).toEqual({});
+    expect(params.artifact.meta).toEqual({});
   });
 
   test("rejects a missing workspace with a pathed message", () => {
@@ -81,12 +81,22 @@ describe("parseParams", () => {
   });
 
   test("annotation kinds stay open (extension kinds are allowed)", () => {
-    const p = parseParams("session.annotate", {
+    const params = parseParams("session.annotate", {
       id: "s",
       annotation: { id: "a1", kind: "praise", anchor: { quote: "x" }, body: "nice" },
     });
-    expect(p.annotation.kind).toBe("praise");
-    expect(p.annotation.anchor.prefix).toBe("");
+    expect(params.annotation.kind).toBe("praise");
+    expect(params.annotation.anchor.prefix).toBe("");
+  });
+
+  test("setViewed takes a full path list and rejects non-string entries", () => {
+    expect(parseParams("session.setViewed", { id: "s", viewedPaths: ["src/a.ts", "src/b.ts"] }).viewedPaths).toEqual([
+      "src/a.ts",
+      "src/b.ts",
+    ]);
+    expect(parseParams("session.setViewed", { id: "s", viewedPaths: [] }).viewedPaths).toEqual([]);
+    expect(() => parseParams("session.setViewed", { id: "s", viewedPaths: [1] })).toThrow(/viewedPaths/);
+    expect(() => parseParams("session.setViewed", { id: "s" })).toThrow(/viewedPaths/);
   });
 
   test("null params are treated as empty", () => {
@@ -112,25 +122,25 @@ describe("validateSessionRecord", () => {
   });
 
   test("rejects a foreign schema version with a readable reason", () => {
-    const r = validateSessionRecord({ ...record, schemaVersion: "99" });
-    expect(r.ok).toBe(false);
-    if (!r.ok) expect(r.error).toContain("schemaVersion");
+    const result = validateSessionRecord({ ...record, schemaVersion: "99" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("schemaVersion");
   });
 
   test("rejects a structurally broken record", () => {
-    const r = validateSessionRecord({ ...record, revisions: "nope" });
-    expect(r.ok).toBe(false);
+    const result = validateSessionRecord({ ...record, revisions: "nope" });
+    expect(result.ok).toBe(false);
   });
 });
 
 /**
- * Wire pins (#70): every schema's entries must cover exactly the keys of the
+ * Wire pins: every schema's entries must cover exactly the keys of the
  * schema type it mirrors. Runtime complement to the compile-time EntriesOf
  * check - the samples are fully populated and typed, so a new field in
  * @cueloop/schema shows up here too.
  */
 describe("wire pins", () => {
-  const keys = (o: object) => Object.keys(o).sort();
+  const keys = (subject: object) => Object.keys(subject).sort();
   const entryKeys = (schema: { entries: object }) => Object.keys(schema.entries).sort();
 
   const fullMeta: Required<ArtifactMeta> = {
@@ -163,6 +173,7 @@ describe("wire pins", () => {
     revisions: [fullRevision],
     annotations: [fullAnnotation],
     workingCopy: "# P edited",
+    viewedPaths: ["src/a.ts"],
     verdict: fullVerdict,
     status: "pending",
     createdAt: "now",