hilos-agent 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
   "type": "module",
   "bin": {

package/src/agent-events.mjs

@@ -0,0 +1,371 @@
+// Normalized vendor stream parser (0272). The KEYSTONE of the "Agents feel
+// alive" epic: coding CLIs each narrate their work in a different, unstable
+// wire format (Claude Code emits `--output-format stream-json` NDJSON, Codex
+// emits `--json` item events, Cursor emits unstructured text). This module turns
+// any of them into ONE small, typed `AgentEvent` stream the UI can render as a
+// live "what the agent is doing right now" card.
+//
+// Design rules that make this safe to point at an untrusted, evolving CLI:
+//   - PURE + dependency-free (node builtins only) so it stands alone and is
+//     unit-tested without a sandbox — mirror of the .mjs siblings' style.
+//   - NEVER throws. A vendor changing its format, a non-JSON log line, or an
+//     unknown event type must DEGRADE (emit nothing), never crash a run.
+//   - Every string that reaches the UI is sanitized (token-shaped secrets
+//     stripped, length capped) — a chatty CLI can echo a `Bearer …` header.
+//
+// Claude shapes here MATCH `lib/hosted-worklog.ts` / `lib/hosted-agent.ts`
+// (`formatClaudeEvent`, `parseStreamResult`) so ticket 0274 can swap the daemon's
+// hand-rolled `lastLine` capture (see handler.mjs onData ~:787) for this parser
+// with zero behavior change. NOTHING imports this yet except the test — wiring is
+// 0274.
+
+/**
+ * @typedef {object} AgentEvent
+ * A normalized, render-ready step. Exactly one of these per meaningful thing the
+ * coding agent did. Small on purpose — the LiveRunCard maps `t` to a label.
+ * @property {'phase'|'edit'|'run'|'read'|'think'|'note'|'session'|'result'} t
+ *   - 'session' → { sessionId }        the CLI's resumable session id (init only)
+ *   - 'edit'    → { path }             wrote/edited a file
+ *   - 'read'    → { path }             read a file
+ *   - 'run'     → { cmd }              ran a shell command
+ *   - 'note'    → { text }             the agent's narration / thinking (think→note)
+ *   - 'result'  → { ok, summary? }     the run finished (ok=false on error)
+ *   - 'phase'   → { name }             reserved lifecycle marker (unused by v1
+ *                                       parsers; kept so 0274 can add start/end
+ *                                       phases without widening the type)
+ * @property {string} [sessionId]
+ * @property {string} [path]
+ * @property {string} [cmd]
+ * @property {string} [text]
+ * @property {string} [name]
+ * @property {boolean} [ok]
+ * @property {string} [summary]
+ */
+
+// --- Security: sanitize everything that reaches the UI ---------------------
+
+const MAX_LEN = 300;
+const REDACTED = "[redacted]";
+
+// Token-shaped strings a CLI might echo (auth headers, keys it was handed, hex/
+// base64 blobs). Order matters — specific prefixes before the generic blobs so a
+// `ghp_…` is labelled, not swallowed by the base64 rule.
+const SECRET_PATTERNS = [
+  /\bBearer\s+[A-Za-z0-9._\-]+/gi, // "Bearer <token>"
+  /\bhilos_[A-Za-z0-9]{8,}/g, // hilos MCP bearer tokens
+  /\bsbp_[A-Za-z0-9]{16,}/g, // Supabase access/management tokens (SUPABASE_ACCESS_TOKEN)
+  /\bgithub_pat_[A-Za-z0-9_]{20,}/g, // fine-grained GitHub PAT
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/g, // ghp_/gho_/ghu_/ghs_/ghr_ GitHub tokens
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/g, // Slack tokens
+  /\bsk-[A-Za-z0-9_-]{16,}/g, // OpenAI/Anthropic-style secret keys
+  /\b[A-Fa-f0-9]{32,}\b/g, // long hex blobs
+  /\b[A-Za-z0-9+/]{40,}={0,2}\b/g, // long base64 blobs
+];
+
+/**
+ * Strip token-shaped secrets and cap length. Exported so the server (0274+) can
+ * reuse the exact same redaction on anything it echoes. Never throws; non-string
+ * input → "".
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function sanitizeText(value) {
+  if (typeof value !== "string") return "";
+  let out = value;
+  for (const re of SECRET_PATTERNS) out = out.replace(re, REDACTED);
+  if (out.length > MAX_LEN) out = out.slice(0, MAX_LEN - 1) + "…";
+  return out;
+}
+
+// --- Line parsing per vendor ----------------------------------------------
+
+/** JSON.parse that returns null instead of throwing on a non-JSON line. */
+function tryParse(line) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed) return null;
+  try {
+    const obj = JSON.parse(trimmed);
+    return obj && typeof obj === "object" ? obj : null;
+  } catch {
+    return null; // log noise / partial line / plain text → ignore
+  }
+}
+
+/** Map a Claude/agent tool name to a normalized event kind (or null to skip). */
+function toolKind(name) {
+  switch (name) {
+    case "Edit":
+    case "MultiEdit":
+    case "Write":
+    case "NotebookEdit":
+      return "edit";
+    case "Read":
+      return "read";
+    case "Bash":
+      return "run";
+    default:
+      // Grep/Glob/WebFetch/Task/etc. carry less "alive" signal; ignore in v1 so
+      // an unknown tool can never crash the parser. 0274 may promote some.
+      return null;
+  }
+}
+
+/** One assistant content block → an AgentEvent, or null. */
+function blockToEvent(block) {
+  if (!block || typeof block !== "object") return null;
+  if (block.type === "text" && typeof block.text === "string") {
+    const text = sanitizeText(block.text.replace(/\s+/g, " ").trim());
+    return text ? { t: "note", text } : null;
+  }
+  if (block.type === "tool_use" && typeof block.name === "string") {
+    const kind = toolKind(block.name);
+    if (!kind) return null;
+    const input = block.input && typeof block.input === "object" ? block.input : {};
+    if (kind === "run") {
+      const cmd = typeof input.command === "string" ? input.command.replace(/\s+/g, " ").trim() : "";
+      return { t: "run", cmd: sanitizeText(cmd) };
+    }
+    const raw = input.file_path ?? input.path ?? input.notebook_path;
+    const path = typeof raw === "string" ? sanitizeText(raw) : "";
+    return { t: kind, path };
+  }
+  return null;
+}
+
+/**
+ * Parse ONE Claude Code `stream-json` NDJSON line → AgentEvent[]. Shapes mirror
+ * `lib/hosted-agent.ts`: system init (session_id), assistant turns (text +
+ * tool_use), and the final result. Everything else (user tool_result, unknown
+ * types) → [].
+ */
+function parseClaudeLine(line) {
+  const obj = tryParse(line);
+  if (!obj) return [];
+  if (obj.type === "system" && typeof obj.session_id === "string") {
+    return [{ t: "session", sessionId: sanitizeText(obj.session_id) }];
+  }
+  if (obj.type === "result") {
+    const ok = obj.is_error !== true && obj.subtype !== "error";
+    const summary = typeof obj.result === "string" ? sanitizeText(obj.result) : undefined;
+    return [summary ? { t: "result", ok, summary } : { t: "result", ok }];
+  }
+  if (obj.type === "assistant" && obj.message && Array.isArray(obj.message.content)) {
+    const out = [];
+    for (const block of obj.message.content) {
+      const ev = blockToEvent(block);
+      if (ev) out.push(ev);
+    }
+    return out;
+  }
+  return [];
+}
+
+/**
+ * Parse ONE Codex `--json` item line → AgentEvent[]. Best-effort / experimental:
+ * Codex's format is younger and less documented, so we read the kind from either
+ * `item.type` (the `{type:"item.completed", item:{…}}` envelope) or a bare
+ * top-level `type`, and pull fields from whichever object carries them. Unknown
+ * kinds → [].
+ */
+function parseCodexLine(line) {
+  const obj = tryParse(line);
+  if (!obj) return [];
+  const item = obj.item && typeof obj.item === "object" ? obj.item : obj;
+  const kind = item.type ?? obj.type;
+  switch (kind) {
+    case "command_execution": {
+      const raw = item.command ?? item.cmd;
+      const cmd = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : "";
+      return cmd ? [{ t: "run", cmd: sanitizeText(cmd) }] : [];
+    }
+    case "file_change": {
+      const changes = Array.isArray(item.changes)
+        ? item.changes
+        : item.path
+          ? [{ path: item.path }]
+          : [];
+      const out = [];
+      for (const c of changes) {
+        const p = c && (c.path ?? c.file_path);
+        if (typeof p === "string" && p) out.push({ t: "edit", path: sanitizeText(p) });
+      }
+      return out;
+    }
+    case "agent_message": {
+      const raw = item.text ?? item.message;
+      const text = typeof raw === "string" ? sanitizeText(raw.replace(/\s+/g, " ").trim()) : "";
+      return text ? [{ t: "note", text }] : [];
+    }
+    case "task_complete":
+    case "turn.completed": {
+      const raw = item.text ?? item.message ?? obj.text;
+      const summary = typeof raw === "string" ? sanitizeText(raw) : undefined;
+      return [summary ? { t: "result", ok: true, summary } : { t: "result", ok: true }];
+    }
+    default:
+      return [];
+  }
+}
+
+/** claude / claude_code / claude-code all mean the Claude parser. */
+function normalizeVendor(vendor) {
+  const v = String(vendor || "").toLowerCase();
+  if (v === "claude" || v === "claude_code" || v === "claude-code") return "claude";
+  if (v === "codex") return "codex";
+  return "cursor"; // cursor + ANY unknown vendor → lastLine fallback
+}
+
+// --- Streaming parsers -----------------------------------------------------
+
+/**
+ * The daemon pushes raw stdout chunks (see handler.mjs onData ~:787) that can
+ * split a JSON object mid-line. A structured parser buffers the partial tail and
+ * only parses COMPLETE lines; flush() drains a trailing unterminated line.
+ * @param {(line: string) => AgentEvent[]} parseLine
+ */
+function makeLineBufferedParser(parseLine) {
+  let buf = "";
+  return {
+    /** @param {string} chunk @returns {AgentEvent[]} */
+    push(chunk) {
+      buf += String(chunk ?? "");
+      const out = [];
+      let nl;
+      while ((nl = buf.indexOf("\n")) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        for (const ev of parseLine(line)) out.push(ev);
+      }
+      return out;
+    },
+    /** @returns {AgentEvent[]} */
+    flush() {
+      const out = [];
+      if (buf.trim()) for (const ev of parseLine(buf)) out.push(ev);
+      buf = "";
+      return out;
+    },
+  };
+}
+
+/**
+ * Fallback for Cursor and any vendor with no structured stream. There's nothing
+ * to parse, so we only remember the last non-empty line seen — matching exactly
+ * what the daemon does today (handler.mjs onData) so we NEVER regress below it —
+ * and emit at most one sparse note on flush.
+ */
+function makeCursorParser() {
+  let lastLine = "";
+  return {
+    /** @returns {AgentEvent[]} */
+    push(chunk) {
+      const lines = String(chunk ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (lines.length) lastLine = lines[lines.length - 1];
+      return []; // no structured events mid-stream
+    },
+    /** @returns {AgentEvent[]} */
+    flush() {
+      if (!lastLine) return [];
+      const text = sanitizeText(lastLine);
+      lastLine = "";
+      return text ? [{ t: "note", text }] : [];
+    },
+  };
+}
+
+/**
+ * Build a stateful stream parser for `vendor`.
+ * @param {'claude'|'claude_code'|'codex'|'cursor'|string} vendor
+ * @returns {{ push: (chunk: string) => AgentEvent[], flush: () => AgentEvent[] }}
+ */
+export function makeStreamParser(vendor) {
+  const v = normalizeVendor(vendor);
+  if (v === "claude") return makeLineBufferedParser(parseClaudeLine);
+  if (v === "codex") return makeLineBufferedParser(parseCodexLine);
+  return makeCursorParser();
+}
+
+// --- Human step labels (what the LiveRunCard shows) ------------------------
+
+/** Describe a shell command in plain words (design rule: no emoji, calm copy). */
+function describeRun(cmd) {
+  const c = String(cmd || "").trim();
+  if (!c) return "Running a command";
+  if (/\b(test|tests)\b|vitest|jest|pytest|\bgo test\b/i.test(c)) return "Running tests";
+  const short = c.length > 60 ? c.slice(0, 59) + "…" : c;
+  return `Running ${short}`;
+}
+
+/**
+ * One AgentEvent → a human step label, or null for events that aren't shown as
+ * steps (session/phase are metadata). Pure.
+ * @param {AgentEvent} event
+ * @returns {string | null}
+ */
+export function stepLabel(event) {
+  switch (event && event.t) {
+    case "edit":
+      return event.path ? `Editing ${event.path}` : "Editing files";
+    case "read":
+      return event.path ? `Reading ${event.path}` : "Reading files";
+    case "run":
+      return describeRun(event.cmd);
+    case "note":
+      return event.text ? event.text : null;
+    case "result":
+      return event.ok ? "Done" : "Finished with errors";
+    default:
+      return null; // session / phase / unknown → not a step
+  }
+}
+
+/**
+ * A bounded ring buffer of the most recent human step labels. Coalesces
+ * sequential edits to the SAME file into one step (a run that touches one file
+ * ten times reads as one "Editing …" line) and drops immediate duplicate
+ * labels. `limit` steps kept (default 8) — the card shows a short rolling window.
+ * @param {number} [limit]
+ */
+export function createStepRing(limit = 8) {
+  const steps = [];
+  let lastEditPath = null; // for collapsing consecutive same-file edits
+
+  /** @param {AgentEvent} event */
+  function push(event) {
+    const label = stepLabel(event);
+    if (!label) return;
+    if (event.t === "edit") {
+      if (lastEditPath === event.path) return; // same file again → collapse
+      lastEditPath = event.path;
+    } else {
+      lastEditPath = null; // any other step breaks an edit run
+    }
+    if (steps.length && steps[steps.length - 1] === label) return; // dup guard
+    steps.push(label);
+    if (steps.length > limit) steps.shift();
+  }
+
+  return {
+    push,
+    /** @returns {string[]} */
+    labels: () => steps.slice(),
+    /** @returns {string | null} */
+    latest: () => (steps.length ? steps[steps.length - 1] : null),
+  };
+}
+
+/**
+ * Fold a batch of events through a fresh ring → the coalesced step labels. Pure
+ * convenience over createStepRing for callers that have the whole list.
+ * @param {AgentEvent[]} events
+ * @param {number} [limit]
+ * @returns {string[]}
+ */
+export function summarizeSteps(events, limit = 8) {
+  const ring = createStepRing(limit);
+  for (const ev of events || []) ring.push(ev);
+  return ring.labels();
+}

package/src/config.mjs

@@ -63,6 +63,11 @@ const DEFAULTS = {
   // spam. 0 disables. Clamped to >=15s so a misconfig can't spam realtime
   // UPDATEs. (Distinct from cli.mjs's 15s LOCAL terminal heartbeat.)
   heartbeatMs: 180000,
+  // Live-progress throttle (0274): when the server supports post_progress, the
+  // code run streams a coalesced "what I'm doing right now" card instead of the
+  // 3-min heartbeat. This caps how often it pushes an UPDATE (leading+trailing).
+  // Clamped to >=750ms so a misconfig can't hammer realtime.
+  progressMs: 2000,
   // Cap a chat reply / plan-ack so a stalled model can't dead-air the channel;
   // on timeout we post an honest "taking longer than expected" line.
   chatTimeoutMs: 90000,
@@ -88,6 +93,7 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
     codingCmd: process.env.CODING_CMD,
     chatCmd: process.env.HILOS_CHAT_CMD,
     heartbeatMs: process.env.HILOS_HEARTBEAT_MS ? Number(process.env.HILOS_HEARTBEAT_MS) : undefined,
+    progressMs: process.env.HILOS_PROGRESS_MS ? Number(process.env.HILOS_PROGRESS_MS) : undefined,
     chatTimeoutMs: process.env.HILOS_CHAT_TIMEOUT_MS ? Number(process.env.HILOS_CHAT_TIMEOUT_MS) : undefined,
     backfill: process.env.HILOS_BACKFILL === "1" ? true : undefined,
     once: process.env.HILOS_ONCE === "1" ? true : undefined,
@@ -96,6 +102,8 @@ export function resolveConfig({ flags = {}, join: joinPayload } = {}) {
   for (const [k, v] of Object.entries(env)) if (v !== undefined && v !== "") merged[k] = v;
   // Clamp the chat heartbeat: 0 (off) stays off, otherwise never below 15s.
   if (merged.heartbeatMs > 0) merged.heartbeatMs = Math.max(15000, Number(merged.heartbeatMs) || 0);
+  // Clamp the live-progress throttle to a >=750ms floor (a bad value → the default).
+  merged.progressMs = Math.max(750, Number(merged.progressMs) || 2000);
   if (joinPayload) {
     merged.url = joinPayload.url;
     merged.token = joinPayload.token;
@@ -122,6 +130,7 @@ const LIVE_FIELDS = [
   "decisionTimeoutMs",
   "decisionPollMs",
   "heartbeatMs",
+  "progressMs",
   "chatTimeoutMs",
   // NOT queueConcurrency: the queue is built once at startup, so it can't change
   // live. queueAcks IS live (intake() reads it per-mention from liveCfg).
@@ -146,8 +155,10 @@ export function reloadConfig(prev) {
   if (process.env.CODING_CMD) next.codingCmd = process.env.CODING_CMD;
   if (process.env.HILOS_CHAT_CMD) next.chatCmd = process.env.HILOS_CHAT_CMD;
   if (process.env.HILOS_HEARTBEAT_MS) next.heartbeatMs = Number(process.env.HILOS_HEARTBEAT_MS);
+  if (process.env.HILOS_PROGRESS_MS) next.progressMs = Number(process.env.HILOS_PROGRESS_MS);
   if (process.env.HILOS_CHAT_TIMEOUT_MS) next.chatTimeoutMs = Number(process.env.HILOS_CHAT_TIMEOUT_MS);
   if (next.heartbeatMs > 0) next.heartbeatMs = Math.max(15000, Number(next.heartbeatMs) || 0);
+  next.progressMs = Math.max(750, Number(next.progressMs) || 2000);
   if (file.repos) next.repos = { ...DEFAULTS.repos, ...file.repos };
   return next;
 }

package/src/daemon.mjs

@@ -89,3 +89,21 @@ export function mentionHandle(name) {
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
 }
+
+/**
+ * A GitHub PR reference embedded in `text` for `repoFullName`, or null. The
+ * server tags a "request changes" rework ping with the existing PR's URL
+ * ("…update the PR <url>…"), so the daemon can update THAT PR's branch
+ * (same-branch iteration) instead of opening a brand-new one.
+ *
+ * Anchored on a "PR <url>" lead-in (and scoped to the channel's repo) so only an
+ * explicit "update the PR <url>" — the server ping, or a person naming a PR —
+ * triggers continuation. A stray reference link to some other PR (same or other
+ * repo, quoted for context) must NOT hijack the branch.
+ */
+export function detectPrContinuation(text, repoFullName) {
+  const m = /\bPR\s+(https?:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+))/i.exec(String(text || ""));
+  if (!m) return null;
+  if (repoFullName && m[2].toLowerCase() !== String(repoFullName).toLowerCase()) return null;
+  return { url: m[1], repoFullName: m[2], number: Number(m[3]) };
+}

package/src/followup.mjs

@@ -0,0 +1,161 @@
+// Same-PR follow-up resolver (0281) — the decision core for "a human replied in a
+// thread asking for a change; do we continue the PR this thread already owns, or
+// fork a new one?" Pure + dependency-free (it needs no imports at all) so it
+// unit-tests without any I/O and is shared by the daemon (handler.mjs) and the
+// hosted path (lib/, via TS import).
+//
+// The PRIMARY classifier is the LLM (the daemon's routeIntent reads intent in any
+// language, in context); the cue lists below are ONLY a hint for that prompt and a
+// deterministic FALLBACK when the model is unavailable. Never let the cue lists be
+// the main brain — they're the safety net.
+
+/**
+ * The three reads of a follow-up message, relative to the run its thread owns:
+ *   'change'    — continue/adjust that work ("also make it blue", "actually revert")
+ *   'new-scope' — explicitly wants a SEPARATE PR ("do that in a new PR")
+ *   'ambiguous' — unclear; a plain follow-up with no explicit fresh-PR cue
+ * @typedef {'change' | 'new-scope' | 'ambiguous'} FollowupSignal
+ */
+
+/**
+ * The routing decision:
+ *   'iterate'  — continue the SAME branch/PR the thread already owns
+ *   'redirect' — supersede the old run and start a fresh, separate PR
+ *   'new'      — today's default: a brand-new branch + run (no run to continue)
+ * @typedef {'iterate' | 'new' | 'redirect'} FollowupMode
+ */
+
+/**
+ * Illustrative "continue this work" cues, multi-language friendly. NOT exhaustive
+ * and NOT the primary classifier — a hint for the LLM prompt and the deterministic
+ * fallback. Matched as substrings against a normalized (lowercased,
+ * punctuation-collapsed) message.
+ */
+export const CHANGE_CUES = [
+  // English
+  "also",
+  "actually",
+  "instead",
+  "revert",
+  "undo",
+  "roll back",
+  "change it",
+  "make it",
+  "tweak",
+  "adjust",
+  "one more",
+  "on second thought",
+  "same pr",
+  "keep going",
+  // Spanish
+  "también",
+  "en vez",
+  "revierte",
+  "deshaz",
+  "cámbialo",
+  "ajusta",
+  // Portuguese / French / German (small illustrative set)
+  "ao invés",
+  "au lieu",
+  "annule",
+  "stattdessen",
+];
+
+/**
+ * Illustrative "make it a SEPARATE PR" cues — an explicit request to fork rather
+ * than continue. Same role: LLM hint + deterministic fallback.
+ */
+export const NEW_SCOPE_CUES = [
+  // English
+  "separate pr",
+  "separate branch",
+  "new pr",
+  "another pr",
+  "different pr",
+  "fresh pr",
+  "its own pr",
+  "own pr",
+  "new branch",
+  "as a new",
+  "in a new",
+  // Spanish
+  "pr aparte",
+  "pr separado",
+  "otro pr",
+  "nuevo pr",
+  "rama aparte",
+  // Portuguese / French
+  "nova pr",
+  "pr séparée",
+];
+
+/** Lowercase + collapse any run of non-alphanumeric (unicode letters kept) to a
+ *  single space, so matching is case- AND punctuation-insensitive. */
+function normalize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** True when the normalized haystack contains the normalized cue, so "new  PR!"
+ *  matches "new pr". */
+function hasCue(normalizedHaystack, cue) {
+  const c = normalize(cue);
+  if (!c) return false;
+  return normalizedHaystack === c || normalizedHaystack.includes(c);
+}
+
+/**
+ * Deterministic cue-based classifier — the FALLBACK when the LLM produced no
+ * signal. Explicit new-scope cues win over change cues (an explicit "in a new PR"
+ * is a stronger intent than a stray "also"); nothing matched → 'ambiguous'.
+ * @param {string} text
+ * @returns {FollowupSignal}
+ */
+export function classifyFollowupCue(text) {
+  const h = normalize(text);
+  if (!h) return "ambiguous";
+  if (NEW_SCOPE_CUES.some((c) => hasCue(h, c))) return "new-scope";
+  if (CHANGE_CUES.some((c) => hasCue(h, c))) return "change";
+  return "ambiguous";
+}
+
+/** Coerce an arbitrary model/string signal into the enum; unknown → 'ambiguous'. */
+export function normalizeSignal(raw) {
+  const s = normalize(raw);
+  if (s === "new scope" || s === "newscope" || s === "new" || s === "separate") return "new-scope";
+  if (s === "change" || s === "iterate" || s === "continue") return "change";
+  if (s === "ambiguous" || s === "unsure" || s === "unknown") return "ambiguous";
+  return "ambiguous";
+}
+
+/**
+ * The truth table. Deliberately small + exhaustive over
+ * (hasActiveRun × prOpen × signal):
+ *
+ *   hasActiveRun | prOpen | signal      -> mode
+ *   -------------|--------|-------------|----------
+ *   false        |   *    |    *        -> 'new'       (today's behavior — nothing to continue)
+ *   true         | true   | 'change'    -> 'iterate'   (continue the same PR)
+ *   true         | true   | 'ambiguous' -> 'iterate'   (default a plain reply to the open PR it belongs to)
+ *   true         | true   | 'new-scope' -> 'redirect'  (explicit "separate PR" — supersede + fork)
+ *   true         | false  |    *        -> 'new'        (PR merged/closed — NEVER iterate onto it)
+ *
+ * Safety: iterate REQUIRES an open PR, so a false 'iterate' can't push a genuinely
+ * new task onto a merged/closed PR; an explicit new-scope always forks even when a
+ * PR is open.
+ *
+ * @param {{ hasActiveRun: boolean, prOpen: boolean, signal: FollowupSignal }} o
+ * @returns {FollowupMode}
+ */
+export function resolveFollowupMode({ hasActiveRun, prOpen, signal } = {}) {
+  if (!hasActiveRun) return "new";
+  // Recency guard: only ever continue an OPEN PR. A run whose PR is merged/closed
+  // (or that never opened one) starts fresh — a follow-up there is new work.
+  if (!prOpen) return "new";
+  if (signal === "new-scope") return "redirect";
+  // 'change' or 'ambiguous' on an open PR → continue it.
+  return "iterate";
+}