git-reviewer 2.14.1 → 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-379-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:
 
@@ -79,7 +83,9 @@ git reviewer export [repository] [--format json|prompt]
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
       --no-open     Print the URL instead of opening a browser
+      --no-intro    Open the review without the first-run help
       --staged      Review only staged changes (HEAD vs index)
+      --no-untracked Review tracked working-tree changes only
   -f, --format <f>  Export format: json (default) or prompt
   -h, --help        Show help
   -v, --version     Show the version
@@ -103,6 +109,19 @@ changes. As with the default view, reload after changing what is staged. Saved c
 are shared between views and may refer to code outside the current comparison;
 check their anchors before applying them.
 
+Wholly untracked directories with more than 200 files appear as one directory
+row with a file count and no diff. Smaller directories stay reviewable file by
+file. Tracked changes are always listed individually, and `.gitignore` still
+applies. The scope note names any folded directories and their counts.
+The headline counts individual files separately from folded folders and the
+files inside them. Tracked changes appear first; reloading keeps your selection.
+
+Use `git reviewer --no-untracked` to exclude all untracked files. If there are
+no tracked working-tree changes, the view stays empty instead of loading the
+last commit. Staged and commit comparisons keep their usual behavior.
+Saved reviews and exports retain this tracked-only scope. The text review and
+agent prompt explain the exclusion; older comments remain shared between views.
+
 ### When you are not standing in a repository
 
 The page opens on a picker rather than on an empty box:
@@ -330,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;",
@@ -369,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.
@@ -383,11 +451,61 @@ 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
+
+`POST /api/load-repo` opens a repository. `repoPath` is required; choose a comparison or staged changes:
+
+```json
+{"repoPath":"/home/you/work/api","base":"main","head":"feature"}
+```
+
+To review a commit range, use `"commits": {"from":"abc123","to":"def456"}` instead of `base`/`head`. To review staged changes, use `"staged": true` without comparison fields. `head` is optional when using `base`.
+
+For tracked working-tree changes only, send `"untracked": false`. It defaults
+to `true`. Folded directory entries carry `directory: true` and `fileCount`;
+they have no file diff.
+
+`POST /api/save-comments` persists comments for an open session:
+
+```json
+{
+  "repoId": "<repoId returned by load-repo>",
+  "comments": [
+    {
+      "file": "src/app.js",
+      "line": 12,
+      "lineContent": "const value = 1;",
+      "text": "Consider renaming this variable.",
+      "selectedText": "const value",
+      "followUps": [{"text":"Please also update its uses.","timestamp":"2026-01-01T00:00:00.000Z"}]
+    }
+  ]
+}
+```
+
+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:
+
+```json
+{"repoId":"<repoId returned by load-repo>"}
+```
+
+The startup `--json` output does not include `repoId`: no session exists at startup. A client obtains its own `repoId` by calling `POST /api/load-repo`.
+
 A `repoId` is a random per-session handle, not a path. Requests that resolve
 outside the opened repository are refused, and a path that names nothing gets a
 404.
@@ -410,7 +528,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 379 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.
@@ -92,6 +101,9 @@ async function exportReview(options) {
       error instanceof NoMatchingCommentsError ||
       error instanceof ReviewOwnershipError
     ) {
+      if (repoPath === given && error instanceof NoReviewError && !(await repoRoot(given))) {
+        throw new UsageError(`${given} is not inside a git repository, and no review is saved for it.`);
+      }
       throw new UsageError(error.message);
     }
     throw error;
@@ -104,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.
  *
@@ -162,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);
 
@@ -197,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();
   };
@@ -250,13 +508,34 @@ async function main() {
     options.port ?? (Number(process.env.PORT) || DEFAULT_PORT),
     { onReviewSubmitted, handoff: handingOff, onIdle }
   );
-  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath, options.staged);
+  const port = server.address().port;
+  const url = buildUrl(
+    `http://${DEFAULT_HOST}:${port}`,
+    repoPath,
+    options.staged,
+    options.noIntro,
+    options.untracked
+  );
 
-  note(`\n  Code Reviewer  ${url}`);
-  if (repoPath) note(`  reviewing      ${repoPath}`);
-  note(handingOff
-    ? '\n  Submit the review in the browser and it will be written here.\n'
-    : '\n  Close the tab when you are done, or press Ctrl+C.\n');
+  if (options.json) {
+    // One machine-readable line instead of the banner, so an agent can read
+    // the URL without a regex that breaks the day the banner is reworded.
+    // stderr, like everything else here: stdout is reserved for the review.
+    // No repoId: none exists yet. The page creates one via POST /api/load-repo.
+    note(JSON.stringify({
+      url,
+      port,
+      repository: repoPath,
+      pid: process.pid,
+      version
+    }));
+  } else {
+    note(`\n  Code Reviewer  ${url}`);
+    if (repoPath) note(`  reviewing      ${repoPath}`);
+    note(handingOff
+      ? '\n  Submit the review in the browser and it will be written here.\n'
+      : '\n  Close the tab when you are done, or press Ctrl+C.\n');
+  }
 
   if (options.open && !(await openInBrowser(url))) {
     note('  Could not open a browser — open the URL above yourself.\n');

package/lib/agent.js

@@ -23,6 +23,7 @@ const SCHEMA = 'code-review/v1';
  * @property {string} generatedAt ISO 8601
  * @property {{path: string, name: string, head: string|null, branch: string|null}} repository
  * @property {'working'|'staged'|'lastCommit'|'range'|null} mode
+ * @property {boolean} [untracked] false when the working comparison excluded untracked files
  * @property {{comments: number, files: number}} summary
  * @property {AgentComment[]} comments
  */
@@ -30,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
  */
 
 /**
@@ -48,9 +52,10 @@ const SCHEMA = 'code-review/v1';
  * @param {string|null} [args.head] the commit the review was written against
  * @param {string|null} [args.branch]
  * @param {string|null} [args.mode]
+ * @param {boolean} [args.untracked]
  * @returns {ReviewDocument}
  */
-function buildReviewDocument({ repoPath, comments, generatedAt, head = null, branch = null, mode = null, range = null }) {
+function buildReviewDocument({ repoPath, comments, generatedAt, head = null, branch = null, mode = null, range = null, untracked }) {
   const grouped = groupByFile(comments);
 
   return {
@@ -63,6 +68,9 @@ function buildReviewDocument({ repoPath, comments, generatedAt, head = null, bra
       branch
     },
     mode,
+    // Older saves say nothing about untracked files. Only record an explicit
+    // exclusion in a working comparison; other scopes do not use this flag.
+    ...(mode === 'working' && untracked === false ? { untracked: false } : {}),
     // Omitted rather than null when there is no range, so `"range" in
     // document` is a meaningful test -- the same rule the optional comment
     // fields follow. A `working` review has no range and never will.
@@ -161,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,
@@ -173,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;
     });
   }
@@ -198,10 +211,15 @@ function toAgentComment(comment, id) {
  * @param {ReviewDocument} document
  * @returns {string|null}
  */
-function describeScope({ repository, mode, range }) {
+function describeScope({ repository, mode, range, untracked }) {
   const at = repository.head ? ` (${repository.head})` : '';
 
   if (mode === 'working') {
+    if (untracked === false) {
+      return `Comparison: tracked changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}. ` +
+        'Untracked files are excluded from this comparison. Saved comments are shared between review views ' +
+        'and may refer to changes outside this comparison; check their anchors before applying them.';
+    }
     return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
   }
 
@@ -312,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('');
     }
@@ -322,4 +342,4 @@ function formatPrompt(document) {
   return `${lines.join('\n')}`;
 }
 
-module.exports = { buildReviewDocument, filterReviewDocument, formatPrompt, SCHEMA };
+module.exports = { buildReviewDocument, filterReviewDocument, formatPrompt, describeScope, SCHEMA };