hilos-agent 0.6.0 → 0.9.0

package/src/progress-emitter.mjs

@@ -16,16 +16,17 @@
 //   - 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";
+import { createActivityFold, 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, `agy`/`antigravity` → antigravity,
- * `hermes` → hermes, everything else → unknown. Handles an
- * absolute path (`/usr/local/bin/claude`) by taking the basename.
+ * `cursor`/`cursor-agent` → cursor, `opencode` → opencode,
+ * `agy`/`antigravity` → antigravity, `hermes` → hermes, everything else →
+ * unknown. Handles an absolute path (`/usr/local/bin/claude`) by taking the
+ * basename.
  * @param {string} codingCmd
- * @returns {'claude_code'|'codex'|'cursor'|'antigravity'|'hermes'|'unknown'}
+ * @returns {'claude_code'|'codex'|'cursor'|'opencode'|'antigravity'|'hermes'|'unknown'}
  */
 export function detectVendor(codingCmd) {
   const first = String(codingCmd || "").trim().split(/\s+/)[0] || "";
@@ -35,6 +36,8 @@ export function detectVendor(codingCmd) {
   // `agent` is Cursor's canonical binary name since Jan 2026 (the installer
   // symlinks both; `cursor-agent` remains an alias) — 0572.
   if (base === "cursor" || base === "cursor-agent" || base === "agent") return "cursor";
+  // opencode installs a single `opencode` binary (~/.opencode/bin) — 0592.
+  if (base === "opencode") return "opencode";
   if (base === "agy" || base === "antigravity") return "antigravity";
   if (base === "hermes") return "hermes";
   return "unknown";
@@ -50,15 +53,18 @@ export function detectVendor(codingCmd) {
  * --output-format text (explicit, so a CLI default change can never post raw
  * JSONL into the channel) and --trust (its Jan-2026 workspace-trust gate fails
  * headless runs at spawn in untrusted directories — 0572; pre-2026 CLIs reject
- * the flag and runCli retries without it). Returns "" for unknown (caller
- * falls back to codingCmd).
- * @param {'claude_code'|'codex'|'cursor'|'antigravity'|'hermes'|'unknown'} vendor
+ * the flag and runCli retries without it). opencode carries no flags: `opencode
+ * run` IS its non-interactive mode (plain `opencode` opens the TUI), and its
+ * model comes from the user's own provider config (0592). Returns "" for
+ * unknown (caller falls back to codingCmd).
+ * @param {'claude_code'|'codex'|'cursor'|'opencode'|'antigravity'|'hermes'|'unknown'} vendor
  * @returns {string}
  */
 export function fastChatCmd(vendor) {
   if (vendor === "claude_code") return "claude -p --model claude-haiku-4-5";
   if (vendor === "codex") return "codex exec --skip-git-repo-check";
   if (vendor === "cursor") return "cursor-agent -p --output-format text --trust";
+  if (vendor === "opencode") return "opencode run";
   if (vendor === "antigravity") return "agy -p";
   if (vendor === "hermes") return "hermes -z";
   return "";
@@ -73,15 +79,93 @@ export function fastChatCmd(vendor) {
  * cursor-agent 2026.07.23 that the LAST occurrence wins, so the code run
  * streams NDJSON while chat keeps text. codex returns [] — its stream flags
  * are deferred to 0278 rather than guessed (an unproven flag could break the run).
- * @param {'claude_code'|'codex'|'cursor'|'antigravity'|'hermes'|'unknown'} vendor
+ * opencode (0608): `--format json`. 0592 left it OFF because nothing parsed its
+ * event shape and the rawTail fallback drops JSON-looking lines; the
+ * agent-events parser now reads those events (steps, the final summary, and the
+ * `sessionID` that thread pinning needs), so it's a strict upgrade, not a
+ * liveness trade. The FAST chat path stays plain `opencode run` (prose, not NDJSON).
+ * @param {'claude_code'|'codex'|'cursor'|'opencode'|'antigravity'|'hermes'|'unknown'} vendor
  * @returns {string[]}
  */
 export function codeStreamArgs(vendor) {
   if (vendor === "claude_code") return ["--output-format", "stream-json", "--verbose"];
   if (vendor === "cursor") return ["--output-format", "stream-json"];
+  if (vendor === "opencode") return ["--format", "json"];
   return [];
 }
 
+/**
+ * The server an `opencode run --attach <url>` command targets, or null for a
+ * normal local run. Read off the TOKENIZED command (never a substring match —
+ * the prompt is a separate argv entry, but a user's own `--attach` could
+ * otherwise be faked by prompt text). Supports both `--attach <url>` and
+ * `--attach=<url>`; an `--attach` with no value still counts as attached (the
+ * mode is what matters here, not the address).
+ * @param {string} codingCmd
+ * @returns {string|null}
+ */
+export function attachTarget(codingCmd) {
+  const tokens = String(codingCmd || "").trim().split(/\s+/).filter(Boolean);
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i] === "--attach") return tokens[i + 1] && !tokens[i + 1].startsWith("-") ? tokens[i + 1] : "";
+    if (tokens[i].startsWith("--attach=")) return tokens[i].slice("--attach=".length);
+  }
+  return null;
+}
+
+/**
+ * Extra args that PIN the code run to a project directory, appended to the code
+ * run's argv when the vendor needs it. opencode only (0608): live-verified on
+ * opencode 1.18.5 that it resolves its project from the environment's `PWD`
+ * rather than from the spawned process's cwd, so a daemon launched anywhere
+ * else runs the CLI against the WRONG directory — and its sessions are scoped
+ * per project, so a `--session` created under another directory HANGS the CLI
+ * instead of erroring. `--dir <cwd>` makes the project deterministic and equal
+ * to the directory we actually run in, which is what makes thread-to-session
+ * pinning sound. Every other vendor honors cwd → [].
+ *
+ * 0615 made the spawned env's `PWD` match the cwd on every path, so this is no
+ * longer the only thing holding opencode to the right directory. It stays: it
+ * is the CLI's own explicit contract for the project (an env var is a side
+ * channel), and it keeps the attach-mode distinction below meaningful.
+ *
+ * EXCEPTION — `--attach`: when the command attaches to a running opencode
+ * server, `--dir` means "a path on the REMOTE server", so handing it our local
+ * repo path would point the run at a directory that may not exist there. An
+ * attached server owns its own project, so we send nothing and let it decide.
+ * @param {'claude_code'|'codex'|'cursor'|'opencode'|'antigravity'|'hermes'|'unknown'} vendor
+ * @param {string} cwd
+ * @param {string} [codingCmd] — the full coding command, for the --attach check
+ * @returns {string[]}
+ */
+export function codeDirArgs(vendor, cwd, codingCmd = "") {
+  if (vendor !== "opencode") return [];
+  if (attachTarget(codingCmd) !== null) return []; // remote project — not ours to set
+  if (typeof cwd !== "string" || !cwd.trim()) return [];
+  return ["--dir", cwd];
+}
+
+/**
+ * The identity of the PROJECT a captured session belongs to — recorded with the
+ * session (0608) and required to match before a resume, because an opencode
+ * `--session` from a different project hangs the CLI. Locally that identity is
+ * the directory we run in; under `--attach` the project lives on the remote
+ * server, so the identity is that server (`attach:<url>`) — two threads pointed
+ * at different servers still can't cross sessions, and switching a command from
+ * local to attached (or between servers) correctly refuses to resume.
+ * Non-opencode vendors just record the directory.
+ * @param {'claude_code'|'codex'|'cursor'|'opencode'|'antigravity'|'hermes'|'unknown'} vendor
+ * @param {string} cwd
+ * @param {string} [codingCmd]
+ * @returns {string}
+ */
+export function codeProjectKey(vendor, cwd, codingCmd = "") {
+  const dir = typeof cwd === "string" ? cwd : "";
+  if (vendor !== "opencode") return dir;
+  const attached = attachTarget(codingCmd);
+  return attached === null ? dir : `attach:${attached}`;
+}
+
 // 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.
@@ -141,6 +225,9 @@ export function createProgressEmitter({
   clearTimer = defaultClearTimer,
 } = {}) {
   const ring = createStepRing(stepLimit);
+  // The ring's richer sibling (0750): structured rows for the activity feed.
+  // Older servers drop the unknown field; newer ones render it (0537).
+  const activity = createActivityFold();
   const files = [];
   const fileSet = new Set();
   const startedAt = now();
@@ -166,6 +253,7 @@ export function createProgressEmitter({
   function fold(ev) {
     if (!ev || typeof ev !== "object") return;
     ring.push(ev); // steps[] (coalesces same-file edits + dup labels)
+    activity.push(ev); // feed rows (tense follows status; server re-validates)
     switch (ev.t) {
       case "session":
         if (ev.sessionId) sessionId = ev.sessionId;
@@ -191,6 +279,7 @@ export function createProgressEmitter({
   /**
    * The current live progress payload (also what `send` receives).
    * @returns {{ state: string, phase?: string, step?: string, steps: string[],
+   *   activity?: {kind: string, text: string, status: string, n?: number}[],
    *   filesTouched: string[], lastLine?: string, elapsedMs: number, sessionId?: string }}
    */
   function snapshot() {
@@ -203,6 +292,8 @@ export function createProgressEmitter({
     };
     if (phase) snap.phase = sanitizeText(phase);
     if (step) snap.step = sanitizeText(step);
+    const rows = activity.list();
+    if (rows.length) snap.activity = rows;
     const ll = sanitizeText(lastLine);
     if (ll) snap.lastLine = ll;
     if (sessionId) snap.sessionId = sanitizeText(sessionId); // for 0282 (server drops it today)
@@ -289,6 +380,9 @@ export function createProgressEmitter({
       }
       for (const ev of tail) fold(ev);
       state = finalState === "error" ? "error" : "done";
+      // Settle the in-flight row instead of leaving "Editing…" forever; only
+      // an error finish marks it failed (mirrors lib/hosted-progress.ts).
+      activity.settle(state === "error" ? "failed" : "done");
       if (state === "error") {
         const r = sanitizeText(reason);
         if (r) errorMessage = r;

package/src/resume.mjs

@@ -7,7 +7,8 @@
 // with full context.
 //
 // Two pieces, both PURE where it matters + node-builtins-only:
-//   1. buildResumeArgs(vendor, sessionId) — the vendor-gated `--resume` flags.
+//   1. buildResumeArgs(vendor, sessionId) — the vendor-gated resume flags
+//      (`--resume` for claude_code/cursor, `--session` for opencode — 0608).
 //   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
@@ -17,8 +18,9 @@
 //   - 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+).
+//   - We NEVER guess a vendor's resume flag. claude_code, cursor and opencode
+//     have proven ones (0282/0573/0608); codex degrades to today's
+//     branch+feedback iterate (deferred to 0278+).
 
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
@@ -32,28 +34,95 @@ export const STATE_FILE = "state.json";
  *  and a genuinely stale session can never be resurrected for a resume. */
 export const STATE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 
+/** opencode session ids are `ses_` + an opaque id (live-captured off
+ *  `opencode run --format json`, 1.18.5). The prefix is the cheap shape guard
+ *  that keeps a foreign id (a claude/cursor uuid inherited from an older state
+ *  entry) from ever reaching `--session`. */
+const OPENCODE_SESSION_RE = /^ses_[A-Za-z0-9_-]+$/;
+
 /**
- * The `--resume` flags for a coding vendor, or [] when resume isn't safe/known.
+ * The resume flags for a coding vendor, or [] when resume isn't safe/known.
  *
  * claude_code: `--resume <id>`, proven and compatible with
  * `--output-format stream-json`. cursor (0573): `--resume <chatId>` —
  * live-verified against cursor-agent 2026.07.23 that a resumed `-p` run
  * answers from the prior session's context; the id is the `session_id` its
- * stream-json init/result events carry. codex has an UNCONFIRMED resume flag,
- * so we emit NOTHING rather than guess — a wrong flag could break the run; it
- * degrades to today's branch+feedback iterate. A falsy or non-string sessionId
- * also returns [] (nothing to resume).
+ * stream-json init/result events carry. opencode (0608): `--session <ses_…>`
+ * — live-verified against opencode 1.18.5 that `opencode run -s <id> "…"`
+ * continues the pinned session non-interactively (a follow-up recalled what
+ * the first run did); the id is the `sessionID` every `--format json` event
+ * carries. Its `--fork` twin is deliberately NOT emitted: the daemon has no
+ * thread-branching semantics to map onto it today. codex has an UNCONFIRMED
+ * resume flag, so we emit NOTHING rather than guess — a wrong flag could break
+ * the run; it degrades to today's branch+feedback iterate. A falsy or
+ * non-string sessionId also returns [] (nothing to resume).
  *
- * @param {'claude_code'|'codex'|'cursor'|'hermes'|'unknown'} vendor
+ * @param {'claude_code'|'codex'|'cursor'|'opencode'|'hermes'|'unknown'} vendor
  * @param {string|null|undefined} sessionId
  * @returns {string[]}
  */
 export function buildResumeArgs(vendor, sessionId) {
-  if (vendor !== "claude_code" && vendor !== "cursor") return [];
   if (typeof sessionId !== "string" || !sessionId.trim()) return [];
+  if (vendor === "opencode") {
+    // A wrong id is not free here: an unknown id exits 1 ("Session not found"),
+    // and an id from ANOTHER project directory HANGS the CLI — so only pass a
+    // well-shaped one. The handler's project-dir gate covers the rest (0608).
+    return OPENCODE_SESSION_RE.test(sessionId.trim()) ? ["--session", sessionId.trim()] : [];
+  }
+  if (vendor !== "claude_code" && vendor !== "cursor") return [];
   return ["--resume", sessionId];
 }
 
+/** Vendors whose resume flag is proven (see buildResumeArgs). */
+const RESUMABLE_VENDORS = new Set(["claude_code", "cursor", "opencode"]);
+
+/**
+ * Should this iterate resume a recorded session? PURE — the handler passes what
+ * it read, this decides, so the whole gate is unit-testable.
+ *
+ * Confidence, in order: a resumable vendor, a LOCAL record (the proof the
+ * session lives on this machine — a providerSessionId that came only from the
+ * server likely belongs to another machine/instance), the same hostname, the
+ * same VENDOR, the same PROJECT, an id, and agreement with any server-side id.
+ * Anything short of that degrades to the branch+feedback iterate, which is only
+ * ever slower — never wrong.
+ *
+ * - vendor: an entry written by a different CLI holds a foreign id shape. Swap
+ *   `codingCmd` from opencode to claude between runs (the daemon hot-reloads
+ *   config) and a `ses_…` would reach `--resume`: a guaranteed failed
+ *   invocation. An entry written before 0608 has no vendor → degrade once, then
+ *   the next capture rewrites the entry with one.
+ * - project: opencode sessions are scoped per project, and a `--session` from
+ *   another project HANGS its CLI rather than erroring (0608). Only enforced
+ *   for opencode, whose entries carry the key; other vendors resume as before.
+ *
+ * @param {object} o
+ * @param {string} o.vendor — the CURRENT command's vendor
+ * @param {object|null} o.entry — the local state entry for this thread root
+ * @param {string|null} [o.serverSessionId] — activeRun.providerSessionId
+ * @param {string} o.machine — this hostname
+ * @param {string} [o.projectKey] — codeProjectKey() for the run we're about to do
+ * @returns {{ sessionId: string|null, reason: string }}
+ */
+export function resumeDecision({ vendor, entry, serverSessionId = null, machine, projectKey = "" }) {
+  if (!RESUMABLE_VENDORS.has(vendor)) return { sessionId: null, reason: "vendor-has-no-resume-flag" };
+  const local = entry && typeof entry === "object" ? entry : null;
+  if (!local || !local.sessionId) {
+    return { sessionId: null, reason: serverSessionId ? "no-local-record" : "nothing-recorded" };
+  }
+  if (local.machine !== machine) return { sessionId: null, reason: "recorded-on-another-machine" };
+  if (local.vendor !== vendor) {
+    return { sessionId: null, reason: local.vendor ? "recorded-by-another-vendor" : "vendor-not-recorded" };
+  }
+  if (vendor === "opencode" && local.cwd !== projectKey) {
+    return { sessionId: null, reason: local.cwd ? "recorded-in-another-project" : "project-not-recorded" };
+  }
+  if (serverSessionId && serverSessionId !== local.sessionId) {
+    return { sessionId: null, reason: "server-records-a-different-session" };
+  }
+  return { sessionId: local.sessionId, reason: "ok" };
+}
+
 // ---------------------------------------------------------------------------
 // Pure state transforms (no fs, no clock, no os — the caller injects nowMs).
 // ---------------------------------------------------------------------------
@@ -122,8 +191,12 @@ export function readStateEntry(dir, threadRoot) {
 /**
  * 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()).
+ * `entry` should carry { runId, branch, prUrl, sessionId, machine, vendor, cwd,
+ * updatedAt }; `vendor` is the CLI that created the session (an id is only valid
+ * for its own vendor) and `cwd` is the project key it belongs to — opencode
+ * sessions are scoped to a project, so its resume gate requires the match
+ * (0608). Both are read back by resumeDecision(). The prune clock derives from
+ * entry.updatedAt (falling back to the injected now()).
  *
  * @param {string} dir
  * @param {string} threadRoot

package/src/run.mjs

@@ -99,6 +99,16 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     // Semantic local-folder intent (0515): the server guarantees a forced-tool
     // ask/ship/deploy decision. Older servers fall back to the local router.
     agentIntent: toolNames.includes("classify_agent_intent"),
+    // Relaying a human's merge/close instruction (0701/0704). Both tools are
+    // required; on an older server the daemon simply never relays and behaves
+    // exactly as before. The authority is the server's either way — the daemon
+    // only passes along the id of the message that asked.
+    prActions: toolNames.includes("merge_pr") && toolNames.includes("close_pr"),
+    // Harness-enforced runtime permission bridge (0593). Both tools are
+    // required: a request without a durable reply path must fail closed.
+    runtimePermissions:
+      toolNames.includes("request_permission") &&
+      toolNames.includes("get_permission_decision"),
   };
 
   // Register local folders (0324/0325): a folder-mode daemon announces each

package/src/thread-pr.mjs

@@ -0,0 +1,305 @@
+// The thread's pull request, daemon side (0704). 0701 resolves "which PR is this
+// thread about?" once on the server and serves the answer to every substrate; the
+// daemon reads it off `list_mentions` as `message.threadPr` and uses it for two
+// decisions:
+//
+//   1. ADOPT vs FRESH — a mention in a PR thread means "continue THIS pull
+//      request": fetch its head branch, push onto it, never `git checkout -b`.
+//   2. RELAY — "merge it" / "close it" is executed through the merge_pr /
+//      close_pr MCP tools rather than answered with "a human has to click".
+//
+// Pure + dependency-free apart from followup.mjs (the ONE truth table, shared
+// with the server), so every rule below unit-tests without git, gh, or a network.
+//
+// Both decisions are deliberately conservative. The daemon is not the authority
+// on either one: the server confirms the PR is really open before an iterate can
+// land (and here `gh` does too), and `executePrAction` owns the merge/close gate
+// — it re-classifies the cited instruction with a forced-tool model call, checks
+// the author's workspace role, and refuses fail-closed. A daemon false NEGATIVE
+// costs one extra mention; a daemon false POSITIVE is still caught server-side.
+
+import { resolveFollowupMode } from "./followup.mjs";
+
+/**
+ * @typedef {Object} ThreadPrAnchor
+ * @property {string} repoFullName
+ * @property {number} prNumber
+ * @property {string} prUrl
+ * @property {string|null} state   'open' | 'merged' | 'closed' | null (unknown)
+ * @property {string|null} branch  head branch when the evidence recorded one
+ * @property {string|null} source  'run' | 'report' | 'message' | 'link'
+ */
+
+/**
+ * Sanitize the `threadPr` block off a list_mentions payload. Everything here
+ * arrives over the wire, so nothing is trusted: a malformed anchor is simply no
+ * anchor, and the daemon behaves exactly as it did before 0704.
+ * @param {any} raw
+ * @returns {ThreadPrAnchor|null}
+ */
+export function normalizeThreadPr(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const repoFullName = typeof raw.repoFullName === "string" ? raw.repoFullName.trim() : "";
+  const prUrl = typeof raw.prUrl === "string" ? raw.prUrl.trim() : "";
+  const prNumber = Number(raw.prNumber);
+  if (!repoFullName || !prUrl) return null;
+  if (!Number.isInteger(prNumber) || prNumber <= 0) return null;
+  const state = typeof raw.state === "string" && raw.state.trim() ? raw.state.trim().toLowerCase() : null;
+  const branch = typeof raw.branch === "string" && raw.branch.trim() ? raw.branch.trim() : null;
+  const source = typeof raw.source === "string" && raw.source.trim() ? raw.source.trim() : null;
+  return { repoFullName, prNumber, prUrl, state, branch, source };
+}
+
+/** Case-insensitive `owner/repo` equality — GitHub is case-insensitive on both. */
+function sameRepo(a, b) {
+  return String(a || "").toLowerCase() === String(b || "").toLowerCase();
+}
+
+/**
+ * Should this mention adopt the thread's pull request instead of cutting a new
+ * branch? Mirrors the server's thread-anchor fallback in app/api/agent/route.ts
+ * signal for signal:
+ *
+ *   - Only THREAD-LOCAL evidence may direct code onto a PR. A 'link' anchor is
+ *     channel-wide — it would route an unrelated thread's work onto whatever PR
+ *     the room happens to have linked.
+ *   - The anchor must live in the repo this channel clones. A pasted cross-repo
+ *     PR is context for chat and review, never an iterate target: the daemon
+ *     would push a same-named branch into the wrong repository.
+ *   - A known-terminal anchor (merged/closed) never adopts. Unknown state is
+ *     only a hypothesis — `gh` proves it before anything is checked out
+ *     (see confirmAnchorOpen).
+ *   - The shared truth table decides intent: an explicit "in a separate PR"
+ *     forks even inside a PR thread.
+ *
+ * @param {{ threadPr: any, repoFullName: string, signal: string|null|undefined }} o
+ * @returns {{ adopt: boolean, reason: string, anchor: ThreadPrAnchor|null }}
+ */
+export function anchorIterateDecision({ threadPr, repoFullName, signal } = {}) {
+  const anchor = normalizeThreadPr(threadPr);
+  if (!anchor) return { adopt: false, reason: "no-anchor", anchor: null };
+  if (anchor.source === "link") return { adopt: false, reason: "link-anchor", anchor };
+  if (!sameRepo(anchor.repoFullName, repoFullName)) {
+    return { adopt: false, reason: "other-repo", anchor };
+  }
+  if (anchor.state === "merged" || anchor.state === "closed") {
+    return { adopt: false, reason: `anchor-${anchor.state}`, anchor };
+  }
+  // prOpen:true is the hypothesis this function is allowed to make (the terminal
+  // states are already out); hasActiveRun:true says "this thread owns work" —
+  // the anchor IS that work, whether or not a run row survived.
+  const mode = resolveFollowupMode({
+    hasActiveRun: true,
+    prOpen: true,
+    signal: signal || "ambiguous",
+  });
+  if (mode !== "iterate") return { adopt: false, reason: "new-scope", anchor };
+  return { adopt: true, reason: "adopt", anchor };
+}
+
+/**
+ * The staleness guard. `live` is what `gh pr view --json state,headRefName,…`
+ * reported for the anchor; this decides whether the daemon may check that branch
+ * out and push to it. Same shape as the server's confirmOpenPr: open, with a head
+ * branch, living in the base repo (a fork head is another repository's branch —
+ * pushing "to it" would touch an unrelated same-named branch here).
+ *
+ * No proof, no adoption: an unreachable `gh` returns null and the run starts a
+ * fresh branch rather than gambling on a possibly-merged PR.
+ *
+ * @param {{ live: any, anchor: ThreadPrAnchor }} o
+ * @returns {{ ok: boolean, branch: string|null, reason: string }}
+ */
+export function confirmAnchorOpen({ live, anchor } = {}) {
+  if (!anchor) return { ok: false, branch: null, reason: "no-anchor" };
+  if (!live || typeof live !== "object") return { ok: false, branch: null, reason: "unverified" };
+  const state = typeof live.state === "string" ? live.state.trim().toLowerCase() : "";
+  if (state === "merged" || state === "closed") return { ok: false, branch: null, reason: state };
+  if (state !== "open") return { ok: false, branch: null, reason: "unverified" };
+  const headRepo = typeof live.headRepoFullName === "string" ? live.headRepoFullName : null;
+  if (headRepo && !sameRepo(headRepo, anchor.repoFullName)) {
+    return { ok: false, branch: null, reason: "fork-head" };
+  }
+  const branch = typeof live.headRefName === "string" && live.headRefName.trim() ? live.headRefName.trim() : null;
+  if (!branch) return { ok: false, branch: null, reason: "unverified" };
+  return { ok: true, branch, reason: "open" };
+}
+
+/**
+ * One line for the run's status card when an intended adoption did NOT happen —
+ * the person asked inside a PR thread, so silence would read as "it's pushing to
+ * my PR" while a fresh branch is being cut. Returns "" when there is nothing to
+ * confess (the reasons that are simply "this isn't an iterate").
+ * @param {{ reason: string, anchor: ThreadPrAnchor|null }} o
+ */
+export function staleAnchorNote({ reason, anchor } = {}) {
+  if (!anchor) return "";
+  const pr = `PR #${anchor.prNumber}`;
+  if (reason === "merged" || reason === "anchor-merged") {
+    return `${pr} is already merged, so this goes on a new branch instead.`;
+  }
+  if (reason === "closed" || reason === "anchor-closed") {
+    return `${pr} is closed, so this goes on a new branch instead.`;
+  }
+  if (reason === "fork-head") {
+    return `${pr} is from a fork, so I can't push to its branch — this goes on a new branch instead.`;
+  }
+  if (reason === "unverified") {
+    return `I couldn't confirm ${pr} is still open, so this goes on a new branch instead.`;
+  }
+  if (reason === "checkout-failed") {
+    return `I couldn't check out ${pr}'s branch, so this goes on a new branch instead.`;
+  }
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// Merge / close cue classification
+// ---------------------------------------------------------------------------
+//
+// The server's own merge/close intent is an LLM call (decideAgentIntent with
+// allowPrActions). The daemon cannot reach it: the MCP `classify_agent_intent`
+// tool exposes ask/ship/deploy only — it never offers review/merge/close — so
+// there is no shared classifier to import here. Per 0704 this is therefore a
+// deliberately narrow phrase matcher over explicit instructions, and it is a
+// TRIGGER, not an authority: every match is handed to merge_pr / close_pr, where
+// the server re-classifies the cited human message with a forced-tool model call
+// before it spends the App's write token.
+//
+// Bias: miss rather than guess. A missed cue costs one clearer sentence.
+
+/** The pronouns/nouns an instruction can name the PR with. */
+const OBJECT = String.raw`(?:it|this|that|them|the\s+pr|this\s+pr|that\s+pr|the\s+pull\s+request|this\s+pull\s+request|that\s+pull\s+request|it\s+in|this\s+one|that\s+one|el\s+pr|la\s+pr)`;
+const PR_REF = String.raw`(?:#\d{1,6}|https?:\/\/\S*\/pull\/\d{1,6})`;
+
+const MERGE_PATTERNS = [
+  new RegExp(String.raw`\bmerge\s+${OBJECT}\b`, "i"),
+  new RegExp(String.raw`\bmerge\s+${PR_REF}`, "i"),
+  // "land it" is unambiguous for a pull request. "ship it" is NOT — it is also
+  // the daemon's own word for "go do the work", so it stays out of this list.
+  new RegExp(String.raw`\bland\s+${OBJECT}\b`, "i"),
+  /\bmerge\s+away\b/i,
+  // Spanish / Portuguese imperatives, matching the multi-language spirit of the
+  // follow-up cue lists.
+  /\b(?:mergea(?:lo|la)?|merg[eé]alo|haz\s+merge|fusiona(?:lo|la)?|fusi[oó]nal[oa])\b/i,
+];
+
+const CLOSE_PATTERNS = [
+  new RegExp(String.raw`\bclose\s+${OBJECT}\b`, "i"),
+  new RegExp(String.raw`\bclose\s+${PR_REF}`, "i"),
+  new RegExp(String.raw`\b(?:abandon|discard|scrap)\s+${OBJECT}\b`, "i"),
+  /\b(?:cierra(?:lo|la)?|ci[eé]rral[oa]|descarta(?:lo|la)?|desc[aá]rtal[oa])\b/i,
+];
+
+/** A sentence that says the opposite, defers, or hypothesizes is not an
+ *  instruction. Checked against the sentence the cue appeared in. */
+const DISQUALIFIERS = [
+  // Negation and deferral.
+  /\b(?:don'?t|do\s+not|dont|never|no\s+need|hold\s+off|not\s+yet|wait|hang\s+on|instead\s+of)\b/i,
+  /\bno\s+(?:lo|la|le)\b/i,
+  /\b(?:todav[ií]a|a[uú]n)\s+no\b/i,
+  // Conditional / sequenced — "once CI passes, merge it" is a plan, not a go.
+  /\b(?:if|once|when|after|before|unless|until|assuming|in\s+case|whenever)\b/i,
+  /\b(?:si|cuando|despu[eé]s|antes)\b/i,
+  // Someone else is doing it.
+  /\b(?:i|we)(?:'|’)?(?:ll|\s+will|\s+am\s+going\s+to|\s+can|\s+should)\s+(?:merge|close)\b/i,
+  /\b(?:i|we)\s+(?:just\s+)?(?:merged|closed)\b/i,
+  // Vocabulary that contains the verb but means something else entirely.
+  /\bmerge\s+(?:conflict|commit|base|queue|strategy)/i,
+  /\bclose\s+(?:call|enough|to)\b/i,
+  /\b(?:already|just)\s+(?:merged|closed)\b/i,
+];
+
+/** Politeness markers that keep a question-shaped sentence an instruction. */
+const POLITE_REQUEST = /\b(?:can\s+you|could\s+you|would\s+you|will\s+you|please|puedes|podr[ií]as|por\s+favor)\b/i;
+
+/** Strip `@handle` mentions so "@scout merge it" reads as "merge it". */
+function stripMentions(text) {
+  return String(text || "").replace(/(^|\s)@[a-z0-9][a-z0-9._-]*/gi, " ");
+}
+
+/** Sentences, roughly. Newlines end a sentence too — chat rarely punctuates. */
+function sentences(text) {
+  return text
+    .split(/(?<=[.!?…])\s+|\n+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function isInstruction(sentence) {
+  if (DISQUALIFIERS.some((re) => re.test(sentence))) return false;
+  // A question is a question ("should we merge it?") unless it's the polite
+  // shape of an order ("can you merge it?").
+  if (/\?\s*$/.test(sentence) && !POLITE_REQUEST.test(sentence)) return false;
+  return true;
+}
+
+/**
+ * Does this message explicitly instruct a merge or a close of the thread's PR?
+ * Returns 'merge', 'close', or null. A message that appears to ask for both gets
+ * null — an ambiguous instruction is not one.
+ * @param {string} text
+ * @returns {'merge'|'close'|null}
+ */
+export function classifyPrActionCue(text) {
+  const body = stripMentions(text);
+  if (!body.trim()) return null;
+  let merge = false;
+  let close = false;
+  for (const sentence of sentences(body)) {
+    if (!isInstruction(sentence)) continue;
+    if (MERGE_PATTERNS.some((re) => re.test(sentence))) merge = true;
+    if (CLOSE_PATTERNS.some((re) => re.test(sentence))) close = true;
+  }
+  if (merge && close) return null;
+  if (merge) return "merge";
+  if (close) return "close";
+  return null;
+}
+
+/**
+ * Should this mention be relayed to merge_pr / close_pr instead of routed as
+ * chat or code? Every "no" is a fall-through to today's behavior — the relay
+ * only ever ADDS a path.
+ *
+ * Requires an anchor: without one the daemon has no idea which PR "it" is, and
+ * guessing is exactly the failure 0701 exists to prevent. It deliberately does
+ * NOT check whether the anchor is in this channel's repo, whether the asker is
+ * allowed, or whether the message names a different PR — those are the server's
+ * calls, and its refusals are better written than anything decided here.
+ *
+ * @param {{ body: string, threadPr: any, mode: string|null, canRelay: boolean }} o
+ * @returns {{ relay: boolean, action: 'merge'|'close'|null, reason: string, anchor: ThreadPrAnchor|null }}
+ */
+export function prActionRelayDecision({ body, threadPr, mode, canRelay } = {}) {
+  const anchor = normalizeThreadPr(threadPr);
+  const action = classifyPrActionCue(body);
+  if (!action) return { relay: false, action: null, reason: "no-cue", anchor };
+  // Chat only is the human saying this agent does not act here (the server
+  // refuses PR actions the same way when mayExecute is false).
+  if (mode === "ask") return { relay: false, action, reason: "chat-only", anchor };
+  if (!canRelay) return { relay: false, action, reason: "no-tool", anchor };
+  if (!anchor) return { relay: false, action, reason: "no-anchor", anchor };
+  return { relay: true, action, reason: "relay", anchor };
+}
+
+/**
+ * What to say after a relay. The server posts the outcome of every executed
+ * action AND every refusal that reached executePrAction (its `message`), so
+ * repeating it would double-post in the thread. Only the tool-level refusals —
+ * which come back as `error` and are posted by nobody — need a message from the
+ * daemon, and they are surfaced verbatim: the server's wording is the authority.
+ * @param {any} result the parsed merge_pr / close_pr tool result
+ * @returns {{ post: string|null, ok: boolean, alreadyPosted: boolean }}
+ */
+export function prActionReply(result) {
+  if (!result || typeof result !== "object") {
+    return { post: null, ok: false, alreadyPosted: false };
+  }
+  if (result.ok === false && typeof result.error === "string" && result.error.trim()) {
+    return { post: result.error, ok: false, alreadyPosted: false };
+  }
+  // ok:true, or an executePrAction refusal — either way it already spoke in the
+  // thread with its own words.
+  return { post: null, ok: result.ok === true, alreadyPosted: true };
+}