hilos-agent 0.1.15 → 0.4.0

package/src/handler.mjs

@@ -9,20 +9,72 @@
 
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { rmSync } from "node:fs";
+import { rmSync, mkdtempSync, existsSync } from "node:fs";
+import { hostname, tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   branchSlug,
   truncateDiff,
   resolveRepoPath,
+  resolveFolderPath,
+  diffStatusSets,
   parseShortstat,
   buildProposalReport,
   decisionKind,
   commitMessage,
   prTitleBody,
   mentionHandle,
+  detectPrContinuation,
 } from "./daemon.mjs";
-import { runCli, buildHeartbeat, ackText, oneLine } from "./cli.mjs";
+import { runCli, buildHeartbeat, ackText, oneLine, fmtElapsed } 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) {
@@ -30,10 +82,26 @@ function requesterTag(author) {
   return handle ? `@${handle}` : "";
 }
 
+function compactRunMarker(status, branch) {
+  const b = branch ? ` \`${branch}\`` : "";
+  if (status === "pushed") return `Needs review:${b}`;
+  if (status === "discarded" || status === "cancelled") return `Stopped:${b}`;
+  if (status === "no-changes") return `Done:${b}`;
+  if (status === "changes" || status === "timeout") return `Needs follow-up:${b}`;
+  return `Failed:${b}`;
+}
+
 function defaultDeps() {
   return {
     git: (cwd, args) =>
       spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 50 * 1024 * 1024 }),
+    // The async CLI runner, injectable so folder mode (and tests) can drive the
+    // coding run without spawning a real process. The repo flow still uses the
+    // imported runCli directly (unchanged); only folder mode goes through deps.
+    runCli: (opts) => runCli(opts),
+    // Does a path exist on disk? Injectable so folder mode's "missing folder"
+    // guard is unit-testable without touching the real filesystem.
+    pathExists: (p) => existsSync(p),
     openPR: (cwd, { title, body, branch, base }) => {
       const r = spawnSync(
         "gh",
@@ -54,6 +122,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,12 +181,12 @@ 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.
+  // `parentId` here is the run's thread root. Terminal outcomes ask the server
+  // for channel visibility, but the workspace decides whether final agent
+  // results actually 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) {
@@ -139,21 +219,46 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       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; the workspace setting decides
+    // whether that final report is also channel-visible. Without a status id
+    // (older server / status post failed) fall back to posting a fresh report.
+    const reportArgs = {
       channelId,
-      parentId,
-      broadcast: true,
       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 };
   }
 
@@ -192,7 +297,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
@@ -207,10 +312,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; the workspace setting decides channel visibility.
+  // Otherwise post a fresh final report.
+  const reportArgs = {
     channelId,
-    parentId,
-    broadcast: true,
     title: `Shipped: ${title}`,
     summary: prUrl
       ? `${lead}the coding agent committed on \`${cur}\` and opened a pull request.`
@@ -219,8 +325,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 };
 }
 
@@ -248,9 +369,24 @@ 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, runCliFn }) {
+  const doRun = runCliFn || runCli; // folder mode injects deps.runCli; repo flow uses the import
   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` +
@@ -263,11 +399,13 @@ 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, stay conversational; implementation and PR flow are for clear ` +
+    `action language.` +
+    `${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}`;
-  const run = await runCli({
+  const run = await doRun({
     cmd: parts[0],
     args: [...parts.slice(1), prompt],
     timeoutMs: cfg.chatTimeoutMs || cfg.runTimeoutMs,
@@ -275,8 +413,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
@@ -286,9 +430,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 };
 }
 
 /**
@@ -325,6 +469,34 @@ export function codeTaskPrompt(o) {
   return p;
 }
 
+/**
+ * The prompt handed to the coding CLI in FOLDER mode (0322): the agent works
+ * directly in the user's own folder — no branch, no PR, no commit step. Same
+ * imperative "edit files now" framing as codeTaskPrompt, but it tells the agent
+ * its edits land straight in the folder and bans git/gh (there's nothing for the
+ * daemon to commit; the changes ARE the deliverable).
+ * @param {{ message?: { body?: string } | null, context?: { transcript?: string } | null, brief?: string, folderPath?: string }} [o]
+ */
+export function folderTaskPrompt(o) {
+  const { message, context, brief, folderPath } = o || {};
+  const task = (brief && brief.trim()) || String(message?.body || "").trim();
+  const where = folderPath ? ` in the local folder ${folderPath}` : "";
+  let p =
+    `You are a coding agent working directly${where}. Implement the following by EDITING ` +
+    `FILES now — make the changes directly in this folder, do not just describe them, do not ` +
+    `ask questions:\n\n${task}`;
+  p +=
+    `\n\nIMPORTANT: your edits apply DIRECTLY to the user's folder — there is no branch, no ` +
+    `commit, and no pull request. Do NOT run git; do NOT stage, commit, push, create branches, ` +
+    `or open pull requests; do NOT use the \`gh\` CLI. Just leave your edits in the folder for ` +
+    `the person to review.`;
+  const transcript = context?.transcript?.trim();
+  if (transcript) {
+    p += `\n\nBackground from the team's discussion (context only — the task above is what to do):\n${transcript}`;
+  }
+  return p;
+}
+
 /** owner/name from a GitHub remote URL (https or ssh), or null. */
 export function normalizeRemote(url) {
   const m = String(url || "")
@@ -409,9 +581,15 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   const { transcript } = context || (await fetchContext({ channelId, tool, parentId }));
   const name = me?.agentName || "an assistant";
   // Tell the agent what the room is connected to so it doesn't ask "which repo?".
+  // repoLink is already folder-excluded (handleTask picks kind!=='folder'), so the
+  // "repository" line never claims a folder path is a repo. When there's no repo
+  // but this channel maps to a local folder on THIS machine, say that instead.
+  const folderPath = !repoLink ? resolveFolderPath(cfg, channelId) : null;
   const repoLine = repoLink
     ? `This channel is connected to the repository ${repoLink.repo_full_name}; assume that repo for any code work — don't ask which one.`
-    : `If asked to change code, note that a repo isn't linked to this channel yet.`;
+    : folderPath
+      ? `This channel is connected to the local folder ${folderPath} on this machine; assume that folder for any file work — don't ask which one.`
+      : `If asked to change code, note that a repo isn't linked to this channel yet.`;
   const prompt =
     `You are ${name}, a teammate in a team chat (hilos). Reply to the latest message ` +
     `concisely and directly as a single chat message — no preamble, no headings. ` +
@@ -495,6 +673,598 @@ 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)
+  );
+}
+
+function agentMode(message) {
+  const mode = message?.agentMode || message?.metadata?.agentMode;
+  return mode === "ask" || mode === "ship" ? mode : null;
+}
+
+/** 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;
+  const updateReviewMarker = async (body) => {
+    if (!ack?.messageId || parentId) return;
+    await tool("edit_message", { messageId: ack.messageId, body }).catch(() => {});
+  };
+
+  // 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(() => {});
+    await updateReviewMarker(`Review failed: ${label}`);
+    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(() => {});
+    await updateReviewMarker(`Review stopped: ${label}`);
+    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(() => {});
+    await updateReviewMarker(`Review failed: ${label}`);
+    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(() => {});
+    await updateReviewMarker(`Review failed: ${label}`);
+    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))`);
+  await updateReviewMarker(`Review ready: ${label}`);
+  return { status: "reviewed", verdict, findings: findings.length, prUrl };
+}
+
+/** Render a changed-file list for the folder report card. */
+function renderChangedList({ created, modified, deleted }) {
+  const lines = [];
+  for (const f of created) lines.push(`- added \`${f}\``);
+  for (const f of modified) lines.push(`- changed \`${f}\``);
+  for (const f of deleted) lines.push(`- removed \`${f}\``);
+  return lines.join("\n");
+}
+
+/**
+ * FOLDER MODE (0322). A channel with NO linked GitHub repo but a `folders`
+ * mapping runs the coding CLI directly in that folder and applies changes in
+ * place — it's the user's own machine, same trust as running the CLI themselves.
+ * No branch, no push, no PR, no `gh` — ever. When the folder is a git repo we
+ * snapshot `git status` before/after to report exactly what changed and to offer
+ * a precise revert on reject; a non-git folder gets an honest "can't track / can't
+ * auto-undo" report. The report card drives a decision: approve = keep (already
+ * live), request-changes = re-run in place (bounded), reject = revert the run's
+ * own changes (git repos only).
+ */
+async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps, signal, parentId, folderPath, brief, workspaceMemory, context }) {
+  void me;
+  const git = deps.git;
+  const tag = requesterTag(message.author);
+  const lead = tag ? `${tag} — ` : "";
+
+  // 1. The mapped folder must actually exist on disk — be honest and actionable.
+  if (!deps.pathExists(folderPath)) {
+    await tool("post_message", {
+      channelId,
+      parentId,
+      body:
+        `I couldn't find the folder \`${folderPath}\` on this machine — it may have moved, been ` +
+        `renamed, or live on a drive that isn't mounted. Fix the path in my \`folders\` config ` +
+        `(or restore the folder), then mention me again.`,
+    });
+    return { status: "no-path" };
+  }
+
+  // 2. Is it a git repo? If so, snapshot the pre-run status so we can (a) report
+  // exactly what the run changed and (b) revert precisely on reject. We NEVER touch
+  // the index (no `git add`), never branch, never push. A non-git folder still runs
+  // — we just can't offer diff/undo.
+  const insideWorkTree = git(folderPath, ["rev-parse", "--is-inside-work-tree"]);
+  const isGit = insideWorkTree.status === 0 && String(insideWorkTree.stdout || "").trim() === "true";
+  const beforeStatus = isGit ? String(git(folderPath, ["status", "--porcelain"]).stdout || "") : "";
+  const dirtyBefore = isGit && beforeStatus.trim() !== "";
+
+  // 3. Instant ack / thread anchor (mirrors the repo flow). When the mention was in
+  // a thread we stay in it; a top-level mention makes the ack the thread anchor so
+  // the run's progress + report card live under it.
+  const ack = await tool("post_message", {
+    channelId,
+    parentId,
+    body: `On it — working directly in \`${folderPath}\`. Changes apply straight to your folder (no branch, no PR); I'll report what changed.`,
+  });
+  const ackId = ack?.messageId ?? null;
+  const threadRoot = parentId ?? ackId;
+
+  // Live progress: reuse the streaming card (post_progress) when the server
+  // supports it, else the edit-in-place heartbeat, else nothing. Kept across
+  // request-changes re-runs on the same status message.
+  let progressId = null;
+  const folderWorking = (elapsedMs, lastLine) => {
+    const base = `Working in \`${folderPath}\` — ${fmtElapsed(elapsedMs)} elapsed. I'll report what changed when it's done.`;
+    const tail = oneLine(lastLine);
+    return tail ? `${base}\n\nLatest: ${tail}` : base;
+  };
+
+  // Run the coding CLI in the folder, streaming progress + honoring timeouts and
+  // the abort signal (reuses runCli via deps + the progress-emitter machinery).
+  const runFolderCli = async (promptText) => {
+    const parts = cfg.codingCmd.split(" ").filter(Boolean);
+    const vendor = detectVendor(cfg.codingCmd);
+    const streamOn = Boolean(caps.postProgress);
+    const streamArgs = streamOn ? codeStreamArgs(vendor) : [];
+    let emitter = null;
+    let progressInflight = Promise.resolve();
+    let stopHeartbeat = () => {};
+    let lastLine = "";
+    // With stream args the CLI's stdout is NDJSON events, not prose — parse it and
+    // keep the final `result` event's summary so the report card gets clean text
+    // (raw stdout would dump JSON into the report). Without stream args, stdout IS
+    // the prose and resultText stays empty.
+    let resultText = "";
+    const resultParser = streamArgs.length ? makeStreamParser(vendor) : null;
+    const foldResultEvents = (events) => {
+      for (const ev of events || []) {
+        if (ev && ev.t === "result" && ev.summary) resultText = ev.summary;
+      }
+    };
+    if (streamOn) {
+      if (!progressId) {
+        try {
+          const r = await tool("post_message", { channelId, parentId: threadRoot, body: folderWorking(0, "") });
+          progressId = r?.messageId ?? null;
+        } catch {
+          progressId = null;
+        }
+      }
+      const statusId = progressId;
+      if (statusId) {
+        emitter = createProgressEmitter({
+          parser: makeStreamParser(vendor),
+          now: deps.now,
+          throttleMs: cfg.progressMs,
+          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 if (caps.editMessage && cfg.heartbeatMs > 0) {
+      const start = deps.now();
+      let stopped = false;
+      let busy = false;
+      const beat = setInterval(async () => {
+        if (stopped || busy) return;
+        busy = true;
+        const body = folderWorking(deps.now() - start, lastLine);
+        try {
+          if (!progressId) {
+            const r = await tool("post_message", { channelId, parentId: threadRoot, body });
+            progressId = r?.messageId ?? null;
+          } else {
+            await tool("edit_message", { messageId: progressId, body });
+          }
+        } catch {
+          /* a heartbeat must never break the run */
+        } finally {
+          busy = false;
+        }
+      }, cfg.heartbeatMs);
+      if (beat.unref) beat.unref();
+      stopHeartbeat = () => {
+        stopped = true;
+        clearInterval(beat);
+      };
+    }
+    let run;
+    try {
+      run = await deps.runCli({
+        cmd: parts[0],
+        args: [...parts.slice(1), ...streamArgs, memoryPreamble(workspaceMemory) + promptText],
+        cwd: folderPath,
+        timeoutMs: cfg.runTimeoutMs,
+        label: "coding",
+        signal,
+        onData: (c) => {
+          const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
+          if (lines.length) lastLine = lines[lines.length - 1];
+          if (resultParser) {
+            try {
+              foldResultEvents(resultParser.push(String(c)));
+            } catch {
+              /* result extraction must never break the run */
+            }
+          }
+          if (emitter) {
+            try {
+              emitter.feed(c);
+            } catch {
+              /* a progress fold must never break the run */
+            }
+          }
+        },
+      });
+    } finally {
+      stopHeartbeat();
+      if (emitter) {
+        const errored = Boolean(run && (run.aborted || run.error || run.status !== 0));
+        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 */
+        }
+        try {
+          await progressInflight;
+        } catch {
+          /* a drain failure must never break the run */
+        }
+      }
+    }
+    if (resultParser) {
+      try {
+        foldResultEvents(resultParser.flush());
+      } catch {
+        /* result extraction must never break the run */
+      }
+    }
+    if (run.aborted || signal?.aborted) return { aborted: true };
+    const failed = Boolean(run.error) || run.status !== 0;
+    return {
+      aborted: false,
+      stdout: run.stdout || "",
+      // Clean prose for the report: the stream `result` summary when streaming,
+      // else empty (raw stdout is prose only in the non-streamed case).
+      resultText,
+      streamed: streamArgs.length > 0,
+      failed,
+      errCode: run.error?.code || null,
+      errMessage: run.error?.message || null,
+      status: run.status,
+      stderrTail: oneLine((run.stderr || "").trim().split("\n").slice(-3).join(" "), 300),
+    };
+  };
+
+  // Compute what the run changed (git repos only), vs the pre-run snapshot.
+  const computeChanged = () => {
+    if (!isGit) return { modified: [], created: [], deleted: [] };
+    const afterStatus = String(git(folderPath, ["status", "--porcelain"]).stdout || "");
+    return diffStatusSets(beforeStatus, afterStatus);
+  };
+  const hasChanges = (c) => c.created.length + c.modified.length + c.deleted.length > 0;
+
+  const buildReport = (runResult, changed) => {
+    const changedList = renderChangedList(changed);
+    const stat = isGit ? truncateDiff(String(git(folderPath, ["diff", "--stat"]).stdout || "")).text.trim() : "";
+    // Streamed runs put NDJSON on stdout — use the parsed result summary there;
+    // non-streamed stdout is the agent's prose and is safe to quote.
+    const rawOut = (runResult.resultText || (runResult.streamed ? "" : runResult.stdout) || "").trim();
+    const parts = [`${lead}worked directly in \`${folderPath}\`.`];
+    if (rawOut) parts.push(rawOut.slice(0, 2000));
+    if (isGit) parts.push(changedList ? `Changed files:\n${changedList}` : "No tracked file changes were detected.");
+    if (stat) parts.push("```\n" + stat + "\n```");
+    const caveats = [`Changes were applied directly to ${folderPath} — there is no branch or PR to review.`];
+    if (!isGit) caveats.push("This folder isn't a git repository, so I can't show a file-level diff or automatically undo the changes.");
+    if (dirtyBefore) caveats.push("The folder already had uncommitted local changes before this run — those are mixed in with mine.");
+    if (runResult.failed) {
+      const why = runResult.errMessage ? `: ${runResult.errMessage}` : runResult.status != null ? ` (exit ${runResult.status})` : "";
+      caveats.push(`The coding agent didn't exit cleanly${why} — review the changes carefully.`);
+    }
+    const folderName = folderPath.split("/").filter(Boolean).pop() || folderPath;
+    return { title: `Folder run: ${folderName}`, summary: parts.join("\n\n"), caveats, todos: [] };
+  };
+
+  // --- Run ---
+  let runResult = await runFolderCli(folderTaskPrompt({ message, context, brief, folderPath }));
+  if (runResult.aborted) {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body: `Stopped — I left \`${folderPath}\` as it was.`,
+    });
+    return { status: "cancelled" };
+  }
+
+  let changed = computeChanged();
+
+  // Honest early exits (no report/decision): a failed run that changed nothing, or
+  // a clean success that changed nothing.
+  if (runResult.failed && (!isGit || !hasChanges(changed))) {
+    let body;
+    if (runResult.errCode === "ENOENT") {
+      body = `I couldn't start \`${cfg.codingCmd}\` — is it installed and on PATH?`;
+    } else {
+      const why = runResult.errMessage
+        ? ` (${runResult.errMessage})`
+        : runResult.status != null
+          ? ` (the CLI exited ${runResult.status})`
+          : "";
+      const tail = runResult.stderrTail ? `: ${runResult.stderrTail}` : "";
+      const left = isGit ? `\`${folderPath}\` is unchanged` : `check \`${folderPath}\` for any partial edits`;
+      body = `The run didn't finish${why}${tail}. ${left} — mention me to retry.`;
+    }
+    await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body });
+    return { status: "run-failed" };
+  }
+  if (!runResult.failed && isGit && !hasChanges(changed)) {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body: `The run finished but nothing changed in \`${folderPath}\`. Mention me to try a different approach.`,
+    });
+    return { status: "no-changes" };
+  }
+
+  // --- Report card + decision loop ---
+  const postFolderReport = async (rr, ch) => {
+    const report = buildReport(rr, ch);
+    const res = await tool("post_report", { channelId, parentId: threadRoot, broadcast: true, ...report });
+    return res?.messageId ?? null;
+  };
+  let reportMessageId = await postFolderReport(runResult, changed);
+  let decision = await awaitDecision({ tool, channelId, reportMessageId, cfg, deps, parentId: threadRoot, signal });
+
+  const maxRounds = cfg.maxRounds || 3;
+  let round = 1;
+  while (decision.kind === "changes" && round < maxRounds) {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      body: `Revising in \`${folderPath}\` with your feedback${decision.note ? `: ${decision.note}` : ""} (round ${round + 1}/${maxRounds}).`,
+    });
+    runResult = await runFolderCli(
+      folderTaskPrompt({ message, context, brief, folderPath }) +
+        `\n\nReviewer feedback to address: ${decision.note || "(see the channel)"}`,
+    );
+    if (runResult.aborted) {
+      await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body: `Stopped — I left \`${folderPath}\` as it was.` });
+      return { status: "cancelled" };
+    }
+    changed = computeChanged();
+    reportMessageId = await postFolderReport(runResult, changed);
+    decision = await awaitDecision({ tool, channelId, reportMessageId, cfg, deps, parentId: threadRoot, signal });
+    round += 1;
+  }
+
+  // --- Terminal ---
+  if (decision.kind === "approved") {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body: `${lead}approved — the changes are already live in \`${folderPath}\`.`,
+    });
+    return { status: "folder-done", decision: "approved" };
+  }
+
+  if (decision.kind === "rejected") {
+    if (!isGit) {
+      const all = [...changed.created, ...changed.modified, ...changed.deleted];
+      await tool("post_message", {
+        channelId,
+        parentId: threadRoot,
+        broadcast: Boolean(threadRoot),
+        body:
+          `Rejected — but \`${folderPath}\` isn't a git repository, so I can't automatically undo the changes. ` +
+          (all.length ? `I touched:\n${renderChangedList(changed)}\n\nRevert these by hand.` : `Please review the folder and revert by hand.`),
+      });
+      return { status: "folder-done", decision: "rejected", reverted: false };
+    }
+    // Revert ONLY what the run itself changed: checkout tracked modifications +
+    // deletions, remove untracked files the run created. Never a blanket reset —
+    // pre-existing local changes stay untouched.
+    const trackedToRestore = [...changed.modified, ...changed.deleted];
+    if (trackedToRestore.length) git(folderPath, ["checkout", "--", ...trackedToRestore]);
+    if (changed.created.length) git(folderPath, ["clean", "-fd", "--", ...changed.created]);
+    const revertedList = renderChangedList(changed);
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body:
+        `Rejected — reverted my changes in \`${folderPath}\`.` +
+        (revertedList ? `\n\nRestored:\n${revertedList}` : "") +
+        (dirtyBefore ? `\n\nYour pre-existing local changes were left untouched.` : ""),
+    });
+    return { status: "folder-done", decision: "rejected", reverted: true };
+  }
+
+  if (decision.kind === "cancelled") {
+    await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body: `Stopped — the changes so far are still in \`${folderPath}\`.` });
+    return { status: "cancelled" };
+  }
+
+  // Timeout (or a leftover 'changes' past the round cap): note + release, same as
+  // the repo flow.
+  await tool("post_message", {
+    channelId,
+    parentId: threadRoot,
+    broadcast: Boolean(threadRoot),
+    body: `Still awaiting your review of the changes in \`${folderPath}\`. They're already applied — mention me to revise or revert once you've decided.`,
+  });
+  return { status: "folder-done", decision: "timeout" };
+}
+
 /** 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 = {}) {
@@ -505,7 +1275,10 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   const parentId = message.parentId ?? null;
 
   const { links = [] } = await tool("get_links", { channelId }).catch(() => ({ links: [] }));
-  const repoLink = links.find((l) => l.repo_full_name);
+  // A folder link (0324) carries the folder PATH in repo_full_name for display —
+  // it is NOT a GitHub repo, so it must never be picked as the channel's repo.
+  // Exclude kind='folder'; pr/branch/repo rows with repo_full_name still count.
+  const repoLink = links.find((l) => l.kind !== "folder" && l.repo_full_name);
   // Workspace memory ("soul") — shared project context the agent should know.
   const { memory: workspaceMemory = null } = await tool("get_workspace_memory", {}).catch(() => ({
     memory: null,
@@ -515,26 +1288,135 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // crucial: a reply like "yeah, do it" only means something against what was
   // just said.
   const context = await fetchContext({ channelId, tool, parentId });
+  const mode = agentMode(message);
+
+  // 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.
+  // No repo linked → either FOLDER mode (0322: a channel mapped to a plain local
+  // folder can still get coding work done) or, failing that, just reply. A linked
+  // repo always wins — the folder map is only consulted when there's no repo link.
   if (!repoLink) {
+    const folderPath = resolveFolderPath(cfg, channelId);
+    if (folderPath) {
+      // Same chat-vs-code decision the repo path uses: mode 'ask'/'ship' short-
+      // circuit exactly as in the repo flow, otherwise the LLM router judges intent
+      // (its CLI call goes through deps.runCli so folder mode is unit-testable).
+      const routed =
+        mode === "ask"
+          ? { code: false, reply: null }
+          : mode === "ship"
+            ? { code: true, task: message.body }
+            : await routeIntent({
+                name: me?.agentName || "an assistant",
+                repoFullName: folderPath,
+                transcript: context.transcript,
+                workspaceMemory,
+                cfg,
+                signal,
+                runCliFn: deps.runCli,
+              });
+      if (routed.aborted || signal?.aborted) {
+        await tool("post_message", { channelId, parentId, body: "Stopped." });
+        return { status: "chat" };
+      }
+      if (routed.code) {
+        return await handleFolderTask({
+          message,
+          channelId,
+          tool,
+          me,
+          caps,
+          cfg,
+          deps,
+          signal,
+          parentId,
+          folderPath,
+          brief: routed.task,
+          workspaceMemory,
+          context,
+        });
+      }
+      // Not a coding task → post the router's reply if it produced one, else fall
+      // through to a normal conversational reply.
+      if (routed.reply) {
+        await tool("post_message", { channelId, parentId, body: routed.reply });
+        return { status: "chat" };
+      }
+    }
     await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps });
     return { status: "chat" };
   }
   const repoFullName = repoLink.repo_full_name;
 
+  if (mode === "ask") {
+    await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps });
+    return { status: "chat" };
+  }
+
+  // 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.
-  const routed = await routeIntent({
-    name: me?.agentName || "an assistant",
-    repoFullName,
-    transcript: context.transcript,
-    workspaceMemory,
-    cfg,
-    signal,
-  });
+  // 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 =
+    mode === "ship"
+      ? { code: true, task: message.body, followupSignal: null }
+      : await routeIntent({
+          name: me?.agentName || "an assistant",
+          repoFullName,
+          transcript: context.transcript,
+          workspaceMemory,
+          cfg,
+          signal,
+          hasActiveRun: activeRunOpen,
+        });
   if (routed.aborted || signal?.aborted) {
     await tool("post_message", { channelId, parentId, body: "Stopped." });
     return { status: "chat" };
@@ -552,6 +1434,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
@@ -627,23 +1523,95 @@ 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;
   // 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
@@ -652,7 +1620,44 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // 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;
-  if (ackId && caps.editMessage && cfg.chatCmd) {
+  const updateChannelMarker = async (body) => {
+    if (!ackId || parentId || !body) return;
+    await tool("edit_message", { messageId: ackId, body }).catch(() => {});
+  };
+  // 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({
@@ -669,9 +1674,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();
@@ -714,27 +1759,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");
@@ -763,9 +1920,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 };
@@ -779,6 +1935,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({
@@ -821,19 +2007,66 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // Post the right cancel message: honest about whether cleanup actually worked.
   const postStopped = async () => {
     const clean = discardBranch();
+    const body = clean
+      ? `Stopped — discarded \`${branch}\`.`
+      : `Stopped, but couldn't fully clean \`${branch}\` — run \`git reset --hard && git switch ${startRef.ref || cfg.defaultBranch}\` in ${repoPath}.`;
     await tool("post_message", {
       channelId,
       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}.`,
+      body,
     });
+    await updateChannelMarker(compactRunMarker("cancelled", branch));
     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 {
+      // Pass the task's channelId so the server scopes recall to this project AND
+      // can apply the guest gate (0298): the daemon's token is long-lived with no
+      // bound channel, so the server relies on this per-call channelId to decide
+      // whether a guest is present. Residual: a recall that omits channelId can't
+      // be guest-gated server-side (no channel to check) — the daemon always
+      // passes it here, so that path is covered.
+      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) {
@@ -850,10 +2083,15 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           `re-mention me to ship or discard.`,
       });
       await finalizeProgress(`\`${branch}\` has the agent's own commits — needs review.`);
+      await updateChannelMarker(compactRunMarker("changes", branch));
       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,
@@ -863,12 +2101,23 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       channelId,
       deps,
       parentId: threadRoot,
+      settleId: selfSettleId,
+      runId,
     });
+    await recordSession(selfResult.prUrl);
+    await updateChannelMarker(compactRunMarker(selfResult.status, selfResult.branch));
+    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})`
@@ -876,16 +2125,23 @@ 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: 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]);
+    }
+    await updateChannelMarker(
+      compactRunMarker(staged.failed ? "run-failed" : "no-changes", branch),
+    );
     return { status: staged.failed ? "run-failed" : "no-changes" };
   }
 
@@ -895,20 +2151,39 @@ 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 final report instead.
+    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: 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);
+    await updateChannelMarker(compactRunMarker(result.status, result.branch));
+    return { ...result, stat: staged.stat, sessionId: runSessionId };
   }
 
   await finalizeProgress(`Coding done on \`${branch}\` — proposal below for review.`);
@@ -948,16 +2223,22 @@ 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: 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);
+  await updateChannelMarker(compactRunMarker(result.status, result.branch));
+  return { ...result, reportMessageId: proposal.reportMessageId, stat: proposal.stat, rounds: round, sessionId: runSessionId };
   } finally {
     // Whatever happened, give the user their uncommitted work back.
     await restoreStash();