@levistudio/redline 0.2.0 → 0.4.0

package/src/cli.ts

@@ -4,6 +4,10 @@ import { mkdir, writeFile } from "fs/promises";
 import { spawnSync } from "child_process";
 import { createRequire } from "module";
 import path from "path";
+// reviewSummary only `import type`s from ./sidecar, so it pulls in no
+// third-party deps at runtime — safe to import statically ahead of the
+// preflight. abandon() needs it synchronously (signal context).
+import { collectEscalations, formatReviewSummary } from "./reviewSummary";
 
 // Ensure redline's own dependencies are resolvable before any third-party
 // imports load. `redline` is invoked from arbitrary projects: in a checkout
@@ -41,24 +45,25 @@ 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 {
+  getAgentProvider,
+  invalidProviderMessage,
+  parseAgentProviderId,
+  resolveProviderId,
+} = await import("./agentProvider");
 
-// 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);
+function argValue(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  return idx !== -1 ? args[idx + 1] : undefined;
+}
+
+function selectProvider(args: string[]) {
+  const raw = argValue(args, "--agent") ?? process.env.REDLINE_AGENT;
+  if (raw && !parseAgentProviderId(raw)) {
+    console.error(invalidProviderMessage(raw));
+    process.exit(1);
+  }
+  return getAgentProvider(resolveProviderId(raw));
 }
 
 // Walk up from `start` looking for a git root (a `.git` directory or file —
@@ -96,11 +101,33 @@ function maybePrintGitignoreHint(filePath: string) {
 
 const args = process.argv.slice(2);
 
+if (args[0] === "--version" || args[0] === "-v") {
+  const pkgPath = path.resolve(import.meta.dir, "..", "package.json");
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
+    console.log(pkg.version ?? "unknown");
+  } catch {
+    console.log("unknown");
+  }
+  process.exit(0);
+}
+
+// redline install-skill [--agent claude|codex|both]
+if (args[0] === "install-skill") {
+  const script = path.resolve(import.meta.dir, "..", "scripts", "install-skill.sh");
+  if (!existsSync(script)) {
+    console.error(`Install script not found: ${script}`);
+    process.exit(1);
+  }
+  const result = spawnSync("bash", [script, ...args.slice(1)], { stdio: "inherit" });
+  process.exit(result.status ?? 1);
+}
+
 // 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>]");
+    console.error("Usage: redline resolve <file.md> [--model <model-id>] [--agent claude|codex]");
     process.exit(1);
   }
   const resolved = path.resolve(filePath);
@@ -108,15 +135,20 @@ if (args[0] === "resolve") {
     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 });
+  const model = argValue(args, "--model");
+  const provider = selectProvider(args);
+  try {
+    provider.preflight();
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  resolve(resolved, { model, agentProvider: provider.id });
 } else {
   // redline <file>  — open review reader
   const filePath = args[0];
   if (!filePath) {
-    console.error("Usage: redline <file.md>");
+    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]");
     process.exit(1);
   }
   const resolved = path.resolve(filePath);
@@ -125,18 +157,26 @@ if (args[0] === "resolve") {
     process.exit(1);
   }
   const noAgent = args.includes("--no-agent");
+  const provider = selectProvider(args);
 
   // 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();
+  // the user just wants inline comments without an agent conversation, so
+  // requiring a provider CLI on PATH would be a hostile gate.
+  if (!noAgent) {
+    try {
+      provider.preflight();
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+  }
 
-  const contextFlag = args.indexOf("--context");
-  const context = contextFlag !== -1 ? args[contextFlag + 1] : undefined;
+  const context = argValue(args, "--context");
   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");
+  const sidecarFile = path.join(path.dirname(resolved), ".review", path.basename(resolved) + ".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.
@@ -159,7 +199,7 @@ if (args[0] === "resolve") {
   // 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 app = createServer(resolved, { context, csrfToken, noAgent, agentName: provider.displayName });
   const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: app.fetch, idleTimeout: 0 });
   const url = `http://localhost:${server.port}`;
 
@@ -177,6 +217,7 @@ if (args[0] === "resolve") {
       started_at: new Date().toISOString(),
       pid: process.pid,
       csrf_token: csrfToken,
+      agent_provider: provider.id,
     }, null, 2));
   } catch (e) {
     console.error("[redline] Failed to write startup file:", e);
@@ -189,14 +230,14 @@ if (args[0] === "resolve") {
   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 (noAgent) console.log(`  Mode: manual annotation (--no-agent — no ${provider.displayName} 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
+  // a transient provider-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
@@ -211,7 +252,7 @@ if (args[0] === "resolve") {
       [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 },
+        env: { ...process.env, REDLINE_PORT: String(server.port), REDLINE_TOKEN: csrfToken, REDLINE_AGENT: provider.id },
       }
     );
     agentProc = proc;
@@ -274,19 +315,36 @@ 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
+    // 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[] = [];
+    try {
+      if (existsSync(sidecarFile)) {
+        const raw = readFileSync(sidecarFile, "utf-8");
+        if (raw.trim()) escalations = collectEscalations(JSON.parse(raw));
+      }
+    } catch { /* best effort — never block shutdown on the summary */ }
+    payload.escalations = escalations;
     // 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}"` : ""}`);
+    if (escalations.length) {
+      console.log(
+        `\n⚠ ${escalations.length} comment${escalations.length !== 1 ? "s" : ""} escalated to the launching agent — see ${path.basename(resultFile)}`
+      );
+    }
+    const escSuffix = escalations.length ? ` escalations=${escalations.length}` : "";
+    console.log(`\nREDLINE_RESULT: ${status}${lastRevisionError ? ` reason="${lastRevisionError}"` : ""}${escSuffix}`);
     // 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 }) => {
+  app.onFinished(async ({ totalRounds, totalComments }) => {
     serverExiting = true;
     killAgent().catch(() => { /* shutdown already in flight */ });
     try { unlinkSync(startupFile); } catch { /* best effort */ }
@@ -296,10 +354,25 @@ if (args[0] === "resolve") {
     console.log(`   ${totalRounds} round${totalRounds !== 1 ? "s" : ""} · ${totalComments} comment${totalComments !== 1 ? "s" : ""} addressed`);
     console.log(`   Revised document: ${resolved}`);
     console.log(`${line}`);
+
+    // Print the full comment threads so the launching agent — which has no
+    // live channel to the inline review agent — sees everything the reviewer
+    // said, including escalated feedback meant for it.
+    let escalations: import("./reviewSummary").EscalationItem[] = [];
+    try {
+      const { loadSidecar } = await import("./sidecar");
+      const sidecar = await loadSidecar(resolved);
+      escalations = collectEscalations(sidecar);
+      console.log(`\n${formatReviewSummary(sidecar)}`);
+    } catch (e) {
+      console.error("[redline] Failed to build review summary:", e);
+    }
+
     // Machine-greppable result line for a calling agent. Keep this stable.
-    console.log(`REDLINE_RESULT: approved file=${resolved} rounds=${totalRounds} comments=${totalComments}`);
+    const escSuffix = escalations.length ? ` escalations=${escalations.length}` : "";
+    console.log(`\nREDLINE_RESULT: approved file=${resolved} rounds=${totalRounds} comments=${totalComments}${escSuffix}`);
     console.log("");
-    writeResult({ status: "approved", file: resolved, rounds: totalRounds, comments: totalComments })
+    writeResult({ status: "approved", file: resolved, rounds: totalRounds, comments: totalComments, escalations })
       .finally(() => process.exit(0));
   });
 

package/src/client/cards.ts

@@ -1,4 +1,4 @@
-import { escapeHtml, latestVerdict, type ClientComment, type ThreadEntry } from "./lib";
+import { escapeHtml, isEscalated, latestVerdict, type ClientComment, type ThreadEntry } from "./lib";
 import { state } from "./state";
 
 export type CardCallbacks = {
@@ -41,6 +41,12 @@ export function buildCommentCard(comment: ClientComment): HTMLDivElement {
       quote.appendChild(vbadge);
     }
   }
+  if (isEscalated(comment)) {
+    const ebadge = document.createElement("span");
+    ebadge.className = "escalate-badge";
+    ebadge.textContent = "↑ Escalated";
+    quote.appendChild(ebadge);
+  }
   quote.appendChild(document.createTextNode('"' + comment.quote + '"'));
   card.appendChild(quote);
 
@@ -166,6 +172,9 @@ function buildThreadEntry(entry: ThreadEntry, isLatestVerdict: boolean): HTMLDiv
     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>`;
+  }
   const messageHtml = entry.messageHtml ?? escapeHtml(entry.message);
   div.innerHTML = `
     <div class="thread-role ${role}">${escapeHtml(label)}</div>

package/src/client/lib.ts

@@ -22,6 +22,7 @@ export type ThreadEntry = {
   messageHtml?: string;
   requires_revision?: boolean;
   revision_reason?: string;
+  escalate?: boolean;
 };
 
 export function escapeHtml(s: string): string {
@@ -44,6 +45,11 @@ export function latestVerdict(comment: ClientComment): "revise" | "accept" | nul
   return null;
 }
 
+// True when an agent reply flagged this comment for the launching agent.
+export function isEscalated(comment: ClientComment): boolean {
+  return (comment.thread || []).some((e) => e.role === "agent" && e.escalate === true);
+}
+
 export function nearestCell(node: Node): HTMLElement | null {
   const el = node.nodeType === Node.TEXT_NODE ? node.parentNode : node;
   return el && (el as Element).closest ? ((el as Element).closest("td, th") as HTMLElement | null) : null;
@@ -86,63 +92,138 @@ export type Captured = {
   context_after: string;
 };
 
-// Walk the prose container's text nodes, locate the selection's start, and
-// return the quote with surrounding context. Returns null when the selection
-// can't be relocated against flat text (e.g. crossed an <img>).
-export function captureSelection(prose: Element, sel: Selection, text: string): Captured | null {
-  const range = sel.getRangeAt(0);
+type FlatSegment = {
+  node: Text | HTMLImageElement;
+  start: number;
+  len: number;
+  isImg: boolean;
+};
 
-  const walker = (prose.ownerDocument || document).createTreeWalker(prose, NodeFilter.SHOW_TEXT);
-  const segments: { node: Text; start: number }[] = [];
+// An <img> contributes no characters of its own, so on its own it can't be
+// anchored against. We give it a presence in the flat text as an
+// `[image: alt]` token — the same shape the image-only comment path uses — so
+// a selection can run text → image → text and still round-trip.
+function imgToken(img: HTMLImageElement): string {
+  return "[image: " + (img.alt || "") + "]";
+}
+
+// Walk a container into a flat string plus the segments that produced it.
+// Text nodes contribute their value; <img> elements contribute an
+// `[image: alt]` token. Segments are in document order. captureSelection and
+// highlightText both build flat through here so their coordinates agree.
+function buildFlat(container: Element): { flat: string; segments: FlatSegment[] } {
+  const doc = container.ownerDocument || document;
+  const walker = doc.createTreeWalker(container, NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT, {
+    acceptNode(n: Node) {
+      if (n.nodeType === Node.TEXT_NODE) return NodeFilter.FILTER_ACCEPT;
+      return (n as Element).tagName === "IMG" ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+    },
+  });
+  const segments: FlatSegment[] = [];
   let flat = "";
   let node: Node | null;
   while ((node = walker.nextNode())) {
-    const tn = node as Text;
-    segments.push({ node: tn, start: flat.length });
-    flat += tn.nodeValue ?? "";
-  }
-
-  let quoteStart = -1;
-  for (const seg of segments) {
-    if (seg.node === range.startContainer) {
-      quoteStart = seg.start + range.startOffset;
-      break;
+    if (node.nodeType === Node.TEXT_NODE) {
+      const v = (node as Text).nodeValue ?? "";
+      segments.push({ node: node as Text, start: flat.length, len: v.length, isImg: false });
+      flat += v;
+    } else {
+      const img = node as HTMLImageElement;
+      const tok = imgToken(img);
+      segments.push({ node: img, start: flat.length, len: tok.length, isImg: true });
+      flat += tok;
     }
   }
+  return { flat, segments };
+}
 
-  if (quoteStart === -1) {
-    return { quote: text, context_before: "", context_after: "" };
-  }
+// Map both range endpoints onto the flat text and return the quote with
+// surrounding context. Returns null only when the selection can't be resolved
+// against the flat text at all.
+//
+// The quote is sliced straight out of `flat` rather than reconstructed from
+// `sel.toString()`. sel.toString() joins blocks with "\n"/"\n\n" separators
+// that don't exist in the walker's output, and marked emits stray whitespace
+// text nodes between block tags — so the two never line up across a block
+// boundary. Working in flat coordinates sidesteps the mismatch: `flat` is the
+// single source of truth, and highlightText re-finds the quote against the
+// same flat string later. `text` is kept only as a last-resort fallback for
+// the rare case where an endpoint can't be resolved.
+export function captureSelection(prose: Element, sel: Selection, text: string): Captured | null {
+  const range = sel.getRangeAt(0);
+  const { flat, segments } = buildFlat(prose);
+  if (segments.length === 0) return null;
 
-  // Block boundaries: sel.toString() inserts "\n\n" between blocks (e.g. a
-  // heading followed by a paragraph), but the text-node walker concatenates
-  // with no separator. Strip those runs from `text` so it can match `flat`.
-  // We keep single \n (which can appear inside a single text node, e.g. a
-  // code block) untouched.
-  const normalized = text.replace(/\n{2,}/g, "");
+  // Map a range boundary point onto an index into `flat`. Text-node boundaries
+  // are the common case; Chrome sometimes anchors a drag to an element node
+  // plus a child index, which we resolve to the nearest segment edge.
+  const pointToFlat = (container: Node, offset: number, side: "start" | "end"): number => {
+    for (const seg of segments) {
+      if (seg.node === container) {
+        if (seg.isImg) return offset > 0 ? seg.start + seg.len : seg.start;
+        return seg.start + offset;
+      }
+    }
+    if (container.nodeType === Node.TEXT_NODE) return -1;
+    const kids = container.childNodes;
+    const segEnd = (seg: FlatSegment) => seg.start + seg.len;
+    if (side === "start") {
+      const ref = offset < kids.length ? kids[offset]! : null;
+      if (ref) {
+        for (const seg of segments) {
+          if (ref === seg.node || ref.contains(seg.node)) return seg.start;
+          if (ref.compareDocumentPosition(seg.node) & Node.DOCUMENT_POSITION_FOLLOWING)
+            return seg.start;
+        }
+        return flat.length;
+      }
+      let end = -1;
+      for (const seg of segments) if (container.contains(seg.node)) end = segEnd(seg);
+      return end === -1 ? flat.length : end;
+    }
+    const ref = offset > 0 ? kids[offset - 1]! : null;
+    if (ref) {
+      let end = -1;
+      for (const seg of segments) {
+        if (
+          ref === seg.node ||
+          ref.contains(seg.node) ||
+          ref.compareDocumentPosition(seg.node) & Node.DOCUMENT_POSITION_PRECEDING
+        ) {
+          end = segEnd(seg);
+        }
+      }
+      return end === -1 ? 0 : end;
+    }
+    for (const seg of segments) if (container.contains(seg.node)) return seg.start;
+    return 0;
+  };
 
-  const slice = flat.slice(quoteStart, quoteStart + normalized.length);
-  if (slice !== normalized) {
-    // Trimming in the caller can shift the true start a few chars away from
-    // range.startOffset. Search a small window around quoteStart for the
-    // normalized text before giving up.
-    const windowStart = Math.max(0, quoteStart - 64);
-    const windowEnd = Math.min(flat.length, quoteStart + normalized.length + 64);
-    const found = flat.indexOf(normalized, windowStart);
-    if (found === -1 || found >= windowEnd) return null;
-    quoteStart = found;
+  let flatStart = pointToFlat(range.startContainer, range.startOffset, "start");
+  let flatEnd = pointToFlat(range.endContainer, range.endOffset, "end");
+  if (flatStart === -1 || flatEnd === -1 || flatEnd <= flatStart) {
+    return text ? { quote: text, context_before: "", context_after: "" } : null;
   }
 
+  // Trim whitespace overshoot: a drag that ends a hair past a block — or
+  // starts in the gap before one — shouldn't fail or carry stray newlines.
+  // This is the "clamp": a small overshoot anchors to what the user meant.
+  while (flatStart < flatEnd && /\s/.test(flat[flatStart]!)) flatStart++;
+  while (flatEnd > flatStart && /\s/.test(flat[flatEnd - 1]!)) flatEnd--;
+  if (flatEnd <= flatStart) return null;
+
   return {
-    quote: normalized,
-    context_before: flat.slice(Math.max(0, quoteStart - 32), quoteStart),
-    context_after: flat.slice(quoteStart + normalized.length, quoteStart + normalized.length + 32),
+    quote: flat.slice(flatStart, flatEnd),
+    context_before: flat.slice(Math.max(0, flatStart - 32), flatStart),
+    context_after: flat.slice(flatEnd, flatEnd + 32),
   };
 }
 
 // Wrap occurrences of `text` inside `container` with <mark> elements. Uses
-// `contextBefore` to disambiguate when a quote appears multiple times.
-// Image quotes (`[image: alt]`) wrap the matching <img> instead.
+// `contextBefore` to disambiguate when a quote appears multiple times. The
+// quote is matched against the same flat text captureSelection produced, so
+// `[image: alt]` tokens in the quote wrap the corresponding <img> — whether
+// the quote is image-only or text mixed with an image.
 // Returns the marks created (caller can attach event listeners).
 export function highlightText(
   container: Element,
@@ -154,35 +235,9 @@ export function highlightText(
   const doc = container.ownerDocument || document;
   const marks: HTMLElement[] = [];
 
-  const imgMatch = text.match(/^\[image:\s*(.*)\]$/);
-  if (imgMatch) {
-    const alt = imgMatch[1];
-    const imgs = container.querySelectorAll("img");
-    for (const img of imgs) {
-      if ((img.alt || "") === alt) {
-        const mark = doc.createElement("mark");
-        mark.className = "rl-highlight rl-img" + (resolved ? " resolved" : "");
-        mark.dataset.commentId = id;
-        img.parentNode!.insertBefore(mark, img);
-        mark.appendChild(img);
-        marks.push(mark);
-        return marks;
-      }
-    }
-    return marks;
-  }
-
   (container as HTMLElement).normalize();
 
-  const walker = doc.createTreeWalker(container, NodeFilter.SHOW_TEXT);
-  const segments: { node: Text; start: number }[] = [];
-  let flat = "";
-  let node: Node | null;
-  while ((node = walker.nextNode())) {
-    const tn = node as Text;
-    segments.push({ node: tn, start: flat.length });
-    flat += tn.nodeValue ?? "";
-  }
+  const { flat, segments } = buildFlat(container);
 
   let quoteStart = -1;
   if (contextBefore) {
@@ -194,18 +249,28 @@ export function highlightText(
 
   const quoteEnd = quoteStart + text.length;
 
-  const toWrap: { node: Text; localStart: number; localEnd: number }[] = [];
   for (const seg of segments) {
-    const segEnd = seg.start + (seg.node.nodeValue?.length ?? 0);
-    if (segEnd <= quoteStart || seg.start >= quoteEnd) continue;
-    toWrap.push({
-      node: seg.node,
-      localStart: Math.max(0, quoteStart - seg.start),
-      localEnd: Math.min(seg.node.nodeValue?.length ?? 0, quoteEnd - seg.start),
-    });
-  }
+    const segStart = seg.start;
+    const segEnd = seg.start + seg.len;
+    if (segEnd <= quoteStart || segStart >= quoteEnd) continue;
+
+    if (seg.isImg) {
+      // Image tokens are atomic — wrap the <img> only when the quote covers
+      // the whole token, never on a partial overlap.
+      if (segStart < quoteStart || segEnd > quoteEnd) continue;
+      const img = seg.node as HTMLImageElement;
+      const mark = doc.createElement("mark");
+      mark.className = "rl-highlight rl-img" + (resolved ? " resolved" : "");
+      mark.dataset.commentId = id;
+      img.parentNode!.insertBefore(mark, img);
+      mark.appendChild(img);
+      marks.push(mark);
+      continue;
+    }
 
-  for (const { node: tn, localStart, localEnd } of toWrap) {
+    const tn = seg.node as Text;
+    const localStart = Math.max(0, quoteStart - segStart);
+    const localEnd = Math.min(seg.len, quoteEnd - segStart);
     const mark = doc.createElement("mark");
     mark.className = "rl-highlight" + (resolved ? " resolved" : "");
     mark.dataset.commentId = id;

package/src/client/render.ts

@@ -3,8 +3,9 @@ import {
   highlightText as _highlightText,
   preserveScroll as _preserveScroll,
   latestVerdict,
+  isEscalated,
 } from "./lib";
-import { state, apiFetch, showError } from "./state";
+import { state, apiFetch, showError, reportMutationFailure } from "./state";
 import {
   buildCommentCard,
   captureTypingState,
@@ -171,7 +172,7 @@ export async function saveComment(
       showError(data.error || "Failed to save comment");
     }
   } catch (err: unknown) {
-    showError("Failed to save comment: " + (err as Error).message);
+    reportMutationFailure("Failed to save comment", err);
   }
 }
 
@@ -195,7 +196,7 @@ export async function submitReply(id: string, message: string): Promise<void> {
       showError(data.error || "Failed to save reply");
     }
   } catch (err: unknown) {
-    showError("Failed to save reply: " + (err as Error).message);
+    reportMutationFailure("Failed to save reply", err);
   }
 }
 
@@ -220,7 +221,7 @@ export async function resolveComment(id: string): Promise<void> {
       showError(data.error || "Failed to resolve comment");
     }
   } catch (err: unknown) {
-    showError("Failed to resolve: " + (err as Error).message);
+    reportMutationFailure("Failed to resolve", err);
   }
 }
 
@@ -240,7 +241,7 @@ export async function reopenComment(id: string): Promise<void> {
       showError(data.error || "Failed to reopen comment");
     }
   } catch (err: unknown) {
-    showError("Failed to reopen: " + (err as Error).message);
+    reportMutationFailure("Failed to reopen", err);
   }
 }
 
@@ -345,6 +346,17 @@ 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
+        // 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.`;
+          banner.appendChild(escLine);
+        }
         banner.style.display = "block";
       }
 

package/src/client/selection.ts

@@ -197,7 +197,7 @@ export function initSelectionHandlers(): void {
 
       const captured = captureSelection(sel, text);
       if (!captured) {
-        showError("Highlight a single passage \u2014 selections that cross images or sections can't be anchored.");
+        showError("Couldn't anchor that selection \u2014 try highlighting the passage again.");
         sel.removeAllRanges();
         return;
       }