hilos-agent 0.1.14 → 0.1.16

package/src/handler.mjs

@@ -9,7 +9,8 @@
 
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { rmSync } from "node:fs";
+import { rmSync, mkdtempSync } from "node:fs";
+import { hostname, tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   branchSlug,
@@ -21,8 +22,57 @@ import {
   commitMessage,
   prTitleBody,
   mentionHandle,
+  detectPrContinuation,
 } from "./daemon.mjs";
 import { runCli, buildHeartbeat, ackText, oneLine } from "./cli.mjs";
+import { makeStreamParser } from "./agent-events.mjs";
+import { detectVendor, codeStreamArgs, createProgressEmitter } from "./progress-emitter.mjs";
+import { resolveFollowupMode, classifyFollowupCue, normalizeSignal } from "./followup.mjs";
+import { buildResumeArgs, readStateEntry, writeState, HILOS_DIR } from "./resume.mjs";
+import {
+  buildReviewPrompt,
+  parseReviewOutput,
+  reviewDedupeKey,
+  shouldReview,
+} from "./review.mjs";
+import { buildMemoryBlock } from "./memory.mjs";
+
+/** PR number from a github pull-request URL, or null. */
+function prNumberFromUrl(url) {
+  const m = /\/pull\/(\d+)/.exec(String(url || ""));
+  return m ? Number(m[1]) : null;
+}
+
+// How many times ONE reviewer will review the SAME PR before it stops — the
+// ping-pong bound. Keyed by reviewDedupeKey(prUrl, reviewerId), counted in-process
+// on the long-lived daemon so an author<->reviewer pair can't loop forever. A
+// human re-triggering the review is the escape hatch past the cap.
+const reviewRounds = new Map();
+
+
+// Sentinel the router model emits (only when a thread already owns a run) to
+// classify a follow-up: change | new-scope | ambiguous. Parsed out of the router
+// output and stripped from the coding brief.
+const FOLLOWUP_SIGNAL = "__FOLLOWUP__";
+
+/** Pull the follow-up classification out of the router's output and strip the
+ *  token from the text, so the signal never leaks into the coding brief / a chat
+ *  reply. Returns { followupSignal, stripped }.
+ *
+ *  Strip ONLY the `__FOLLOWUP__ <value>` token (plus any surrounding whitespace),
+ *  NOT the whole line: if the model ever emits `__CODE__` and `__FOLLOWUP__` on the
+ *  SAME line, removing the line would drop `__CODE__` too and misroute a real code
+ *  run into a chat reply. Removing just the token preserves `__CODE__` while still
+ *  keeping the signal out of the brief. */
+export function extractFollowup(text) {
+  const m = /__FOLLOWUP__[:\s]+([a-z][a-z-]*)/i.exec(text);
+  const followupSignal = m ? normalizeSignal(m[1]) : null;
+  const stripped = text
+    .replace(/\s*__FOLLOWUP__(?:[:\s]+[a-z][a-z-]*)?/gi, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+  return { followupSignal, stripped };
+}
 
 /** `@handle` for the person who asked, so the report tags them. */
 function requesterTag(author) {
@@ -54,6 +104,18 @@ function defaultDeps() {
       const url = (r.stdout || "").trim();
       return r.status === 0 && url ? url : null;
     },
+    // The head branch of an existing PR (by URL or number), so a "request
+    // changes" rework can check it out and update the SAME PR rather than
+    // opening a duplicate.
+    prHeadRef: (cwd, ref) => {
+      const r = spawnSync(
+        "gh",
+        ["pr", "view", String(ref), "--json", "headRefName", "--jq", ".headRefName // empty"],
+        { cwd, encoding: "utf8" },
+      );
+      const out = (r.stdout || "").trim();
+      return r.status === 0 && out ? out : null;
+    },
     sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
     now: () => Date.now(),
   };
@@ -101,15 +163,19 @@ async function linkPrFromUrl({ tool, channelId, url }) {
   await tool("link_pr", { channelId, repoFullName: m[1], prNumber: Number(m[2]) }).catch(() => {});
 }
 
-async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId }) {
+async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, existingPrUrl, settleId, runId }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
+  // `parentId` here is the run's thread root: every outcome below is terminal, so
+  // it broadcasts back to the channel (visible in both thread and channel) — the
+  // hosted runner's reply_broadcast. A no-op when there's no thread root.
   if (decision.kind === "approved") {
     // Guard: nothing staged → don't push an empty branch and falsely report "shipped".
     if (deps.git(repoPath, ["diff", "--cached", "--quiet"]).status === 0) {
       await tool("post_message", {
         channelId,
         parentId,
+        broadcast: true,
         body: `Approved, but there are no staged changes to commit on \`${branch}\`.`,
       });
       return { status: "nothing-staged", branch };
@@ -119,6 +185,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       await tool("post_message", {
         channelId,
         parentId,
+        broadcast: true,
         body: `Approved, but the commit failed: ${(commit.stderr || "").trim().slice(0, 300)}`,
       });
       return { status: "commit-failed", branch };
@@ -128,25 +195,53 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       await tool("post_message", {
         channelId,
         parentId,
+        broadcast: true,
         body: `Approved, but the push failed: ${(push.stderr || "").trim().slice(0, 300)}`,
       });
       return { status: "push-failed", branch };
     }
     const { title, body } = prTitleBody(task, branch);
-    const pr = deps.openPR(repoPath, { title, body, branch, base: cfg.defaultBranch });
-    await tool("post_report", {
+    // Continuing an existing PR (request-changes rework): the push already
+    // updated it — reuse its URL instead of opening a duplicate. Otherwise open
+    // a fresh PR.
+    const pr = existingPrUrl
+      ? { ok: true, url: existingPrUrl }
+      : deps.openPR(repoPath, { title, body, branch, base: cfg.defaultBranch });
+    // Seamless single card (0289): when a live status message was streaming this
+    // run, SETTLE the report onto it in place (broadcast keeps it channel-visible)
+    // so the one card cross-fades from live run → report — no separate progress
+    // message + separate report card. Without a status id (older server / status
+    // post failed) fall back to posting a fresh broadcast report as before.
+    const reportArgs = {
       channelId,
-      parentId,
       title: `Shipped: ${title}`,
       summary:
         pr.ok && pr.url
-          ? `${lead}pushed \`${branch}\` and opened a pull request.`
+          ? existingPrUrl
+            ? `${lead}pushed an update to \`${branch}\` and updated the pull request.`
+            : `${lead}pushed \`${branch}\` and opened a pull request.`
           : `${lead}pushed \`${branch}\`. Open a PR manually — \`gh\` failed.`,
       prUrl: pr.ok && pr.url ? pr.url : undefined,
       caveats: pr.ok ? [] : [`gh pr create failed: ${(pr.stderr || "").trim().slice(0, 200)}`],
-    });
+    };
+    await tool(
+      "post_report",
+      settleId
+        ? { ...reportArgs, messageId: settleId, broadcast: true }
+        : { ...reportArgs, parentId, broadcast: true },
+    );
     // Work produced a PR → attach it to the channel so its live pill shows up.
     await linkPrFromUrl({ tool, channelId, url: pr.ok ? pr.url : null });
+    // Bind the PR to the thread's run (0279/0280) so a follow-up continues it.
+    // Best-effort; only when a run was recorded (caps.runs on this server).
+    if (runId) {
+      await tool("update_run", {
+        runId,
+        ...(pr.ok && pr.url ? { prUrl: pr.url } : {}),
+        status: "awaiting_review",
+        ...(settleId ? { reportMsgId: settleId } : {}),
+      }).catch(() => {});
+    }
     return { status: "pushed", branch, prUrl: pr.ok ? pr.url : null };
   }
 
@@ -155,7 +250,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     deps.git(repoPath, ["clean", "-fd"]);
     deps.git(repoPath, ["switch", "-"]);
     deps.git(repoPath, ["branch", "-D", branch]);
-    await tool("post_message", { channelId, parentId, body: `Rejected — discarded \`${branch}\`.` });
+    await tool("post_message", { channelId, parentId, broadcast: true, body: `Rejected — discarded \`${branch}\`.` });
     return { status: "discarded", branch };
   }
 
@@ -163,6 +258,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     await tool("post_message", {
       channelId,
       parentId,
+      broadcast: true,
       body: `Got it${decision.note ? `: ${decision.note}` : ""}. Leaving \`${branch}\` for a follow-up.`,
     });
     return { status: "changes", branch, note: decision.note };
@@ -171,6 +267,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
   await tool("post_message", {
     channelId,
     parentId,
+    broadcast: true,
     body: `Still awaiting review on \`${branch}\`. Re-mention me once you've decided.`,
   });
   return { status: "timeout", branch };
@@ -183,7 +280,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
  * push the branch it's on (no-op if already pushed), reuse the PR it opened or
  * open one, and report it. Used only when NOT gated (bias-to-action).
  */
-async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId }) {
+async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, settleId, runId }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
   // The agent may have committed on the daemon's branch or switched to one of its
@@ -198,9 +295,11 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
     prUrl = pr.ok && pr.url ? pr.url : null;
   }
   const { title } = prTitleBody(task, cur);
-  await tool("post_report", {
+  // Seamless single card (0289): settle onto the live status message when one was
+  // streaming this run (broadcast keeps it channel-visible); otherwise a fresh
+  // broadcast report, exactly as before.
+  const reportArgs = {
     channelId,
-    parentId,
     title: `Shipped: ${title}`,
     summary: prUrl
       ? `${lead}the coding agent committed on \`${cur}\` and opened a pull request.`
@@ -209,8 +308,23 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
         : `${lead}the coding agent committed on \`${cur}\` locally, but pushing it failed.`,
     prUrl: prUrl || undefined,
     caveats: push.status === 0 ? [] : [`git push failed: ${(push.stderr || "").trim().slice(0, 200)}`],
-  });
+  };
+  await tool(
+    "post_report",
+    settleId
+      ? { ...reportArgs, messageId: settleId, broadcast: true }
+      : { ...reportArgs, parentId, broadcast: true },
+  );
   if (prUrl) await linkPrFromUrl({ tool, channelId, url: prUrl });
+  // Bind the PR to the thread's run (0279/0280). Best-effort; only when recorded.
+  if (runId) {
+    await tool("update_run", {
+      runId,
+      ...(prUrl ? { prUrl } : {}),
+      status: "awaiting_review",
+      ...(settleId ? { reportMsgId: settleId } : {}),
+    }).catch(() => {});
+  }
   return { status: push.status === 0 ? "pushed" : "commit-local", branch: cur, prUrl };
 }
 
@@ -238,9 +352,23 @@ const CODE_SIGNAL = "__CODE__";
  * `error` is set when the model produced nothing (so the caller can be honest
  * about a timeout vs a missing binary instead of inventing a reply).
  */
-async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal }) {
+async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal, hasActiveRun = false }) {
   const cmd = cfg.chatCmd || cfg.codingCmd;
   const parts = cmd.split(" ").filter(Boolean);
+  // When this thread already owns an OPEN pull request (a follow-up reply), the
+  // router ALSO reads whether the latest message continues that PR, wants a
+  // separate one, or is unclear — the primary signal for same-PR continuation
+  // (0281). resolveFollowupMode turns it into iterate/redirect/new; the cue list
+  // in followup.mjs is only the fallback when the model says nothing.
+  const followupBlock = hasActiveRun
+    ? `\n\nThis message is a reply in a thread that ALREADY owns an OPEN pull request. If (and ` +
+      `only if) you emitted ${CODE_SIGNAL} above, ALSO output on its OWN line the token ` +
+      `${FOLLOWUP_SIGNAL} followed by exactly one of: change | new-scope | ambiguous — ` +
+      `"change" if the latest message continues or adjusts THAT pull request's work ("also make ` +
+      `it blue", "actually revert that", "tweak the copy"), "new-scope" if it EXPLICITLY asks for ` +
+      `a separate or new pull request, "ambiguous" otherwise. Default a plain follow-up to ` +
+      `"change". This line is metadata — keep it OUT of the imperative spec.`
+    : "";
   const prompt =
     `You are ${name}, a teammate in a team chat (hilos) connected to the git repository ` +
     `${repoFullName}. Read the conversation and judge what the LATEST message wants from you.\n\n` +
@@ -253,7 +381,8 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     `that lists who reacted with each emoji.\n\n` +
     `Otherwise — a question, a greeting, general discussion, or they explicitly don't want code ` +
     `yet — just reply to them concisely and directly as a single chat message (no preamble, no ` +
-    `headings). When unsure, prefer to act (${CODE_SIGNAL}); this is a build channel.\n\n` +
+    `headings). When unsure, prefer to act (${CODE_SIGNAL}); this is a build channel.` +
+    `${followupBlock}\n\n` +
     `You are only routing here — output ONLY your text response. Do NOT use any tools, do NOT ` +
     `edit files, do NOT run commands; a separate step does the actual coding.\n\n` +
     `${memoryPreamble(workspaceMemory)}Conversation so far:\n${transcript}`;
@@ -265,8 +394,14 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     signal,
   });
   if (run.aborted || signal?.aborted) return { aborted: true };
-  const out = (run.stdout || "").trim();
-  if (!out) return { code: false, reply: null, error: run.error || new Error("no output") };
+  const raw = (run.stdout || "").trim();
+  if (!raw) return { code: false, reply: null, error: run.error || new Error("no output") };
+  // Lift the follow-up classification out (and strip its line) before parsing the
+  // brief, so the signal never pollutes the coding spec or a chat reply. Only
+  // meaningful when a run is active; otherwise there's no token to find.
+  const { followupSignal, stripped: out } = hasActiveRun
+    ? extractFollowup(raw)
+    : { followupSignal: null, stripped: raw };
   // Accept the sentinel ANYWHERE, not just the first line — models sometimes add a
   // line of preamble before it ("Got it, …\n__CODE__\n<brief>"). If it appears,
   // it's a code run; the brief is whatever follows the sentinel's line and any
@@ -276,9 +411,9 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
   if (idx >= 0) {
     const after = out.slice(idx + CODE_SIGNAL.length);
     const nl = after.indexOf("\n");
-    return { code: true, task: (nl >= 0 ? after.slice(nl + 1) : after).trim() };
+    return { code: true, task: (nl >= 0 ? after.slice(nl + 1) : after).trim(), followupSignal };
   }
-  return { code: false, reply: out };
+  return { code: false, reply: out, followupSignal };
 }
 
 /**
@@ -485,6 +620,200 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   await deliver(body);
 }
 
+/** True when this mention is a request for THIS agent to review a PR (0286/0288). */
+export function isReviewRequest(message) {
+  return (
+    message?.kind === "review-request" ||
+    Boolean(message?.metadata?.reviewRequest) ||
+    Boolean(message?.reviewRequest)
+  );
+}
+
+/** The PR url a review-request/review points at, from the mention's reviewOf or the
+ *  channel's linked PR — whichever is present. */
+function reviewTargetPrUrl(message) {
+  return message?.reviewOf?.prUrl || message?.pr?.url || null;
+}
+
+/** Flatten get_reviews output into a compact, task-ready findings list the author's
+ *  coding agent can act on (the review MESSAGE body only carries the summary). Uses
+ *  the MOST RECENT review so a re-review supersedes stale findings. Returns "" when
+ *  there's nothing structured to add. */
+export function formatReviewFindings(got) {
+  const reviews = Array.isArray(got?.reviews) ? got.reviews : [];
+  if (!reviews.length) return "";
+  const latest = reviews[reviews.length - 1]; // get_reviews returns oldest→newest
+  const lines = [];
+  if (latest.summary) lines.push(latest.summary.trim());
+  for (const f of Array.isArray(latest.findings) ? latest.findings : []) {
+    if (!f || !f.note) continue;
+    const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""} — ` : "";
+    lines.push(`- [${f.severity || "info"}] ${loc}${f.note}`);
+  }
+  return lines.join("\n").slice(0, 4000);
+}
+
+/**
+ * EXECUTE a cross-agent review (WS3, 0288). A review-request lands in this agent's
+ * mentions; here it actually reads the PR's diff and posts an ADVISORY review that
+ * @-tags the author. It is strictly READ-ONLY and never touches git:
+ *   - the full diff comes from get_pr_diff (no checkout needed),
+ *   - the CLI runs in a throwaway temp dir so any stray file write is contained and
+ *     discarded (belt-and-suspenders with the prompt's edit/git ban), and
+ *   - this function ONLY calls post_review — never post_report, a decision, a
+ *     branch, a commit, a push, or a PR. The human stays the sole merge gate.
+ * Best-effort: any failure posts an honest note and returns; it never throws into
+ * the poll loop. Bounded by shouldReview()/reviewRounds so a reviewer can't
+ * re-review the same PR endlessly (the ping-pong bound).
+ */
+async function reviewTask({ message, channelId, tool, me, cfg, workspaceMemory, context, signal }) {
+  const parentId = message.parentId ?? null;
+  const prUrl = reviewTargetPrUrl(message);
+  const reviewOf =
+    message?.reviewOf && (message.reviewOf.prUrl || message.reviewOf.messageId)
+      ? message.reviewOf
+      : prUrl
+        ? { prUrl }
+        : null;
+  if (!prUrl || !reviewOf) {
+    await tool("post_message", {
+      channelId,
+      parentId,
+      body: `I was asked to review, but I couldn't find which PR — link the PR (or ask again with its URL) and I'll take a look.`,
+    }).catch(() => {});
+    return { status: "review-no-pr" };
+  }
+
+  // Ping-pong bound: don't re-review the same PR past the round cap.
+  const reviewerId = me?.agentId || me?.id || me?.agentName || "reviewer";
+  const key = reviewDedupeKey(prUrl, reviewerId);
+  const rounds = reviewRounds.get(key) || 0;
+  const maxRounds = cfg.maxRounds || 3;
+  if (!shouldReview({ rounds, maxRounds })) {
+    await tool("post_message", {
+      channelId,
+      parentId,
+      body: `I've already reviewed this PR ${rounds} time(s) — I'll leave it to a human from here so we don't loop.`,
+    }).catch(() => {});
+    return { status: "review-capped", rounds };
+  }
+
+  const prNum = prNumberFromUrl(prUrl);
+  const label = prNum ? `PR #${prNum}` : "the PR";
+  // Instant, channel-visible ack; anchors the thread for the review card.
+  const ack = await tool("post_message", {
+    channelId,
+    parentId,
+    body: `Reviewing ${label} now — I'll post my read shortly.`,
+  }).catch(() => null);
+  const threadRoot = parentId ?? ack?.messageId ?? null;
+
+  // The diff — the whole review is fed off this (no clone, no gh creds).
+  // Capture the failure reason on BOTH error shapes: a soft failure returns
+  // { ok:false, error } (auth/no-token/fetch), a hard failure throws and we map its
+  // message here — so the honest note below can say WHY, not just that it couldn't.
+  const diff = await tool("get_pr_diff", { prUrl, channelId }).catch((e) => ({ ok: false, error: e?.message }));
+  if (!diff || diff.ok === false || !Array.isArray(diff.files) || diff.files.length === 0) {
+    const reason = diff?.error || diff?.message;
+    const why = reason ? ` (${reason})` : "";
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body: `I couldn't read ${label}'s diff to review it${why}. It may be private, merged, or not linked here.`,
+    }).catch(() => {});
+    return { status: "review-no-diff" };
+  }
+
+  // The author's own summary (when the request pointed at their report message) —
+  // extra intent for the reviewer. Best-effort.
+  let reportSummary = null;
+  if (reviewOf.messageId) {
+    const gr = await tool("get_report", { messageId: reviewOf.messageId }).catch(() => null);
+    if (gr?.found && gr.report?.summary) reportSummary = gr.report.summary;
+  }
+
+  const prompt = buildReviewPrompt({
+    diffFiles: diff.files,
+    task: message.body,
+    reportSummary,
+    threadContext: context?.transcript,
+    workspaceMemory,
+  });
+
+  // Read-only run: a throwaway cwd contains any stray write; the daemon reads ONLY
+  // stdout and never stages/commits anything. Review uses the fast chat command
+  // when set (no acceptEdits → can't write), falling back to the coding command.
+  const cmd = cfg.reviewCmd || cfg.chatCmd || cfg.codingCmd;
+  const parts = String(cmd).split(" ").filter(Boolean);
+  let sandboxDir = null;
+  try {
+    sandboxDir = mkdtempSync(join(tmpdir(), "hilos-review-"));
+  } catch {
+    sandboxDir = undefined; // fall back to the daemon's cwd; the prompt still bans edits
+  }
+  console.log(`  review → running \`${cmd}\` on ${label} (read-only)…`);
+  const run = await runCli({
+    cmd: parts[0],
+    args: [...parts.slice(1), prompt],
+    cwd: sandboxDir || undefined,
+    timeoutMs: cfg.chatTimeoutMs ? Math.max(cfg.chatTimeoutMs, 120000) : cfg.runTimeoutMs,
+    label: "reviewing",
+    signal,
+  });
+  if (sandboxDir) {
+    try {
+      rmSync(sandboxDir, { recursive: true, force: true });
+    } catch {
+      /* temp dir cleanup is best-effort */
+    }
+  }
+
+  if (run.aborted || signal?.aborted) {
+    await tool("post_message", { channelId, parentId: threadRoot, body: `Stopped the review of ${label}.` }).catch(() => {});
+    return { status: "review-cancelled" };
+  }
+  const text = (run.stdout || "").trim();
+  if (!text) {
+    const enoent = run.error?.code === "ENOENT";
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body: enoent
+        ? `I couldn't start \`${cmd}\` to review ${label} — is it installed and on PATH?`
+        : `I couldn't get a read on ${label} that time — mention me again to retry the review.`,
+    }).catch(() => {});
+    return { status: "review-no-output" };
+  }
+
+  const { verdict, summary, findings } = parseReviewOutput(text);
+  // Advisory ONLY — post_review records a verdict + findings and @-tags the author.
+  // It NEVER merges, blocks, or writes a decision. The server rejects a self-review,
+  // so an agent reviewing its own PR degrades to an honest note here.
+  const posted = await tool("post_review", {
+    channelId,
+    reviewOf,
+    verdict,
+    summary: summary || `Reviewed ${label}.`,
+    findings,
+    parentId: threadRoot || undefined,
+    broadcast: Boolean(threadRoot),
+  }).catch((e) => ({ ok: false, error: e?.message }));
+  if (posted?.ok === false) {
+    // Most common: "You can't review your own work." — surface honestly, no crash.
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      body: `I looked at ${label} but couldn't post the review${posted?.error || posted?.message ? `: ${posted.error || posted.message}` : ""}.`,
+    }).catch(() => {});
+    return { status: "review-post-failed", error: posted?.error || posted?.message };
+  }
+  reviewRounds.set(key, rounds + 1);
+  console.log(`  review → posted ${verdict} on ${label} (${findings.length} finding(s))`);
+  return { status: "reviewed", verdict, findings: findings.length, prUrl };
+}
+
 /** Handle one task. cfg/deps injectable for tests. `opts.signal` (AbortSignal)
  *  cancels an in-flight run — the queue fires it when a human says "stop". */
 export async function handleTask({ message, channelId, tool, me, caps = {} }, cfg, depsOverride, opts = {}) {
@@ -506,6 +835,34 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // just said.
   const context = await fetchContext({ channelId, tool, parentId });
 
+  // REVIEW EXECUTION (0288): a review-request routes to the read-only reviewer
+  // BEFORE the chat/code flow — it reads the PR's diff and posts an advisory review
+  // that @-tags the author. Gated on caps.review (post_review + get_pr_diff on this
+  // server); without it (older deploy) this is skipped and behavior is unchanged.
+  if (caps.review && isReviewRequest(message)) {
+    return await reviewTask({ message, channelId, tool, me, cfg, workspaceMemory, context, signal });
+  }
+
+  // AUTHOR SIDE (0288): a review that @-tags this agent about work it owns. The
+  // review body carries the verdict + summary; the full findings live in metadata,
+  // so pull them via get_reviews and fold them into the conversation the coding
+  // agent sees — then fall through to the normal follow-up machinery, which (0281)
+  // checks out the thread's PR branch and pushes onto the SAME human-gated PR. Best-
+  // effort; a failure just leaves the summary line to drive the iterate.
+  if (caps.review && message?.kind === "review") {
+    const target =
+      message?.reviewOf && (message.reviewOf.prUrl || message.reviewOf.messageId)
+        ? message.reviewOf
+        : reviewTargetPrUrl(message)
+          ? { prUrl: reviewTargetPrUrl(message) }
+          : null;
+    if (target) {
+      const got = await tool("get_reviews", { reviewOf: target }).catch(() => null);
+      const detail = formatReviewFindings(got);
+      if (detail) context.transcript = `${context.transcript}\n\nReviewer findings to address:\n${detail}`;
+    }
+  }
+
   // No repo linked → nothing to build; just reply.
   if (!repoLink) {
     await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps });
@@ -513,10 +870,32 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   }
   const repoFullName = repoLink.repo_full_name;
 
+  // Same-PR follow-up (0281): if this mention is a reply in a thread that already
+  // owns a run (branch + PR), we may continue THAT run instead of forking a
+  // duplicate. Look it up by the thread root — the parentId the reply carried.
+  // Best-effort + gated on the server supporting the runs entity (caps.runs); any
+  // failure falls back to a fresh run (mode 'new'), never breaking the task.
+  let activeRun = null;
+  if (caps.runs && parentId) {
+    const r = await tool("get_active_run", { channelId, threadRootId: parentId }).catch(() => null);
+    if (r && r.found) activeRun = r;
+  }
+  // Only an OPEN PR is iterable: awaiting_review (the review gate) or
+  // changes_requested (a rework in flight). A merged/closed run is never
+  // continued (the resolver's recency guard).
+  const activeRunOpen = Boolean(
+    activeRun && (activeRun.status === "awaiting_review" || activeRun.status === "changes_requested"),
+  );
+
   // Chat vs code is the LLM's call, not a word list: it reads the whole
   // conversation and either returns a chat reply or signals a code run. Handles
   // any phrasing, any language, and "go for it" obviously means "do the thing we
-  // just discussed". When it replies (chat), post that and we're done.
+  // just discussed". When it replies (chat), post that and we're done. When the
+  // thread owns an OPEN PR it ALSO classifies the follow-up (change / new-scope /
+  // ambiguous). Gate on activeRunOpen, not merely Boolean(activeRun): the follow-up
+  // signal is only ever acted on when the PR is open (resolveFollowupMode → 'new'
+  // otherwise), so telling the router the thread "owns an open PR" when the run is
+  // merged/closed would just mislead the model and waste a classification.
   const routed = await routeIntent({
     name: me?.agentName || "an assistant",
     repoFullName,
@@ -524,6 +903,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     workspaceMemory,
     cfg,
     signal,
+    hasActiveRun: activeRunOpen,
   });
   if (routed.aborted || signal?.aborted) {
     await tool("post_message", { channelId, parentId, body: "Stopped." });
@@ -542,6 +922,20 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   }
   // routed.code → fall through to the coding flow below.
 
+  // How this code follow-up routes against the thread's run. The LLM's read
+  // (routed.followupSignal) is primary; the cue list is the fallback when it said
+  // nothing. resolveFollowupMode enforces the safety table — 'iterate' ONLY onto
+  // an open PR, an explicit new-scope forks ('redirect'), everything else is a
+  // fresh run ('new'). A chat reply never reaches here, so a chat is never an
+  // iterate. (Recomputed as `effectiveMode` after branch-prep in case an intended
+  // iterate can't check out its branch.)
+  const followupSignal = routed.followupSignal || classifyFollowupCue(message.body);
+  const followupMode = resolveFollowupMode({
+    hasActiveRun: Boolean(activeRun),
+    prOpen: activeRunOpen,
+    signal: followupSignal,
+  });
+
   let repoPath = resolveRepoPath(cfg, repoFullName);
   if (!repoPath) {
     // Zero-config path: if the daemon is running INSIDE a checkout of this repo
@@ -617,25 +1011,137 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   };
 
   try {
-  const branch = branchSlug(message.body, randomBytes(3).toString("hex"));
   git(repoPath, ["fetch", "origin", cfg.defaultBranch]);
-  const co = git(repoPath, ["switch", "-c", branch]);
-  if (co.status !== 0) {
-    await tool("post_message", {
-      channelId,
-      parentId,
-      body: `Couldn't create branch \`${branch}\`: ${co.stderr.trim()}`,
-    });
-    return { status: "branch-error" };
+
+  // Same-branch iteration: continue an existing PR on its own branch and push
+  // onto it, so the PR updates in place instead of a duplicate opening. Two ways
+  // in, and an explicit token WINS when both apply (they agree — same PR):
+  //   1. detectPrContinuation — an explicit "PR <url>" in the text (the server's
+  //      "request changes" rework ping, or a person naming a PR). The fallback.
+  //   2. the run resolver's 'iterate' (0281) — a plain follow-up reply in a thread
+  //      whose run already owns an OPEN PR. The PRIMARY path.
+  // Otherwise, a fresh branch off the default (today's behavior).
+  const cont = detectPrContinuation(message.body, repoFullName);
+  const iterateUrl = cont?.url || (followupMode === "iterate" && activeRun?.prUrl) || null;
+  let branch = null;
+  let continuingPrUrl = null;
+  if (iterateUrl && deps.prHeadRef) {
+    // Resolve the PR's head branch (source of truth); for a run-based iterate the
+    // run's recorded branch is a fallback if gh can't view the PR.
+    const headRef =
+      deps.prHeadRef(repoPath, iterateUrl) ||
+      (followupMode === "iterate" ? activeRun?.branch || null : null);
+    if (headRef) {
+      // Fetch the PR branch, then point a local branch at its tip via FETCH_HEAD
+      // (works on single-branch clones where `origin/<headRef>` isn't tracked).
+      // `-C` repoints whether or not a stale local copy exists — the daemon is
+      // stateless across runs, so origin is the source of truth.
+      const fetched = git(repoPath, ["fetch", "origin", headRef]);
+      const sw =
+        fetched.status === 0 ? git(repoPath, ["switch", "-C", headRef, "FETCH_HEAD"]) : fetched;
+      if (fetched.status === 0 && sw.status === 0) {
+        branch = headRef;
+        continuingPrUrl = iterateUrl;
+        console.log(`  code → continuing existing PR ${iterateUrl} on \`${headRef}\``);
+      } else {
+        console.log(
+          `  ! couldn't check out PR branch \`${headRef}\` (falling back to a new branch): ${(sw.stderr || "").trim().slice(0, 200)}`,
+        );
+      }
+    }
   }
+  // An explicit PR token (detectPrContinuation) that names a DIFFERENT PR than the
+  // thread's active run must NOT reuse/update that run for the terminal
+  // update_run/report: we push to the TOKEN's PR (via existingPrUrl below), so
+  // binding the unrelated active run would push to the token PR (#99) yet mark the
+  // active run (#142) awaiting_review — a mismatch. Treat this as 'new' for
+  // run-binding: the token still WINS for which PR gets the push; only the
+  // bookkeeping refuses to touch the mismatched run (start_run records a fresh run
+  // for the token PR instead). A token naming the SAME PR the run owns keeps the
+  // iterate-reuse.
+  const explicitTokenMismatch = Boolean(cont?.url && activeRun?.prUrl && cont.url !== activeRun.prUrl);
+  // If we INTENDED to iterate but couldn't check out the PR's branch, we're on a
+  // fresh branch now — so don't reuse the old run either; treat it as a new run.
+  const effectiveMode =
+    explicitTokenMismatch || (followupMode === "iterate" && !continuingPrUrl) ? "new" : followupMode;
+  if (!branch) {
+    branch = branchSlug(message.body, randomBytes(3).toString("hex"));
+    const co = git(repoPath, ["switch", "-c", branch]);
+    if (co.status !== 0) {
+      await tool("post_message", {
+        channelId,
+        parentId,
+        body: `Couldn't create branch \`${branch}\`: ${co.stderr.trim()}`,
+      });
+      return { status: "branch-error" };
+    }
+  }
+  // The branch tip BEFORE the agent runs — the base for detecting commits the
+  // CLI makes itself. For a continuation this is the PR's existing tip (not the
+  // default branch), so its prior commits aren't misread as "the agent
+  // self-committed".
+  const baseRef = (git(repoPath, ["rev-parse", "HEAD"]).stdout || "").trim() || (startRef.ref || cfg.defaultBranch);
 
   // Instant acknowledgement: post a template in <1s so the channel shows life
   // before any model call. If the server supports edit_message and a fast chatCmd
   // is set, a bounded plan-ack edits in a sentence of specifics ("I'll do X…").
   // Best-effort — a slow or failed ack just leaves the template, never blocks.
-  const ack = await tool("post_message", { channelId, parentId, body: ackText(repoFullName) });
+  //
+  // INSPECTABLE ACK (0281): when we're continuing or forking off an existing run,
+  // SAY so plainly (with the PR number + branch) so a human can correct the LLM's
+  // routing before any code lands. This is a key safety mitigation for a wrong
+  // 'iterate'. A plain new run keeps the standard template.
+  let ackBody = ackText(repoFullName);
+  if (continuingPrUrl) {
+    const n = prNumberFromUrl(continuingPrUrl);
+    ackBody = `Continuing ${n ? `PR #${n}` : "the existing pull request"} on \`${branch}\` — I'll push this change there and update the report.`;
+  } else if (effectiveMode === "redirect") {
+    const n = activeRun?.prNumber || prNumberFromUrl(activeRun?.prUrl);
+    ackBody = `Starting a new PR${n ? ` (separate from #${n})` : ""} on \`${branch}\`.`;
+  }
+  const ack = await tool("post_message", { channelId, parentId, body: ackBody });
   const ackId = ack?.messageId ?? null;
-  if (ackId && caps.editMessage && cfg.chatCmd) {
+  // Where the run streams + reports. When the mention was already in a thread,
+  // stay in it. When it was top-level, the ack becomes the thread anchor so the
+  // progress worklog and the report card live UNDER it — one tidy thread instead
+  // of three separate top-level posts — exactly like the hosted/native runner.
+  // The ack itself stays top-level (the channel-visible "on it"); terminal
+  // outcomes + report cards broadcast back to the channel from the thread.
+  const threadRoot = parentId ?? ackId;
+  // Bind this run to the thread root (0279/0280), now follow-up-aware (0281):
+  //   iterate  → REUSE the thread's existing run (don't record a second one); the
+  //              same PR updates in place and its status stays awaiting_review.
+  //   redirect → supersede the old run (so a future follow-up no longer points at
+  //              it), then record a FRESH run for the new, separate PR.
+  //   new      → record a fresh run, exactly as before.
+  // Best-effort throughout — a bookkeeping failure (or an older server without the
+  // runs tools) must NEVER break the run, so it proceeds without a runId.
+  let runId = effectiveMode === "iterate" ? activeRun?.runId ?? null : null;
+  if (caps.runs && threadRoot && effectiveMode !== "iterate") {
+    try {
+      if (effectiveMode === "redirect" && activeRun?.runId) {
+        await tool("update_run", { runId: activeRun.runId, status: "superseded" }).catch(() => {});
+      }
+      const r = await tool("start_run", {
+        channelId,
+        threadRootId: threadRoot,
+        taskText: message.body,
+        branch,
+        // Map an unrecognized command to null rather than the off-vocabulary
+        // "unknown" — provider is documented as claude_code|codex|cursor|hilos.
+        provider: (() => {
+          const v = detectVendor(cfg.codingCmd);
+          return v === "unknown" ? null : v;
+        })(),
+      });
+      runId = r?.runId ?? null;
+    } catch {
+      /* never break the run on a run-record failure */
+    }
+  }
+  // Keep the inspectable continuation/redirect statement (don't overwrite it with
+  // an LLM plan) so a human can correct the routing before code lands.
+  if (ackId && caps.editMessage && cfg.chatCmd && !continuingPrUrl && effectiveMode !== "redirect") {
     // Feed the ack the router's distilled brief AND the conversation — not the raw
     // mention — so it states a real plan instead of "what's the task?".
     const plan = await proposePlanAck({
@@ -652,9 +1158,49 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // then EDIT it on later beats — alive without thread spam. Needs edit_message;
   // without it we skip rather than post a fresh message every beat. lastLine
   // carries the CLI's latest output into the beat.
-  const heartbeatOn = Boolean(caps.editMessage) && cfg.heartbeatMs > 0;
+  // Live progress (0274): when the server supports post_progress, the code run
+  // STREAMS a coalesced "what I'm doing right now" card onto one thread status
+  // message (via the 0272 stream parser) instead of the 3-min edit heartbeat. On
+  // older servers (no post_progress) we fall back to the exact legacy behavior.
+  const streamOn = Boolean(caps.postProgress);
+  const vendor = detectVendor(cfg.codingCmd);
+  const streamArgs = codeStreamArgs(vendor);
+  let runSessionId = null; // captured from the stream for 0282 (resume)
+  const machine = hostname();
+
+  // Session resume (0282): on an ITERATE we can resume the coding agent's SESSION so
+  // the follow-up continues with the first run's reasoning/plan — not just its code
+  // (which the branch checkout already restores). GATE on LOCAL confidence: only
+  // resume when THIS machine's ~/.hilos/state.json recorded that thread's session
+  // AND it matches this hostname. A providerSessionId that came ONLY from the server
+  // (get_active_run) with no local match means the session likely lives on another
+  // machine/instance — a bad `--resume` id makes claude error → empty diff → a failed
+  // run, so we DON'T resume and degrade to today's branch+feedback (never worse).
+  // Only claude_code has a proven resume flag; codex/cursor/unknown → [] anyway.
+  let resumeSessionId = null;
+  if (effectiveMode === "iterate" && vendor === "claude_code") {
+    const local = (() => {
+      try {
+        return readStateEntry(HILOS_DIR, threadRoot);
+      } catch {
+        return null;
+      }
+    })();
+    const serverSid = activeRun?.providerSessionId || null;
+    // Confidence = a local record, for THIS machine, with a session id. If the server
+    // also has one it must AGREE (a mismatch means the run moved — don't resume a
+    // stale/foreign id). A server-only id (no local record) is never resumed.
+    if (local && local.machine === machine && local.sessionId && (!serverSid || serverSid === local.sessionId)) {
+      resumeSessionId = local.sessionId;
+      console.log(`  code → resuming session ${local.sessionId} for this iterate (local + machine match)`);
+    } else if (serverSid) {
+      console.log("  code → not resuming (session recorded on another machine or unverified locally); using branch + feedback");
+    }
+  }
+
+  const heartbeatOn = Boolean(caps.editMessage) && cfg.heartbeatMs > 0 && !streamOn;
   let lastLine = "";
-  let progressId = null; // the thread progress reply, once a beat has posted it
+  let progressId = null; // the thread progress/status reply, once one has posted
   const startHeartbeat = () => {
     if (!heartbeatOn) return () => {};
     const start = deps.now();
@@ -666,7 +1212,8 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       const body = buildHeartbeat({ repoFullName, branch, elapsedMs: deps.now() - start, lastLine });
       try {
         if (!progressId) {
-          const r = await tool("post_message", { channelId, parentId, body });
+          // Progress is the worklog — it streams in the thread only (no broadcast).
+          const r = await tool("post_message", { channelId, parentId: threadRoot, body });
           progressId = r?.messageId ?? null;
         } else {
           await tool("edit_message", { messageId: progressId, body });
@@ -696,27 +1243,139 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // Run the CLI and stage everything it changed; return the diff stats (no post).
   // Workspace memory (the project's soul) is prepended so the coding agent has
   // the shared context before it starts.
-  const runAndStage = async (promptText) => {
+  const runAndStage = async (promptText, { resume = true } = {}) => {
     console.log(
       `  code → running \`${cfg.codingCmd}\` in ${repoPath} (this can take a few minutes; output appears when it finishes)…`,
     );
-    const stopHeartbeat = startHeartbeat();
+    // Streaming path: post ONE thread status message up front, then stream a live
+    // card into it via post_progress. Legacy path: the 3-min edit heartbeat. Only
+    // one of them runs — never both.
+    let stopHeartbeat = () => {};
+    let emitter = null;
+    // Every post_progress write we dispatch, chained so the finally can await ALL
+    // of them before the run returns. This closes the read-modify-write race with
+    // the in-place settle (0289): if a trailing progress write were still landing
+    // when post_report settles the report, it would re-write metadata WITHOUT the
+    // report (it read the pre-settle snapshot) and clobber it. Draining every send
+    // here guarantees no progress write is in flight once we settle.
+    let progressInflight = Promise.resolve();
+    if (streamOn) {
+      if (!progressId) {
+        try {
+          const r = await tool("post_message", {
+            channelId,
+            parentId: threadRoot,
+            body: buildHeartbeat({ repoFullName, branch, elapsedMs: 0, lastLine: "" }),
+          });
+          progressId = r?.messageId ?? null;
+        } catch {
+          progressId = null; // no status card → the run still proceeds
+        }
+      }
+      const statusId = progressId;
+      if (statusId) {
+        emitter = createProgressEmitter({
+          parser: makeStreamParser(vendor),
+          now: deps.now,
+          throttleMs: cfg.progressMs,
+          // The module never imports MCP — the send fn is injected here. It must
+          // never throw into the run (createProgressEmitter also guards).
+          send: (p) => {
+            try {
+              const r = tool("post_progress", { messageId: statusId, progress: p });
+              if (r && typeof r.then === "function") {
+                const done = r.then(() => {}, () => {});
+                progressInflight = Promise.all([progressInflight, done]).then(
+                  () => {},
+                  () => {},
+                );
+              }
+            } catch {
+              /* a progress send must never break the run */
+            }
+          },
+        });
+      }
+    } else {
+      stopHeartbeat = startHeartbeat();
+    }
+    // The code run gets the vendor's stream flags appended to its ARGV (not the
+    // display string), and ONLY the code run — chat/routing/plan-ack stay plain.
+    // On an iterate we ALSO insert `--resume <id>` (0282) into the code ARGV
+    // (after the base args, before the stream flags + the trailing prompt) so the
+    // follow-up continues the first run's session; `resume:false` (the never-worse
+    // fallback) suppresses it. buildResumeArgs is [] unless vendor+session make
+    // resume safe, so a non-resume run is byte-identical to the pre-0282 ARGV.
+    const resumeArgs = resume ? buildResumeArgs(vendor, resumeSessionId) : [];
+    const codeArgs = streamOn
+      ? [...parts.slice(1), ...resumeArgs, ...streamArgs]
+      : [...parts.slice(1), ...resumeArgs];
     let run;
     try {
       run = await runCli({
         cmd: parts[0],
-        args: [...parts.slice(1), memoryPreamble(workspaceMemory) + promptText],
+        args: [...codeArgs, memoryPreamble(workspaceMemory) + promptText],
         cwd: repoPath,
         timeoutMs: cfg.runTimeoutMs,
         label: "coding",
         signal,
         onData: (c) => {
+          // Keep tracking lastLine as a fallback (legacy heartbeat / honesty).
           const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
           if (lines.length) lastLine = lines[lines.length - 1];
+          if (emitter) {
+            try {
+              emitter.feed(c);
+            } catch {
+              /* a progress fold must never break the run */
+            }
+          }
         },
       });
     } finally {
       stopHeartbeat();
+      if (emitter) {
+        // Terminal state: flip the status card off "working" (state 'done'/'error')
+        // so it stops claiming the agent is alive. For a run that produced work,
+        // the gate:false path then SETTLES the report onto this same card in place
+        // (0289) — the card cross-fades run → report; for no-changes/failed/gate
+        // outcomes this terminal 'done'/'error' is the card's final state.
+        const errored = Boolean(run && (run.aborted || run.error || run.status !== 0));
+        // On error, carry an honest reason onto the card (0294) — the same signal
+        // the chat note uses: spawn error message, else exit status, plus a short
+        // stderr tail. Sanitized again server-side; an old server just drops it.
+        let reason = "";
+        if (errored && run && !run.aborted) {
+          const stderrTail = oneLine((run.stderr || "").trim().split("\n").slice(-3).join(" "), 200);
+          if (run.error?.code === "ENOENT") {
+            reason = `Couldn't start ${parts[0]} — is it installed and on PATH?`;
+          } else if (run.error?.message) {
+            reason = run.error.message;
+          } else if (run.status != null) {
+            reason = `The CLI exited ${run.status}`;
+          }
+          if (stderrTail) reason = reason ? `${reason}: ${stderrTail}` : stderrTail;
+        }
+        try {
+          emitter.done(errored ? "error" : "done", reason);
+        } catch {
+          /* ignore */
+        }
+        // Wait for every progress write (including the terminal one above) to land
+        // BEFORE runAndStage returns, so nothing is in flight when the caller
+        // settles the report onto this card — no lost-update clobber (0289).
+        try {
+          await progressInflight;
+        } catch {
+          /* a drain failure must never break the run */
+        }
+        try {
+          const snap = emitter.snapshot();
+          if (snap && snap.sessionId) runSessionId = snap.sessionId;
+        } catch {
+          /* ignore */
+        }
+      }
     }
     if (run.aborted || signal?.aborted) {
       console.log("  code → cancelled");
@@ -745,9 +1404,8 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       // (commit/push/PR) despite being told only to edit. Detect commits it made
       // on this branch so we report + ship them instead of falsely claiming "no
       // changes" and deleting a branch that has real work.
-      const base = startRef.ref || cfg.defaultBranch;
       const ahead =
-        Number((git(repoPath, ["rev-list", "--count", `${base}..HEAD`]).stdout || "0").trim()) || 0;
+        Number((git(repoPath, ["rev-list", "--count", `${baseRef}..HEAD`]).stdout || "0").trim()) || 0;
       if (ahead > 0) {
         console.log(`  code → agent self-committed (${ahead} commit(s) ahead); reconciling`);
         return { empty: true, failed: false, ahead };
@@ -761,6 +1419,36 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     return { empty: false, diffText, truncated, omittedLines, stat, runFailed: run.status !== 0 };
   };
 
+  // Persist the run's coding-agent session (0282) so a LATER iterate can resume it.
+  // Two records, both best-effort — a failure here NEVER breaks the run:
+  //   - update_run({ providerSessionId }) → the server's durable record (survives a
+  //     daemon restart; also read by the hosted UI). Only when a runId was recorded.
+  //   - ~/.hilos/state.json for this thread root, stamped with THIS machine — the
+  //     LOCAL proof the session lives here, which the resume gate above requires.
+  // Called after each run (a resumed run yields a possibly-new sessionId, so the
+  // chain continues across multiple iterations) and again post-ship to fill prUrl.
+  const recordSession = async (prUrl) => {
+    const sid = runSessionId;
+    if (!sid) return;
+    if (runId) {
+      await tool("update_run", { runId, providerSessionId: sid }).catch(() => {});
+    }
+    try {
+      if (threadRoot) {
+        writeState(HILOS_DIR, threadRoot, {
+          runId: runId || null,
+          branch,
+          prUrl: prUrl || continuingPrUrl || null,
+          sessionId: sid,
+          machine,
+          updatedAt: new Date().toISOString(),
+        });
+      }
+    } catch {
+      /* a state write must never break the run */
+    }
+  };
+
   // Post a proposal card (approve-before-push mode) from a staged change.
   const postProposal = async (staged) => {
     const report = buildProposalReport({
@@ -774,7 +1462,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       stat: staged.stat,
       runFailed: staged.runFailed,
     });
-    const res = await tool("post_report", { channelId, parentId, ...report });
+    const res = await tool("post_report", { channelId, parentId: threadRoot, broadcast: true, ...report });
     return { reportMessageId: res?.messageId ?? null, stat: staged.stat };
   };
 
@@ -805,7 +1493,8 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     const clean = discardBranch();
     await tool("post_message", {
       channelId,
-      parentId,
+      parentId: threadRoot,
+      broadcast: true,
       body: clean
         ? `Stopped — discarded \`${branch}\`.`
         : `Stopped, but couldn't fully clean \`${branch}\` — run \`git reset --hard && git switch ${startRef.ref || cfg.defaultBranch}\` in ${repoPath}.`,
@@ -813,8 +1502,47 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     return { status: "cancelled", branch };
   };
 
-  const staged = await runAndStage(codeTaskPrompt({ message, context, brief: routed.task, repoFullName }));
+  // Team memory recall (0297): best-effort fetch accumulated learnings for this
+  // channel before the coding run so the coding agent has the team's conventions
+  // and gotchas from the start. Capability-gated: older servers without the
+  // `recall` tool degrade silently (caps.recall=false → skip, no change in
+  // behavior). A recall failure — network hiccup, server error — NEVER fails the
+  // task; it is caught and the run proceeds without the block.
+  let teamMemoryBlock = "";
+  if (caps.recall) {
+    try {
+      const recalled = await tool("recall", { channelId, limit: 20 }).catch(() => null);
+      const mems = Array.isArray(recalled?.memories) ? recalled.memories : [];
+      teamMemoryBlock = buildMemoryBlock(mems);
+    } catch {
+      /* recall failure must never break the coding task */
+    }
+  }
+
+  const codePrompt =
+    (teamMemoryBlock ? teamMemoryBlock + "\n\n" : "") +
+    codeTaskPrompt({ message, context, brief: routed.task, repoFullName });
+  let staged = await runAndStage(codePrompt);
   if (staged.aborted) return await postStopped();
+  // Never-worse-than-today (0282): if we RESUMED a session and that run FAILED (a
+  // stale/foreign `--resume` id makes claude error out → empty diff → failed), retry
+  // ONCE without --resume — the exact branch+feedback iterate we'd have run before
+  // 0282. A dead session can therefore never dead-end an iteration. Gated on
+  // staged.failed (the reliable resume-error signal) so a legitimate no-op run isn't
+  // re-run. Adopt the retry regardless — it IS the pre-0282 baseline.
+  if (resumeSessionId && staged.empty && staged.failed) {
+    console.log("  code → resumed run failed; retrying once without --resume (branch + feedback)");
+    const retry = await runAndStage(codePrompt, { resume: false });
+    if (retry.aborted) return await postStopped();
+    staged = retry;
+  }
+  // Persist this run's session (best-effort) so the NEXT iterate can resume it and
+  // machine-match. prUrl is filled in again at ship time.
+  await recordSession(continuingPrUrl);
+  // Resume is a ONE-shot for the first run of this iterate: the gate:true feedback
+  // rounds below are intra-run refinements (same working tree, same PR turn), not a
+  // fresh cross-turn resume, so they must NOT replay the original `--resume` id.
+  resumeSessionId = null;
   // The CLI committed on its own (clean tree, but commits ahead of base). Don't
   // report "no changes" or delete the branch — surface the real work.
   if (staged.empty && !staged.failed && staged.ahead > 0) {
@@ -823,7 +1551,8 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       // honest and let the human review instead of auto-shipping. Leave the branch.
       await tool("post_message", {
         channelId,
-        parentId,
+        parentId: threadRoot,
+        broadcast: true,
         body:
           `The coding agent committed on \`${branch}\` itself (I asked it to only edit files). ` +
           `Under approve-before-push I won't auto-push it — review \`${branch}\` locally, then ` +
@@ -832,8 +1561,12 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       await finalizeProgress(`\`${branch}\` has the agent's own commits — needs review.`);
       return { status: "self-committed-gated", branch };
     }
-    await finalizeProgress(`Agent shipped \`${branch}\` itself — report below.`);
-    return await shipSelfDriven({
+    // When a live status card was streaming, settle the report onto it (0289) —
+    // the card cross-fades run → report. Skip finalizeProgress then (it edits the
+    // card's body, which the settle overwrites with the report anyway).
+    const selfSettleId = streamOn && progressId ? progressId : null;
+    if (!selfSettleId) await finalizeProgress(`Agent shipped \`${branch}\` itself — report below.`);
+    const selfResult = await shipSelfDriven({
       repoPath,
       branch,
       task: routed.task || message.body,
@@ -842,13 +1575,23 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       tool,
       channelId,
       deps,
-      parentId,
+      parentId: threadRoot,
+      settleId: selfSettleId,
+      runId,
     });
+    await recordSession(selfResult.prUrl);
+    return selfResult;
   }
   if (staged.empty) {
+    // When continuing an existing PR, never delete that branch — it's the open
+    // PR — and don't say "cleaning up". Just report and leave the PR as it was.
+    const cleanupNote = continuingPrUrl ? "" : ` Cleaning up \`${branch}\`.`;
+    const retryTail = continuingPrUrl
+      ? ` — \`${branch}\` is unchanged; mention me to retry.`
+      : ` Cleaning up \`${branch}\` — mention me to retry.`;
     let body;
     if (staged.failed && staged.errCode === "ENOENT") {
-      body = `I couldn't start \`${cfg.codingCmd}\` — is it installed and on PATH? Cleaning up \`${branch}\`.`;
+      body = `I couldn't start \`${cfg.codingCmd}\` — is it installed and on PATH?${cleanupNote}`;
     } else if (staged.failed) {
       const why = staged.errMessage
         ? ` (${staged.errMessage})`
@@ -856,16 +1599,20 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           ? ` (the CLI exited ${staged.status})`
           : "";
       const tail = staged.stderrTail ? `: ${staged.stderrTail}` : "";
-      body = `The run didn't finish${why}${tail}. Cleaning up \`${branch}\` — mention me to retry.`;
+      body = `The run didn't finish${why}${tail}.${retryTail}`;
     } else {
-      body = `No changes were produced. Cleaning up \`${branch}\`.`;
+      body = continuingPrUrl
+        ? `That feedback produced no further changes — \`${branch}\` is unchanged.`
+        : `No changes were produced.${cleanupNote}`;
     }
-    await tool("post_message", { channelId, parentId, body });
+    await tool("post_message", { channelId, parentId: threadRoot, broadcast: true, body });
     await finalizeProgress(
       staged.failed ? `Run ended early on \`${branch}\` — see the note below.` : `No changes needed on \`${branch}\`.`,
     );
-    git(repoPath, ["switch", "-"]);
-    git(repoPath, ["branch", "-D", branch]);
+    if (!continuingPrUrl) {
+      git(repoPath, ["switch", "-"]);
+      git(repoPath, ["branch", "-D", branch]);
+    }
     return { status: staged.failed ? "run-failed" : "no-changes" };
   }
 
@@ -875,32 +1622,50 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   if (!cfg.gate) {
     // A "stop" that lands between the run finishing and the ship must still win.
     if (signal?.aborted) return await postStopped();
+    // Seamless single card (0289): when a live status card streamed this run,
+    // settle the report onto it in place instead of posting a separate report
+    // message. Only the DEFAULT gate:false report settles in place; gate:true's
+    // proposal → decision → report lifecycle stays on separate messages (a
+    // separate ticket). No status card (older server / status post failed) →
+    // settleId is null and applyDecision posts a fresh broadcast report as before.
+    const settleId = streamOn && progressId ? progressId : null;
     const result = await applyDecision({
       decision: { kind: "approved" },
       repoPath,
       branch,
-      task: message.body,
+      // For a continuation the raw mention is the rework ping ("please update the
+      // PR …"); use the router's distilled brief for a clean commit/PR title.
+      task: continuingPrUrl ? routed.task || message.body : message.body,
       requester: message.author,
       cfg,
       tool,
       channelId,
       deps,
-      parentId,
+      parentId: threadRoot,
+      existingPrUrl: continuingPrUrl,
+      settleId,
+      runId,
     });
-    await finalizeProgress(`Done on \`${branch}\` — see the report below.`);
-    return { ...result, stat: staged.stat };
+    // The settle already flipped the card to the report (body + metadata); editing
+    // the body again would clobber the report summary, so only finalize when we
+    // posted a separate report.
+    if (!settleId) await finalizeProgress(`Done on \`${branch}\` — see the report below.`);
+    // Re-record with the now-known PR url so the local session record + the run row
+    // carry the PR the session belongs to (best-effort; session id unchanged).
+    await recordSession(result.prUrl);
+    return { ...result, stat: staged.stat, sessionId: runSessionId };
   }
 
   await finalizeProgress(`Coding done on \`${branch}\` — proposal below for review.`);
   let proposal = await postProposal(staged);
-  let decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps, parentId, signal });
+  let decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps, parentId: threadRoot, signal });
   if (decision.kind === "cancelled") return await postStopped();
   const maxRounds = cfg.maxRounds || 3;
   let round = 1;
   while (decision.kind === "changes" && round < maxRounds) {
     await tool("post_message", {
       channelId,
-      parentId,
+      parentId: threadRoot,
       body: `Revising with your feedback${decision.note ? `: ${decision.note}` : ""} (round ${round + 1}/${maxRounds}).`,
     });
     const refined = await runAndStage(
@@ -910,13 +1675,14 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     if (refined.empty) {
       await tool("post_message", {
         channelId,
-        parentId,
+        parentId: threadRoot,
+        broadcast: true,
         body: `That feedback produced no further changes — leaving \`${branch}\` as proposed.`,
       });
       break;
     }
     proposal = await postProposal(refined);
-    decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps, parentId, signal });
+    decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps, parentId: threadRoot, signal });
     if (decision.kind === "cancelled") return await postStopped();
     round += 1;
   }
@@ -927,16 +1693,21 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     decision,
     repoPath,
     branch,
-    task: message.body,
+    // A gate:true approve on a continuation already has an open PR — reuse it so
+    // we update in place instead of a failing `gh pr create`.
+    task: continuingPrUrl ? routed.task || message.body : message.body,
     requester: message.author,
     cfg,
     tool,
     channelId,
     deps,
-    parentId,
+    parentId: threadRoot,
+    existingPrUrl: continuingPrUrl,
+    runId,
   });
   await finalizeProgress(`Done on \`${branch}\` — see the report below.`);
-  return { ...result, reportMessageId: proposal.reportMessageId, stat: proposal.stat, rounds: round };
+  await recordSession(result.prUrl);
+  return { ...result, reportMessageId: proposal.reportMessageId, stat: proposal.stat, rounds: round, sessionId: runSessionId };
   } finally {
     // Whatever happened, give the user their uncommitted work back.
     await restoreStash();