@levistudio/redline 0.4.0 → 0.5.0

package/AGENTS.md

@@ -35,6 +35,9 @@ redline <file> --context "..." # opens with a reviewer-supplied focus statement
 redline <file> --agent codex   # use Codex instead of the auto-detected/default provider
 redline <file> --no-agent      # manual annotation mode — no agent spawn, no provider CLI required on PATH
 redline resolve <file>         # one-shot: read the sidecar, run the revision pass, write back
+redline author-needed <file>   # list comments where the inline agent requested author input
+redline author-reply <file> <comment-id> --message "..." # post an author-marked reply into the thread
+redline author-wait <file>     # block until author input is needed or the review result is written
 ```
 
 The bare-arg path also spawns a dedicated agent subprocess alongside the server — see "The dedicated agent process" below.
@@ -196,12 +199,13 @@ JSON was tried first and abandoned: agent replies frequently contain quotes, cod
 
 The verdict is **agent-owned**. The human cannot flip it directly. Disagreement flows through a follow-up reply, which gives the agent a chance to re-classify rather than be silently overridden.
 
-## Escalation to the launching agent
+## Author handoff
 
-The inline review agent and the agent that *launched* `redline` share no live channel — the sidecar is the only persisted artifact, and the launching agent only regains control when the session exits. So two mechanisms carry feedback back to it:
+The inline review agent and the agent that *authored/launched* `redline` are separate processes. The sidecar is the persisted artifact, and `.startup.json` gives the authoring agent a local API bridge while the session is live. Two mechanisms carry feedback back to it:
 
-- **`ESCALATE` verdict.** A second, orthogonal flag in the reply envelope. The agent sets `ESCALATE: true` when a comment can't be acted on from inside the review — it needs the launching agent's project context, tools, or authority (an external style guide, a spec to check against, a wider-project decision). It's stored as `escalate?: boolean` on the agent's `ThreadEntry` and rendered as an "↑ Escalated" badge on the comment and an "↑ Routed to the launching agent" note in the thread. Escalation is independent of `requires_revision` — the agent judges each on its own.
-- **Closeout transcript.** On `finished`, the CLI loads the sidecar and prints every comment thread verbatim via [src/reviewSummary.ts](src/reviewSummary.ts) (`formatReviewSummary`), with a dedicated callout listing escalated comments (`collectEscalations`). The escalation count is also written to `.review/<file>.result` and appended to the `REDLINE_RESULT:` line. This is the launching agent's read point — it sees the transcript when control hands back.
+- **`ESCALATE` verdict.** The storage/envelope name is still `ESCALATE` for compatibility, but product language is **author reply needed**. The inline agent sets `ESCALATE: true` when a comment needs author-level input: information, tools, authority, or project context it cannot access from the document and comment thread (an external style guide, a spec to check against, a wider-project decision). It does **not** set it for ordinary requested edits, reframes, emphasis changes, rewrites, or approvals; those are handled by `requires_revision`. It's stored as `escalate?: boolean` on the agent's `ThreadEntry` and rendered as an "↑ Author reply needed" badge on the comment. The author handoff signal is independent of `requires_revision` — the agent judges each on its own.
+- **Live author replies.** The authoring agent can run `redline author-wait <file>` while a session is open; it returns JSON when either a pending author-needed comment appears or the final `.result` is written. For pending comments, it can run `redline author-reply <file> <comment-id> --message "..."` to post back into the same thread, then wait again. When the server is live, the reply command uses `.review/<file>.startup.json` and the local API so the browser soft-refreshes; if the server is gone, it falls back to a locked sidecar write.
+- **Closeout transcript.** On `finished`, the CLI loads the sidecar and prints every comment thread verbatim via [src/reviewSummary.ts](src/reviewSummary.ts) (`formatReviewSummary`), with a dedicated callout listing comments that need author input (`collectEscalations`). The count is also written to `.review/<file>.result` and appended to the `REDLINE_RESULT:` line. This remains the fallback read point for abandoned or unfinished sessions.
 
 ## Security & resilience as built
 

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to Redline are documented here. The format follows [Keep a C
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-15
+
+### Added
+- Added author-handoff CLI commands: `redline author-needed <file>` lists pending author-needed comments, `redline author-reply <file> <comment-id> --message "..."` posts an author-marked reply back into the thread, and `redline author-wait <file>` blocks until either author input is needed or the review finishes.
+
+### Changed
+- Reframed M9 author handoff language from "escalated to the launching agent" to "author reply needed" while preserving the existing `ESCALATE`/`escalations` compatibility fields.
+
+## [0.4.1] - 2026-05-15
+
+### Fixed
+- `redline-review` now launches Redline with `--open` so agent sessions open the review in the user's real browser instead of relying on clickable localhost links that some agent UIs capture in an embedded preview panel.
+
 ## [0.4.0] - 2026-05-15
 
 ### Added
@@ -60,7 +73,9 @@ Initial public release on npm as `@levistudio/redline`.
 - Auto-installs missing dependencies on first CLI run.
 - Initial test suite: server, sidecar, parsing, model-picking, rendering, diff, SSE, integration, happy-dom client.
 
-[Unreleased]: https://github.com/alevi/redline/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/alevi/redline/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/alevi/redline/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/alevi/redline/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/alevi/redline/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/alevi/redline/releases/tag/v0.3.0
 [0.2.0]: https://github.com/alevi/redline/releases/tag/v0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levistudio/redline",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Inline comments on Markdown files, for human-in-the-loop AI doc review.",
   "keywords": [
     "markdown",

package/skills/redline-review/SKILL.md

@@ -20,8 +20,8 @@ STARTUP="$DIR/.review/$BASE.startup.json"
 RESULT="$DIR/.review/$BASE.result"
 LOG=/tmp/redline-$BASE.log
 
-# Kick off the review in the background.
-__REDLINE_BIN__ "$FILE" > "$LOG" 2>&1 &
+# Kick off the review in the background and open it in the user's real browser.
+__REDLINE_BIN__ "$FILE" --open > "$LOG" 2>&1 &
 
 # Step 1: wait for startup, read the URL.
 for i in $(seq 1 60); do [ -f "$STARTUP" ] && break; sleep 0.5; done
@@ -34,20 +34,19 @@ PID=$(grep -o '"pid": *[0-9]*' "$STARTUP" | grep -o '[0-9]*')
 echo "REDLINE_URL: $URL"
 echo "REDLINE_PID: $PID"
 
-# Step 2: surface the URL to the human (you do this after the first shell call returns
-# — see the next section), then wait for the redline process to exit. Watching
-# the PID (essentially free) instead of polling for the result file means you
-# wake up within ~0.5s of the human clicking Done, not up to 30s later.
-while kill -0 "$PID" 2>/dev/null; do sleep 0.5; done
-cat "$RESULT"
+# Step 2: tell the human the browser opened (you do this after the first shell call returns
+# — see the next section), then wait until either author input is needed or the
+# review exits. If author input is needed, answer it with author-reply and run
+# author-wait again.
+__REDLINE_BIN__ author-wait "$FILE"
 ```
 
 The startup file at `.review/<basename>.startup.json` is written synchronously when the server begins listening; it contains `url`, `port`, `file`, `result_file`, `started_at`, `pid`. The result file at `.review/<basename>.result` is written when the session ends (approved, abandoned, or error).
 
 In practice, run the script above as **two separate shell calls** so you can tell the human the URL between steps:
 1. First call: everything through `echo "REDLINE_PID: $PID"`. Returns in ~1s with the URL and PID on stdout.
-2. Surface the URL to the human in your reply text (see "Surfacing the URL" below).
-3. Second call: just the `while kill -0` loop waiting for the PID, then `cat "$RESULT"`. Long timeout (`timeout: 1800000` = 30 min, or longer).
+2. Tell the human Redline opened in their browser, and include the URL only as a fallback (see "Surfacing the URL" below).
+3. Second call: `__REDLINE_BIN__ author-wait "$FILE"`. It returns either `{ "kind": "author-needed", ... }` or `{ "kind": "result", ... }`. Long timeout (`timeout: 1800000` = 30 min, or longer). If it returns author-needed JSON, answer with `author-reply`, then run `author-wait` again.
 
 If invocation fails (binary missing, startup file never appears, etc.), surface the error verbatim and stop — do not try to recover. The human will re-run `redline install-skill`.
 
@@ -61,11 +60,9 @@ The context string is shown in the reader's header so the human knows what they'
 
 ### Surfacing the URL
 
-After the first shell call returns with `REDLINE_URL: http://localhost:NNNN`, surface that URL in your reply text. The human has no other signal that something is waiting for them. One short sentence:
+The `--open` flag launches the review in the user's real browser via the OS opener (`open` on macOS, `xdg-open` on Linux, `start` on Windows). After the first shell call returns with `REDLINE_URL: http://localhost:NNNN`, tell the human the browser opened and include the URL only as a fallback. Do **not** make the URL the primary action; in some agent UIs, clicking localhost opens an embedded preview panel instead of the user's browser.
 
-> "Opening this in Redline for review at http://localhost:NNNN — cmd-click to open. I'll continue once you click Done."
-
-(There is an `--open` flag that auto-launches the browser, but prefer leaving it off — the human may not be at the keyboard the moment the session starts, and a stolen-focus browser tab is worse than a URL they click when ready.)
+> "I opened this in Redline in your browser. Fallback URL: http://localhost:NNNN. I'll continue once you click Done."
 
 ## How to interpret the result
 
@@ -87,13 +84,13 @@ The full loop, when you are the outer agent producing the doc:
 
 1. Write the markdown file to disk at an absolute path.
 2. Tell the human in one sentence what's about to happen.
-3. First shell call: launch `__REDLINE_BIN__ <abs-path> --context "<one-liner>"` in the background and poll for `.startup.json`. Returns in ~1s with the URL.
-4. Surface the URL to the human in your reply text so they can cmd-click to open.
-5. Second shell call: wait on the redline PID (`while kill -0 "$PID" 2>/dev/null; do sleep 0.5; done`) then `cat "$RESULT"`, with a long timeout (30+ min). While the session runs, you are idle — do not start unrelated work, do not run other tools.
+3. First shell call: launch `__REDLINE_BIN__ <abs-path> --context "<one-liner>" --open` in the background and poll for `.startup.json`. Returns in ~1s with the URL.
+4. Tell the human Redline opened in their browser and include the URL only as a fallback.
+5. Second shell call: run `__REDLINE_BIN__ author-wait "$FILE"`. If it returns `kind: "author-needed"`, answer with `__REDLINE_BIN__ author-reply "$FILE" <comment-id> --message "..."`, then run `author-wait` again. Do not start unrelated work while the session runs.
 6. On `approved`: re-read the file from disk (it may have been revised) and continue with whatever required sign-off.
 7. On `abandoned` or `error`: stop and ask the human how to proceed; do not retry automatically.
 
-You do not need to reply to comments — Redline spawns its own agent subprocess for that. You do not need to invoke `redline resolve` separately — revisions happen inside the session when the human accepts.
+You usually do not need to reply to comments — Redline spawns its own inline agent subprocess for that. The exception is an author-needed handoff: if `author-wait` returns `kind: "author-needed"`, you are the authoring agent and should answer only when you have the project context, tools, or authority the inline agent lacked. You do not need to invoke `redline resolve` separately — revisions happen inside the session when the human accepts.
 
 ## When *not* to use this
 

package/src/agent.ts

@@ -91,7 +91,7 @@ const REPLY_SYSTEM_PROMPT_BODY =
   "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" +
-  "Separately, decide whether this comment needs the agent that LAUNCHED this review rather than you. That outer agent has the project context, tools, and authority you don't — e.g. an external style guide or canon you can't see, a spec to check the document against, or a decision that depends on the wider project. When the comment asks for something like that, set ESCALATE: true and briefly tell the reviewer in your message that you've routed it to the launching agent. Otherwise ESCALATE: false. Escalating does not change requires_revision — judge that on its own.\n" +
+  "Separately, decide whether this comment needs an AUTHOR reply from the agent that launched/wrote this document rather than you. ESCALATE is rare for now: set ESCALATE: true only when the reviewer explicitly asks for information, tools, authority, or project context you cannot access from the document and comment thread — for example an external style guide, a hidden spec, repo-wide code context, or a decision the authoring agent must make. Do NOT route ordinary requested edits, reframes, emphasis changes, priority changes, rewrites, or approvals; those are handled by requires_revision. If the comment can be satisfied by editing this document, set ESCALATE: false. When you do route to the author, briefly tell the reviewer that an author reply is needed. Author handoff does not change requires_revision — judge that on its own.\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" +

package/src/authorHandoff.ts

@@ -0,0 +1,191 @@
+import { existsSync, readFileSync } from "fs";
+import { readFile } from "fs/promises";
+import path from "path";
+import { loadSidecar, withSidecar, type Comment, type Sidecar, type ThreadEntry } from "./sidecar";
+
+export interface AuthorNeededItem {
+  round: number;
+  commentId: string;
+  quote: string;
+  request: string;
+  note: string;
+  resolved: boolean;
+}
+
+function flatten(s: string, n: number): string {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > n ? flat.slice(0, n - 1).trimEnd() + "…" : flat;
+}
+
+function latestIndex(thread: ThreadEntry[], predicate: (entry: ThreadEntry) => boolean): number {
+  for (let i = thread.length - 1; i >= 0; i--) {
+    if (predicate(thread[i]!)) return i;
+  }
+  return -1;
+}
+
+export function collectAuthorNeeded(sidecar: Sidecar): AuthorNeededItem[] {
+  const items: AuthorNeededItem[] = [];
+  for (const round of sidecar.rounds) {
+    for (const comment of round.comments) {
+      const escIdx = latestIndex(comment.thread, (entry) => entry.role === "agent" && entry.escalate === true);
+      if (escIdx === -1) continue;
+      const authorIdx = latestIndex(comment.thread, (entry) => entry.role === "agent" && entry.author === true);
+      if (authorIdx > escIdx) continue;
+
+      const agentEntry = comment.thread[escIdx]!;
+      let request = "";
+      for (let i = escIdx - 1; i >= 0; i--) {
+        if (comment.thread[i]!.role === "human") {
+          request = comment.thread[i]!.message;
+          break;
+        }
+      }
+
+      items.push({
+        round: round.round,
+        commentId: comment.id,
+        quote: flatten(comment.quote, 120),
+        request: flatten(request, 500),
+        note: flatten(agentEntry.revision_reason || agentEntry.message, 500),
+        resolved: comment.resolved,
+      });
+    }
+  }
+  return items;
+}
+
+export async function listAuthorNeeded(filePath: string): Promise<AuthorNeededItem[]> {
+  return collectAuthorNeeded(await loadSidecar(filePath));
+}
+
+export interface AuthorReplyResult {
+  via: "server" | "sidecar";
+  commentId: string;
+}
+
+export type AuthorWaitResult =
+  | { kind: "author-needed"; file: string; author_needed: AuthorNeededItem[] }
+  | { kind: "result"; file: string; result: Record<string, unknown> };
+
+function startupPath(filePath: string): string {
+  return path.join(path.dirname(filePath), ".review", path.basename(filePath) + ".startup.json");
+}
+
+function resultPath(filePath: string): string {
+  return path.join(path.dirname(filePath), ".review", path.basename(filePath) + ".result");
+}
+
+function readStartup(filePath: string): { url?: string; csrf_token?: string } | null {
+  const sp = startupPath(filePath);
+  if (!existsSync(sp)) return null;
+  try {
+    return JSON.parse(readFileSync(sp, "utf-8")) as { url?: string; csrf_token?: string };
+  } catch {
+    return null;
+  }
+}
+
+async function postToLiveServer(
+  filePath: string,
+  commentId: string,
+  message: string,
+  name: string,
+): Promise<boolean> {
+  const startup = readStartup(filePath);
+  if (!startup?.url || !startup.csrf_token) return false;
+  try {
+    const res = await fetch(`${startup.url}/api/comment/${encodeURIComponent(commentId)}/reply`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Redline-Token": startup.csrf_token,
+      },
+      body: JSON.stringify({ role: "agent", name, message, author: true }),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function findComment(sidecar: Sidecar, commentId: string): Comment | null {
+  for (const round of sidecar.rounds) {
+    const found = round.comments.find((comment) => comment.id === commentId);
+    if (found) return found;
+  }
+  return null;
+}
+
+export async function postAuthorReply(
+  filePath: string,
+  commentId: string,
+  message: string,
+  options: { name?: string } = {},
+): Promise<AuthorReplyResult> {
+  const trimmed = message.trim();
+  if (!trimmed) throw new Error("message is required");
+  const name = options.name?.trim() || "Author";
+
+  if (await postToLiveServer(filePath, commentId, trimmed, name)) {
+    return { via: "server", commentId };
+  }
+
+  const result = await withSidecar(filePath, (sidecar) => {
+    const comment = findComment(sidecar, commentId);
+    if (!comment) return { ok: false as const };
+    comment.thread.push({
+      role: "agent",
+      name,
+      message: trimmed,
+      at: new Date().toISOString(),
+      author: true,
+    });
+    return { ok: true as const };
+  });
+  if (!result.ok) throw new Error(`Comment not found: ${commentId}`);
+  return { via: "sidecar", commentId };
+}
+
+export function formatAuthorNeeded(items: AuthorNeededItem[]): string {
+  if (items.length === 0) return "No author replies needed.";
+  const lines = [
+    `${items.length} comment${items.length === 1 ? " needs an author reply" : "s need author replies"}:`,
+  ];
+  for (const item of items) {
+    lines.push(`- ${item.commentId} (round ${item.round}${item.resolved ? ", resolved" : ", open"}): "${item.quote}"`);
+    if (item.request) lines.push(`  Reviewer: ${item.request}`);
+    if (item.note) lines.push(`  Inline agent: ${item.note}`);
+  }
+  return lines.join("\n");
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function waitForAuthorEvent(
+  filePath: string,
+  options: { intervalMs?: number; timeoutMs?: number } = {},
+): Promise<AuthorWaitResult> {
+  const intervalMs = Math.max(50, options.intervalMs ?? 500);
+  const deadline = options.timeoutMs != null ? Date.now() + options.timeoutMs : null;
+  const rp = resultPath(filePath);
+
+  while (true) {
+    const authorNeeded = await listAuthorNeeded(filePath);
+    if (authorNeeded.length > 0) {
+      return { kind: "author-needed", file: filePath, author_needed: authorNeeded };
+    }
+
+    if (existsSync(rp)) {
+      const raw = await readFile(rp, "utf-8");
+      return { kind: "result", file: filePath, result: JSON.parse(raw) as Record<string, unknown> };
+    }
+
+    if (deadline != null && Date.now() >= deadline) {
+      throw new Error("Timed out waiting for author-needed comments or review result");
+    }
+    await sleep(intervalMs);
+  }
+}

package/src/cli.ts

@@ -45,6 +45,7 @@ preflightDependencies();
 // Dynamic imports so preflight runs before module resolution pulls in third-party deps.
 const { createServer } = await import("./server");
 const { resolve } = await import("./resolve");
+const { formatAuthorNeeded, listAuthorNeeded, postAuthorReply, waitForAuthorEvent } = await import("./authorHandoff");
 const {
   getAgentProvider,
   invalidProviderMessage,
@@ -123,6 +124,81 @@ if (args[0] === "install-skill") {
   process.exit(result.status ?? 1);
 }
 
+// redline author-needed <file> [--json]
+if (args[0] === "author-needed") {
+  const filePath = args[1];
+  if (!filePath) {
+    console.error("Usage: redline author-needed <file.md> [--json]");
+    process.exit(1);
+  }
+  const resolved = path.resolve(filePath);
+  if (!existsSync(resolved)) {
+    console.error(`File not found: ${resolved}`);
+    process.exit(1);
+  }
+  const items = await listAuthorNeeded(resolved);
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ file: resolved, author_needed: items }, null, 2));
+  } else {
+    console.log(formatAuthorNeeded(items));
+  }
+  process.exit(0);
+}
+
+// redline author-reply <file> <comment-id> --message "..."
+if (args[0] === "author-reply") {
+  const filePath = args[1];
+  const commentId = args[2];
+  const message = argValue(args, "--message");
+  if (!filePath || !commentId || !message) {
+    console.error("Usage: redline author-reply <file.md> <comment-id> --message \"...\" [--name \"Author\"]");
+    process.exit(1);
+  }
+  const resolved = path.resolve(filePath);
+  if (!existsSync(resolved)) {
+    console.error(`File not found: ${resolved}`);
+    process.exit(1);
+  }
+  try {
+    const result = await postAuthorReply(resolved, commentId, message, { name: argValue(args, "--name") });
+    console.log(`Posted author reply to ${result.commentId} via ${result.via}.`);
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// redline author-wait <file> [--timeout-ms <ms>] [--interval-ms <ms>]
+if (args[0] === "author-wait") {
+  const filePath = args[1];
+  if (!filePath) {
+    console.error("Usage: redline author-wait <file.md> [--timeout-ms <ms>] [--interval-ms <ms>]");
+    process.exit(1);
+  }
+  const resolved = path.resolve(filePath);
+  if (!existsSync(resolved)) {
+    console.error(`File not found: ${resolved}`);
+    process.exit(1);
+  }
+  const timeoutRaw = argValue(args, "--timeout-ms");
+  const intervalRaw = argValue(args, "--interval-ms");
+  const timeoutMs = timeoutRaw != null ? Number(timeoutRaw) : undefined;
+  const intervalMs = intervalRaw != null ? Number(intervalRaw) : undefined;
+  if ((timeoutRaw != null && !Number.isFinite(timeoutMs)) || (intervalRaw != null && !Number.isFinite(intervalMs))) {
+    console.error("--timeout-ms and --interval-ms must be numbers");
+    process.exit(1);
+  }
+  try {
+    const result = await waitForAuthorEvent(resolved, { timeoutMs, intervalMs });
+    console.log(JSON.stringify(result, null, 2));
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 // redline resolve <file> [--model <id>]
 if (args[0] === "resolve") {
   const filePath = args[1];
@@ -148,7 +224,7 @@ if (args[0] === "resolve") {
   // redline <file>  — open review reader
   const filePath = args[0];
   if (!filePath) {
-    console.error("Usage: redline <file.md>\n       redline resolve <file.md> [--model <model-id>] [--agent claude|codex]\n       redline install-skill [--agent claude|codex|both]");
+    console.error("Usage: redline <file.md>\n       redline resolve <file.md> [--model <model-id>] [--agent claude|codex]\n       redline author-needed <file.md> [--json]\n       redline author-reply <file.md> <comment-id> --message \"...\" [--name \"Author\"]\n       redline author-wait <file.md> [--timeout-ms <ms>] [--interval-ms <ms>]\n       redline install-skill [--agent claude|codex|both]");
     process.exit(1);
   }
   const resolved = path.resolve(filePath);
@@ -315,7 +391,7 @@ if (args[0] === "resolve") {
     const status = lastRevisionError ? "error" : "abandoned";
     const payload: Record<string, unknown> = { status, file: resolved };
     if (lastRevisionError) payload.reason = lastRevisionError;
-    // Carry escalations through the error/abandon path too — on an incomplete
+    // Carry author handoffs through the error/abandon path too — on an incomplete
     // session they matter more, not less. Read the sidecar synchronously:
     // abandon runs in signal context where async I/O may not complete.
     let escalations: import("./reviewSummary").EscalationItem[] = [];
@@ -334,7 +410,7 @@ if (args[0] === "resolve") {
     } catch { /* best effort */ }
     if (escalations.length) {
       console.log(
-        `\n⚠ ${escalations.length} comment${escalations.length !== 1 ? "s" : ""} escalated to the launching agent — see ${path.basename(resultFile)}`
+        `\n⚠ ${escalations.length} comment${escalations.length !== 1 ? "s need" : " needs"} an author reply — see ${path.basename(resultFile)}`
       );
     }
     const escSuffix = escalations.length ? ` escalations=${escalations.length}` : "";
@@ -355,9 +431,9 @@ if (args[0] === "resolve") {
     console.log(`   Revised document: ${resolved}`);
     console.log(`${line}`);
 
-    // Print the full comment threads so the launching agent — which has no
+    // Print the full comment threads so the authoring agent — which has no
     // live channel to the inline review agent — sees everything the reviewer
-    // said, including escalated feedback meant for it.
+    // said, including author-level feedback meant for it.
     let escalations: import("./reviewSummary").EscalationItem[] = [];
     try {
       const { loadSidecar } = await import("./sidecar");

package/src/client/cards.ts

@@ -44,7 +44,7 @@ export function buildCommentCard(comment: ClientComment): HTMLDivElement {
   if (isEscalated(comment)) {
     const ebadge = document.createElement("span");
     ebadge.className = "escalate-badge";
-    ebadge.textContent = "↑ Escalated";
+    ebadge.textContent = "↑ Author reply needed";
     quote.appendChild(ebadge);
   }
   quote.appendChild(document.createTextNode('"' + comment.quote + '"'));
@@ -164,16 +164,16 @@ export function buildCommentCard(comment: ClientComment): HTMLDivElement {
 
 function buildThreadEntry(entry: ThreadEntry, isLatestVerdict: boolean): HTMLDivElement {
   const role = entry.role ?? "agent";
-  const label = entry.name ?? (role === "agent" ? "Agent" : "Human");
+  const label = entry.name ?? (entry.author ? "Author" : role === "agent" ? "Agent" : "Human");
   const div = document.createElement("div");
-  div.className = "thread-entry";
+  div.className = "thread-entry" + (entry.author ? " author-entry" : "");
   let verdictHtml = "";
   if (role === "agent" && entry.requires_revision === true && isLatestVerdict) {
     const reason = entry.revision_reason ? escapeHtml(entry.revision_reason) : "edit queued";
     verdictHtml = `<div class="verdict revise"><span class="verdict-icon">\u270E</span><span>${reason}</span></div>`;
   }
   if (role === "agent" && entry.escalate === true) {
-    verdictHtml += `<div class="verdict escalate"><span class="verdict-icon">\u2191</span><span>Routed to the launching agent</span></div>`;
+    verdictHtml += `<div class="verdict escalate"><span class="verdict-icon">\u2191</span><span>Author reply needed</span></div>`;
   }
   const messageHtml = entry.messageHtml ?? escapeHtml(entry.message);
   div.innerHTML = `

package/src/client/lib.ts

@@ -23,6 +23,7 @@ export type ThreadEntry = {
   requires_revision?: boolean;
   revision_reason?: string;
   escalate?: boolean;
+  author?: boolean;
 };
 
 export function escapeHtml(s: string): string {
@@ -45,9 +46,18 @@ export function latestVerdict(comment: ClientComment): "revise" | "accept" | nul
   return null;
 }
 
-// True when an agent reply flagged this comment for the launching agent.
+// True when an agent reply flagged this comment for authoring-agent input.
 export function isEscalated(comment: ClientComment): boolean {
-  return (comment.thread || []).some((e) => e.role === "agent" && e.escalate === true);
+  const thread = comment.thread || [];
+  let escIdx = -1;
+  let authorIdx = -1;
+  for (let i = thread.length - 1; i >= 0; i--) {
+    const entry = thread[i]!;
+    if (escIdx === -1 && entry.role === "agent" && entry.escalate === true) escIdx = i;
+    if (authorIdx === -1 && entry.role === "agent" && entry.author === true) authorIdx = i;
+    if (escIdx !== -1 && authorIdx !== -1) break;
+  }
+  return escIdx !== -1 && authorIdx < escIdx;
 }
 
 export function nearestCell(node: Node): HTMLElement | null {

package/src/client/render.ts

@@ -346,15 +346,15 @@ export function applyRoundState(): void {
           bannerText = `${reviseCount} of ${total} comments imply edits.`;
         }
         banner.textContent = bannerText;
-        // Escalations are orthogonal to the revise/accept verdict — a comment
-        // can be answered in-thread yet still need the launching agent. Call
+        // Author handoff is orthogonal to the revise/accept verdict — a comment
+        // can be answered in-thread yet still need authoring-agent input. Call
         // it out on its own line so it survives all three banner branches.
         const escCount = state.comments.filter(isEscalated).length;
         if (escCount > 0) {
           const escLine = document.createElement("div");
           escLine.className = "banner-escalation";
           escLine.textContent =
-            `↑ ${escCount} comment${escCount !== 1 ? "s" : ""} escalated to the launching agent.`;
+            `↑ ${escCount} comment${escCount !== 1 ? "s need" : " needs"} an author reply.`;
           banner.appendChild(escLine);
         }
         banner.style.display = "block";

package/src/client/styles.css

@@ -496,6 +496,13 @@ mark.rl-highlight.rl-img:hover, mark.rl-highlight.rl-img.active {
 }
 .thread-role.human { color: var(--accent); }
 .thread-role.agent { color: #3b5bdb; }
+.thread-entry.author-entry {
+  border-left: 3px solid #7c3aed;
+  padding-left: 10px;
+}
+.thread-entry.author-entry .thread-role {
+  color: #5b21b6;
+}
 
 .thread-message {
   font-size: 13.5px;
@@ -597,7 +604,7 @@ mark.rl-highlight.rl-img:hover, mark.rl-highlight.rl-img.active {
 .verdict-badge.revise { background: #fef3c7; color: #92400e; }
 .verdict-badge.accept { background: #e5e7eb; color: var(--text-muted); }
 
-/* Escalation badge on the quote line — comment routed to the launching agent */
+/* Author-reply-needed badge on the quote line */
 .escalate-badge {
   display: inline-flex;
   align-items: center;
@@ -803,8 +810,8 @@ mark.rl-highlight.rl-img:hover, mark.rl-highlight.rl-img.active {
   align-items: center;
   gap: 8px;
 }
-/* Escalation sub-line under the round banner — purple to match the
-   ↑ Escalated comment badges, distinct from the green verdict copy. */
+/* Author-handoff sub-line under the round banner — purple to match the
+   ↑ Author reply needed badges, distinct from the green verdict copy. */
 .banner-escalation {
   margin-top: 6px;
   padding-top: 6px;

package/src/reviewSummary.ts

@@ -1,10 +1,10 @@
 // Closeout summary of a finished review.
 //
-// The inline review agent (src/agent.ts) and the agent that *launched* redline
+// The inline review agent (src/agent.ts) and the agent that *authored/launched* redline
 // share no live channel — the sidecar is the only persisted artifact, and the
-// launching agent only regains control when the session exits. So at closeout
+// authoring agent only regains control when the session exits. So at closeout
 // the CLI prints every comment thread verbatim. Anything the reviewer said —
-// including feedback meant for the launching agent — lands in front of it.
+// including feedback meant for the authoring agent — lands in front of it.
 //
 // Comments the inline agent explicitly flagged (`escalate: true`) get a
 // dedicated section so they aren't lost in the full transcript.
@@ -15,7 +15,7 @@ export interface EscalationItem {
   round: number;
   quote: string;
   request: string; // the reviewer message the inline agent couldn't act on
-  note: string;    // the agent's escalation note
+  note: string;    // the agent's author-handoff note
 }
 
 function flatten(s: string, n: number): string {
@@ -24,19 +24,24 @@ function flatten(s: string, n: number): string {
 }
 
 function isEscalated(c: Comment): boolean {
-  return c.thread.some((e) => e.role === "agent" && e.escalate === true);
+  const escIdx = latestIndex(c.thread, (e) => e.role === "agent" && e.escalate === true);
+  if (escIdx === -1) return false;
+  const authorIdx = latestIndex(c.thread, (e) => e.role === "agent" && e.author === true);
+  return authorIdx < escIdx;
 }
 
-// Pull out every comment the inline agent routed to the launching agent.
+// Pull out every comment the inline agent routed to the authoring agent.
 export function collectEscalations(sidecar: Sidecar): EscalationItem[] {
   const items: EscalationItem[] = [];
   for (const round of sidecar.rounds) {
     for (const c of round.comments) {
-      const escIdx = c.thread.findIndex((e) => e.role === "agent" && e.escalate === true);
+      const escIdx = latestIndex(c.thread, (e) => e.role === "agent" && e.escalate === true);
       if (escIdx === -1) continue;
+      const authorIdx = latestIndex(c.thread, (e) => e.role === "agent" && e.author === true);
+      if (authorIdx > escIdx) continue;
       const agentEntry = c.thread[escIdx]!;
-      // The reviewer message immediately before the escalation is the request
-      // the inline agent couldn't fulfill.
+      // The reviewer message immediately before the author handoff is the
+      // request the inline agent couldn't fulfill.
       let request = "";
       for (let i = escIdx - 1; i >= 0; i--) {
         if (c.thread[i]!.role === "human") { request = c.thread[i]!.message; break; }
@@ -52,8 +57,15 @@ export function collectEscalations(sidecar: Sidecar): EscalationItem[] {
   return items;
 }
 
-// A readable transcript of every comment thread, plus an escalation callout.
-// Printed to stdout on session close so the launching agent can read it.
+function latestIndex(thread: Comment["thread"], predicate: (entry: Comment["thread"][number]) => boolean): number {
+  for (let i = thread.length - 1; i >= 0; i--) {
+    if (predicate(thread[i]!)) return i;
+  }
+  return -1;
+}
+
+// A readable transcript of every comment thread, plus an author-handoff callout.
+// Printed to stdout on session close so the authoring agent can read it.
 export function formatReviewSummary(sidecar: Sidecar): string {
   const lines: string[] = [`Review threads — ${sidecar.file}`];
 
@@ -62,7 +74,7 @@ export function formatReviewSummary(sidecar: Sidecar): string {
     lines.push("", `Round ${round.round}`);
     round.comments.forEach((c, i) => {
       const tags = [c.resolved ? "resolved" : "open"];
-      if (isEscalated(c)) tags.push("escalated");
+      if (isEscalated(c)) tags.push("author reply needed");
       lines.push(`  ${i + 1}. "${flatten(c.quote, 80)}" — ${tags.join(" · ")}`);
       for (const e of c.thread) {
         const who = e.role === "human" ? "Reviewer" : (e.name || "Agent");
@@ -75,7 +87,7 @@ export function formatReviewSummary(sidecar: Sidecar): string {
   if (esc.length > 0) {
     lines.push(
       "",
-      `⚠ ${esc.length} comment${esc.length !== 1 ? "s" : ""} escalated to you (the launching agent):`,
+      `⚠ ${esc.length} comment${esc.length !== 1 ? "s need" : " needs"} an author reply from you:`,
     );
     for (const e of esc) {
       lines.push(`  • "${e.quote}" (round ${e.round})`);
@@ -84,7 +96,7 @@ export function formatReviewSummary(sidecar: Sidecar): string {
     }
     lines.push(
       "",
-      "The inline review agent couldn't act on these. Address them in the",
+      "The inline review agent marked these for author-level input. Address them in the",
       "document or with the user before considering the review closed out.",
     );
   }

package/src/server.ts

@@ -472,6 +472,7 @@ export function createServer(
       requires_revision?: boolean;
       revision_reason?: string;
       escalate?: boolean;
+      author?: boolean;
     }>();
     if (!body.message?.trim()) return c.json({ ok: false, error: "message is required" }, 400);
     const role = (body.role === "human" ? "human" : "agent") as "human" | "agent";
@@ -491,12 +492,13 @@ export function createServer(
           if (body.revision_reason?.trim()) entry.revision_reason = body.revision_reason.trim();
         }
         if (body.escalate === true) entry.escalate = true;
+        if (body.author === true) entry.author = true;
       }
       comment.thread.push(entry);
       return { skip: false as const, roundNumber: round.round, comment };
     });
     if (out.skip) return c.json({ ok: false, error: out.error }, out.status as 400 | 404);
-    if (role === "human") {
+    if (role === "human" || (role === "agent" && body.author === true)) {
       broadcast("comment-reply", { round: out.roundNumber, commentId: id });
     }
     return c.json({ ok: true, comment: out.comment });

package/src/sidecar.ts

@@ -14,10 +14,14 @@ export interface ThreadEntry {
   requires_revision?: boolean;
   revision_reason?: string;
   // Set true on an agent reply when the comment can't be acted on from inside
-  // this review — it needs the agent that *launched* redline (project context,
-  // tools, or authority the inline agent lacks). Surfaced in the closeout
-  // summary so the launching agent picks it up. Only set on agent entries.
+  // this review — it needs author-level context, tools, or authority the inline
+  // agent lacks. Surfaced in the closeout summary so the authoring agent picks
+  // it up. Only set on agent entries.
   escalate?: boolean;
+  // Set true on an agent entry posted by the authoring/launching agent rather
+  // than the inline review agent. This lets the UI distinguish author replies
+  // without changing the legacy role shape.
+  author?: boolean;
 }
 
 // Latest agent verdict on a comment thread: