feat: batch question delivery and fold open questions into Send

A reviewer can fire several questions before the agent comes back, but
each await delivered exactly one event — the rest sat queued with
nothing telling the agent to return, so it appeared stuck.

One await now drains every queued question into a single event: the
new `questions` array carries them in arrival order and the singular
`question` field (the oldest) stays for compatibility, so a lone
question reads uniformly as a one-element array. Send flushes queued
question events — superseded by the round — and ReviewResult gains
`openQuestions`: every still-unanswered question (same answered
heuristic the UI uses), built with the same payload constructor as
/api/ask so the shapes can't drift. The contract adds the loop rule:
after handling any event, await again immediately — more may already
be queued. Batch-drain safety rests on a documented invariant: a Send
flushes all queued questions before enqueuing its review, so a review
can never sit between two queued questions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015jcfPg9g4TTWQksf8vhHps

Author: ymansurozer

scripts/smoke.mjs

@@ -87,6 +87,34 @@ try {
   assert.equal(ev1.question.lineNumber, 2);
   console.log("✓ await → question event");
 
+  // Two more questions fired back-to-back with no await parked → they batch: a single await
+  // hands over BOTH, oldest first, with the singular `question` kept for compatibility.
+  await post("/api/ask", {
+    path: "a.txt",
+    lineNumber: 2,
+    side: "additions",
+    body: "batched one?",
+  });
+  await post("/api/ask", {
+    path: "a.txt",
+    lineNumber: 2,
+    side: "additions",
+    body: "batched two?",
+  });
+  const batchState = await getJson("/api/state");
+  assert.equal(batchState.queuedQuestions, 2, "both questions queued with no listener");
+  const evBatch = JSON.parse(cli("await", "--repo", tmp, "--session", ID, "--timeout", "5"));
+  assert.equal(evBatch.kind, "question");
+  assert.equal(evBatch.questions.length, 2, "both questions delivered in one event");
+  assert.deepEqual(
+    evBatch.questions.map((q) => q.body),
+    ["batched one?", "batched two?"],
+  );
+  assert.equal(evBatch.question.body, "batched one?", "singular question is the oldest");
+  const drainedState = await getJson("/api/state");
+  assert.equal(drainedState.queuedQuestions, 0, "batch drained in one await");
+  console.log("✓ multiple questions batch into one await event");
+
   // agent posts ephemeral activity while working → visible in the state payload
   const status = JSON.parse(
     cli("status", "--repo", tmp, "--session", ID, "--body", "Reading a.txt…"),

src/server.test.ts

@@ -192,6 +192,90 @@ test("an unconsumed question surfaces as queuedQuestions", async () => {
   });
 });
 
+test("multiple questions asked before an await batch into one event, oldest first", async () => {
+  await withServer(async (handle) => {
+    await post(handle.url, "api/ask", { path: "a.ts", lineNumber: 1, body: "first?" });
+    await post(handle.url, "api/ask", { path: "a.ts", lineNumber: 2, body: "second?" });
+    const ev = (await fetch(`${handle.url}api/await-send`).then((r) => r.json())) as {
+      kind: string;
+      question: { body: string };
+      questions: { body: string }[];
+    };
+    assert.equal(ev.kind, "question");
+    assert.equal(ev.questions.length, 2);
+    assert.deepEqual(
+      ev.questions.map((q) => q.body),
+      ["first?", "second?"],
+    );
+    assert.deepEqual(ev.question, ev.questions[0]); // singular is the oldest
+    // Both drained — nothing left queued for the UI's waiting indicator.
+    const st = await getState(handle.url);
+    assert.equal(st.queuedQuestions, 0);
+  });
+});
+
+test("Send flushes queued questions and folds the unanswered ones into openQuestions", async () => {
+  await withServer(async (handle, _root, st) => {
+    // Two open question comments the reviewer left (the source for openQuestions), plus the
+    // matching live question events (the source for the queue) — two independent representations.
+    st.comments.push(
+      {
+        id: "q1",
+        path: "a.ts",
+        side: "additions",
+        lineNumber: 1,
+        body: "why q1?",
+        createdAt: "2026-01-01T00:00:00Z",
+        updatedAt: "2026-01-01T00:00:00Z",
+        status: "open",
+        intent: "question",
+        role: "user",
+      },
+      {
+        id: "q2",
+        path: "a.ts",
+        side: "additions",
+        lineNumber: 2,
+        body: "why q2?",
+        createdAt: "2026-01-01T00:00:01Z",
+        updatedAt: "2026-01-01T00:00:01Z",
+        status: "open",
+        intent: "question",
+        role: "user",
+      },
+    );
+    await post(handle.url, "api/ask", { path: "a.ts", lineNumber: 1, body: "why q1?" });
+    await post(handle.url, "api/ask", { path: "a.ts", lineNumber: 2, body: "why q2?" });
+
+    const sent = (await post(handle.url, "api/send", await getState(handle.url)).then((r) =>
+      r.json(),
+    )) as { sent?: boolean };
+    assert.equal(sent.sent, true);
+
+    // The review is emitted on the send response's 'finish'; poll until it lands. The queued
+    // questions are flushed in the same step, so queuedQuestions must be 0 by then.
+    let status = await getState(handle.url);
+    for (let i = 0; i < 100 && status.queuedReviews === 0; i++) {
+      await new Promise((r) => setTimeout(r, 10));
+      status = await getState(handle.url);
+    }
+    assert.equal(status.queuedReviews, 1);
+    assert.equal(status.queuedQuestions, 0); // superseded questions flushed
+
+    // Next await is the review (not a stale question), carrying both unanswered questions.
+    const ev = (await fetch(`${handle.url}api/await-send`).then((r) => r.json())) as {
+      kind: string;
+      result: { openQuestions: { body: string }[] };
+    };
+    assert.equal(ev.kind, "review");
+    assert.deepEqual(ev.result.openQuestions.map((q) => q.body).sort(), ["why q1?", "why q2?"]);
+
+    // Nothing dribbles in after the round: a bounded await times out (204).
+    const after = await fetch(`${handle.url}api/await-send?timeout=1`);
+    assert.equal(after.status, 204);
+  });
+});
+
 test("save strips transient desk-status keys so they never persist on state", async () => {
   await withServer(async (handle, _root, st) => {
     const payload = await getState(handle.url);

src/server.ts

@@ -18,11 +18,18 @@ import {
   mergeReviewState,
   nowIso,
   persistReview,
+  questionPayload,
   readGlobalSettings,
   syncGitState,
   writeGlobalSettings,
 } from "./state.js";
-import type { AgentActivity, AwaitEvent, DeskStatus, ReviewState } from "./types.js";
+import type {
+  AgentActivity,
+  AwaitEvent,
+  DeskStatus,
+  QuestionPayload,
+  ReviewState,
+} from "./types.js";
 
 const execFileAsync = promisify(execFile);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -301,7 +308,14 @@ export async function startServer(options: ServerOptions): Promise<ServerHandle>
         const resultJson = path.join(sessionDir, `${state.id}-result.json`);
         const payload = buildReviewResult(state, { resultJson, sessionDir }, overallNote);
         await fs.writeFile(resultJson, JSON.stringify(payload, null, 2) + "\n", "utf8");
-        res.on("finish", () => emitEvent({ kind: "review", result: payload }));
+        res.on("finish", () => {
+          // Drop any still-queued questions: the review supersedes them (their unanswered ones
+          // ride out in result.openQuestions), so stale question events never dribble in after
+          // the round lands. This is also the invariant the await-send batch drain relies on.
+          for (let i = eventQueue.length - 1; i >= 0; i--)
+            if (eventQueue[i].kind === "question") eventQueue.splice(i, 1);
+          emitEvent({ kind: "review", result: payload });
+        });
         return json(res, 200, { ok: true, sent: true, resultJson });
       }
       if (req.method === "POST" && url.pathname === "/api/ask") {
@@ -321,23 +335,37 @@ export async function startServer(options: ServerOptions): Promise<ServerHandle>
             "ask requires path and body",
             "Send { path, lineNumber, side, body } as JSON.",
           );
-        emitEvent({
-          kind: "question",
-          question: {
-            path: b.path,
-            lineNumber: Number(b.lineNumber ?? 1),
-            side: b.side === "deletions" ? "deletions" : "additions",
-            body: text,
-            mode: state.mode,
-            session: state.session,
-          },
+        // Bake the singular into a one-element `questions` here so a question handed straight
+        // to a parked waiter already carries the array — batching only has to merge on drain.
+        const question = questionPayload(state, {
+          path: b.path,
+          lineNumber: Number(b.lineNumber ?? 1),
+          side: b.side === "deletions" ? "deletions" : "additions",
+          body: text,
         });
+        emitEvent({ kind: "question", question, questions: [question] });
         return json(res, 200, { ok: true });
       }
       if (req.method === "GET" && url.pathname === "/api/await-send") {
         // Long-poll the tagged event stream: resolves with the next queued event
         // ({kind:"question"|"review"}). Lets the agent learn of questions and Sends
         // without the desk process exiting.
+        // When the head is a question, drain ALL queued questions into one event (the reviewer
+        // can fire several before the agent returns) — singular `question` is the oldest,
+        // `questions` holds them in arrival order. Safe because a Send flushes every queued
+        // question before enqueuing its review (see /api/send), so a review can never sit
+        // between two queued questions; draining all questions can't skip past a review.
+        if (eventQueue[0]?.kind === "question") {
+          const batched: QuestionPayload[] = [];
+          for (let i = eventQueue.length - 1; i >= 0; i--) {
+            const ev = eventQueue[i];
+            if (ev.kind === "question") {
+              batched.unshift(...ev.questions);
+              eventQueue.splice(i, 1);
+            }
+          }
+          return json(res, 200, { kind: "question", question: batched[0], questions: batched });
+        }
         const queued = eventQueue.shift();
         if (queued) return json(res, 200, queued);
         let settled = false;

src/spec.test.ts

@@ -22,10 +22,15 @@ const ANCHORS = [
   // a question is READ-ONLY: answer it, don't edit code in response (guards issue 04)
   "answering is READ-ONLY",
   "NEVER edit tracked",
+  // question batching + immediate re-await (issue 05)
+  "batched into this delivery",
+  "await again immediately",
   // result + acting
   "ReviewResult",
   "approvedFiles",
   "overallNote",
+  // unanswered questions fold into the Send (issue 05)
+  "openQuestions",
   "How to act on a review",
   // guided review schema (folded in from the old guide-spec)
   "Guide JSON schema",

src/spec.ts

@@ -53,7 +53,8 @@ done
 \`\`\`
 - \`galley await [--timeout <s>]\` — block for the next event, print one tagged JSON envelope,
   exit. No --timeout → holds open; --timeout <s> → empty stdout (204) after <s>s, re-poll. Exit
-  non-zero = no live desk (start one).
+  non-zero = no live desk (start one). After handling ANY event, await again immediately — more
+  may already be queued (the human keeps working while you act).
 - \`galley comment --path <f> --line <n> [--side additions|deletions] --body "…"\` — agent reply.
   Live desk → posts over HTTP (~1.5s), threaded under the matching human comment; no desk →
   appended to the saved review. Match path/line/side. Agent comments are never echoed back as
@@ -67,13 +68,17 @@ done
 
 ## Events
 await yields exactly one:
-- {"kind":"question","question":{path,lineNumber,side,body,mode,session}} — reviewer wants an
-  answer NOW. A question asks for an ANSWER, not a code change: answering is READ-ONLY — read the
-  file for context, answer with \`galley comment\` at path/lineNumber/side. NEVER edit tracked
-  files in response (same rule as "Between rounds"). The only exception: the question's own text
-  explicitly asks for an immediate change — then treat it as actionable, and still follow the
-  between-rounds discipline (edit, then \`galley reload\`). Questions are a live side-channel:
-  NEVER in a Send/ReviewResult. Slow answer → post \`galley status\` lines so the human sees
+- {"kind":"question","question":{path,lineNumber,side,body,mode,session},"questions":[…]} —
+  reviewer wants an answer NOW. \`questions\` holds every question batched into this delivery
+  (the human can fire several before you return), arrival order; \`question\` is the oldest, kept
+  for compatibility. Answer EACH one. A question asks for an ANSWER, not a code change:
+  answering is READ-ONLY — read the file for context, answer with \`galley comment\` at
+  path/lineNumber/side.
+  NEVER edit tracked files in response (same rule as "Between rounds"). The only exception: the
+  question's own text explicitly asks for an immediate change — then treat it as actionable, and
+  still follow the between-rounds discipline (edit, then \`galley reload\`). Questions are a live
+  side-channel: NEVER in a Send/ReviewResult (except openQuestions below, which folds any you
+  never answered into the round). Slow answer → post \`galley status\` lines so the human sees
   progress, not a static spinner.
 - {"kind":"review","result":{…ReviewResult…}} — reviewer clicked Send. Act on result.
 
@@ -86,6 +91,10 @@ The \`result\` field of a review event:
   an overall remark, or an afterthought instruction for what to do after applying the review
   (e.g. "after applying, run the formatter"). It is NOT tied to any line and not a per-line change.
 - stagedFiles[], approvedFiles[]
+- openQuestions[]: {path,lineNumber,side,body,mode,session} — questions the reviewer asked but you
+  never answered, folded into this Send and superseding any queued live question events. Answer
+  each with \`galley comment\` (same READ-ONLY discipline as a live question) as part of acting on
+  the round.
 - artifacts: {resultJson, sessionDir}, both under
   ~/.galley/<repoHash>/<session>/ where repoHash = sha256(abs repo root)[:16]
 The arrays above ARE the review — act on them directly; there's no prose summary to parse.

src/state.test.ts

@@ -467,6 +467,50 @@ test("buildReviewResult excludes questions from requestedChanges, keeps an actio
   assert.equal(r.requestedChanges[0]!.body, "rename this");
 });
 
+test("buildReviewResult.openQuestions lists unanswered questions and drops answered ones", () => {
+  const s = state({
+    session: "sess",
+    mode: "repo",
+    comments: [
+      comment({
+        id: "open",
+        path: "a.ts",
+        lineNumber: 4,
+        body: "why here?",
+        intent: "question",
+        role: "user",
+        createdAt: "2026-01-01T00:00:00Z",
+      }),
+      // Answered: a later agent reply lands in the same thread (same path/side/line).
+      comment({
+        id: "answered",
+        path: "a.ts",
+        lineNumber: 7,
+        body: "and this?",
+        intent: "question",
+        role: "user",
+        createdAt: "2026-01-01T00:00:00Z",
+      }),
+      comment({
+        id: "reply",
+        path: "a.ts",
+        lineNumber: 7,
+        body: "because X",
+        intent: "note",
+        role: "agent",
+        createdAt: "2026-01-01T00:01:00Z",
+      }),
+    ],
+  });
+  const r = buildReviewResult(s, { resultJson: "r.json", sessionDir: "d" });
+  assert.equal(r.openQuestions.length, 1);
+  assert.equal(r.openQuestions[0]!.body, "why here?");
+  assert.equal(r.openQuestions[0]!.lineNumber, 4);
+  // Same shape as an await question — mode/session threaded through.
+  assert.equal(r.openQuestions[0]!.mode, "repo");
+  assert.equal(r.openQuestions[0]!.session, "sess");
+});
+
 test("buildReviewResult carries mode/target/base", () => {
   const s = state({ mode: "pr", target: "feature-x", base: "abc123" });
   const r = buildReviewResult(s, { resultJson: "r.json", sessionDir: "d" });

src/state.ts

@@ -15,6 +15,7 @@ import {
 import type {
   ChangeState,
   Decision,
+  QuestionPayload,
   ReviewComment,
   ReviewFile,
   ReviewMode,
@@ -676,6 +677,45 @@ export async function appendComment(
   return comment;
 }
 
+// The single QuestionPayload constructor — shared by /api/ask (live question event) and
+// computeOpenQuestions (questions folded into a Send) so the two payload shapes can't drift.
+export function questionPayload(
+  state: Pick<ReviewState, "mode" | "session">,
+  q: { path: string; lineNumber: number; side: "additions" | "deletions"; body: string },
+): QuestionPayload {
+  return {
+    path: q.path,
+    lineNumber: q.lineNumber,
+    side: q.side,
+    body: q.body,
+    mode: state.mode,
+    session: state.session,
+  };
+}
+
+// Questions the reviewer asked but the agent hasn't answered yet. Mirrors the UI's "answered"
+// heuristic (src/ui/annotations.ts): an open question comment is unanswered until a later agent
+// reply lands in the same thread (same path/side/line). These ride out on the Send's ReviewResult
+// so an agent that never saw the live await still owes each an answer.
+export function computeOpenQuestions(state: ReviewState): QuestionPayload[] {
+  return state.comments
+    .filter(
+      (c) =>
+        c.intent === "question" &&
+        c.status === "open" &&
+        c.role !== "agent" &&
+        !state.comments.some(
+          (r) =>
+            r.role === "agent" &&
+            r.path === c.path &&
+            r.side === c.side &&
+            r.lineNumber === c.lineNumber &&
+            +new Date(r.createdAt) > +new Date(c.createdAt),
+        ),
+    )
+    .map((c) => questionPayload(state, c));
+}
+
 export function buildReviewResult(
   state: ReviewState,
   artifacts: { resultJson: string; sessionDir: string },
@@ -704,6 +744,7 @@ export function buildReviewResult(
     overallNote: note || undefined,
     stagedFiles: state.stagedFiles,
     approvedFiles: computeApprovedFiles(state),
+    openQuestions: computeOpenQuestions(state),
     artifacts,
   };
 }