@levistudio/redline 0.1.0

package/src/agent.ts

@@ -0,0 +1,283 @@
+import path from "path";
+import { existsSync, unlinkSync } from "fs";
+import { appendFile, mkdir, readFile } from "fs/promises";
+import { resolve } from "./resolve";
+import { pickReplyModel } from "./pickModel";
+import { parseReply } from "./parseReply";
+import { newEnvelope } from "./promptEnvelope";
+import { contextBlock } from "./contextBlock";
+import { loadSidecar } from "./sidecar";
+
+const filePath = process.argv[2];
+if (!filePath) {
+  console.error("[agent] Usage: agent <file.md>");
+  process.exit(1);
+}
+
+// Test-only crash hook: shortly after startup, if REDLINE_AGENT_CRASH_FILE
+// points to an existing file, delete it and exit non-zero. The delay is so
+// the agent connects to SSE and logs "[agent] connected" first — the test
+// then waits for a *second* connect to prove the restart fired. Unlink
+// ensures the restart spawn starts cleanly.
+const crashFile = process.env.REDLINE_AGENT_CRASH_FILE;
+if (crashFile) {
+  setTimeout(() => {
+    if (!existsSync(crashFile)) return;
+    console.log(`[agent] crash hook fired — exiting (file=${crashFile})`);
+    try { unlinkSync(crashFile); } catch { /* best effort */ }
+    process.exit(99);
+  }, 500);
+}
+
+// Test-only "always crash" hook: every spawn exits non-zero after a short
+// delay, so the cli's restart cap can be exercised end-to-end. Unlike the
+// crash-file hook above, this leaves no trigger to delete — every spawn
+// crashes until the cli gives up.
+if (process.env.REDLINE_AGENT_CRASH_ALWAYS === "1") {
+  setTimeout(() => {
+    console.log("[agent] crash-always hook fired — exiting");
+    process.exit(99);
+  }, 100);
+}
+
+const BASE_URL = `http://localhost:${process.env.REDLINE_PORT ?? "3000"}`;
+const CSRF_TOKEN = process.env.REDLINE_TOKEN ?? "";
+
+// Inject `X-Redline-Token` on every mutating call back to the server. The
+// server rejects unauthenticated POST/DELETE/PUT/PATCH on /api/*; without
+// this header the agent's replies would be silently 403'd.
+const CSRF_HEADER = { "X-Redline-Token": CSRF_TOKEN };
+
+async function logReplyFailure(commentId: string, err: unknown) {
+  const logDir = path.join(path.dirname(path.resolve(filePath)), ".review");
+  await mkdir(logDir, { recursive: true });
+  const logPath = path.join(logDir, "errors.log");
+  const msg = err instanceof Error ? err.message : String(err);
+  const stack = err instanceof Error && err.stack ? `\n${err.stack}` : "";
+  const entry =
+    `\n=== ${new Date().toISOString()} — reply failure — comment ${commentId} ===\n` +
+    `file:    ${path.resolve(filePath)}\n` +
+    `reason:  ${msg}${stack}\n` +
+    `===\n`;
+  try {
+    await appendFile(logPath, entry, "utf-8");
+    console.error(`[agent] Logged reply failure → .review/errors.log`);
+  } catch {
+    // best-effort — don't mask the original error
+  }
+}
+
+function replySystemPrompt(envelopeHint: string): string {
+  return REPLY_SYSTEM_PROMPT_BODY + "\n\n" + envelopeHint;
+}
+
+const REPLY_SYSTEM_PROMPT_BODY =
+  "You are an AI writing assistant responding to inline review comments on a Markdown document. " +
+  "The reviewer has selected a passage and left a comment or question. Reply in the cards rail — keep it tight.\n" +
+  "- Match reply length to the reviewer's comment. A one-line comment gets a one-line reply. A typo flag gets \"Got it\" or similar.\n" +
+  "- Only propose replacement text or alternatives when the reviewer explicitly asks for them. Don't volunteer options they didn't request.\n" +
+  "- If the reviewer asks a question, answer it directly. If they approve something, a short confirmation is enough.\n" +
+  "- Never recap what they said back to them. No preamble. Start with the substance.\n" +
+  "- Hard ceiling: 3 sentences unless the reviewer's comment genuinely requires more.\n" +
+  "\n" +
+  "After your reply, decide: would fully addressing this comment require editing the document itself, or was it answered within the conversation?\n" +
+  "- requires_revision: true  → an edit to the doc is implied (typo fix, rewording, restructure, content change, etc.)\n" +
+  "- requires_revision: false → the conversation answered it (clarifying question, approval, agent explanation that doesn't imply an edit)\n" +
+  "\n" +
+  "When requires_revision is true, the UI already shows the reason next to your reply — DO NOT restate the planned edit in your message. The message should engage with the reviewer (acknowledge, confirm, or briefly engage with their point); the reason describes the edit. Don't say the same thing twice.\n" +
+  "Bad:  message: \"Will add a line 3 to the example.\"  reason: \"Add a third line to the hard line breaks example\"  ← redundant\n" +
+  "Good: message: \"Got it.\"  reason: \"Add a third line to the hard line breaks example\"\n" +
+  "When requires_revision is false, leave reason empty (or a very short note about why no edit). The reply IS the answer.\n" +
+  "\n" +
+  "Output exactly this format and nothing else (no prose before/after, no code fences). Use these literal markers — do not escape quotes inside the message:\n" +
+  "REQUIRES_REVISION: <true|false>\n" +
+  "REASON: <one short sentence describing the edit, or empty>\n" +
+  "---MESSAGE---\n" +
+  "<your reply text — quotes, punctuation, anything>\n" +
+  "---END---";
+
+const inProgress = new Set<string>();
+
+async function fetchComments() {
+  const res = await fetch(`${BASE_URL}/api/comments`);
+  return res.json() as Promise<{ comments: any[]; roundResolved: boolean }>;
+}
+
+async function postThinking(commentId: string) {
+  await fetch(`${BASE_URL}/api/comment/${commentId}/thinking`, {
+    method: "POST",
+    headers: CSRF_HEADER,
+  });
+}
+
+async function postReply(
+  commentId: string,
+  message: string,
+  requires_revision: boolean,
+  revision_reason: string
+) {
+  await fetch(`${BASE_URL}/api/comment/${commentId}/reply`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...CSRF_HEADER },
+    body: JSON.stringify({ role: "agent", name: "Claude", message, requires_revision, revision_reason }),
+  });
+}
+
+async function postAgentReplied() {
+  await fetch(`${BASE_URL}/api/agent-replied`, {
+    method: "POST",
+    headers: CSRF_HEADER,
+  });
+}
+
+async function handleComment(commentId: string) {
+  if (inProgress.has(commentId)) return;
+  inProgress.add(commentId);
+
+  try {
+    const data = await fetchComments();
+    const comment = data.comments.find((c: any) => c.id === commentId);
+    if (!comment || comment.resolved) return;
+
+    // Only respond when the last message was from the human
+    const thread: any[] = comment.thread ?? [];
+    if (thread.length === 0 || thread[thread.length - 1].role !== "human") return;
+
+    await postThinking(commentId);
+
+    const docText = await readFile(path.resolve(filePath), "utf-8");
+    const sidecar = await loadSidecar(path.resolve(filePath));
+    const env = newEnvelope();
+    const threadText = thread
+      .map((e: any) => `${e.role === "human" ? "Reviewer" : "Agent"}: ${e.message}`)
+      .join("\n");
+
+    // Wrap every user-controlled string (document, quote, thread, optional
+    // reviewer-supplied context) in a per-prompt UUID-anchored envelope so
+    // adversarial content inside any of them can't masquerade as system
+    // instructions or as another section. The context block is empty when
+    // the user didn't pass --context.
+    const userMessage =
+      contextBlock(sidecar.context, env) +
+      `## Document\n\n${env.wrap("document", docText)}\n\n---\n\n` +
+      `## Comment\n\nQuoted passage:\n${env.wrap("quote", comment.quote)}\n\n` +
+      `Thread:\n${env.wrap("thread", threadText)}`;
+
+    const lastMessage = thread[thread.length - 1].message as string;
+    const model = pickReplyModel(lastMessage);
+    console.log(`[agent] replying to ${commentId} with ${model}`);
+
+    const cliBin = process.env.CLAUDE_CODE_EXECPATH ?? "claude";
+    const proc = Bun.spawn(
+      [cliBin, "-p", "--system-prompt", replySystemPrompt(env.systemPromptHint()), "--model", model],
+      { stdin: "pipe", stdout: "pipe", stderr: "inherit" }
+    );
+    proc.stdin.write(userMessage);
+    proc.stdin.end();
+
+    let reply = "";
+    const reader = proc.stdout.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      reply += new TextDecoder().decode(value);
+    }
+
+    if (reply.trim()) {
+      const parsed = parseReply(reply);
+      console.log(`[agent] verdict for ${commentId}: requires_revision=${parsed.requires_revision}`);
+      await postReply(commentId, parsed.message, parsed.requires_revision, parsed.reason);
+    }
+  } catch (err) {
+    await logReplyFailure(commentId, err);
+    throw err;
+  } finally {
+    inProgress.delete(commentId);
+    if (inProgress.size === 0) {
+      postAgentReplied().catch((e) => console.error("[agent] postAgentReplied failed:", e));
+    }
+  }
+}
+
+async function handleAccepted() {
+  console.log("[agent] accepted — running revision...");
+  try {
+    await resolve(path.resolve(filePath));
+  } catch (err: any) {
+    const msg = err?.message ?? String(err);
+    console.error("[agent] revision failed:", msg);
+    try {
+      await fetch(`${BASE_URL}/api/revision-error`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...CSRF_HEADER },
+        body: JSON.stringify({ message: msg }),
+      });
+    } catch { /* server may be down — non-fatal */ }
+  }
+}
+
+async function handleEvent(type: string, payload: any) {
+  if (type === "comment-added" || type === "comment-reply") {
+    handleComment(payload.commentId).catch((e) =>
+      console.error("[agent] error handling comment:", e)
+    );
+  } else if (type === "accepted") {
+    handleAccepted().catch((e) =>
+      console.error("[agent] error handling accepted:", e)
+    );
+  } else if (type === "finished") {
+    console.log("[agent] review finished — no revision needed");
+  }
+}
+
+async function connect() {
+  let retryDelay = 1000;
+
+  while (true) {
+    try {
+      const res = await fetch(`${BASE_URL}/api/events`);
+      if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
+
+      console.log("[agent] connected — listening for comments");
+      retryDelay = 1000;
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let eventType = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+
+        for (const line of lines) {
+          if (line.startsWith("event: ")) {
+            eventType = line.slice(7).trim();
+          } else if (line.startsWith("data: ")) {
+            const data = line.slice(6).trim();
+            try {
+              const payload = JSON.parse(data);
+              handleEvent(eventType, payload).catch((e) =>
+                console.error("[agent] unhandled event error:", e)
+              );
+            } catch {}
+            eventType = "";
+          } else if (line === "") {
+            eventType = "";
+          }
+        }
+      }
+    } catch {
+      // server not up yet or restarting — keep retrying
+    }
+
+    await new Promise((r) => setTimeout(r, retryDelay));
+    retryDelay = Math.min(retryDelay * 2, 10000);
+  }
+}
+
+connect();

package/src/cli.ts

@@ -0,0 +1,332 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync, writeFileSync, unlinkSync, readFileSync, statSync } from "fs";
+import { mkdir, writeFile } from "fs/promises";
+import { spawnSync } from "child_process";
+import { createRequire } from "module";
+import path from "path";
+
+// Ensure redline's own dependencies are resolvable before any third-party
+// imports load. `redline` is invoked from arbitrary projects: in a checkout
+// they sit in `<root>/node_modules`, but when installed from npm they're
+// hoisted to the consumer's top-level `node_modules`. Use Node's standard
+// module resolution so both layouts are handled.
+//
+// The auto-install fallback is for the checkout case (`git clone` + run
+// without `bun install`). When already installed from a registry, deps are
+// always resolvable and we never fall through to it.
+function preflightDependencies() {
+  const root = path.resolve(import.meta.dir, "..");
+  const pkgPath = path.join(root, "package.json");
+  // Compiled single-file binaries have no package.json next to the script —
+  // skip the check entirely in that case.
+  if (!existsSync(pkgPath)) return;
+  let pkg: { dependencies?: Record<string, string> };
+  try { pkg = JSON.parse(readFileSync(pkgPath, "utf8")); } catch { return; }
+  const deps = Object.keys(pkg.dependencies ?? {});
+  const require = createRequire(pkgPath);
+  const missing = deps.filter((d) => {
+    try { require.resolve(d); return false; } catch { return true; }
+  });
+  if (missing.length === 0) return;
+  console.log(`[redline] Dependencies missing from ${root}/node_modules: ${missing.join(", ")}`);
+  console.log(`[redline] Running \`bun install\` in the redline checkout…`);
+  const r = spawnSync("bun", ["install"], { cwd: root, stdio: "inherit" });
+  if (r.status !== 0) {
+    console.error(`\n[redline] \`bun install\` failed. Run it manually in ${root} and retry.`);
+    process.exit(1);
+  }
+}
+preflightDependencies();
+
+// Dynamic imports so preflight runs before module resolution pulls in third-party deps.
+const { createServer } = await import("./server");
+const { resolve } = await import("./resolve");
+
+// Verify the `claude` CLI is reachable before we start, so first-run users
+// without Claude Code installed get a clear message instead of a silent agent
+// crash later (the agent process shells out to `claude -p`; without it, replies
+// fail and errors land in `.review/errors.log` where nobody looks).
+//
+// Resolution mirrors the runtime: prefer CLAUDE_CODE_EXECPATH (used by tests
+// and advanced setups), then look for `claude` on PATH.
+function preflightClaudeCli() {
+  const exec = process.env.CLAUDE_CODE_EXECPATH;
+  if (exec && existsSync(exec)) return;
+  if (Bun.which("claude")) return;
+  console.error(
+    "\n[redline] Could not find the `claude` CLI on PATH.\n" +
+    "Redline shells out to Claude Code for agent replies and revisions.\n" +
+    "Install it from https://claude.com/claude-code and re-run.\n"
+  );
+  process.exit(1);
+}
+
+// Walk up from `start` looking for a git root (a `.git` directory or file —
+// worktrees use a file). Returns the directory containing it, or null.
+function findGitRoot(start: string): string | null {
+  let dir = start;
+  while (true) {
+    if (existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// If the file lives inside a git repo and `.review/` isn't already ignored,
+// print a one-line hint. We don't edit .gitignore — just nudge.
+function maybePrintGitignoreHint(filePath: string) {
+  const root = findGitRoot(path.dirname(filePath));
+  if (!root) return;
+  const gitignorePath = path.join(root, ".gitignore");
+  let contents = "";
+  try {
+    if (existsSync(gitignorePath) && statSync(gitignorePath).isFile()) {
+      contents = readFileSync(gitignorePath, "utf-8");
+    }
+  } catch { /* unreadable — fall through and hint */ }
+  const lines = contents.split("\n").map((l) => l.trim());
+  const ignored = lines.some((l) =>
+    l === ".review" || l === ".review/" || l === "**/.review" || l === "**/.review/"
+  );
+  if (ignored) return;
+  console.log(`\n  Tip: redline writes to .review/ next to your file. Add this to ${path.relative(process.cwd(), gitignorePath) || ".gitignore"} to keep it out of git:`);
+  console.log(`    .review/`);
+}
+
+const args = process.argv.slice(2);
+
+// redline resolve <file> [--model <id>]
+if (args[0] === "resolve") {
+  const filePath = args[1];
+  if (!filePath) {
+    console.error("Usage: redline resolve <file.md> [--model <model-id>]");
+    process.exit(1);
+  }
+  const resolved = path.resolve(filePath);
+  if (!existsSync(resolved)) {
+    console.error(`File not found: ${resolved}`);
+    process.exit(1);
+  }
+  const modelFlag = args.indexOf("--model");
+  const model = modelFlag !== -1 ? args[modelFlag + 1] : undefined;
+  preflightClaudeCli();
+  resolve(resolved, { model });
+} else {
+  // redline <file>  — open review reader
+  const filePath = args[0];
+  if (!filePath) {
+    console.error("Usage: redline <file.md>");
+    process.exit(1);
+  }
+  const resolved = path.resolve(filePath);
+  if (!existsSync(resolved)) {
+    console.error(`File not found: ${resolved}`);
+    process.exit(1);
+  }
+  const noAgent = args.includes("--no-agent");
+
+  // Manual annotation mode skips both the preflight and the agent spawn —
+  // the user just wants inline comments without a Claude conversation, so
+  // requiring claude on PATH would be a hostile gate.
+  if (!noAgent) preflightClaudeCli();
+
+  const contextFlag = args.indexOf("--context");
+  const context = contextFlag !== -1 ? args[contextFlag + 1] : undefined;
+  const autoOpen = args.includes("--open");
+
+  const resultFile = path.join(path.dirname(resolved), ".review", path.basename(resolved) + ".result");
+  const startupFile = path.join(path.dirname(resolved), ".review", path.basename(resolved) + ".startup.json");
+
+  // Clear stale state from a prior run so a polling agent can't be misled
+  // by a leftover .result or .startup.json file that predates this process.
+  for (const f of [resultFile, startupFile]) {
+    try { unlinkSync(f); } catch { /* not present is fine */ }
+  }
+
+  async function writeResult(payload: Record<string, unknown>) {
+    try {
+      await mkdir(path.dirname(resultFile), { recursive: true });
+      await writeFile(resultFile, JSON.stringify(payload, null, 2), "utf-8");
+    } catch (e) {
+      console.error("[redline] Failed to write result file:", e);
+    }
+  }
+
+  // CSRF token threaded through to: createServer (mints from this), the agent
+  // subprocess (via REDLINE_TOKEN env), and startup.json (so a calling skill
+  // or test runner can read it). `REDLINE_TOKEN` from env wins so an outer
+  // caller can pin the token if it needs to.
+  const csrfToken = process.env.REDLINE_TOKEN ?? crypto.randomUUID();
+
+  const app = createServer(resolved, { context, csrfToken, noAgent });
+  const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: app.fetch, idleTimeout: 0 });
+  const url = `http://localhost:${server.port}`;
+
+  // Surface the URL to a calling agent that can't read this process's stdout.
+  // (Bash with timeout buffers stdout until the process exits — for blocking
+  // invocations the agent would otherwise never see the URL until the human
+  // clicked Done. Polling this file gives a deterministic, race-free signal.)
+  try {
+    mkdirSync(path.dirname(startupFile), { recursive: true });
+    writeFileSync(startupFile, JSON.stringify({
+      url,
+      port: server.port,
+      file: resolved,
+      result_file: resultFile,
+      started_at: new Date().toISOString(),
+      pid: process.pid,
+      csrf_token: csrfToken,
+    }, null, 2));
+  } catch (e) {
+    console.error("[redline] Failed to write startup file:", e);
+  }
+
+  const bar = "─".repeat(60);
+  console.log(`\n${bar}`);
+  console.log(`Redline review session`);
+  console.log(`  File: ${resolved}`);
+  console.log(`  URL:  ${url}`);
+  console.log(`  Result: ${resultFile}`);
+  console.log(`${bar}`);
+  if (noAgent) console.log(`  Mode: manual annotation (--no-agent — no Claude replies, no revision pass)`);
+  if (!autoOpen) console.log(`\n  → cmd-click the URL when you're ready to review\n`);
+  else console.log("");
+
+  maybePrintGitignoreHint(resolved);
+
+  // Auto-restart the agent if it dies unexpectedly (harness reaping, OOM,
+  // a transient claude-CLI auth blip, etc). Capped to MAX_RESTARTS within
+  // RESTART_WINDOW_MS so a permanently-broken environment doesn't loop forever.
+  const RESTART_WINDOW_MS = 60_000;
+  // Cap is overrideable via env so integration tests can exercise the
+  // give-up path without spawning the agent six times.
+  const MAX_RESTARTS = Number(process.env.REDLINE_MAX_RESTARTS ?? 5);
+  const restartTimes: number[] = [];
+  let agentProc: ReturnType<typeof Bun.spawn>;
+  let serverExiting = false;
+
+  function spawnAgent() {
+    const proc = Bun.spawn(
+      [process.execPath, "run", path.join(import.meta.dir, "agent.ts"), resolved],
+      {
+        stdout: "inherit", stderr: "inherit", stdin: "ignore",
+        env: { ...process.env, REDLINE_PORT: String(server.port), REDLINE_TOKEN: csrfToken },
+      }
+    );
+    agentProc = proc;
+    proc.exited.then((code) => {
+      if (serverExiting) return;
+      if (code === 0) return;
+      const now = Date.now();
+      while (restartTimes.length && now - restartTimes[0] > RESTART_WINDOW_MS) restartTimes.shift();
+      if (restartTimes.length >= MAX_RESTARTS) {
+        const reason = `Agent crashed ${restartTimes.length}× in ${RESTART_WINDOW_MS / 1000}s — replies unavailable. Restart redline to recover.`;
+        console.error(
+          `\n[redline] ${reason} The review can still be completed manually. Check .review/errors.log.`
+        );
+        // Surface the dead-agent state to the browser so the user isn't left
+        // wondering why replies stopped. Best-effort: server may already be down.
+        fetch(`http://localhost:${server.port}/api/agent-unavailable`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "X-Redline-Token": csrfToken },
+          body: JSON.stringify({ reason }),
+        }).catch(() => { /* server already gone */ });
+        return;
+      }
+      restartTimes.push(now);
+      console.error(
+        `[redline] Agent exited unexpectedly (code ${code}) — restarting (${restartTimes.length}/${MAX_RESTARTS}).`
+      );
+      spawnAgent();
+    });
+  }
+  if (!noAgent) spawnAgent();
+
+  // Graceful shutdown: SIGTERM first so agent.ts can flush in-flight HTTP
+  // posts and close its SSE connection cleanly, then SIGKILL after 2s if
+  // the agent is still alive (broken handler, stuck syscall, etc.).
+  // Async-aware version for the abandon/finish paths; the sync version
+  // (`killAgentSync`) is used inside `process.on("exit")` where we can't await.
+  const SHUTDOWN_GRACE_MS = 2000;
+  async function killAgent() {
+    if (!agentProc) return;
+    try { agentProc.kill("SIGTERM"); } catch { return; /* already dead */ }
+    const deadline = new Promise<void>((resolve) => setTimeout(resolve, SHUTDOWN_GRACE_MS));
+    await Promise.race([agentProc.exited.then(() => undefined), deadline]);
+    if (agentProc && agentProc.exitCode === null) {
+      try { agentProc.kill("SIGKILL"); } catch { /* already dead */ }
+    }
+  }
+  function killAgentSync() {
+    try { agentProc?.kill("SIGTERM"); } catch { /* already dead */ }
+  }
+  // Tracks the last unrecovered revision failure. If the session abandons while
+  // this is set, the result file reports "error" instead of "abandoned" so a
+  // calling agent can distinguish "user walked away" from "revision broke."
+  let lastRevisionError: string | null = null;
+
+  const abandon = () => {
+    if (serverExiting) return;
+    serverExiting = true;
+    killAgent().catch(() => { /* shutdown already in flight */ });
+    try { unlinkSync(startupFile); } catch { /* best effort */ }
+    const status = lastRevisionError ? "error" : "abandoned";
+    const payload: Record<string, unknown> = { status, file: resolved };
+    if (lastRevisionError) payload.reason = lastRevisionError;
+    // Synchronous write so the result file lands even if the runtime is
+    // terminating due to a signal (async I/O may not complete in that case).
+    try {
+      mkdirSync(path.dirname(resultFile), { recursive: true });
+      writeFileSync(resultFile, JSON.stringify(payload, null, 2));
+    } catch { /* best effort */ }
+    console.log(`\nREDLINE_RESULT: ${status}${lastRevisionError ? ` reason="${lastRevisionError}"` : ""}`);
+    // Exit 3 = revision error; 2 = abandoned. Both still distinguish from 0 (approved).
+    process.exit(lastRevisionError ? 3 : 2);
+  };
+
+  // Happy-path finish: human clicked Done.
+  app.onFinished(({ totalRounds, totalComments }) => {
+    serverExiting = true;
+    killAgent().catch(() => { /* shutdown already in flight */ });
+    try { unlinkSync(startupFile); } catch { /* best effort */ }
+    const line = "─".repeat(60);
+    console.log(`\n${line}`);
+    console.log(`✓  Review complete — ${path.basename(resolved)}`);
+    console.log(`   ${totalRounds} round${totalRounds !== 1 ? "s" : ""} · ${totalComments} comment${totalComments !== 1 ? "s" : ""} addressed`);
+    console.log(`   Revised document: ${resolved}`);
+    console.log(`${line}`);
+    // Machine-greppable result line for a calling agent. Keep this stable.
+    console.log(`REDLINE_RESULT: approved file=${resolved} rounds=${totalRounds} comments=${totalComments}`);
+    console.log("");
+    writeResult({ status: "approved", file: resolved, rounds: totalRounds, comments: totalComments })
+      .finally(() => process.exit(0));
+  });
+
+  // Tab-close abandonment: if no browser reconnects within the abandon grace, exit cleanly.
+  app.onAbandon(abandon);
+
+  // Track revision-error state so a session that abandons after a broken revision
+  // exits with status: "error" rather than "abandoned".
+  app.onRevisionError((message) => {
+    lastRevisionError = message;
+    console.error(`[redline] Revision failed: ${message}`);
+  });
+  app.onRevisionRecovered(() => {
+    if (lastRevisionError) console.log("[redline] Revision-error state cleared.");
+    lastRevisionError = null;
+  });
+
+  process.on("exit", () => { serverExiting = true; killAgentSync(); });
+  // SIGINT/SIGTERM = abandoned session. Exit 2 so a calling agent can
+  // distinguish "user gave up" from "user clicked Done" (exit 0).
+  process.on("SIGINT", abandon);
+  process.on("SIGTERM", abandon);
+
+  if (autoOpen) {
+    const open =
+      process.platform === "darwin" ? "open" :
+      process.platform === "win32"  ? "start" : "xdg-open";
+    Bun.spawn([open, url]);
+  }
+}