hilos-agent 0.1.15 → 0.4.0

package/src/progress-emitter.mjs

@@ -0,0 +1,270 @@
+// Progress emitter (0274). The daemon-side glue between the 0272 vendor stream
+// parser (agent-events.mjs) and the 0273 `post_progress` MCP tool: it folds the
+// parser's normalized AgentEvents into ONE live "what I'm doing right now"
+// snapshot and pushes it, coalesced + throttled, to a single thread-anchored
+// status message. Retires the old 3-minute edit heartbeat — the card now moves
+// as the run moves.
+//
+// Design rules (mirror the .mjs siblings):
+//   - PURE + node-builtins-only. It NEVER imports MCP: the caller injects `send`
+//     (a fn that calls post_progress) so this module is unit-tested offline with
+//     no network, no daemon, no CLI.
+//   - NEVER throws into the run. `send` is wrapped; a parser hiccup degrades.
+//   - Deterministic/testable: `now` is injected, and the trailing timer goes
+//     through injectable `setTimer`/`clearTimer` so tests drive it with no real
+//     setTimeout (fake clock + manual flush).
+//   - Defense-in-depth: every string is re-sanitized here (the parser already
+//     redacts, the server will redact again) and arrays are clamped.
+
+import { createStepRing, sanitizeText } from "./agent-events.mjs";
+
+/**
+ * Which parser/stream-flags a coding command wants, from its FIRST token.
+ * `claude`/`claude-code` → claude_code, `codex` → codex,
+ * `cursor`/`cursor-agent` → cursor, everything else → unknown. Handles an
+ * absolute path (`/usr/local/bin/claude`) by taking the basename.
+ * @param {string} codingCmd
+ * @returns {'claude_code'|'codex'|'cursor'|'unknown'}
+ */
+export function detectVendor(codingCmd) {
+  const first = String(codingCmd || "").trim().split(/\s+/)[0] || "";
+  const base = (first.split(/[/\\]/).pop() || "").toLowerCase();
+  if (base === "claude" || base === "claude-code" || base === "claude_code") return "claude_code";
+  if (base === "codex") return "codex";
+  if (base === "cursor" || base === "cursor-agent") return "cursor";
+  return "unknown";
+}
+
+/**
+ * Extra args to make the code run EMIT a structured stream, appended to the code
+ * run's argv (NOT the display string) and ONLY for the code run. Only claude_code
+ * has a proven flag (`--output-format stream-json --verbose`, per lib/agent-cli.ts
+ * + scripts/verify-sandbox-mcp.mjs). codex/cursor return [] — their stream flags
+ * are deferred to 0278 rather than guessed (an unproven flag could break the run).
+ * @param {'claude_code'|'codex'|'cursor'|'unknown'} vendor
+ * @returns {string[]}
+ */
+export function codeStreamArgs(vendor) {
+  if (vendor === "claude_code") return ["--output-format", "stream-json", "--verbose"];
+  return [];
+}
+
+// A raw stdout line that starts like JSON is the structured NDJSON we already
+// parse into steps — keep it OUT of the `lastLine` text fallback (which exists
+// for text-only CLIs), so a Claude run never surfaces raw JSON as its status.
+const looksLikeJson = (line) => /^[[{]/.test(line);
+
+/** Last non-empty, non-JSON line of a raw chunk (the text-only liveness tail). */
+function rawTail(chunk) {
+  const lines = String(chunk ?? "")
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!looksLikeJson(lines[i])) return lines[i];
+  }
+  return "";
+}
+
+const defaultSetTimer = (fn, ms) => {
+  const id = setTimeout(fn, ms);
+  if (id && typeof id.unref === "function") id.unref();
+  return id;
+};
+const defaultClearTimer = (id) => clearTimeout(id);
+
+/**
+ * Build a stateful progress emitter.
+ *
+ * Throttle — LEADING + TRAILING: the first update after a quiet gap is sent
+ * IMMEDIATELY (leading, so the card lights up the instant work starts), then
+ * further updates within `throttleMs` are coalesced and one TRAILING send fires
+ * at the end of the window (so a chatty CLI can't spam realtime). `flush()` and
+ * `done()` bypass the throttle for the final, guaranteed delivery.
+ *
+ * Coalesce: steps go through the 0272 ring (consecutive same-file edits collapse
+ * to one "Editing …", duplicate labels drop); `filesTouched` is a bounded,
+ * de-duped set.
+ *
+ * @param {object} o
+ * @param {{ push: (chunk: string) => any[], flush: () => any[] }} o.parser — a
+ *   makeStreamParser(vendor) instance; this module owns feeding + flushing it.
+ * @param {(progress: object) => any} o.send — injected sender (calls post_progress).
+ * @param {() => number} [o.now] — clock (injectable for tests).
+ * @param {number} [o.throttleMs] — coalesce window (default 2000).
+ * @param {number} [o.stepLimit] — rolling step window (default 8).
+ * @param {number} [o.fileLimit] — filesTouched cap (default 20).
+ * @param {(fn: () => void, ms: number) => any} [o.setTimer] — trailing-timer arm.
+ * @param {(id: any) => void} [o.clearTimer] — trailing-timer clear.
+ */
+export function createProgressEmitter({
+  parser,
+  send,
+  now = Date.now,
+  throttleMs = 2000,
+  stepLimit = 8,
+  fileLimit = 20,
+  setTimer = defaultSetTimer,
+  clearTimer = defaultClearTimer,
+} = {}) {
+  const ring = createStepRing(stepLimit);
+  const files = [];
+  const fileSet = new Set();
+  const startedAt = now();
+
+  let state = "working";
+  let phase = null;
+  let lastLine = "";
+  let sessionId = null;
+  let errorMessage = null; // set only by done("error", reason) — the failure "why" (0294)
+
+  let lastSentAt = null; // null → the first send is a leading (immediate) send
+  let pending = false;
+  let timerId = null;
+
+  function addFile(path) {
+    const p = sanitizeText(path);
+    if (!p || fileSet.has(p)) return; // dedupe — a file appears once
+    files.push(p);
+    fileSet.add(p);
+    while (files.length > fileLimit) fileSet.delete(files.shift()); // bound, drop oldest
+  }
+
+  function fold(ev) {
+    if (!ev || typeof ev !== "object") return;
+    ring.push(ev); // steps[] (coalesces same-file edits + dup labels)
+    switch (ev.t) {
+      case "session":
+        if (ev.sessionId) sessionId = ev.sessionId;
+        break;
+      case "edit":
+      case "read":
+        if (ev.path) addFile(ev.path);
+        break;
+      case "note":
+        if (ev.text) lastLine = sanitizeText(ev.text); // a clean note beats the raw tail
+        break;
+      case "phase":
+        if (ev.name) phase = sanitizeText(ev.name);
+        break;
+      case "result":
+        if (ev.summary) lastLine = sanitizeText(ev.summary);
+        break;
+      default:
+        break;
+    }
+  }
+
+  /**
+   * The current live progress payload (also what `send` receives).
+   * @returns {{ state: string, phase?: string, step?: string, steps: string[],
+   *   filesTouched: string[], lastLine?: string, elapsedMs: number, sessionId?: string }}
+   */
+  function snapshot() {
+    const step = ring.latest();
+    const snap = {
+      state,
+      steps: ring.labels().map(sanitizeText).slice(-stepLimit),
+      filesTouched: files.map(sanitizeText).slice(-fileLimit),
+      elapsedMs: Math.max(0, now() - startedAt),
+    };
+    if (phase) snap.phase = sanitizeText(phase);
+    if (step) snap.step = sanitizeText(step);
+    const ll = sanitizeText(lastLine);
+    if (ll) snap.lastLine = ll;
+    if (sessionId) snap.sessionId = sanitizeText(sessionId); // for 0282 (server drops it today)
+    if (errorMessage) snap.errorMessage = errorMessage; // 0294 (older servers drop it)
+    return snap;
+  }
+
+  function clearTrailing() {
+    if (timerId != null) {
+      try {
+        clearTimer(timerId);
+      } catch {
+        /* ignore */
+      }
+      timerId = null;
+    }
+  }
+
+  function emit() {
+    // A progress send must NEVER throw into the run.
+    try {
+      const r = send(snapshot());
+      if (r && typeof r.catch === "function") r.catch(() => {});
+    } catch {
+      /* swallow */
+    }
+  }
+
+  function doSend() {
+    clearTrailing();
+    pending = false;
+    lastSentAt = now();
+    emit();
+  }
+
+  function armTrailing() {
+    if (timerId != null) return; // one timer at a time
+    const wait = lastSentAt == null ? 0 : Math.max(0, throttleMs - (now() - lastSentAt));
+    timerId = setTimer(() => {
+      timerId = null;
+      if (pending) doSend();
+    }, wait);
+  }
+
+  function scheduleSend() {
+    const t = now();
+    if (lastSentAt == null || t - lastSentAt >= throttleMs) {
+      doSend(); // leading — light up immediately
+    } else {
+      pending = true; // trailing — coalesce, one send at window end
+      armTrailing();
+    }
+  }
+
+  return {
+    /** Feed a raw stdout chunk: parse → fold → (throttled) send. */
+    feed(chunk) {
+      let events = [];
+      try {
+        events = parser.push(chunk) || [];
+      } catch {
+        events = []; // a parser hiccup must not break the run
+      }
+      const tail = rawTail(chunk); // text-only liveness fallback
+      if (tail) lastLine = sanitizeText(tail);
+      for (const ev of events) fold(ev); // a clean note/summary overrides the tail
+      scheduleSend();
+    },
+    /** Force-send the current snapshot now (bypasses the throttle). */
+    flush() {
+      doSend();
+    },
+    /**
+     * Final send: drain the parser, flip state, cancel timers. On an error
+     * finish, `reason` (the CLI's error / stderr tail / exit status) rides along
+     * as a sanitized `errorMessage` so the settled card can say WHY (0294).
+     */
+    done(finalState, reason) {
+      let tail = [];
+      try {
+        tail = parser.flush() || [];
+      } catch {
+        tail = [];
+      }
+      for (const ev of tail) fold(ev);
+      state = finalState === "error" ? "error" : "done";
+      if (state === "error") {
+        const r = sanitizeText(reason);
+        if (r) errorMessage = r;
+      }
+      clearTrailing();
+      pending = false;
+      lastSentAt = now();
+      emit();
+    },
+    snapshot,
+  };
+}

package/src/resume.mjs

@@ -0,0 +1,143 @@
+// Session resume (0282) — the daemon's "true same-PR iteration context" layer.
+//
+// Today an iterate (0281) checks out the PR branch and re-runs the coding agent
+// with the reviewer's feedback in the prompt: the CODE is there, but the agent's
+// SESSION memory (its plan/reasoning from the first run) is gone. This module lets
+// the follow-up RESUME that session (`claude -p --resume <id>`) so it continues
+// with full context.
+//
+// Two pieces, both PURE where it matters + node-builtins-only:
+//   1. buildResumeArgs(vendor, sessionId) — the vendor-gated `--resume` flags.
+//   2. a tiny best-effort state store keyed by thread_root_msg_id at
+//      ~/.hilos/state.json. The LOCAL record proves a session exists on THIS
+//      machine — the confidence signal the handler gates `--resume` on (a
+//      providerSessionId that came ONLY from the server likely lives elsewhere).
+//
+// Design rules (mirror the .mjs siblings):
+//   - The pure transforms (parse/merge/prune/serialize) take an injected clock
+//     (nowMs) and never call Date.now/os, so they unit-test with a fixed time.
+//   - Every fs read/write is guarded: a state IO failure NEVER breaks a run.
+//   - We NEVER guess a vendor's resume flag. Only claude_code has a proven one;
+//     codex/cursor degrade to today's branch+feedback iterate (deferred to 0278+).
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The daemon's state dir (same parent as ~/.hilos/agent.json — see config.mjs). */
+export const HILOS_DIR = join(homedir(), ".hilos");
+/** The state file inside HILOS_DIR (a JSON object map: threadRoot → entry). */
+export const STATE_FILE = "state.json";
+/** Prune entries older than this on every write (7 days) — the store stays small
+ *  and a genuinely stale session can never be resurrected for a resume. */
+export const STATE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * The `--resume` flags for a coding vendor, or [] when resume isn't safe/known.
+ *
+ * ONLY claude_code has a proven, confirmed resume flag (`--resume <id>`, compatible
+ * with `--output-format stream-json`). codex/cursor have UNCONFIRMED resume flags,
+ * so we emit NOTHING rather than guess — a wrong flag could break the run; they
+ * degrade to today's branch+feedback iterate (deferred to 0278/later). A falsy or
+ * non-string sessionId also returns [] (nothing to resume).
+ *
+ * @param {'claude_code'|'codex'|'cursor'|'unknown'} vendor
+ * @param {string|null|undefined} sessionId
+ * @returns {string[]}
+ */
+export function buildResumeArgs(vendor, sessionId) {
+  if (vendor !== "claude_code") return [];
+  if (typeof sessionId !== "string" || !sessionId.trim()) return [];
+  return ["--resume", sessionId];
+}
+
+// ---------------------------------------------------------------------------
+// Pure state transforms (no fs, no clock, no os — the caller injects nowMs).
+// ---------------------------------------------------------------------------
+
+/** Parse a state.json string into a plain object map. Malformed JSON, a non-object
+ *  (array / string / null), or anything unexpected → {} (safe empty map). */
+export function parseStateMap(text) {
+  try {
+    const o = JSON.parse(text);
+    if (o && typeof o === "object" && !Array.isArray(o)) return o;
+  } catch {
+    /* malformed — treat as empty */
+  }
+  return {};
+}
+
+/** Drop entries whose `updatedAt` is missing/unparseable or older than maxAgeMs
+ *  relative to the injected nowMs. Returns a NEW map (does not mutate input). */
+export function pruneStateMap(map, nowMs, maxAgeMs = STATE_MAX_AGE_MS) {
+  const out = {};
+  const src = map && typeof map === "object" && !Array.isArray(map) ? map : {};
+  for (const [k, v] of Object.entries(src)) {
+    if (!v || typeof v !== "object") continue;
+    const t = Date.parse(v.updatedAt);
+    if (Number.isFinite(t) && nowMs - t <= maxAgeMs) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Prune the old map, then set/overwrite the entry for `threadRoot`. The fresh entry
+ * is added AFTER the prune so it can never be pruned by its own write, even if its
+ * timestamp is odd. Returns a NEW map. The caller stamps `entry.updatedAt`.
+ */
+export function mergeStateMap(map, threadRoot, entry, nowMs, maxAgeMs = STATE_MAX_AGE_MS) {
+  const pruned = pruneStateMap(map, nowMs, maxAgeMs);
+  return { ...pruned, [threadRoot]: entry };
+}
+
+/** Serialize a state map for disk. Compact (minimal IO). */
+export function serializeStateMap(map) {
+  return JSON.stringify(map);
+}
+
+// ---------------------------------------------------------------------------
+// Guarded fs layer — best-effort, NEVER throws into a run.
+// ---------------------------------------------------------------------------
+
+/** Read the whole state map from `${dir}/state.json`. Missing file / read error /
+ *  malformed JSON → {}. */
+export function readState(dir) {
+  try {
+    return parseStateMap(readFileSync(join(dir, STATE_FILE), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/** The single entry for a thread root, or null. Used by the resume gate. */
+export function readStateEntry(dir, threadRoot) {
+  if (!dir || !threadRoot) return null;
+  const e = readState(dir)[threadRoot];
+  return e && typeof e === "object" ? e : null;
+}
+
+/**
+ * Write/overwrite the entry for `threadRoot`, pruning stale entries. Best-effort:
+ * returns true on success, false on any failure (a state write NEVER breaks a run).
+ * `entry` should carry { runId, branch, prUrl, sessionId, machine, updatedAt }; the
+ * prune clock derives from entry.updatedAt (falling back to the injected now()).
+ *
+ * @param {string} dir
+ * @param {string} threadRoot
+ * @param {object} entry
+ * @param {{ now?: () => number }} [opts]
+ * @returns {boolean}
+ */
+export function writeState(dir, threadRoot, entry, { now = Date.now } = {}) {
+  if (!dir || !threadRoot || !entry || typeof entry !== "object") return false;
+  try {
+    const stamped = Date.parse(entry.updatedAt);
+    const nowMs = Number.isFinite(stamped) ? stamped : now();
+    const next = mergeStateMap(readState(dir), threadRoot, entry, nowMs);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, STATE_FILE), serializeStateMap(next));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/review.mjs

@@ -0,0 +1,237 @@
+// Cross-agent REVIEW EXECUTION (WS3, ticket 0288) — the pure core the daemon uses
+// to turn a PR diff into a posted, ADVISORY review. Node-builtins-only, no I/O, so
+// prompt shaping + output parsing + the ping-pong guard are all unit-testable.
+//
+// A review is advisory: it never merges, blocks, or edits files. buildReviewPrompt
+// asks the CLI to ANALYZE a diff (read-only) and emit a structured verdict;
+// parseReviewOutput turns whatever the model wrote back into a
+// { verdict, summary, findings } the daemon hands to post_review (which @-tags the
+// author). The human stays the sole merge gate.
+
+export const REVIEW_VERDICTS = ["looks-good", "suggest-changes", "blocking"];
+export const REVIEW_SEVERITIES = ["info", "warning", "blocking"];
+
+// Bounds so a prompt-injected / runaway review can't bloat a message or the UI.
+// (Mirror lib/reviews.ts sanitize intent — kept in sync by value, not import,
+// since this module is dependency-free .mjs shipped in the daemon package.)
+const MAX_FINDINGS = 50;
+const MAX_NOTE = 600;
+const MAX_FILE = 300;
+const MAX_SUMMARY = 4000;
+
+/** The first line the CLI must emit — parsed leniently, but asked for exactly. */
+export const VERDICT_MARK = "VERDICT:";
+
+/** Render one diff file for the prompt: a header + its (already byte-budgeted) patch. */
+function renderDiffFile(f) {
+  const name = String(f?.filename || "unknown");
+  const status = f?.status ? ` (${f.status})` : "";
+  const add = Number.isFinite(f?.additions) ? f.additions : 0;
+  const del = Number.isFinite(f?.deletions) ? f.deletions : 0;
+  const head = `### ${name}${status} +${add} -${del}`;
+  const patch = typeof f?.patch === "string" && f.patch.trim() ? f.patch : "(no textual patch available)";
+  const cut = f?.patchTruncated ? "\n… (patch truncated to fit the review budget)" : "";
+  return `${head}\n${patch}${cut}`;
+}
+
+/**
+ * The prompt handed to the review CLI. It instructs a strictly READ-ONLY review of
+ * the provided diff (the diff is already byte-budgeted by get_pr_diff, so the CLI
+ * needs no checkout) and a structured verdict the daemon can parse.
+ *
+ * @param {{
+ *   diffFiles?: Array<{filename:string,status?:string,additions?:number,deletions?:number,patch?:string,patchTruncated?:boolean}>,
+ *   task?: string, reportSummary?: string, threadContext?: string, workspaceMemory?: string
+ * }} [o]
+ * @returns {string}
+ */
+export function buildReviewPrompt(o) {
+  const { diffFiles = [], task, reportSummary, threadContext, workspaceMemory } = o || {};
+  const files = Array.isArray(diffFiles) ? diffFiles : [];
+  const diffBlock = files.length
+    ? files.map(renderDiffFile).join("\n\n")
+    : "(no files in this diff)";
+
+  let p =
+    `You are a senior engineer doing a CODE REVIEW of a pull request for a teammate. ` +
+    `Review is ADVISORY: you only give feedback — you do NOT merge, approve, or block, ` +
+    `and a human makes the final call.\n\n` +
+    `STRICTLY READ-ONLY: the full diff is included below, so you do NOT need a checkout. ` +
+    `Do NOT edit, create, or delete any files. Do NOT run git or the \`gh\` CLI. Do NOT ` +
+    `stage, commit, push, or open/close anything. ONLY analyze the diff and write your review.\n\n` +
+    `Respond in EXACTLY this shape:\n` +
+    `1. A FIRST line: \`${VERDICT_MARK} <looks-good|suggest-changes|blocking>\` ` +
+    `(looks-good = ship it; suggest-changes = non-blocking improvements; blocking = a real bug ` +
+    `or risk that should be fixed first).\n` +
+    `2. Then 1–3 sentences summarizing your assessment.\n` +
+    `3. Then, optionally, specific findings — one per line — as: ` +
+    `\`- [info|warning|blocking] path/to/file:line — what and why\`.\n\n` +
+    `Be concrete and kind. Prefer real correctness/security/regression issues over style nits.`;
+
+  if (task && task.trim()) {
+    p += `\n\nWhat this PR was meant to do:\n${task.trim()}`;
+  }
+  if (reportSummary && reportSummary.trim()) {
+    p += `\n\nThe author's own summary of the change:\n${reportSummary.trim()}`;
+  }
+  if (threadContext && threadContext.trim()) {
+    p += `\n\nConversation around the PR (background):\n${threadContext.trim().slice(-4000)}`;
+  }
+  if (workspaceMemory && workspaceMemory.trim()) {
+    p += `\n\nProject context (the team's soul):\n${workspaceMemory.trim().slice(-2000)}`;
+  }
+  p += `\n\nThe PR diff to review:\n\n${diffBlock}`;
+  return p;
+}
+
+/** Coerce to a known verdict, or null. */
+function asVerdict(v) {
+  const s = String(v || "").trim().toLowerCase().replace(/\s+/g, "-");
+  return REVIEW_VERDICTS.includes(s) ? s : null;
+}
+
+/** Coerce to a known severity, or 'info'. */
+function asSeverity(v) {
+  const s = String(v || "").trim().toLowerCase();
+  return REVIEW_SEVERITIES.includes(s) ? s : "info";
+}
+
+// A findings line: "- [severity] rest" (bullet + bracketed severity required, so a
+// prose bullet in the summary isn't mistaken for a structured finding).
+const FINDING_RE = /^\s*[-*]\s*\[(info|warning|warn|blocking|block|error|major|minor|nit)\]\s*(.*)$/i;
+// Within `rest`, pull an optional "path:line" head before an em/en/hyphen dash.
+const LOC_RE = /^([^\s—–:][^:\n]*?):(\d+)\s*[—–-]+\s*(.*)$/;
+const PATH_ONLY_RE = /^([^\s—–][^—–\n]*?)\s*[—–-]+\s+(.*)$/;
+
+/** Map loose severity words the model might use onto the three canonical ones. */
+function canonSeverity(raw) {
+  const s = String(raw || "").toLowerCase();
+  if (s === "warn") return "warning";
+  if (s === "block" || s === "error" || s === "major") return "blocking";
+  if (s === "minor" || s === "nit") return "info";
+  return asSeverity(s);
+}
+
+/** Parse one findings line into a finding, or null if it isn't one. */
+function parseFinding(line) {
+  const m = FINDING_RE.exec(line);
+  if (!m) return null;
+  const severity = canonSeverity(m[1]);
+  let rest = (m[2] || "").trim();
+  let file;
+  let lineNo;
+  let note = rest;
+  const loc = LOC_RE.exec(rest);
+  if (loc) {
+    file = loc[1].trim();
+    const n = parseInt(loc[2], 10);
+    if (Number.isFinite(n) && n > 0) lineNo = n;
+    note = loc[3].trim();
+  } else {
+    const po = PATH_ONLY_RE.exec(rest);
+    // Only treat the head as a path when it actually looks like one (has a dot or
+    // slash) — otherwise "- [warning] Missing null check — fix it" would wrongly
+    // read "Missing null check" as a filename.
+    if (po && /[./]/.test(po[1])) {
+      file = po[1].trim();
+      note = po[2].trim();
+    }
+  }
+  note = note.trim();
+  if (!note) note = rest || "(no detail)";
+  const out = { severity, note: note.slice(0, MAX_NOTE) };
+  if (file) out.file = file.slice(0, MAX_FILE);
+  if (lineNo) out.line = lineNo;
+  return out;
+}
+
+/**
+ * Parse the review CLI's free text into a structured review. Total + lenient —
+ * NEVER throws. Rules:
+ *   - verdict: an explicit `VERDICT: x` line wins; else the first canonical verdict
+ *     token anywhere; else 'looks-good' ONLY if the text clearly says so; else, when
+ *     there is any text at all, 'suggest-changes' (advisory default — never a false
+ *     "looks good"); empty text → 'suggest-changes' with an empty summary.
+ *   - findings: lines shaped `- [severity] path:line — note`.
+ *   - summary: the text minus the verdict line and the finding lines, first non-empty
+ *     block, capped.
+ * @param {string} text
+ * @returns {{ verdict: string, summary: string, findings: Array<{severity:string,file?:string,line?:number,note:string}> }}
+ */
+export function parseReviewOutput(text) {
+  const raw = typeof text === "string" ? text : "";
+  const trimmed = raw.trim();
+  if (!trimmed) return { verdict: "suggest-changes", summary: "", findings: [] };
+
+  const lines = trimmed.split(/\r?\n/);
+  const findings = [];
+  const summaryLines = [];
+  let verdict = null;
+
+  for (const line of lines) {
+    // Explicit verdict line (highest confidence).
+    const vm = /verdict\s*[:\-]?\s*(looks[-\s]?good|suggest[-\s]?changes|blocking|approve|lgtm)/i.exec(line);
+    if (vm && !verdict) {
+      const tok = vm[1].toLowerCase();
+      verdict =
+        /approve|lgtm|looks/.test(tok) ? "looks-good" : tok.replace(/\s+/g, "-");
+      verdict = asVerdict(verdict) || (/approve|lgtm|looks/.test(tok) ? "looks-good" : verdict);
+      continue; // don't fold the verdict line into the summary
+    }
+    const f = parseFinding(line);
+    if (f) {
+      if (findings.length < MAX_FINDINGS) findings.push(f);
+      continue;
+    }
+    summaryLines.push(line);
+  }
+
+  // No explicit verdict line → infer from the prose, conservatively.
+  if (!verdict) {
+    const low = trimmed.toLowerCase();
+    if (/\bblocking\b/.test(low)) verdict = "blocking";
+    else if (/looks[-\s]?good|lgtm|ship it|approve/.test(low)) verdict = "looks-good";
+    else if (/suggest[-\s]?changes/.test(low)) verdict = "suggest-changes";
+    // A blocking finding forces at least 'suggest-changes' if nothing else said so.
+    else if (findings.some((f) => f.severity === "blocking")) verdict = "blocking";
+    else verdict = "suggest-changes"; // advisory default — never a false "looks good"
+  }
+  // Guard: if any finding is blocking, don't let a stray "looks-good" bless it.
+  if (verdict === "looks-good" && findings.some((f) => f.severity === "blocking")) {
+    verdict = "suggest-changes";
+  }
+
+  const summary = summaryLines
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim()
+    .slice(0, MAX_SUMMARY);
+  return { verdict, summary, findings };
+}
+
+/**
+ * A stable key for "this reviewer has reviewed this PR" — so a reviewer doesn't
+ * re-review the same PR endlessly and an author<->reviewer pair can't ping-pong.
+ * @param {string} prUrl
+ * @param {string} reviewerId
+ * @returns {string}
+ */
+export function reviewDedupeKey(prUrl, reviewerId) {
+  return `${String(reviewerId || "?")}::${String(prUrl || "?")}`;
+}
+
+/**
+ * The round/dedupe guard. Returns true only when it's safe to review again:
+ *   - never past maxRounds for this key, and
+ *   - never a second time for an exact `seenKey` already in `seen`.
+ * Pure — the caller owns the `seen`/rounds state (a Map/Set on the long-lived
+ * daemon process), so the ping-pong bound survives across poll passes.
+ * @param {{ rounds?: number, maxRounds?: number, seenKey?: string, seen?: Set<string> }} [o]
+ * @returns {boolean}
+ */
+export function shouldReview(o) {
+  const { rounds = 0, maxRounds = 3, seenKey, seen } = o || {};
+  if (Number.isFinite(rounds) && rounds >= maxRounds) return false;
+  if (seen && seenKey && typeof seen.has === "function" && seen.has(seenKey)) return false;
+  return true;
+}