git-reviewer 2.15.0 → 2.16.0

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml/badge.svg)](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-415-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-500-brightgreen.svg)](test/)
 [![Dependencies](https://img.shields.io/badge/dependencies-3-brightgreen.svg)](package.json)
 
 **English** · [简体中文](docs/README.zh-CN.md) · [日本語](docs/README.ja.md)
@@ -48,6 +48,10 @@ Nothing is installed into the project, there is nothing to sign in to, and
 nothing leaves your machine. If you would rather not install it,
 `npx git-reviewer` works the same way.
 
+You can also ask while you read. Connect the Claude Code session that wrote the
+code, and it answers each comment in its thread as you write it; see
+[Ask the session that wrote the code](#ask-the-session-that-wrote-the-code).
+
 When the review and the hand-off happen at different times, the two-step form
 still works and is the one to reach for:
 
@@ -345,6 +349,7 @@ rather than guess when an anchor has vanished.
   "comments": [
     {
       "id": "src/auth.js:10",
+      "key": "Xq3vB9aK",
       "file": "src/auth.js",
       "line": 10,
       "anchor": "  if (scheme !== SCHEME || !token) return null;",
@@ -384,6 +389,54 @@ comment, finding the code a comment quotes rather than trusting its line
 number. Where an agent cannot leave a command running, it asks you to start
 `git reviewer` yourself and reads the result with `git reviewer export`.
 
+## Ask the session that wrote the code
+
+The agent that wrote a change knows why it is the way it is: it read the code
+around it, weighed the alternatives and chose one. reviewer can put your
+comments to that session, and its answers appear in the thread, under the
+comment, as they are written. You review in the browser and ask as you go:
+"why throw here instead of repricing?" on one file, "which edge cases are not
+tested?" on another, and each thread gets its answer from the agent that
+wrote the code, in its own words.
+
+**From the page.** Click **Ask Claude Code**, pick the session. Claude Code
+keeps every session's transcript, and reviewer lists the ones that ran in
+this repository. From then on every comment you write, and every reply you
+add, goes to that session; threads that were already waiting go first. The
+session is resumed in the background as a copy, so the original transcript
+is left exactly as it was. The copy can read the repository and nothing else:
+no edits, no shell, none of your MCP servers.
+
+**Live, in your terminal.** To have the session itself answer, the one you
+can watch and step into, connect it:
+
+```bash
+git reviewer connect                 # the most recent session that worked here
+git reviewer connect --list          # choose one
+git reviewer connect --session 9fef2341
+```
+
+This resumes the session with reviewer attached as a Claude Code
+[channel](https://code.claude.com/docs/en/channels). Every comment arrives in
+the session as it is written, and it answers in the thread with the `reply`
+tool, with your own permissions. Channels are a research preview, so Claude
+Code asks you to confirm the development channel when it starts.
+
+**Any agent.** Two commands are the whole protocol, so anything that can run a
+command can take part:
+
+```bash
+git reviewer watch              # one JSON line per comment waiting for an answer
+git reviewer reply <key> "Because the spec says inclusive."
+git reviewer reply <key> - < answer.md   # or the answer on stdin
+```
+
+Every comment has a stable `key`. It is in the export, and in each line `watch`
+prints. Answers are stored as follow-ups with a `by` field naming who wrote
+them, so an agent's reply is never mistaken for your own note. They export
+labelled as such too, so a review handed over afterwards carries the whole
+conversation.
+
 ## HTTP API
 
 The UI is a client of this; nothing is hidden from you.
@@ -398,9 +451,13 @@ The UI is a client of this; nothing is hidden from you.
 | `GET /api/alive` | Held open by the page; when the last one closes, a terminal run stops |
 | `GET /api/file/:repoId/:path` | The file's diff, as structured lines |
 | `GET /api/file-full/:repoId/:path` | Every line of the file, for context |
-| `POST /api/save-comments` | Persist the current comments |
-| `GET /api/load-comments/:repoId` | Restore saved comments |
+| `POST /api/save-comments` | Persist the current comments. Send back the `lastUpdated` you loaded and the save is conditional: if the file has moved on since, it answers `409` with the current `comments` and `lastUpdated` instead of overwriting them |
+| `GET /api/load-comments/:repoId` | Restore saved comments, with `lastUpdated`, the version token a conditional save sends back |
 | `POST /api/submit-review` | Render the saved comments to a review file |
+| `GET /api/events/:repoId` | Server-sent events for an open review: `comments` whenever the saved comments change, whoever changed them; `agents` as agents connect, leave or start on a thread; `partial` with an answer still being written |
+| `GET /api/agent/sessions/:repoId` | The Claude Code sessions that ran in this repository, newest first |
+| `POST /api/agent/connect` | `{repoId, sessionId, fork}`: have that session answer the review's comments in the background. `fork` defaults to `true`, a copy of the session |
+| `POST /api/agent/disconnect` | `{repoId}`: stop the background session |
 | `DELETE /api/cleanup/:repoId` | End the session; files on disk are untouched |
 
 ### POST request bodies
@@ -435,7 +492,11 @@ they have no file diff.
 }
 ```
 
-Each comment requires `file` (non-empty string), `line` (positive integer), and `text` (non-empty string). `lineContent`, `selectedText`, and `followUps` are optional.
+Each comment requires `file` (non-empty string), `line` (positive integer), and `text` (non-empty string). `lineContent`, `selectedText`, `followUps` and `key` are optional. A comment sent without a `key` gets one derived from its content, so the same list posted twice keeps its identities. Follow-ups take `key`, `timestamp`, and `by` for a reply from someone other than the reviewer. Follow-ups already saved for a comment are kept even when a save leaves them out, so a stale save cannot erase an agent's answer.
+
+Add `"lastUpdated"` with the value `load-comments` returned (`null` for a review
+not saved yet) to make the save conditional, as the page does. Without it the
+save overwrites whatever is on disk, as it always has.
 
 `POST /api/submit-review` renders the previously saved comments:
 
@@ -467,7 +528,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 415 tests
+npm test              # 500 tests
 npm run test:watch
 npm run test:coverage
 ```

package/bin/reviewer.js

@@ -3,6 +3,7 @@
 
 const fs = require('fs').promises;
 const path = require('path');
+const { spawn } = require('child_process');
 
 const { parseArgs, buildUrl, UsageError, usage, invokedAs } = require('../lib/cli');
 const { homeRelative } = require('../lib/paths');
@@ -18,6 +19,14 @@ const {
 } = require('../lib/export');
 const { startServer, DEFAULT_PORT, DEFAULT_HOST } = require('../server');
 const { version } = require('../package.json');
+const { updateSavedComments } = require('../lib/store');
+const { watchComments } = require('../lib/watch');
+const { announce } = require('../lib/presence');
+const { mintKey } = require('../lib/comments');
+const { appendReply, awaitingAnswer, newReviewerMessages, describeThread, lastAuthor } = require('../lib/threads');
+const { listClaudeSessions } = require('../lib/claude-sessions');
+const { runChannel } = require('../lib/channel');
+const { resolveClaudeCommand } = require('../lib/claude-command');
 
 // What to call this command when it talks about itself: whatever the person
 // typed, so a hint can be pasted back as-is. See invokedAs in lib/cli.js.
@@ -107,6 +116,244 @@ async function exportReview(options) {
   );
 }
 
+/**
+ * The root of the repository a command is about, or a usage error.
+ *
+ * @param {string|null} given the repository named on the command line
+ * @returns {Promise<string>}
+ */
+async function requireRepository(given) {
+  const target = given ?? process.cwd();
+  const root = await repoRoot(target);
+  if (!root) throw new UsageError(`${target} is not inside a git repository.`);
+  return root;
+}
+
+/** How a session is shown in a list: its name, or what it was first asked. */
+function sessionLabel(session) {
+  return session.title ?? session.firstPrompt ?? '(no prompt)';
+}
+
+/**
+ * `reviewer connect`: open the Claude Code session that worked here, with
+ * reviewer attached as a channel.
+ *
+ * Every comment the reviewer writes then arrives in that session as it is
+ * written, and the session answers in the thread with the `reply` tool. This
+ * is the session in a terminal, live: the person can watch it work and step
+ * in. During the channels research preview Claude Code asks once, at
+ * startup, to confirm a development channel; that is expected.
+ *
+ * @param {import('../lib/cli').CliOptions} options
+ */
+async function connectCommand(options) {
+  const repoPath = await requireRepository(options.repoPath);
+  const sessions = await listClaudeSessions(repoPath, { limit: 50 });
+
+  if (options.list) {
+    if (sessions.length === 0) {
+      note(`No Claude Code session has worked in ${repoPath} yet.`);
+      return;
+    }
+    for (const session of sessions) {
+      process.stdout.write(`${session.id}  ${session.updatedAt.slice(0, 16).replace('T', ' ')}  ${sessionLabel(session)}\n`);
+    }
+    return;
+  }
+
+  let chosen = null;
+  if (options.session) {
+    const matches = sessions.filter(session => session.id.startsWith(options.session));
+    if (matches.length !== 1) {
+      throw new UsageError(matches.length === 0
+        ? `No Claude Code session ${options.session} has worked in ${repoPath}. ${NAME} connect --list shows them.`
+        : `${options.session} matches ${matches.length} sessions; give more of the id.`);
+    }
+    [chosen] = matches;
+  } else {
+    // The most recent session that is not one of reviewer's own copies:
+    // asking a copy made to answer an earlier review is asking second-hand.
+    chosen = sessions.find(session => !session.title?.startsWith('Review answers:')) ?? sessions[0] ?? null;
+  }
+
+  const title = chosen ? sessionLabel(chosen) : null;
+  const mcpConfig = {
+    mcpServers: {
+      reviewer: {
+        command: process.execPath,
+        args: [path.resolve(__filename), 'channel', repoPath],
+        ...(title ? { env: { REVIEWER_SESSION_TITLE: title } } : {})
+      }
+    }
+  };
+  const args = [
+    ...(chosen ? ['--resume', chosen.id] : []),
+    ...(chosen && options.fork ? ['--fork-session'] : []),
+    '--mcp-config', JSON.stringify(mcpConfig),
+    '--dangerously-load-development-channels', 'server:reviewer'
+  ];
+
+  note(chosen
+    ? `\n  Resuming Claude Code session ${chosen.id}${options.fork ? ' as a copy' : ''}\n  ${title}\n`
+    : `\n  No Claude Code session has worked in ${repoPath} yet; starting a new one.\n`);
+  note('  Claude Code will ask you to confirm the reviewer channel (it is a research preview).');
+  note(`  Then every comment you write in reviewer arrives here, and the answers appear under them.\n`);
+
+  const claude = process.env.REVIEWER_CLAUDE || 'claude';
+  // A session whose directory has since been removed is resumed from the
+  // repository root rather than failing to spawn at all.
+  const cwd = chosen ? await fs.access(chosen.cwd).then(() => chosen.cwd, () => repoPath) : repoPath;
+  const child = spawn(resolveClaudeCommand(claude), args, { cwd, stdio: 'inherit' });
+
+  // Ctrl+C belongs to Claude Code while it runs -- it interrupts a turn, it
+  // does not quit -- and the terminal delivers it to both processes. This one
+  // only waits, so it must not die of the same keypress and leave Claude Code
+  // running on a terminal the shell has already taken back. A request to
+  // stop that comes from outside is passed on instead.
+  const ignore = () => {};
+  const forward = signal => child.kill(signal);
+  process.on('SIGINT', ignore);
+  process.on('SIGQUIT', ignore);
+  process.on('SIGTERM', forward);
+  process.on('SIGHUP', forward);
+  try {
+    await new Promise((resolve, reject) => {
+      child.on('error', error => reject(['ENOENT', 'EINVAL'].includes(error.code)
+        ? new Error(`Could not run "${claude}". Is Claude Code installed and on your PATH? Set REVIEWER_CLAUDE to its path otherwise` +
+          `${process.platform === 'win32' ? ' (the full path of claude.exe)' : ''}.`)
+        : error));
+      child.on('exit', (code, signal) => {
+        process.exitCode = code ?? (signal ? 1 : 0);
+        resolve();
+      });
+    });
+  } finally {
+    process.off('SIGINT', ignore);
+    process.off('SIGQUIT', ignore);
+    process.off('SIGTERM', forward);
+    process.off('SIGHUP', forward);
+  }
+}
+
+/**
+ * `reviewer channel`: the MCP server `connect` asks Claude Code to run.
+ *
+ * @param {import('../lib/cli').CliOptions} options
+ */
+async function channelCommand(options) {
+  const repoPath = await requireRepository(options.repoPath);
+  await runChannel({
+    repoPath,
+    reviewsDir: reviewsDir(),
+    version,
+    title: process.env.REVIEWER_SESSION_TITLE || null
+  });
+}
+
+/**
+ * `reviewer reply <key> <text>`: answer in a thread from the command line.
+ *
+ * For an agent following a review with `reviewer watch`, and anything else
+ * that can run a command. Inside Claude Code the reply is signed `claude`
+ * and carries the session's id; elsewhere it is from `agent` unless `--as`
+ * says who.
+ *
+ * @param {import('../lib/cli').CliOptions} options
+ */
+async function replyCommand(options) {
+  const repoPath = await requireRepository(options.repoPath);
+  if (options.textFromStdin) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    options.text = Buffer.concat(chunks).toString('utf-8').trim();
+    if (options.text === '') throw new UsageError('reply - read nothing from stdin');
+  }
+  const session = process.env.CLAUDE_CODE_SESSION_ID || null;
+  const by = options.as ?? (session ? 'claude' : 'agent');
+
+  let thread = null;
+  await updateSavedComments(reviewsDir(), repoPath, current => {
+    thread = current.comments.find(comment => comment.key === options.key) ?? null;
+    if (!thread) return null;
+    return {
+      comments: appendReply(current.comments, options.key, {
+        key: mintKey(),
+        text: options.text,
+        timestamp: new Date().toISOString(),
+        by,
+        ...(session ? { session } : {})
+      })
+    };
+  });
+
+  // Loudly: a reply that went nowhere and exited 0 would look, to whatever
+  // ran it, exactly like one the reviewer can read.
+  if (!thread) {
+    console.error(`error: no comment with key ${options.key} in the review of ${repoPath}.`);
+    console.error(`  ${NAME} export ${homeRelative(repoPath)} lists the comments and their keys.`);
+    process.exitCode = 1;
+    return;
+  }
+  note(`Replied on ${thread.file}:${thread.line} as ${by}.`);
+}
+
+/**
+ * `reviewer watch`: one JSON line per thing the reviewer says, as they say it.
+ *
+ * Threads already waiting for an answer come first, then each new comment
+ * and each reply the reviewer adds in a thread. Made for an agent that can
+ * follow a command's output -- Claude Code's Monitor tool turns each line
+ * into a message -- and answer with `reviewer reply`.
+ *
+ * @param {import('../lib/cli').CliOptions} options
+ */
+async function watchCommand(options) {
+  const repoPath = await requireRepository(options.repoPath);
+  const dir = reviewsDir();
+  const session = process.env.CLAUDE_CODE_SESSION_ID || null;
+  const presence = announce(dir, repoPath, { kind: 'watch', agent: session ? 'claude' : 'agent', session, title: null });
+  const working = new Set();
+
+  const emit = comment => {
+    const followUps = (comment.followUps ?? []).filter(followUp => !followUp.by);
+    const latest = followUps.length > 0 ? followUps[followUps.length - 1].text : comment.text;
+    process.stdout.write(`${JSON.stringify({
+      key: comment.key,
+      file: comment.file,
+      line: comment.line,
+      text: latest,
+      thread: describeThread(comment)
+    })}\n`);
+    working.add(comment.key);
+  };
+
+  let known = null;
+  const watcher = watchComments(dir, repoPath, state => {
+    if (known === null) {
+      awaitingAnswer(state.comments).forEach(emit);
+    } else {
+      for (const { comment } of newReviewerMessages(known, state.comments)) emit(comment);
+    }
+    for (const key of working) {
+      const thread = state.comments.find(comment => comment.key === key);
+      if (!thread || lastAuthor(thread) !== null) working.delete(key);
+    }
+    presence.update({ working: [...working] });
+    known = state.comments;
+  });
+
+  note(`Watching the review of ${repoPath}. Reply with: ${NAME} reply <key> "<text>"`);
+
+  await new Promise(resolve => {
+    const finish = () => resolve();
+    process.once('SIGINT', finish);
+    process.once('SIGTERM', finish);
+    process.stdout.on('error', finish); // whatever was reading has gone
+  });
+  watcher.close();
+  await presence.close();
+}
+
 /**
  * Which repository the page should open.
  *
@@ -165,6 +412,10 @@ async function main() {
   if (options.command === 'export') {
     return exportReview(options);
   }
+  if (options.command === 'connect') return connectCommand(options);
+  if (options.command === 'channel') return channelCommand(options);
+  if (options.command === 'reply') return replyCommand(options);
+  if (options.command === 'watch') return watchCommand(options);
 
   const repoPath = await repositoryToOpen(options.repoPath);
 
@@ -200,7 +451,11 @@ async function main() {
 
   let handedOff = false;
   const stop = () => {
-    server.close(() => process.exit(0));
+    // A background Claude Code session answering comments stops with us:
+    // asked to straight away, and waited for before the process exits.
+    Promise.resolve(server.stopAgents?.()).catch(() => {}).then(() => {
+      server.close(() => process.exit(0));
+    });
     // Don't wait forever on a browser holding the connection open.
     setTimeout(() => process.exit(0), 2000).unref();
   };

package/lib/agent.js

@@ -31,12 +31,15 @@ const SCHEMA = 'code-review/v1';
 /**
  * @typedef {object} AgentComment
  * @property {string} id stable within a document
+ * @property {string} [key] stable across documents: the key the comment was
+ *   saved with, which `reviewer reply` takes
  * @property {string} file repo-relative path
  * @property {number} line line number when the comment was written
  * @property {string|null} anchor the exact source line, for relocating the comment
  * @property {string} [selection] the snippet the reviewer highlighted
  * @property {string} body
- * @property {Array<{body: string, at?: string}>} [followUps]
+ * @property {Array<{body: string, at?: string, by?: string}>} [followUps]
+ *   `by` names an agent that answered in the thread; absent means the reviewer
  */
 
 /**
@@ -166,6 +169,10 @@ function toAgentComment(comment, id) {
     // Derived from file and line so it stays stable across exports, with a
     // suffix where that is not enough on its own. See `assignIds`.
     id,
+    // The saved key survives the code moving and the comment being edited,
+    // which `id` does not. Added beside it rather than replacing it, so
+    // nothing reading `id` today has to change.
+    ...(comment.key ? { key: comment.key } : {}),
     file: comment.file,
     line: comment.line,
     anchor: comment.lineContent ?? null,
@@ -178,6 +185,7 @@ function toAgentComment(comment, id) {
     entry.followUps = comment.followUps.map(followUp => {
       const item = { body: followUp.text };
       if (followUp.timestamp) item.at = followUp.timestamp;
+      if (followUp.by) item.by = followUp.by;
       return item;
     });
   }
@@ -322,8 +330,10 @@ function formatPrompt(document) {
 
     if (comment.followUps?.length > 0) {
       lines.push('Follow-ups:', '');
+      // An agent's answer is labelled as one. Unlabelled, "I'd keep it
+      // inclusive" would read as the reviewer's own instruction.
       comment.followUps.forEach((followUp, index) => {
-        lines.push(`${index + 1}. ${followUp.body}`);
+        lines.push(`${index + 1}. ${followUp.by ? `(${followUp.by}) ` : ''}${followUp.body}`);
       });
       lines.push('');
     }

package/lib/answerer.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+
+const { updateSavedComments } = require('./store');
+const { watchComments } = require('./watch');
+const { announce, listAgents, watchAgents } = require('./presence');
+const { mintKey } = require('./comments');
+const { awaitingAnswer, newReviewerMessages, appendReply, lastAuthor, followUpIdentity } = require('./threads');
+const { questionFor } = require('./claude-background');
+
+/**
+ * Keep a review's threads answered by a background Claude Code session.
+ *
+ * Everything the reviewer says -- a new comment, a reply in a thread, from
+ * this tab or any other -- reaches the session through the comments file,
+ * and every answer goes back the same way, as a follow-up written `by:
+ * claude`. Nothing here talks to the page directly except the text of an
+ * answer still being written, which is not worth a file write per word.
+ *
+ * Threads already waiting when it connects are answered first, oldest first.
+ */
+
+/** The reviewer's messages in a thread, by identity: the comment, and their follow-ups. */
+function reviewerMessages(comment) {
+  return new Set([
+    `comment:${comment.key}`,
+    ...(comment.followUps ?? []).filter(followUp => !followUp.by).map(followUpIdentity)
+  ]);
+}
+
+class Answerer extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {string} options.reviewsDir
+   * @param {string} options.repoPath
+   * @param {import('./claude-background').BackgroundSession} options.session
+   * @param {{id: string, title: string|null}} options.claudeSession the session being asked
+   * @param {string} [options.agent] the name answers are written under
+   */
+  constructor({ reviewsDir, repoPath, session, claudeSession, agent = 'claude' }) {
+    super();
+    this.reviewsDir = reviewsDir;
+    this.repoPath = repoPath;
+    this.session = session;
+    this.claudeSession = claudeSession;
+    this.agent = agent;
+
+    /** @type {import('./comments').Comment[]|null} */
+    this.known = null;
+    /** @type {Array<{key: string, force: boolean}>} */
+    this.queue = [];
+    /** @type {{key: string, asked: Set<string>}|null} */
+    this.inFlight = null;
+    this.stopped = false;
+
+    this.presence = announce(reviewsDir, repoPath, {
+      kind: 'background',
+      agent,
+      session: claudeSession.id,
+      title: claudeSession.title
+    });
+
+    session.on('session', () => this.emit('status', this.status()));
+    session.on('working', ({ key }) => this.presence.update({ working: [key] }));
+    session.on('partial', ({ key, text }) => this.emit('partial', { key, text }));
+    session.on('answer', ({ key, text, session: answeredBy }) => this.onAnswer(key, text, answeredBy));
+    session.on('failed', ({ key, message }) => {
+      this.inFlight = null;
+      this.presence.update({ working: [] });
+      this.emit('failed', { key, message });
+      this.emit('status', this.status());
+      this.dispatch();
+    });
+    session.on('exit', ({ message, fatal }) => {
+      if (message) this.emit('failed', { key: null, message });
+      // Claude Code could not even be started: say so once and disconnect,
+      // rather than show "connected" while every question fails the same way.
+      if (fatal) this.stop().then(() => this.emit('stopped'));
+    });
+
+    this.watcher = watchComments(reviewsDir, repoPath, state => this.onComments(state.comments));
+    // Threads held back while a live session was answering are this one's
+    // again when it leaves; nothing else would prompt another look.
+    this.agentsWatcher = watchAgents(reviewsDir, repoPath, () => this.dispatch());
+  }
+
+  /** @param {import('./comments').Comment[]} comments */
+  onComments(comments) {
+    if (this.stopped) return;
+    if (this.known === null) {
+      for (const comment of awaitingAnswer(comments)) this.enqueue(comment.key);
+    } else {
+      for (const { comment } of newReviewerMessages(this.known, comments)) this.enqueue(comment.key);
+    }
+    this.known = comments;
+    this.dispatch();
+  }
+
+  enqueue(key, force = false) {
+    const queued = this.queue.find(item => item.key === key);
+    if (queued) {
+      queued.force ||= force;
+      return;
+    }
+    this.queue.push({ key, force });
+  }
+
+  async dispatch() {
+    if (this.stopped || this.inFlight || this.queue.length === 0 || this.known === null) return;
+
+    // An agent answering live, in the reviewer's own terminal, takes
+    // precedence. Two agents answering one thread is noise, and the live one
+    // is the one somebody started on purpose.
+    const live = (await listAgents(this.reviewsDir, this.repoPath).catch(() => []))
+      .some(agent => agent.kind === 'channel');
+    if (live || this.inFlight || this.stopped) return;
+
+    while (this.queue.length > 0) {
+      const { key, force } = this.queue.shift();
+      const comment = this.known.find(entry => entry.key === key);
+      // Gone, or answered by somebody else in the meantime.
+      if (!comment || (!force && lastAuthor(comment) !== null)) continue;
+
+      this.inFlight = { key, asked: reviewerMessages(comment) };
+      this.session.ask(key, questionFor(comment));
+      this.emit('status', this.status());
+      return;
+    }
+    this.emit('status', this.status());
+  }
+
+  async onAnswer(key, text, answeredBy) {
+    const asked = this.inFlight?.key === key ? this.inFlight.asked : new Set();
+    let askAgain = false;
+
+    try {
+      await updateSavedComments(this.reviewsDir, this.repoPath, current => {
+        const thread = current.comments.find(comment => comment.key === key);
+        if (!thread) return null; // deleted while it was being answered
+        // Something the reviewer added while the answer was being written
+        // was not part of the question, so the thread is asked again --
+        // with everything, this answer included -- once this one is posted.
+        askAgain = [...reviewerMessages(thread)].some(identity => !asked.has(identity));
+        return {
+          comments: appendReply(current.comments, key, {
+            key: mintKey(),
+            text,
+            timestamp: new Date().toISOString(),
+            by: this.agent,
+            ...(answeredBy ? { session: answeredBy } : {})
+          })
+        };
+      });
+    } catch (error) {
+      this.emit('failed', { key, message: `Could not save the answer: ${error.message}` });
+    }
+
+    this.inFlight = null;
+    await this.presence.update({ working: [] });
+    if (askAgain) this.enqueue(key, true);
+    // Said even when nothing else is queued: the page shows "answering…"
+    // until it hears this thread is no longer being worked on.
+    this.emit('status', this.status());
+    this.dispatch();
+  }
+
+  status() {
+    return {
+      kind: 'background',
+      agent: this.agent,
+      session: this.claudeSession.id,
+      title: this.claudeSession.title,
+      answeringIn: this.session.answeringSession,
+      forked: this.session.fork,
+      working: this.inFlight?.key ?? null,
+      queued: this.queue.map(item => item.key)
+    };
+  }
+
+  async stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.watcher.close();
+    this.agentsWatcher.close();
+    await this.session.stop();
+    await this.presence.close();
+  }
+}
+
+module.exports = { Answerer };