git-reviewer 2.3.0 → 2.4.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-261-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-270-brightgreen.svg)](test/)
 [![Dependencies](https://img.shields.io/badge/dependencies-3-brightgreen.svg)](package.json)
 
 When an agent writes the code, reading it becomes the bottleneck — and the tool
@@ -19,18 +19,34 @@ marked-up review back to the agent to act on.
 npm install -g git-reviewer
 
 cd ~/your-project
-reviewer                                            # read the diff, comment on it
-reviewer export . --format prompt | claude -p "Apply this review."
+reviewer | claude -p "Apply this review."
 ```
 
+That is the whole loop. `reviewer` opens the review in your browser; when you
+press **Submit Review**, the review is written to stdout and the command
+exits — so whatever is on the other end of the pipe receives it and starts
+work. Nothing to copy, no second command, no file to go and find.
+
+Without a pipe, `reviewer` is just a review tool: it tells you where the
+review was saved and keeps serving, because you may have more to read.
+Everything it says to you goes to stderr either way, so only the review is
+ever on stdout.
+
 ![A terminal installing git-reviewer and running it inside a project; the browser opens on the diff with the first changed file already showing; two review comments are written inline, one with a threaded follow-up; then reviewer export prints those same comments back for a coding agent to act on](docs/demo.gif)
 
 *The whole loop, unedited and in real time — [full resolution](docs/demo.mp4).*
 
-`reviewer` starts a local server and opens your browser on the repository you
-are standing in. 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.
+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.
+
+The recording above shows the two-step form, which still works and is the one
+to reach for when the review and the hand-off happen at different times:
+
+```bash
+reviewer                                            # read the diff, comment on it
+reviewer export . --format prompt | claude -p "Apply this review."
+```
 
 Comments persist between sessions and survive the code moving underneath them —
 including the agent's own edits, which shift every line below the first change —
@@ -146,6 +162,9 @@ shown in full, read back out of `HEAD`:
 | `Escape` | Cancel input |
 | `↑` / `↓` | Move between files |
 
+None of that is guessable, so the review pane says it too, in a **How to
+comment** strip above the diff. Collapse it once and it stays collapsed.
+
 ## What it writes
 
 Two files, both plain text you can read without this app, both in a per-user
@@ -271,7 +290,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 261 tests
+npm test              # 270 tests
 npm run test:watch
 npm run test:coverage
 ```

package/bin/reviewer.js

@@ -5,6 +5,7 @@ const fs = require('fs').promises;
 const path = require('path');
 
 const { parseArgs, buildUrl, UsageError, USAGE } = require('../lib/cli');
+const { homeRelative } = require('../lib/paths');
 const { openInBrowser } = require('../lib/browser');
 const { formatPrompt } = require('../lib/agent');
 const { ReviewOwnershipError } = require('../lib/store');
@@ -22,6 +23,21 @@ const { version } = require('../package.json');
  * The `reviewer` command: start the local server and open it in a browser.
  */
 
+/**
+ * Everything this command says to the person running it.
+ *
+ * stderr, not stdout, and that is the whole design. stdout carries the
+ * finished review so it can be piped into a coding agent; a banner or a
+ * progress line written there lands in the middle of it. Both streams go to
+ * the same terminal when nothing is piping, so this is invisible until it
+ * matters.
+ *
+ * @param {string} [line]
+ */
+function note(line = '') {
+  process.stderr.write(`${line}\n`);
+}
+
 /**
  * Listen on `port`, falling back to any free port if it is taken.
  *
@@ -29,16 +45,17 @@ const { version } = require('../package.json');
  * an EADDRINUSE stack trace.
  *
  * @param {number} port
+ * @param {object} [options] passed through to the server
  * @returns {Promise<import('http').Server>}
  */
-async function listen(port) {
+async function listen(port, options = {}) {
   try {
-    return await startServer({ port, host: DEFAULT_HOST, silent: true });
+    return await startServer({ ...options, port, host: DEFAULT_HOST, silent: true });
   } catch (error) {
     if (error.code !== 'EADDRINUSE') throw error;
 
-    console.log(`Port ${port} is in use, picking another.`);
-    return startServer({ port: 0, host: DEFAULT_HOST, silent: true });
+    note(`Port ${port} is in use, picking another.`);
+    return startServer({ ...options, port: 0, host: DEFAULT_HOST, silent: true });
   }
 }
 
@@ -112,11 +129,11 @@ async function main() {
   // can start against a half-populated directory. See #33.
   const adopted = adoptLegacyReviews();
   if (adopted > 0) {
-    console.log(
+    note(
       `  Copied ${adopted} saved review${adopted === 1 ? '' : 's'} out of the ` +
         `install directory to\n  ${reviewsDir()}\n  so that upgrading or ` +
         'reinstalling this package can no longer delete them.\n' +
-        '  The originals are left where they were.\n'
+        '  The originals are left where they were.'
     );
   }
 
@@ -144,23 +161,68 @@ async function main() {
 
   const repoPath = await repositoryToOpen(options.repoPath);
 
-  const server = await listen(options.port ?? (Number(process.env.PORT) || DEFAULT_PORT));
-  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath);
-
-  console.log(`\n  Code Reviewer  ${url}`);
-  if (repoPath) console.log(`  reviewing      ${repoPath}`);
-  console.log('\n  Press Ctrl+C to stop.\n');
-
-  if (options.open && !(await openInBrowser(url))) {
-    console.log('  Could not open a browser — open the URL above yourself.\n');
-  }
-
+  // Is anything reading our stdout? If so, the review goes there when it is
+  // submitted and the command finishes -- which is what turns the whole loop
+  // into one line:
+  //
+  //     reviewer | claude -p "Apply this review."
+  //
+  // On a terminal there is nothing waiting, so submitting is not the end of
+  // anything: you may have more to review. It says where the review went and
+  // what to run next, and keeps serving.
+  const handingOff = !process.stdout.isTTY;
+
+  let handedOff = false;
   const stop = () => {
     server.close(() => process.exit(0));
     // Don't wait forever on a browser holding the connection open.
     setTimeout(() => process.exit(0), 2000).unref();
   };
 
+  /**
+   * A review has just been written. Say so, or hand it over.
+   *
+   * @param {{document: object, reviewPath: string}} submitted
+   */
+  const onReviewSubmitted = ({ document, reviewPath }) => {
+    const { comments, files } = document.summary;
+    const count = `${comments} comment${comments === 1 ? '' : 's'} on ` +
+      `${files} file${files === 1 ? '' : 's'}`;
+
+    if (!handingOff) {
+      note(`\n  Review saved    ${homeRelative(reviewPath)}`);
+      note(`  ${count}\n`);
+      note('  Hand it to an agent with:');
+      note(`    reviewer export ${repoPath ? homeRelative(repoPath) : '.'} --format prompt | claude -p "Apply this review."\n`);
+      return;
+    }
+
+    // Once is enough: the first submitted review is what the pipe is waiting
+    // for, and a second would arrive after the process has gone.
+    if (handedOff) return;
+    handedOff = true;
+
+    note(`\n  ${count} — handing the review back to your terminal.\n`);
+    process.stdout.write(formatPrompt(document));
+    stop();
+  };
+
+  const server = await listen(
+    options.port ?? (Number(process.env.PORT) || DEFAULT_PORT),
+    { onReviewSubmitted, handoff: handingOff }
+  );
+  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath);
+
+  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  Press Ctrl+C to stop.\n');
+
+  if (options.open && !(await openInBrowser(url))) {
+    note('  Could not open a browser — open the URL above yourself.\n');
+  }
+
   process.on('SIGINT', stop);
   process.on('SIGTERM', stop);
 }

package/lib/cli.js

@@ -18,6 +18,15 @@ Usage:
 Installed under both names: reviewer and git-reviewer. The second name also
 makes it reachable as a git subcommand: git reviewer
 
+Handing a review to an agent:
+  reviewer | claude -p "Apply this review."
+
+  With something reading its output, reviewer writes the finished review there
+  the moment you submit it in the browser, and exits. On a terminal there is
+  nothing waiting, so it says where the review was saved and keeps serving.
+  Everything it tells you goes to stderr either way, so only the review is
+  ever on stdout.
+
 Arguments:
   repository        Path to a git repository, or to any directory inside one.
                     Defaults to the current directory. It is opened
@@ -38,6 +47,8 @@ Options:
 
 Examples:
   reviewer                 review the repository you are standing in
+  reviewer | claude -p "Apply this review."
+                           review it, then hand it straight to an agent
   reviewer ~/work/api      review another repository
   reviewer . --no-open     print the URL, open it yourself
   reviewer export .        print the review as JSON

package/lib/comments.js

@@ -30,10 +30,31 @@
  * Optional fields are omitted rather than stored as `null` so that an absent
  * selection and an empty one are not two different states on disk.
  *
+ * A comment missing its file, line or text is rejected here rather than stored:
+ * `JSON.stringify` would silently drop the missing fields, and the record would
+ * only surface later, in `reviewer export`, as a comment on a file called
+ * `undefined` for an agent to act on.
+ *
  * @param {object} comment
+ * @param {number} index position in the batch, for the error message
  * @returns {Comment}
+ * @throws {TypeError} when a required field is missing or malformed
  */
-function normalizeComment(comment) {
+function normalizeComment(comment, index) {
+  const where = `comments[${index}]`;
+  if (comment === null || typeof comment !== 'object' || Array.isArray(comment)) {
+    throw new TypeError(`${where} must be an object`);
+  }
+  if (typeof comment.file !== 'string' || comment.file.trim() === '') {
+    throw new TypeError(`${where}.file must be a non-empty string`);
+  }
+  if (!Number.isInteger(comment.line) || comment.line < 1) {
+    throw new TypeError(`${where}.line must be a positive integer`);
+  }
+  if (typeof comment.text !== 'string' || comment.text.trim() === '') {
+    throw new TypeError(`${where}.text must be a non-empty string`);
+  }
+
   const normalized = {
     file: comment.file,
     line: comment.line,
@@ -61,13 +82,13 @@ function normalizeComment(comment) {
  *
  * @param {object[]} comments
  * @returns {Comment[]}
- * @throws {TypeError} when `comments` is not an array
+ * @throws {TypeError} when `comments` is not an array or a comment is malformed
  */
 function normalizeComments(comments) {
   if (!Array.isArray(comments)) {
     throw new TypeError('comments must be an array');
   }
-  return comments.map(normalizeComment);
+  return comments.map((comment, index) => normalizeComment(comment, index));
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-reviewer",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Review your coding agent's changes like a pull request — locally, with inline comments and threaded follow-ups, then hand the marked-up review back to the agent",
   "author": "Dheeraj Jha",
   "license": "MIT",

package/public/app.js

@@ -180,8 +180,10 @@ async function loadRepo() {
     // Load saved comments
     const savedComments = await loadCommentsFromBackend();
     if (savedComments.length > 0) {
-      // Store saved comments in a global variable for matching later
-      window.savedComments = savedComments;
+      // These went into `window.savedComments` as well, as a second copy for
+      // the matcher to read. Nothing reads it now, and leaving a stale copy of
+      // the review lying around is how the resurrection happened in the first
+      // place -- so there is one list, and it is this one.
 
       // Add all saved comments to the comments array immediately
       comments = savedComments.map(c => ({
@@ -308,9 +310,20 @@ async function loadFile(filePath, index) {
       throw new Error(data.error || 'Failed to load file');
     }
 
-    // Match saved comments to current diff if available
-    if (window.savedComments && window.savedComments.length > 0) {
-      const matchedComments = matchCommentsToDiff(window.savedComments, filePath, data.diffLines);
+    // Give this file's comments their position in the diff just rendered.
+    //
+    // The source here used to be `window.savedComments`, a snapshot taken when
+    // the repository was opened and never updated again. Everything else works
+    // from `comments`, the live list -- so a comment you deleted was still in
+    // the snapshot, was not found in the live list, and the branch below added
+    // it straight back. It vanished from disk and reappeared on screen, and
+    // the next save wrote the resurrected copy back over the deletion. Editing
+    // one did the same thing by a different route: the text no longer matched,
+    // so the pre-edit copy was added alongside the edited one (#52).
+    //
+    // `comments` is what exists. A comment that is not in it does not exist.
+    if (comments.length > 0) {
+      const matchedComments = matchCommentsToDiff(comments, filePath, data.diffLines);
 
       // Update existing comments in the array with matched diff indices
       matchedComments.forEach(mc => {
@@ -330,6 +343,10 @@ async function loadFile(filePath, index) {
             existing.followUps = mc.followUps;
           }
         } else {
+          // Unreachable now that the matcher is fed the live list: everything
+          // it returns came from there. Kept as a guard rather than removed,
+          // because silently dropping a comment is the worse failure of the
+          // two, and this is the line that would do it.
           // Add new comment if it doesn't exist
           comments.push({
             file: mc.file,
@@ -1085,7 +1102,7 @@ async function submitReview() {
       throw new Error(data.error || 'Failed to submit review');
     }
 
-    showReviewModal(data.reviewContent, data.filename);
+    showReviewModal(data);
     showStatus(`Review submitted successfully! ${data.totalComments} comments`, 'success');
 
   } catch (error) {
@@ -1093,9 +1110,38 @@ async function submitReview() {
   }
 }
 
-// Show review modal with download and copy options
-function showReviewModal(reviewContent, filename) {
-  // Create modal overlay
+/**
+ * What happened when you pressed Submit.
+ *
+ * This used to offer a download and nothing else, which is a strange thing to
+ * put in front of somebody who started this from a terminal: the review is
+ * already a file, and they are more likely to want to know where it is than
+ * to want a second copy of it in ~/Downloads.
+ *
+ * So it says where the review was written, and when something is waiting on
+ * the other end of a pipe it says that instead — because in that case the
+ * answer to "what do I do now" is "nothing, it has already gone".
+ *
+ * @param {{reviewContent: string, filename: string, reviewPath?: string,
+ *   handoff?: boolean, totalComments?: number}} result
+ */
+function showReviewModal(result) {
+  const { reviewContent, filename, reviewPath, handoff, totalComments } = result;
+
+  const count = totalComments === undefined
+    ? ''
+    : `${totalComments} comment${totalComments === 1 ? '' : 's'} · `;
+
+  const destination = handoff
+    ? `<div class="review-destination handed-off">
+         <strong>Handed back to your terminal.</strong>
+         <span>${escapeHtml(count)}The command you ran has printed this review and exited. You can close this window.</span>
+       </div>`
+    : `<div class="review-destination">
+         <strong>Saved</strong>
+         <span class="review-path" title="${escapeHtml(reviewPath ?? '')}">${escapeHtml(reviewPath ?? filename)}</span>
+       </div>`;
+
   const modal = document.createElement('div');
   modal.className = 'review-modal';
   modal.innerHTML = `
@@ -1105,11 +1151,12 @@ function showReviewModal(reviewContent, filename) {
         <button class="close-modal" onclick="this.closest('.review-modal').remove()">×</button>
       </div>
       <div class="review-modal-body">
+        ${destination}
         <pre class="review-text">${escapeHtml(reviewContent)}</pre>
       </div>
       <div class="review-modal-footer">
         <button data-filename="${escapeHtml(filename)}" onclick="downloadReview(this.dataset.filename, this.closest('.review-modal').querySelector('.review-text').textContent)">
-          Download ${escapeHtml(filename)}
+          Download
         </button>
         <button onclick="copyReviewToClipboard(this.closest('.review-modal').querySelector('.review-text').textContent)">
           Copy to Clipboard
@@ -1577,6 +1624,8 @@ document.addEventListener('DOMContentLoaded', () => {
     }
   });
 
+  restoreHowTo();
+
   for (const id of ['recentList', 'browseList']) {
     const list = document.getElementById(id);
     list.addEventListener('click', onPickerActivate);
@@ -1833,3 +1882,54 @@ function onPickerActivate(event) {
   const into = event.target.closest('[data-into]');
   if (into) loadBrowse(into.dataset.into);
 }
+
+
+/* How to comment
+ * ---------------------------------------------------------------------------
+ * Open until it is dismissed, then remembered as dismissed. A hint that cannot
+ * be turned off becomes furniture, and a hint that has to be found is not one.
+ */
+
+/** Where the dismissal is remembered. Per browser; it is a convenience, not state. */
+const HOW_TO_KEY = 'reviewer.howTo.collapsed';
+
+/**
+ * @returns {boolean} whether it has been collapsed before
+ */
+function howToWasCollapsed() {
+  try {
+    return window.localStorage.getItem(HOW_TO_KEY) === 'true';
+  } catch {
+    // A private window, or site data blocked. Showing the hint again is a far
+    // better failure than not rendering the panel at all.
+    return false;
+  }
+}
+
+/**
+ * @param {boolean} collapsed
+ */
+function rememberHowTo(collapsed) {
+  try {
+    window.localStorage.setItem(HOW_TO_KEY, String(collapsed));
+  } catch {
+    // Nothing to do. It reopens next time, which is the harmless direction.
+  }
+}
+
+function toggleHowTo() {
+  const panel = document.getElementById('howTo');
+  const collapsed = panel.classList.toggle('collapsed');
+
+  document.getElementById('howToToggle').setAttribute('aria-expanded', String(!collapsed));
+  rememberHowTo(collapsed);
+}
+
+function restoreHowTo() {
+  const panel = document.getElementById('howTo');
+  if (!panel) return;
+
+  const collapsed = howToWasCollapsed();
+  panel.classList.toggle('collapsed', collapsed);
+  document.getElementById('howToToggle').setAttribute('aria-expanded', String(!collapsed));
+}

package/public/index.html

@@ -101,6 +101,28 @@
           Full Context
         </button>
       </div>
+      <section id="howTo" class="how-to">
+        <button
+          id="howToToggle"
+          class="how-to-toggle"
+          onclick="toggleHowTo()"
+          aria-expanded="true"
+          aria-controls="howToBody">
+          <span class="how-to-chevron" aria-hidden="true">▾</span>
+          How to comment
+        </button>
+        <div id="howToBody" class="how-to-body">
+          <p><strong>Click a line number</strong> in the left column to comment on that line.
+            Removed lines work too — the most useful note is often about deleted code.</p>
+          <p><strong>Hold <kbd>⌘</kbd>/<kbd>Ctrl</kbd> and drag</strong> to select part of a line,
+            then click the line number. The selection is quoted in the comment.</p>
+          <p><kbd>⌘</kbd>/<kbd>Ctrl</kbd> + <kbd>Enter</kbd> saves ·
+            <kbd>Esc</kbd> cancels ·
+            <kbd>↑</kbd> <kbd>↓</kbd> move between files</p>
+          <p>Everything saves as you type. <strong>Submit Review</strong> when you are done.</p>
+        </div>
+      </section>
+
       <div id="codeViewer" class="code-viewer"></div>
     </main>
 

package/public/style.css

@@ -1319,3 +1319,132 @@ button:disabled {
   max-height: calc(100vh - 112px);
   overflow-y: auto;
 }
+
+/* Where the review went
+ *
+ * The modal used to offer a download and nothing else, which is an odd thing
+ * to put in front of somebody who started this from a terminal. The review is
+ * already a file; knowing where is more useful than a second copy of it.
+ */
+.review-destination {
+  display: flex;
+  align-items: baseline;
+  gap: 10px;
+  margin-bottom: 14px;
+  padding: 10px 12px;
+  border: 1px solid #e1e4e8;
+  border-radius: 6px;
+  background: #f6f8fa;
+  font-size: 13px;
+  color: #24292e;
+}
+
+.review-destination.handed-off {
+  border-color: #b7e0c2;
+  background: #eefcf1;
+}
+
+.review-destination strong {
+  flex: none;
+  font-weight: 600;
+}
+
+.review-destination span {
+  min-width: 0;
+  color: #57606a;
+}
+
+.review-destination .review-path {
+  /* Wrapped rather than truncated. There is room in a modal, and every way of
+   * shortening a path hides the half somebody wanted: cut the front and the
+   * directory goes, cut the back and the filename goes. */
+  word-break: break-all;
+  font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+  font-size: 12px;
+}
+
+.review-destination {
+  align-items: flex-start;
+}
+
+/* How to comment
+ *
+ * Nothing on screen said that the column of line numbers was clickable, or
+ * that holding Cmd and dragging selects a snippet to quote. Both are obvious
+ * the second time and invisible the first, which is exactly what a hint is
+ * for -- and exactly why it has to be dismissible rather than permanent.
+ */
+.how-to {
+  flex: none;
+  border-bottom: 1px solid #e1e4e8;
+  background: #f6f8fa;
+}
+
+.how-to-toggle {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  padding: 8px 20px;
+  border: none;
+  background: transparent;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  color: #57606a;
+  text-align: left;
+  cursor: pointer;
+}
+
+.how-to-toggle:hover {
+  color: #24292e;
+}
+
+.how-to-chevron {
+  display: inline-block;
+  font-size: 10px;
+  transition: transform 0.15s ease;
+}
+
+.how-to.collapsed .how-to-chevron {
+  transform: rotate(-90deg);
+}
+
+.how-to.collapsed .how-to-body {
+  display: none;
+}
+
+.how-to-body {
+  padding: 0 20px 12px 20px;
+}
+
+.how-to-body p {
+  margin: 0 0 6px 0;
+  font-size: 12.5px;
+  line-height: 1.5;
+  color: #57606a;
+}
+
+.how-to-body p:last-child {
+  margin-bottom: 0;
+}
+
+.how-to-body strong {
+  color: #24292e;
+  font-weight: 600;
+}
+
+.how-to-body kbd {
+  display: inline-block;
+  min-width: 18px;
+  padding: 1px 5px;
+  border: 1px solid #d1d5da;
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  background: white;
+  font-family: inherit;
+  font-size: 11px;
+  line-height: 1.4;
+  color: #24292e;
+  text-align: center;
+}

package/server.js

@@ -48,13 +48,22 @@ class FileNotFoundError extends Error {
  * @param {string} [options.reviewsDir] where comment and review files are written
  * @param {SessionStore} [options.sessions]
  * @param {(path: string) => import('simple-git').SimpleGit} [options.git] git factory, injectable for tests
+ * @param {(review: {document: object, reviewPath: string, documentPath: string,
+ *   comments: object[]}) => void} [options.onReviewSubmitted] called after a
+ *   review is written, so the process that started the server can act on it.
+ *   This is what lets `reviewer` hand the finished review back to the terminal.
+ * @param {boolean} [options.handoff] whether the caller is going to do
+ *   something with a submitted review. Reported to the page so it can say
+ *   where the review went instead of only offering a download.
  * @returns {import('express').Express}
  */
 function createApp(options = {}) {
   const {
     reviewsDir = resolveReviewsDir(),
     sessions = new SessionStore(),
-    git: gitFactory = simpleGit
+    git: gitFactory = simpleGit,
+    onReviewSubmitted = null,
+    handoff = false
   } = options;
 
   const app = express();
@@ -292,7 +301,10 @@ function createApp(options = {}) {
       }
 
       const repoId = sessions.create(root, mode);
-      console.log(`Loaded repository: ${root} (mode: ${mode})`);
+      // stderr, not stdout. `reviewer | claude -p ...` puts the finished
+      // review on stdout, and anything else written there lands in the middle
+      // of it. Progress is for the person watching; stdout is for the pipe.
+      console.error(`Loaded repository: ${root} (mode: ${mode})`);
 
       try {
         await recordRecent(reviewsDir, root);
@@ -465,16 +477,39 @@ function createApp(options = {}) {
         `${JSON.stringify(document, null, 2)}\n`
       );
 
-      console.log(`Review generated: ${filename} (${comments.length} comments)`);
+      console.error(`Review generated: ${filename} (${comments.length} comments)`);
+
+      const reviewPath = path.join(reviewsDir, filename);
 
       res.json({
         message: 'Review submitted successfully',
         reviewContent,
         filename,
         documentFilename,
+        reviewPath,
+        // The page has no other way to know whether anything is waiting for
+        // this on the other side, and "download it" is the wrong thing to say
+        // to someone whose terminal is about to be handed the same review.
+        handoff,
         review: document,
         totalComments: comments.length
       });
+
+      // After the response, so a slow or throwing consumer cannot make the
+      // browser think the submit failed. The review is already on disk by now
+      // and the caller is told where.
+      if (onReviewSubmitted) {
+        try {
+          onReviewSubmitted({
+            document,
+            reviewPath,
+            documentPath: path.join(reviewsDir, documentFilename),
+            comments
+          });
+        } catch (error) {
+          console.error('Review handoff failed:', error.message);
+        }
+      }
     } catch (error) {
       if (error instanceof ReviewOwnershipError) {
         return res.status(409).json({ error: error.message });
@@ -510,12 +545,14 @@ function startServer(options = {}) {
     silent = false,
     ...appOptions
   } = options;
+  // Everything else in `options` -- reviewsDir, sessions, git, handoff and
+  // onReviewSubmitted -- goes through to the app.
   const app = createApp(appOptions);
 
   return new Promise((resolve, reject) => {
     const server = app.listen(port, host, () => {
       if (!silent) {
-        console.log(`Code Reviewer server running on http://${host}:${server.address().port}`);
+        console.error(`Code Reviewer server running on http://${host}:${server.address().port}`);
       }
       resolve(server);
     });