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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.17",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -9,7 +9,7 @@
     "./review": "./src/review.ts"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.15",
+    "@cueloop/schema": "0.1.0-alpha.17",
     "valibot": "^1.4.2"
   },
   "publishConfig": {

package/src/api.test.ts

@@ -24,42 +24,42 @@ afterEach(() => rmSync(home, { recursive: true, force: true }));
 
 describe("session lifecycle", () => {
   test("create → get → list", () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    expect(s.status).toBe("pending");
-    expect(s.revisions.length).toBe(1);
-    expect(core.sessionGet(s.id).id).toBe(s.id);
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    expect(session.status).toBe("pending");
+    expect(session.revisions.length).toBe(1);
+    expect(core.sessionGet(session.id).id).toBe(session.id);
     expect(core.sessionList({ status: "pending" }).length).toBe(1);
   });
 
   test("annotate upserts by id; remove deletes", () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    core.sessionAnnotate(s.id, {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionAnnotate(session.id, {
       id: "a1",
       kind: "comment",
       anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
       body: "How carefully?",
     });
-    core.sessionAnnotate(s.id, {
+    core.sessionAnnotate(session.id, {
       id: "a1",
       kind: "comment",
       anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
       body: "Define carefully.",
     });
-    expect(core.sessionGet(s.id).annotations.length).toBe(1);
-    expect(core.sessionGet(s.id).annotations[0]!.body).toBe("Define carefully.");
-    core.sessionRemoveAnnotation(s.id, "a1");
-    expect(core.sessionGet(s.id).annotations.length).toBe(0);
+    expect(core.sessionGet(session.id).annotations.length).toBe(1);
+    expect(core.sessionGet(session.id).annotations[0]!.body).toBe("Define carefully.");
+    core.sessionRemoveAnnotation(session.id, "a1");
+    expect(core.sessionGet(session.id).annotations.length).toBe(0);
   });
 
   test("resolve produces feedback.md and maps to the agent contract", () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    core.sessionAnnotate(s.id, {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionAnnotate(session.id, {
       id: "a1",
       kind: "comment",
       anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
       body: "Spell out the steps.",
     });
-    const resolved = core.sessionResolve(s.id, "request_changes", "Needs detail.");
+    const resolved = core.sessionResolve(session.id, "request_changes", "Needs detail.");
     expect(resolved.verdict!.feedback).toContain("# Review: request changes");
     expect(resolved.verdict!.feedback).toContain("> carefully");
     expect(verdictResponse(resolved)).toEqual({ allow: false, feedback: resolved.verdict!.feedback });
@@ -69,26 +69,40 @@ describe("session lifecycle", () => {
   });
 
   test("mutating a resolved session throws", () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    core.sessionResolve(s.id, "approve", "");
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionResolve(session.id, "approve", "");
     expect(() =>
-      core.sessionAnnotate(s.id, { id: "a1", kind: "comment", anchor: { quote: "x", prefix: "", suffix: "" }, body: "b" }),
+      core.sessionAnnotate(session.id, { id: "a1", kind: "comment", anchor: { quote: "x", prefix: "", suffix: "" }, body: "b" }),
     ).toThrow("already resolved");
   });
 
   test("working copy stores edits and clears on revert or no-op", () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    core.sessionSetWorkingCopy(s.id, PLAN.content.replace("carefully", "very carefully"));
-    expect(core.sessionGet(s.id).workingCopy).toContain("very carefully");
-    core.sessionSetWorkingCopy(s.id, PLAN.content);
-    expect(core.sessionGet(s.id).workingCopy).toBeUndefined();
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionSetWorkingCopy(session.id, PLAN.content.replace("carefully", "very carefully"));
+    expect(core.sessionGet(session.id).workingCopy).toContain("very carefully");
+    core.sessionSetWorkingCopy(session.id, PLAN.content);
+    expect(core.sessionGet(session.id).workingCopy).toBeUndefined();
+  });
+
+  test("viewed paths merge, dedupe, clear on empty, and survive a daemon restart", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionSetViewed(session.id, ["src/a.ts", "src/b.ts", "src/a.ts"]);
+    expect(core.sessionGet(session.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts"]);
+    // merge-additive: a stale client sending only its own new mark loses nothing
+    core.sessionSetViewed(session.id, ["src/c.ts"]);
+    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"]);
+    core.sessionSetViewed(session.id, []);
+    expect(core.sessionGet(session.id).viewedPaths).toBeUndefined();
   });
 
   test("revision reopens the session and resets working copy + verdict", () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    core.sessionSetWorkingCopy(s.id, PLAN.content + "\nedit");
-    core.sessionResolve(s.id, "request_changes", "redo");
-    const revised = core.sessionSubmitRevision(s.id, "# Plan v2\n");
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionSetWorkingCopy(session.id, PLAN.content + "\nedit");
+    core.sessionResolve(session.id, "request_changes", "redo");
+    const revised = core.sessionSubmitRevision(session.id, "# Plan v2\n");
     expect(revised.status).toBe("pending");
     expect(revised.verdict).toBeNull();
     expect(revised.workingCopy).toBeUndefined();
@@ -99,37 +113,37 @@ describe("session lifecycle", () => {
 
 describe("the wait contract: verdicts outlive waits", () => {
   test("wait resolves when the verdict arrives", async () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    const wait = core.sessionWait(s.id, 5_000);
-    core.sessionResolve(s.id, "approve", "");
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const wait = core.sessionWait(session.id, 5_000);
+    core.sessionResolve(session.id, "approve", "");
     const resolved = await wait;
     expect(resolved!.verdict!.kind).toBe("approve");
   });
 
   test("wait times out to null; a later wait collects the stored verdict", async () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    const first = await core.sessionWait(s.id, 30);
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const first = await core.sessionWait(session.id, 30);
     expect(first).toBeNull();
-    core.sessionResolve(s.id, "request_changes", "later");
-    const second = await core.sessionWait(s.id, 30);
+    core.sessionResolve(session.id, "request_changes", "later");
+    const second = await core.sessionWait(session.id, 30);
     expect(second!.verdict!.summary).toBe("later");
   });
 
   test("multiple waiters all resolve", async () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    const waits = [core.sessionWait(s.id, 5_000), core.sessionWait(s.id, 5_000)];
-    core.sessionResolve(s.id, "approve", "");
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const waits = [core.sessionWait(session.id, 5_000), core.sessionWait(session.id, 5_000)];
+    core.sessionResolve(session.id, "approve", "");
     const results = await Promise.all(waits);
-    expect(results.every((r) => r?.status === "resolved")).toBe(true);
+    expect(results.every((result) => result?.status === "resolved")).toBe(true);
   });
 });
 
 describe("persistence and recovery", () => {
   test("sessions survive a daemon restart", () => {
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    core.sessionResolve(s.id, "approve", "done");
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionResolve(session.id, "approve", "done");
     const reborn = new DaemonCore(home);
-    const recovered = reborn.sessionGet(s.id);
+    const recovered = reborn.sessionGet(session.id);
     expect(recovered.verdict!.summary).toBe("done");
   });
 
@@ -147,10 +161,10 @@ describe("persistence and recovery", () => {
 describe("events", () => {
   test("lifecycle events fire in order", () => {
     const seen: string[] = [];
-    core.onEvent((e) => seen.push(e.event));
-    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
-    core.sessionAnnotate(s.id, { id: "a1", kind: "comment", anchor: { quote: "thing", prefix: "", suffix: "" }, body: "b" });
-    core.sessionResolve(s.id, "approve", "");
+    core.onEvent((event) => seen.push(event.event));
+    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", "");
     expect(seen).toEqual(["session.created", "inbox.changed", "session.updated", "session.resolved", "inbox.changed"]);
   });
 });

package/src/api.ts

@@ -1,5 +1,5 @@
 /**
- * The daemon's method surface (#14). Transport-independent: the socket
+ * The daemon's method surface. Transport-independent: the socket
  * server and the in-process test harness both call these handlers.
  * The wait contract: verdicts outlive waits - session.wait long-polls,
  * and a verdict resolved while nobody waited is delivered on next contact.
@@ -31,7 +31,7 @@ export interface DaemonEvent {
   sessionId: string;
 }
 
-type EventListener = (e: DaemonEvent) => void;
+type EventListener = (event: DaemonEvent) => void;
 
 export class DaemonCore {
   readonly store: SessionStore;
@@ -50,12 +50,12 @@ export class DaemonCore {
   }
 
   private emit(event: EventName, sessionId: string): void {
-    for (const l of this.listeners) l({ event, sessionId });
+    for (const listener of this.listeners) listener({ event, sessionId });
   }
 
   /** True when nothing awaits a verdict - drives idle-exit. */
   hasPendingSessions(): boolean {
-    return this.store.list().some((s) => s.status === "pending");
+    return this.store.list().some((session) => session.status === "pending");
   }
 
   sessionCreate(params: { workspace: WorkspaceKey; artifact: Artifact }): ReviewSession {
@@ -78,16 +78,16 @@ export class DaemonCore {
   }
 
   sessionGet(id: string): ReviewSession {
-    const s = this.store.get(id);
-    if (!s) throw new DaemonError("not_found", `no session ${id}`);
-    return s;
+    const session = this.store.get(id);
+    if (!session) throw new DaemonError("not_found", `no session ${id}`);
+    return session;
   }
 
   sessionList(filter?: { status?: "pending" | "resolved"; workspace?: Partial<WorkspaceKey> }): ReviewSession[] {
-    return this.store.list().filter((s) => {
-      if (filter?.status && s.status !== filter.status) return false;
-      if (filter?.workspace?.repoRoot && s.workspace.repoRoot !== filter.workspace.repoRoot) return false;
-      if (filter?.workspace?.branch && s.workspace.branch !== filter.workspace.branch) return false;
+    return this.store.list().filter((session) => {
+      if (filter?.status && session.status !== filter.status) return false;
+      if (filter?.workspace?.repoRoot && session.workspace.repoRoot !== filter.workspace.repoRoot) return false;
+      if (filter?.workspace?.branch && session.workspace.branch !== filter.workspace.branch) return false;
       return true;
     });
   }
@@ -98,16 +98,16 @@ export class DaemonCore {
    * still pending - the caller re-polls later; the verdict is never lost).
    */
   sessionWait(id: string, timeoutMs: number): Promise<ReviewSession | null> {
-    const s = this.sessionGet(id);
-    if (s.status === "resolved") return Promise.resolve(s);
+    const current = this.sessionGet(id);
+    if (current.status === "resolved") return Promise.resolve(current);
     return new Promise((resolve) => {
       const list = this.waiters.get(id) ?? [];
       let done = false;
       const timer = setTimeout(() => {
         if (done) return;
         done = true;
-        const idx = list.indexOf(waiter);
-        if (idx !== -1) list.splice(idx, 1);
+        const waiterIndex = list.indexOf(waiter);
+        if (waiterIndex !== -1) list.splice(waiterIndex, 1);
         resolve(null);
       }, timeoutMs);
       const waiter = (session: ReviewSession) => {
@@ -122,72 +122,86 @@ export class DaemonCore {
   }
 
   sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): ReviewSession {
-    const s = this.mutable(id);
-    const existing = s.annotations.findIndex((a) => a.id === annotation.id);
+    const session = this.mutable(id);
+    const existing = session.annotations.findIndex((candidate) => candidate.id === annotation.id);
     const full: Annotation = { ...annotation, createdAt: new Date().toISOString() };
-    if (existing === -1) s.annotations.push(full);
-    else s.annotations[existing] = { ...full, createdAt: s.annotations[existing]!.createdAt };
-    this.store.upsert(s);
+    if (existing === -1) session.annotations.push(full);
+    else session.annotations[existing] = { ...full, createdAt: session.annotations[existing]!.createdAt };
+    this.store.upsert(session);
     this.emit("session.updated", id);
-    return s;
+    return session;
   }
 
   sessionRemoveAnnotation(id: string, annotationId: string): ReviewSession {
-    const s = this.mutable(id);
-    s.annotations = s.annotations.filter((a) => a.id !== annotationId);
-    this.store.upsert(s);
+    const session = this.mutable(id);
+    session.annotations = session.annotations.filter((candidate) => candidate.id !== annotationId);
+    this.store.upsert(session);
     this.emit("session.updated", id);
-    return s;
+    return session;
   }
 
   /** The reviewer's working copy; undefined clears it (revert all edits). */
   sessionSetWorkingCopy(id: string, workingCopy: string | undefined): ReviewSession {
-    const s = this.mutable(id);
-    if (workingCopy === undefined || workingCopy === s.artifact.content) delete s.workingCopy;
-    else s.workingCopy = workingCopy;
-    this.store.upsert(s);
+    const session = this.mutable(id);
+    if (workingCopy === undefined || workingCopy === session.artifact.content) delete session.workingCopy;
+    else session.workingCopy = workingCopy;
+    this.store.upsert(session);
     this.emit("session.updated", id);
-    return s;
+    return session;
+  }
+
+  /**
+   * The guided walk's viewed marks. Merge-additive: walking only ever adds
+   * marks, so concurrent or stale clients converge instead of overwriting
+   * each other. An empty array is the explicit reset.
+   */
+  sessionSetViewed(id: string, viewedPaths: string[]): ReviewSession {
+    const session = this.mutable(id);
+    if (viewedPaths.length === 0) delete session.viewedPaths;
+    else session.viewedPaths = [...new Set([...(session.viewedPaths ?? []), ...viewedPaths])];
+    this.store.upsert(session);
+    this.emit("session.updated", id);
+    return session;
   }
 
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): ReviewSession {
-    const s = this.mutable(id);
+    const session = this.mutable(id);
     const verdict: Verdict = {
       kind: verdictKind,
       summary,
-      feedback: feedbackForSession(s, verdictKind, summary),
+      feedback: feedbackForSession(session, verdictKind, summary),
       resolvedAt: new Date().toISOString(),
     };
-    s.verdict = verdict;
-    s.status = "resolved";
-    this.store.upsert(s);
+    session.verdict = verdict;
+    session.status = "resolved";
+    this.store.upsert(session);
     const parked = this.waiters.get(id) ?? [];
     this.waiters.delete(id);
-    for (const w of parked) w(s);
+    for (const parkedWaiter of parked) parkedWaiter(session);
     this.emit("session.resolved", id);
     this.emit("inbox.changed", id);
-    return s;
+    return session;
   }
 
   /** Agent resubmits: new revision becomes the artifact, session reopens. */
   sessionSubmitRevision(id: string, content: string): ReviewSession {
-    const s = this.sessionGet(id);
+    const session = this.sessionGet(id);
     const now = new Date().toISOString();
-    s.revisions.push({ revision: s.revisions.length + 1, content, submittedAt: now });
-    s.artifact = { ...s.artifact, content };
-    delete s.workingCopy;
-    s.verdict = null;
-    s.status = "pending";
-    this.store.upsert(s);
+    session.revisions.push({ revision: session.revisions.length + 1, content, submittedAt: now });
+    session.artifact = { ...session.artifact, content };
+    delete session.workingCopy;
+    session.verdict = null;
+    session.status = "pending";
+    this.store.upsert(session);
     this.emit("session.revised", id);
     this.emit("inbox.changed", id);
-    return s;
+    return session;
   }
 
   private mutable(id: string): ReviewSession {
-    const s = this.sessionGet(id);
-    if (s.status === "resolved") throw new DaemonError("resolved", `session ${id} is already resolved`);
-    return s;
+    const session = this.sessionGet(id);
+    if (session.status === "resolved") throw new DaemonError("resolved", `session ${id} is already resolved`);
+    return session;
   }
 }
 

package/src/client.ts

@@ -1,6 +1,6 @@
 /**
  * Daemon client: the one library every consumer shares - CLI verbs, the TUI,
- * adapters, and tests. Also owns the lazy-launch story (#14): connect() with
+ * adapters, and tests. Also owns the lazy-launch story: connect() with
  * autostart spawns a detached daemon when the socket is dead, then attaches.
  */
 
@@ -15,25 +15,25 @@ export interface ConnectOptions {
   autostart?: boolean;
 }
 
-type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void };
+type PendingRequest = { resolve: (value: unknown) => void; reject: (error: Error) => void };
 
 export class DaemonClient {
   private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
   private writer: BackpressureWriter | null = null;
-  private pending = new Map<number, Pending>();
+  private pending = new Map<number, PendingRequest>();
   private nextId = 1;
-  private eventListeners = new Set<(e: EventFrame) => void>();
+  private eventListeners = new Set<(event: EventFrame) => void>();
   private closed = false;
 
-  static async connect(opts: ConnectOptions = {}): Promise<DaemonClient> {
-    const home = opts.home ?? cueloopHome();
+  static async connect(options: ConnectOptions = {}): Promise<DaemonClient> {
+    const home = options.home ?? cueloopHome();
     const path = socketPath(home);
     const client = new DaemonClient();
     try {
       await client.dial(path);
       return client;
     } catch (err) {
-      if (!opts.autostart) throw err;
+      if (!options.autostart) throw err;
     }
     // Socket dead or absent: clean a stale file and spawn the daemon detached.
     if (existsSync(path)) rmSync(path, { force: true });
@@ -41,17 +41,17 @@ export class DaemonClient {
     // Generous: a cold or loaded machine pays for a runtime start before the
     // socket exists, and giving up early looks to callers like a broken daemon.
     const deadline = Date.now() + Number(process.env.CUELOOP_START_TIMEOUT_MS ?? 30_000);
-    let lastErr: unknown;
+    let lastError: unknown;
     while (Date.now() < deadline) {
       try {
         await client.dial(path);
         return client;
       } catch (err) {
-        lastErr = err;
+        lastError = err;
         await Bun.sleep(50);
       }
     }
-    throw new Error(`daemon did not come up at ${path}: ${String(lastErr)}`);
+    throw new Error(`daemon did not come up at ${path}: ${String(lastError)}`);
   }
 
   private async dial(path: string): Promise<void> {
@@ -61,14 +61,14 @@ export class DaemonClient {
       unix: path,
       socket: {
         data(_socket, data) {
-          buffer.push(data.toString(), (line) => self.handleFrame(line));
+          buffer.push(data.toString(), (line) => self.routeInboundFrame(line));
         },
         drain() {
           self.writer?.drain();
         },
         close() {
           self.closed = true;
-          for (const p of self.pending.values()) p.reject(new Error("daemon connection closed"));
+          for (const pendingRequest of self.pending.values()) pendingRequest.reject(new Error("daemon connection closed"));
           self.pending.clear();
         },
         error() {},
@@ -80,12 +80,12 @@ export class DaemonClient {
     await this.request("daemon.ping", {}, 2_000);
   }
 
-  onEvent(listener: (e: EventFrame) => void): () => void {
+  onEvent(listener: (event: EventFrame) => void): () => void {
     this.eventListeners.add(listener);
     return () => this.eventListeners.delete(listener);
   }
 
-  private handleFrame(line: string): void {
+  private routeInboundFrame(line: string): void {
     let frame: Response | EventFrame;
     try {
       frame = JSON.parse(line) as Response | EventFrame;
@@ -93,14 +93,14 @@ export class DaemonClient {
       return;
     }
     if ("event" in frame) {
-      for (const l of this.eventListeners) l(frame);
+      for (const listener of this.eventListeners) listener(frame);
       return;
     }
-    const p = this.pending.get(frame.id);
-    if (!p) return;
+    const pendingRequest = this.pending.get(frame.id);
+    if (!pendingRequest) return;
     this.pending.delete(frame.id);
-    if (frame.error) p.reject(new DaemonClientError(frame.error.code, frame.error.message));
-    else p.resolve(frame.result);
+    if (frame.error) pendingRequest.reject(new DaemonClientError(frame.error.code, frame.error.message));
+    else pendingRequest.resolve(frame.result);
   }
 
   request<T = unknown>(method: string, params: unknown, timeoutMs = 30_000): Promise<T> {
@@ -112,13 +112,13 @@ export class DaemonClient {
         reject(new Error(`request ${method} timed out`));
       }, timeoutMs);
       this.pending.set(id, {
-        resolve: (v) => {
+        resolve: (value) => {
           clearTimeout(timer);
-          resolve(v as T);
+          resolve(value as T);
         },
-        reject: (e) => {
+        reject: (error) => {
           clearTimeout(timer);
-          reject(e);
+          reject(error);
         },
       });
       this.writer!.write(JSON.stringify({ id, method, params }) + "\n");
@@ -159,6 +159,9 @@ export class DaemonClient {
   sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession> {
     return this.request("session.setWorkingCopy", { id, workingCopy });
   }
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession> {
+    return this.request("session.setViewed", { id, viewedPaths });
+  }
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
     return this.request("session.resolve", { id, verdictKind, summary });
   }

package/src/protocol.ts

@@ -1,5 +1,5 @@
 /**
- * Wire protocol (#14): newline-delimited JSON over the unix socket.
+ * Wire protocol: newline-delimited JSON over the unix socket.
  * Requests: { id, method, params }  Responses: { id, result } | { id, error }
  * Events (push, after events.subscribe): { event, sessionId }
  */
@@ -25,15 +25,15 @@ export type Frame = Response | EventFrame;
 
 /** Incremental NDJSON splitter; tolerates partial writes. */
 export class LineBuffer {
-  private buf = "";
+  private buffered = "";
 
   push(chunk: string, onLine: (line: string) => void): void {
-    this.buf += chunk;
+    this.buffered += chunk;
     for (;;) {
-      const nl = this.buf.indexOf("\n");
-      if (nl === -1) return;
-      const line = this.buf.slice(0, nl).trim();
-      this.buf = this.buf.slice(nl + 1);
+      const newlineIndex = this.buffered.indexOf("\n");
+      if (newlineIndex === -1) return;
+      const line = this.buffered.slice(0, newlineIndex).trim();
+      this.buffered = this.buffered.slice(newlineIndex + 1);
       if (line) onLine(line);
     }
   }

package/src/review.test.ts

@@ -33,8 +33,8 @@ afterEach(() => {
 });
 
 function sh(args: string[], cwd: string): void {
-  const p = Bun.spawnSync(args, { cwd, stdout: "ignore", stderr: "ignore" });
-  if (p.exitCode !== 0) throw new Error(`${args.join(" ")} failed`);
+  const gitResult = Bun.spawnSync(args, { cwd, stdout: "ignore", stderr: "ignore" });
+  if (gitResult.exitCode !== 0) throw new Error(`${args.join(" ")} failed`);
 }
 
 describe("resolveWorkspace", () => {
@@ -63,13 +63,13 @@ describe("resolveWorkspace", () => {
 describe("openReview", () => {
   test("shapes the artifact: agent, derived title, cwd", async () => {
     const review = await openReview(client, { type: "plan", content: PLAN, cwd: home, agent: "test-agent" });
-    const s = review.session;
-    expect(s.status).toBe("pending");
-    expect(s.artifact.type).toBe("plan");
-    expect(s.artifact.meta.agent).toBe("test-agent");
-    expect(s.artifact.meta.title).toBe("Rollout Plan");
-    expect(s.artifact.meta.cwd).toBe(home);
-    expect(s.workspace).toEqual({ repoRoot: home, branch: "detached" });
+    const session = review.session;
+    expect(session.status).toBe("pending");
+    expect(session.artifact.type).toBe("plan");
+    expect(session.artifact.meta.agent).toBe("test-agent");
+    expect(session.artifact.meta.title).toBe("Rollout Plan");
+    expect(session.artifact.meta.cwd).toBe(home);
+    expect(session.workspace).toEqual({ repoRoot: home, branch: "detached" });
   });
 
   test("an explicit title wins; diffs never derive one from content", async () => {
@@ -99,6 +99,23 @@ describe("openReview", () => {
     const other = await openReview(client, { type: "plan", content: PLAN, cwd: home, agentSessionId: "agent-2" });
     expect(other.id).not.toBe(first.id);
   });
+
+  test("per-file notes land as note annotations anchored at the file path", async () => {
+    const review = await openReview(client, {
+      type: "diff",
+      content: "d",
+      cwd: home,
+      notes: [
+        { path: "src/a.ts", body: "Renames b and adds c." },
+        { path: "src/b.ts", body: "Swaps the line." },
+      ],
+    });
+    const notes = review.session.annotations;
+    expect(notes.length).toBe(2);
+    expect(notes.every((annotation) => annotation.kind === "note")).toBe(true);
+    expect(notes.map((annotation) => annotation.anchor.quote)).toEqual(["src/a.ts", "src/b.ts"]);
+    expect(notes[0]!.body).toBe("Renames b and adds c.");
+  });
 });
 
 describe("awaitVerdict: one long-poll (the hook shape)", () => {
@@ -133,7 +150,7 @@ describe("awaitVerdict: chunked loop (the pi shape)", () => {
     const waiting = review.awaitVerdict({
       timeoutMs: Infinity,
       pollMs: 100,
-      onProgress: (s) => seen.push(s),
+      onProgress: (progress) => seen.push(progress),
     });
     await client.sessionAnnotate(review.id, {
       id: "a1",
@@ -142,8 +159,8 @@ describe("awaitVerdict: chunked loop (the pi shape)", () => {
       body: "Name them.",
     });
     // give the loop a chunk to observe the annotation before resolving
-    for (let i = 0; i < 100 && !seen.some((s) => s.annotations.length === 1); i++) await Bun.sleep(20);
-    expect(seen.some((s) => s.annotations.length === 1)).toBe(true);
+    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);
     await client.sessionResolve(review.id, "request_changes", "Too vague.");
     const verdict = await waiting;
     if (verdict === "pending") throw new Error("expected a verdict");