getgloss 0.13.2 → 0.14.0

package/dist/cli/index.js

@@ -3,7 +3,7 @@
 // src/cli/index.ts
 import { randomUUID as randomUUID3 } from "crypto";
 import { constants } from "fs";
-import { access, rm as rm5, writeFile as writeFile4 } from "fs/promises";
+import { access, rm as rm5, writeFile as writeFile5 } from "fs/promises";
 import path7 from "path";
 import { Command } from "commander";
 import openBrowser from "open";
@@ -30,7 +30,7 @@ import path from "path";
 // package.json
 var package_default = {
   name: "getgloss",
-  version: "0.13.2",
+  version: "0.14.0",
   description: "Local browser-based diff review for coding-agent loops.",
   type: "module",
   packageManager: "pnpm@10.33.2",
@@ -112,6 +112,7 @@ var package_default = {
 
 // src/shared/paths.ts
 var packageVersion = package_default.version;
+var protocolVersion = 1;
 function expandHome(input) {
   if (input === "~") {
     return homedir();
@@ -127,6 +128,9 @@ function globalStateDir() {
 function globalServerFile() {
   return path.join(globalStateDir(), "server.json");
 }
+function globalLastPortFile() {
+  return path.join(globalStateDir(), "last-port");
+}
 function globalServerLockDir() {
   return path.join(globalStateDir(), "server.lock");
 }
@@ -178,6 +182,9 @@ function globalReviewMarkdownFile(reviewId) {
 function globalReviewResolvedFile(reviewId) {
   return path.join(globalReviewDir(reviewId), "resolved.json");
 }
+function globalReviewEventsFile(reviewId) {
+  return path.join(globalReviewDir(reviewId), "events.jsonl");
+}
 async function ensureDir(dir) {
   await mkdir(dir, { recursive: true });
 }
@@ -190,6 +197,8 @@ var DIFF_SCOPE_MODES = ["working", "branch", "explicit"];
 var DIFF_FALLBACK_REASONS = ["working-tree-clean", "missing-branch-base"];
 var REVIEW_SCOPE_MODES = ["all", "single", "range"];
 var RESOLUTION_STATUSES = ["partial", "resolved"];
+var REVIEW_EVENT_ACTORS = ["human", "agent", "system"];
+var AGENT_STATUSES = ["claimed", "working", "blocked", "completed", "failed"];
 var REVIEW_UPDATE_REASONS = [
   "review-resolved",
   "comment-resolved",
@@ -209,10 +218,10 @@ function parseJsonValue(value, guard, label) {
   return value;
 }
 function isServerInfo(value) {
-  return isRecord(value) && isNumber(value.pid) && isNumber(value.port) && isString(value.version) && isString(value.startedAt) && isString(value.stateDir) && isOptionalString(value.cwd) && isOptionalString(value.daemonPath);
+  return isRecord(value) && isNumber(value.pid) && isNumber(value.port) && isString(value.version) && isOptionalNumber(value.protocolVersion) && isString(value.startedAt) && isString(value.stateDir) && isOptionalString(value.cwd) && isOptionalString(value.daemonPath);
 }
 function isHealthResponse(value) {
-  return isRecord(value) && isBoolean(value.ok) && isString(value.version) && isNumber(value.activeReviews) && isOptionalNumber(value.connections) && isOptionalString(value.stateDir) && isOptionalString(value.cwd) && isOptionalString(value.daemonPath);
+  return isRecord(value) && isBoolean(value.ok) && isString(value.version) && isNumber(value.protocolVersion) && isNumber(value.activeReviews) && isOptionalNumber(value.connections) && isOptionalString(value.stateDir) && isOptionalString(value.cwd) && isOptionalString(value.daemonPath);
 }
 function isClearReviewsResult(value) {
   return isRecord(value) && isString(value.reviewsDir) && isString(value.cutoff) && isNumber(value.olderThanDays) && isBoolean(value.dryRun) && isArrayOf(value.candidates, isClearReviewEntry) && isArrayOf(value.deleted, isClearReviewEntry) && isArrayOf(value.skipped, isClearReviewSkipped) && isRecord(value.counts) && isNumber(value.counts.candidates) && isNumber(value.counts.deleted) && isNumber(value.counts.skipped);
@@ -232,8 +241,14 @@ function isOpenResult(value) {
 function isResolveResult(value) {
   return isRecord(value) && value.ok === true && isString(value.reviewId) && isOptionalString(value.turnId) && isOptionalNumber(value.turnIndex) && isReviewStatus(value.status) && isResolutionStatus(value.resolutionStatus) && isResolutionCounts(value.comments) && isString(value.path) && isResolutionBundle(value.resolution);
 }
+function isAgentClaimResponse(value) {
+  return isRecord(value) && value.ok === true && isString(value.reviewId) && isString(value.turnId) && isNumber(value.turnIndex) && value.status === "claimed" && isString(value.feedbackPath) && isString(value.markdownPath) && isString(value.artifactDir) && isFeedbackBundle(value.feedback) && isOptional(value.resolution, isResolutionBundle) && isReviewEvent(value.event);
+}
+function isAgentNoteResponse(value) {
+  return isRecord(value) && value.ok === true && isString(value.reviewId) && isOptionalString(value.turnId) && isOptionalNumber(value.turnIndex) && isOptional(value.status, isAgentStatus) && isString(value.message) && isReviewEvent(value.event);
+}
 function isReviewRecord(value) {
-  return isRecord(value) && isReviewMeta(value.meta) && isArrayOf(value.turns, isReviewTurn) && isDiffPayload(value.diff) && isOptional(value.feedback, isFeedbackBundle) && isOptional(value.resolution, isResolutionBundle);
+  return isRecord(value) && isReviewMeta(value.meta) && isArrayOf(value.turns, isReviewTurn) && isDiffPayload(value.diff) && isOptional(value.feedback, isFeedbackBundle) && isOptional(value.resolution, isResolutionBundle) && isOptional(value.events, (events) => isArrayOf(events, isReviewEvent));
 }
 function isStoredReviewMeta(value) {
   return isRecord(value) && isString(value.id) && isString(value.cwd) && isBaseRef(value.base) && isNullableString(value.branch) && isReviewStatus(value.status) && isString(value.createdAt) && isOptionalString(value.submittedAt) && isOptionalString(value.resolvedAt) && isOptionalString(value.artifactDir) && isOptionalString(value.activeTurnId) && isOptional(
@@ -263,6 +278,9 @@ function isReviewEvent(value) {
   if (!isRecord(value) || !isString(value.reviewId) || !isString(value.type)) {
     return false;
   }
+  if (!hasValidReviewEventEnvelope(value)) {
+    return false;
+  }
   switch (value.type) {
     case "review.opened":
     case "review.cancelled":
@@ -273,6 +291,10 @@ function isReviewEvent(value) {
       return isOptionalString(value.turnId) && isOptionalNumber(value.turnIndex) && isRecord(value.counts) && isNumber(value.counts.files) && isNumber(value.counts.comments);
     case "review.updated":
       return isOptionalString(value.turnId) && isOptionalNumber(value.turnIndex) && isReviewUpdateReason(value.reason) && isReviewStatus(value.status) && isResolutionStatus(value.resolutionStatus) && isResolutionCounts(value.counts);
+    case "agent.claimed":
+      return isString(value.turnId) && isNumber(value.turnIndex) && value.status === "claimed" && isOptionalString(value.message);
+    case "agent.note":
+      return isOptionalString(value.turnId) && isOptionalNumber(value.turnIndex) && isOptional(value.status, isAgentStatus) && isString(value.message);
     default:
       return false;
   }
@@ -362,6 +384,15 @@ function isResolutionStatus(value) {
 function isReviewUpdateReason(value) {
   return isOneOf(value, REVIEW_UPDATE_REASONS);
 }
+function isReviewEventActor(value) {
+  return isOneOf(value, REVIEW_EVENT_ACTORS);
+}
+function isAgentStatus(value) {
+  return isOneOf(value, AGENT_STATUSES);
+}
+function hasValidReviewEventEnvelope(value) {
+  return isOptionalString(value.id) && isOptionalNumber(value.seq) && isOptionalString(value.createdAt) && isOptional(value.actor, isReviewEventActor);
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1182,6 +1213,24 @@ var ServerClient = class {
       "resolve response"
     );
   }
+  async claimReview(reviewId, message, turn) {
+    const request = { message, turn };
+    return this.post(
+      `/api/reviews/${reviewId}/agent/claim`,
+      request,
+      isAgentClaimResponse,
+      "agent claim response"
+    );
+  }
+  async addAgentNote(reviewId, message, status, turn) {
+    const request = { message, status, turn };
+    return this.post(
+      `/api/reviews/${reviewId}/agent/notes`,
+      request,
+      isAgentNoteResponse,
+      "agent note response"
+    );
+  }
   async resolveComment(reviewId, commentId, summary) {
     const request = { summary };
     return this.post(
@@ -1207,7 +1256,8 @@ var ServerClient = class {
       "submit review response"
     );
   }
-  async watchReview(reviewId, timeoutSeconds) {
+  async watchReview(reviewId, options = {}) {
+    const { timeoutSeconds, turnId } = options;
     const deadline = timeoutSeconds && timeoutSeconds > 0 ? Date.now() + timeoutSeconds * 1e3 : null;
     while (true) {
       const remainingMs = deadline ? deadline - Date.now() : null;
@@ -1218,7 +1268,7 @@ var ServerClient = class {
       const timeoutMs = remainingMs === null ? null : Math.min(remainingMs, timedWatchAttemptMs);
       const timeout = timeoutMs ? setTimeout(() => controller.abort(), timeoutMs) : null;
       try {
-        return await this.readReviewEvents(reviewId, controller.signal);
+        return await this.readReviewEvents(reviewId, controller.signal, turnId);
       } catch (error) {
         if (isAbortError(error)) {
           if (deadline && Date.now() < deadline) {
@@ -1237,7 +1287,7 @@ var ServerClient = class {
       }
     }
   }
-  async readReviewEvents(reviewId, signal) {
+  async readReviewEvents(reviewId, signal, turnId) {
     const response = await fetch(`${this.baseUrl}/api/reviews/${reviewId}/events`, {
       signal
     });
@@ -1261,7 +1311,11 @@ var ServerClient = class {
           continue;
         }
         const event = parseJson(dataLine.slice(5).trim(), isReviewEvent, "review event");
-        if (event.type === "review.submitted" || event.type === "review.cancelled") {
+        if (event.type === "review.cancelled") {
+          await reader.cancel().catch(() => void 0);
+          return event;
+        }
+        if (event.type === "review.submitted" && (!turnId || event.turnId === turnId)) {
           await reader.cancel().catch(() => void 0);
           return event;
         }
@@ -1317,7 +1371,13 @@ async function isServerResponsive(info) {
   }
   try {
     const health = await new ServerClient(serverUrl(info)).health();
-    return health.ok === true && health.version === packageVersion;
+    if (health.ok !== true || health.version !== packageVersion || health.protocolVersion !== protocolVersion || health.stateDir !== info.stateDir) {
+      return false;
+    }
+    if (info.daemonPath && health.daemonPath !== info.daemonPath) {
+      return false;
+    }
+    return true;
   } catch {
     return false;
   }
@@ -1346,14 +1406,17 @@ async function startServerUnlocked(existing, options = {}) {
   if (existing) {
     await retireServer(existing);
   }
-  const preferredPort = options.port ?? existing?.port ?? await getPort();
+  const rememberedPort = options.port ?? existing?.port ?? await readLastServerPort();
+  const preferredPort = rememberedPort ?? await getPort();
   try {
     return await launchServer(preferredPort);
   } catch (error) {
-    if (options.port || !existing?.port) {
+    if (options.port) {
       throw error;
     }
-    await removeServerInfoForPid(existing.pid);
+    if (existing) {
+      await removeServerInfoForPid(existing.pid);
+    }
     return launchServer(await getPort());
   }
 }
@@ -1380,6 +1443,7 @@ async function launchServer(port) {
     pid: child.pid ?? -1,
     port,
     version: packageVersion,
+    protocolVersion,
     startedAt: (/* @__PURE__ */ new Date()).toISOString(),
     stateDir: globalStateDir(),
     cwd: process.cwd(),
@@ -1394,6 +1458,7 @@ async function launchServer(port) {
   const deadline = Date.now() + 8e3;
   while (Date.now() < deadline) {
     if (await isServerResponsive(info)) {
+      await writeLastServerPort(port).catch(() => void 0);
       return info;
     }
     await new Promise((resolve) => setTimeout(resolve, 150));
@@ -1402,6 +1467,21 @@ async function launchServer(port) {
   await removeServerInfoForPid(info.pid);
   throw new Error(`Server did not become responsive. See ${globalServerLogFile()}`);
 }
+async function readLastServerPort() {
+  let raw;
+  try {
+    raw = await readFile3(globalLastPortFile(), "utf8");
+  } catch {
+    return null;
+  }
+  const port = Number(raw.trim());
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+}
+async function writeLastServerPort(port) {
+  await ensureDir(globalStateDir());
+  await writeFile3(globalLastPortFile(), `${port}
+`);
+}
 async function withServerLock(fn) {
   const release = await acquireServerLock();
   try {
@@ -1674,7 +1754,7 @@ async function sleep2(milliseconds) {
 
 // src/server/store.ts
 import { createHash } from "crypto";
-import { readdir as readdir2, readFile as readFile4 } from "fs/promises";
+import { appendFile, readdir as readdir2, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
 import path6 from "path";
 import { ulid } from "ulid";
 
@@ -1870,8 +1950,11 @@ var ReviewStore = class {
     const record = normalizeRecord({ meta, turns: [turn], diff: turn.diff });
     this.reviews.set(id, record);
     await this.persistInitial(record, turn);
-    this.emit({ type: "review.opened", reviewId: id });
-    return record;
+    const event = await this.appendReviewEvent(id, "system", {
+      type: "review.opened",
+      reviewId: id
+    });
+    return withEvents(record, [event]);
   }
   async appendTurn(id, diff) {
     const record = await this.get(id);
@@ -1884,14 +1967,18 @@ var ReviewStore = class {
     const latest = latestTurn(record);
     if (latest.status === "pending") {
       if (diffFingerprint(latest.diff) === diffFingerprint(diff)) {
-        this.emit({
+        await this.appendReviewEvent(id, "system", {
           type: "review.turn.created",
           reviewId: id,
           turnId: latest.id,
           turnIndex: latest.index,
           reused: true
         });
-        return { record, turn: latest, reused: true };
+        return {
+          record: withEvents(record, await this.readEvents(id)),
+          turn: latest,
+          reused: true
+        };
       }
       throw new Error(`Review ${id} already has a pending turn`);
     }
@@ -1906,14 +1993,18 @@ var ReviewStore = class {
     });
     this.reviews.set(id, nextRecord);
     await this.persistInitial(nextRecord, turn);
-    this.emit({
+    await this.appendReviewEvent(id, "system", {
       type: "review.turn.created",
       reviewId: id,
       turnId: turn.id,
       turnIndex: turn.index,
       reused: false
     });
-    return { record: nextRecord, turn, reused: false };
+    return {
+      record: withEvents(nextRecord, await this.readEvents(id)),
+      turn,
+      reused: false
+    };
   }
   async list() {
     await this.loadAllReviews();
@@ -1985,7 +2076,7 @@ var ReviewStore = class {
       writeTextFile(markdownPath, serializeFeedbackMarkdown(feedback))
     ]);
     await this.persistMeta(nextRecord);
-    this.emit({
+    await this.appendReviewEvent(id, "human", {
       type: "review.submitted",
       reviewId: id,
       turnId: nextTurn.id,
@@ -1995,12 +2086,86 @@ var ReviewStore = class {
         comments: feedback.comments.length
       }
     });
-    return { record: nextRecord, feedbackPath, markdownPath, turn: nextTurn };
+    return {
+      record: withEvents(nextRecord, await this.readEvents(id)),
+      feedbackPath,
+      markdownPath,
+      turn: nextTurn
+    };
   }
   async feedback(id) {
     const record = await this.get(id);
     return record?.feedback ?? null;
   }
+  async events(id, afterSeq = 0) {
+    const record = await this.get(id);
+    if (!record) {
+      return [];
+    }
+    return this.readEvents(id, afterSeq);
+  }
+  async claim(id, message, turnSelector) {
+    const record = await this.get(id);
+    if (!record) {
+      throw new Error(`Review ${id} not found`);
+    }
+    const turn = turnSelector ? this.resolveTurnSelector(record, turnSelector) : [...record.turns].reverse().find((candidate) => candidate.status === "submitted");
+    if (!turn) {
+      throw new Error(`Review ${id} has no submitted unresolved turn to claim`);
+    }
+    if (turn.status !== "submitted") {
+      throw new Error(`Review ${id} turn ${turn.index} is ${turn.status} and cannot be claimed`);
+    }
+    this.assertResolvable(turn, id);
+    if (!turn.feedbackPath || !turn.markdownPath) {
+      throw new Error(`Review ${id} turn ${turn.index} is missing feedback paths`);
+    }
+    const event = await this.appendReviewEvent(id, "agent", {
+      type: "agent.claimed",
+      reviewId: id,
+      turnId: turn.id,
+      turnIndex: turn.index,
+      status: "claimed",
+      ...message ? { message } : {}
+    });
+    return {
+      ok: true,
+      reviewId: id,
+      turnId: turn.id,
+      turnIndex: turn.index,
+      status: "claimed",
+      feedbackPath: turn.feedbackPath,
+      markdownPath: turn.markdownPath,
+      artifactDir: turn.artifactDir,
+      feedback: turn.feedback,
+      ...turn.resolution ? { resolution: turn.resolution } : {},
+      event
+    };
+  }
+  async addAgentNote(id, message, status, turnSelector) {
+    const record = await this.get(id);
+    if (!record) {
+      throw new Error(`Review ${id} not found`);
+    }
+    const turn = turnSelector ? this.resolveTurnSelector(record, turnSelector) : activeTurn(record);
+    const event = await this.appendReviewEvent(id, "agent", {
+      type: "agent.note",
+      reviewId: id,
+      turnId: turn.id,
+      turnIndex: turn.index,
+      ...status ? { status } : {},
+      message
+    });
+    return {
+      ok: true,
+      reviewId: id,
+      turnId: turn.id,
+      turnIndex: turn.index,
+      ...status ? { status } : {},
+      message,
+      event
+    };
+  }
   async markResolved(id, summary, turnSelector) {
     const record = await this.get(id);
     if (!record) {
@@ -2129,6 +2294,75 @@ var ReviewStore = class {
       }
     };
   }
+  async appendReviewEvent(reviewId, actor, input) {
+    const persistedEvents = await this.readPersistedEvents(reviewId);
+    let existingEvents = persistedEvents ?? [];
+    if (!persistedEvents && input.type !== "review.opened") {
+      const record2 = this.reviews.get(reviewId) ?? await this.loadKnownReview(reviewId);
+      existingEvents = record2 ? synthesizeReviewEvents(record2) : [];
+      if (existingEvents.length > 0) {
+        await ensureDir(globalReviewDir(reviewId));
+        await writeFile4(
+          globalReviewEventsFile(reviewId),
+          `${existingEvents.map((event2) => JSON.stringify(event2)).join("\n")}
+`
+        );
+      }
+    }
+    const event = {
+      ...input,
+      id: ulid(),
+      seq: nextEventSeq(existingEvents),
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      actor
+    };
+    await ensureDir(globalReviewDir(reviewId));
+    await appendFile(globalReviewEventsFile(reviewId), `${JSON.stringify(event)}
+`);
+    const record = this.reviews.get(reviewId);
+    if (record) {
+      this.reviews.set(reviewId, withEvents(record, [...existingEvents, event]));
+    }
+    this.emit(event);
+    return event;
+  }
+  async readEvents(reviewId, afterSeq = 0) {
+    const persistedEvents = await this.readPersistedEvents(reviewId);
+    if (!persistedEvents) {
+      const record = this.reviews.get(reviewId) ?? await this.loadKnownReview(reviewId);
+      if (!record) {
+        return [];
+      }
+      const synthesized = synthesizeReviewEvents(record);
+      if (synthesized.length > 0) {
+        await ensureDir(globalReviewDir(reviewId));
+        await writeFile4(
+          globalReviewEventsFile(reviewId),
+          `${synthesized.map((event) => JSON.stringify(event)).join("\n")}
+`
+        );
+      }
+      this.reviews.set(reviewId, withEvents(record, synthesized));
+      return synthesized.filter((event) => (event.seq ?? 0) > afterSeq);
+    }
+    return persistedEvents.filter((event) => (event.seq ?? 0) > afterSeq);
+  }
+  async readPersistedEvents(reviewId) {
+    let raw;
+    try {
+      raw = await readFile4(globalReviewEventsFile(reviewId), "utf8");
+    } catch (error) {
+      if (isFileNotFound(error)) {
+        return null;
+      }
+      throw new Error(`Could not read review events for ${reviewId}: ${formatError(error)}`, {
+        cause: error
+      });
+    }
+    return raw.split("\n").map((line) => line.trim()).filter(Boolean).map(
+      (line) => parseJsonFile(line, isReviewEvent, "review event", globalReviewEventsFile(reviewId))
+    ).filter((event) => event.reviewId === reviewId);
+  }
   emit(event) {
     for (const listener of this.listeners.get(event.reviewId) ?? []) {
       listener(event);
@@ -2214,7 +2448,9 @@ var ReviewStore = class {
       diff: latest.diff
     });
     this.reviews.set(id, record);
-    return record;
+    const withTimeline = withEvents(record, await this.readEvents(id));
+    this.reviews.set(id, withTimeline);
+    return withTimeline;
   }
   async loadReviewFromTurnsOnly(id) {
     const turns = await this.loadPersistedTurns(id);
@@ -2237,8 +2473,10 @@ var ReviewStore = class {
       diff: latest.diff
     });
     this.reviews.set(id, record);
-    await this.persistMeta(record);
-    return record;
+    const withTimeline = withEvents(record, await this.readEvents(id));
+    this.reviews.set(id, withTimeline);
+    await this.persistMeta(withTimeline);
+    return withTimeline;
   }
   async loadPersistedTurns(id) {
     let entries;
@@ -2383,7 +2621,7 @@ var ReviewStore = class {
       path: resolvedPath,
       resolution
     };
-    this.emit({
+    await this.appendReviewEvent(record.meta.id, "agent", {
       type: "review.updated",
       reviewId: record.meta.id,
       turnId: nextTurn.id,
@@ -2475,6 +2713,88 @@ function turnSummary(turn) {
     comments: resolutionCounts(turn.feedback, turn.resolution?.comments ?? [])
   };
 }
+function withEvents(record, events) {
+  return { ...record, events: events.toSorted(compareReviewEvents) };
+}
+function nextEventSeq(events) {
+  return Math.max(0, ...events.map((event) => event.seq ?? 0)) + 1;
+}
+function synthesizeReviewEvents(record) {
+  let seq = 1;
+  const next = (actor, input, createdAt) => ({
+    ...input,
+    id: ulid(),
+    seq: seq++,
+    createdAt,
+    actor
+  });
+  const events = [
+    next("system", { type: "review.opened", reviewId: record.meta.id }, record.meta.createdAt)
+  ];
+  const turns = record.turns.toSorted((a, b) => a.index - b.index);
+  for (const turn of turns) {
+    if (turn.index > 1) {
+      events.push(
+        next(
+          "system",
+          {
+            type: "review.turn.created",
+            reviewId: record.meta.id,
+            turnId: turn.id,
+            turnIndex: turn.index,
+            reused: false
+          },
+          turn.createdAt
+        )
+      );
+    }
+    if (turn.feedback) {
+      events.push(
+        next(
+          "human",
+          {
+            type: "review.submitted",
+            reviewId: record.meta.id,
+            turnId: turn.id,
+            turnIndex: turn.index,
+            counts: {
+              files: countCommentFiles(turn.feedback.comments),
+              comments: turn.feedback.comments.length
+            }
+          },
+          turn.submittedAt ?? turn.feedback.timestamp
+        )
+      );
+    }
+    if (turn.feedback && turn.resolution) {
+      const counts = resolutionCounts(turn.feedback, turn.resolution.comments);
+      events.push(
+        next(
+          "agent",
+          {
+            type: "review.updated",
+            reviewId: record.meta.id,
+            turnId: turn.id,
+            turnIndex: turn.index,
+            reason: turn.resolution.status === "resolved" ? "review-resolved" : "comment-resolved",
+            status: turn.status,
+            resolutionStatus: turn.resolution.status,
+            counts
+          },
+          turn.resolution.resolvedAt ?? turn.resolution.comments.at(-1)?.resolvedAt ?? turn.resolvedAt ?? turn.submittedAt ?? turn.createdAt
+        )
+      );
+    }
+  }
+  return events.toSorted(compareReviewEvents);
+}
+function compareReviewEvents(left, right) {
+  const seqDelta = (left.seq ?? 0) - (right.seq ?? 0);
+  if (seqDelta !== 0) {
+    return seqDelta;
+  }
+  return (left.createdAt ?? "").localeCompare(right.createdAt ?? "");
+}
 function reconcileTurn(meta, diff, feedback, resolution) {
   const status = resolution?.status === "resolved" ? "resolved" : feedback ? "submitted" : "pending";
   return {
@@ -2612,7 +2932,8 @@ program.command("open").description("Capture local changes and open them for rev
         if (options.open !== false) {
           await openBrowser(url);
         }
-      }
+      },
+      { turnId: turn.id }
     );
     info = watched.info;
     client = new ServerClient(serverUrl(info));
@@ -2715,6 +3036,23 @@ program.command("resolve").argument("<reviewId>", "review id").description("Mark
     );
   }
 );
+program.command("claim").argument("<reviewId>", "review id").description("Claim the latest submitted unresolved review turn for agent work").option("--message <text>", "optional visible agent status message").option("--turn <idOrIndex>", "claim a specific submitted turn").action(async (reviewId, options) => {
+  const globals = program.opts();
+  const info = await ensureServer();
+  const client = new ServerClient(serverUrl(info));
+  const result = await client.claimReview(reviewId, options.message, options.turn);
+  globals.json ? printJson(result) : printPlain(`Claimed review ${reviewId} turn ${result.turnIndex}`);
+});
+program.command("note").argument("<reviewId>", "review id").description("Post a visible agent progress note to a review").requiredOption("--message <text>", "agent note text").option("--status <status>", "agent status: claimed, working, blocked, completed, or failed").option("--turn <idOrIndex>", "attach the note to a specific turn").action(
+  async (reviewId, options) => {
+    const globals = program.opts();
+    const status = parseAgentStatus(options.status);
+    const info = await ensureServer();
+    const client = new ServerClient(serverUrl(info));
+    const result = await client.addAgentNote(reviewId, options.message, status, options.turn);
+    globals.json ? printJson(result) : printPlain(`Added note to review ${reviewId}${status ? ` (${status})` : ""}`);
+  }
+);
 program.command("doctor").description("Diagnose setup and validate git/state").action(async () => {
   const globals = program.opts();
   const checks = [];
@@ -2777,7 +3115,7 @@ program.command("doctor").description("Diagnose setup and validate git/state").a
     }
   }
 });
-async function watchReviewWithReconnect(reviewId, initialInfo, timeoutSeconds, onServerChanged) {
+async function watchReviewWithReconnect(reviewId, initialInfo, timeoutSeconds, onServerChanged, options = {}) {
   const startedAt = Date.now();
   let info = initialInfo;
   while (true) {
@@ -2786,7 +3124,10 @@ async function watchReviewWithReconnect(reviewId, initialInfo, timeoutSeconds, o
       throw new Error(`watch timed out after ${timeoutSeconds} seconds`);
     }
     try {
-      const event = await new ServerClient(serverUrl(info)).watchReview(reviewId, remainingSeconds);
+      const event = await new ServerClient(serverUrl(info)).watchReview(reviewId, {
+        timeoutSeconds: remainingSeconds,
+        turnId: options.turnId
+      });
       return { event, info };
     } catch (error) {
       if (isWatchTimeout(error)) {
@@ -2814,7 +3155,7 @@ async function checkStateDirAccess() {
   try {
     await ensureDir(globalStateDir());
     await access(globalStateDir(), constants.R_OK | constants.W_OK | constants.X_OK);
-    await writeFile4(probePath, "");
+    await writeFile5(probePath, "");
     await rm5(probePath, { force: true });
     return { name: "state-dir", ok: true, detail: stateDirDetail() };
   } catch (error) {
@@ -2862,6 +3203,15 @@ function parseOlderThanDays(value) {
   }
   return days;
 }
+function parseAgentStatus(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (value === "claimed" || value === "working" || value === "blocked" || value === "completed" || value === "failed") {
+    return value;
+  }
+  throw new Error("--status must be one of claimed, working, blocked, completed, or failed");
+}
 function formatClearResult(result) {
   const action = result.dryRun ? "Would delete" : "Deleted";
   const count = result.dryRun ? result.counts.candidates : result.counts.deleted;