hilos-agent 0.10.1 → 0.11.2

package/src/handler.mjs

@@ -8,7 +8,7 @@
 // and pushes only after approval. Your code + credentials stay local.
 
 import { spawnSync } from "node:child_process";
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { rmSync, mkdtempSync, existsSync } from "node:fs";
 import { hostname, tmpdir } from "node:os";
 import { join } from "node:path";
@@ -37,7 +37,15 @@ import {
   scrubHilosEnv,
   envForCwd,
 } from "./cli.mjs";
+import { commandArgv } from "./argv.mjs";
 import { makeStreamParser, createUsageFold } from "./agent-events.mjs";
+import {
+  createDirectionInbox,
+  directionTurnPrompt,
+  directionTurnRan,
+  MAX_DIRECTION_TURNS,
+  readPendingInputs,
+} from "./run-inputs.mjs";
 import {
   detectVendor,
   chatWebArgs,
@@ -54,6 +62,8 @@ import {
   webToolEnv,
 } from "./progress-emitter.mjs";
 import { createTranscriptTap } from "./transcript.mjs";
+import { createLocalHarnessEmitter } from "./local-harness-transport.mjs";
+import { releaseDaemonIterateClaim } from "./iterate-claim-recovery.mjs";
 import { imagePromptNote, renderAttachmentLine } from "./attachments.mjs";
 import { resolveFollowupMode, classifyFollowupCue, normalizeSignal } from "./followup.mjs";
 import {
@@ -87,6 +97,15 @@ import {
 } from "./codex-mcp-session.mjs";
 import { createUngatedRunNotice } from "./permission-gate.mjs";
 import { webMcpAgentPrompt } from "./webmcp-bridge.mjs";
+import {
+  conflictCommitTitle,
+  conflictPromptBlock,
+  conflictRepairBrief,
+  remainingConflictFiles,
+  startConflictMerge,
+  validateConflictMergeState,
+  validConflictRecovery,
+} from "./conflicts.mjs";
 
 /**
  * The environment for a coding/chat CLI run. runCli always strips HILOS_* on top
@@ -250,6 +269,12 @@ function defaultDeps() {
       const url = (r.stdout || "").trim().split("\n").filter(Boolean).pop() || null;
       return { ok: r.status === 0, url, stdout: r.stdout || "", stderr: r.stderr || "" };
     },
+    closePR: (cwd, url) =>
+      spawnSync("gh", ["pr", "close", url], {
+        cwd,
+        env: cwdEnv(cwd),
+        encoding: "utf8",
+      }),
     // The open PR for a branch, if one already exists — so when the CLI opened a
     // PR itself we report THAT instead of opening a duplicate.
     findPR: (cwd, branch) => {
@@ -392,13 +417,31 @@ function openCodePermissionCallbacks({
  * `onStopRequested` is called at most once per sender and must never throw into
  * the run — it is the daemon's cue to tear the process group down.
  *
+ * `onPendingInputs` (1182) receives the room directions a reply lists for a
+ * run-bound sender; it must never throw into the run either.
+ *
  * @param {{ tool: Function, statusId: string, runId?: string|null,
- *   onStopRequested?: (info: {by: string|null}) => any }} o
+ *   onStopRequested?: (info: {by: string|null}) => any,
+ *   onPendingInputs?: (list: Array<{inputId: string, ordinal: number, body: string}>) => any }} o
  */
-export function createProgressSender({ tool, statusId, runId = null, onStopRequested }) {
+export function createProgressSender({ tool, statusId, runId = null, onStopRequested, onPendingInputs }) {
   let inflight = Promise.resolve();
   let stopSeen = false;
+  // 1182 — a room direction rides home on the same beat as the stop. Handed
+  // over on every reply that carries one (the inbox deduplicates), and never
+  // allowed to throw into the run.
+  const takeInputs = (res) => {
+    if (!onPendingInputs || !runId) return;
+    const list = readPendingInputs(res);
+    if (list.length === 0) return;
+    try {
+      onPendingInputs(list);
+    } catch {
+      /* a direction hand-off must never break the run */
+    }
+  };
   const takeStop = (res) => {
+    takeInputs(res);
     if (!res || res.stopRequested !== true) return false;
     if (stopSeen || !onStopRequested) return true;
     stopSeen = true;
@@ -606,6 +649,7 @@ async function runClaudeGatedCli({
   permissionCallbacks,
   sessionId = "",
   resolveSessionId,
+  beforeSpawn,
   log = console,
 }) {
   const server = await deps.startClaudePermissionServer({
@@ -630,6 +674,7 @@ async function runClaudeGatedCli({
       signal,
       env: claudeGateEnv(cfg),
       onData,
+      beforeSpawn,
       // 0785 — a CLI that rejects the gate flags is retried without them. This
       // fires BEFORE that ungated retry is spawned, so the room hears about the
       // downgrade first rather than after the fact.
@@ -657,7 +702,7 @@ function codexRunIsGated(cfg, caps) {
   return shouldGateCodexPermissions({
     vendor: detectVendor(cfg?.codingCmd),
     runtimePermissions: caps?.runtimePermissions,
-    codeArgs: String(cfg?.codingCmd || "").split(" ").filter(Boolean).slice(1),
+    codeArgs: commandArgv(String(cfg?.codingCmd || "")).slice(1),
   });
 }
 
@@ -695,8 +740,19 @@ async function runCodexGatedSession({
   signal,
   onData,
   onEvent,
+  beforeSpawn,
   permissionCallbacks,
 }) {
+  if (typeof beforeSpawn === "function" && (await beforeSpawn()) === false) {
+    return {
+      status: null,
+      stdout: "",
+      stderr: "",
+      aborted: true,
+      authorityLost: true,
+      error: new Error("execution authority lost before spawn"),
+    };
+  }
   const run = await deps.runCodexMcpSession({
     cmd,
     cwd,
@@ -713,6 +769,7 @@ async function runCodexGatedSession({
     env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
     onData,
     onEvent,
+    beforeSpawn,
     ...permissionCallbacks,
   });
   if (!codexMcpTransportUnavailable(run)) return run;
@@ -736,6 +793,7 @@ async function runCodexGatedSession({
     signal,
     env: codingChildEnv(cfg),
     onData,
+    beforeSpawn,
   });
   return { ...fallback, permissionGateDropped: true };
 }
@@ -820,7 +878,339 @@ function githubProvenance({ cfg, me, message, channelId, runId, summary }) {
   };
 }
 
-async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, existingPrUrl, settleId, runId, provenance = {}, usageArgs = {} }) {
+/**
+ * Capture the exact local commit and remote branch value that a daemon push is
+ * allowed to replace. A failed probe is not "branch absent": without a known
+ * before-value there is no safe force-with-lease compensation, so callers must
+ * refuse the push.
+ */
+export function captureRemoteRefLease(git, repoPath, branch) {
+  const ref = `refs/heads/${branch}`;
+  const local = git(repoPath, ["rev-parse", "--verify", "HEAD"]);
+  const headSha = (local.stdout || "").trim();
+  if (local.status !== 0 || !headSha || /\s/.test(headSha)) {
+    return { ok: false, error: "could not resolve the exact local HEAD" };
+  }
+
+  const remote = git(repoPath, ["ls-remote", "--heads", "origin", ref]);
+  if (remote.status !== 0) {
+    return {
+      ok: false,
+      error: `could not read ${ref} from origin: ${(remote.stderr || "git ls-remote failed").trim()}`,
+    };
+  }
+  const lines = (remote.stdout || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length === 0) {
+    return { ok: true, ref, headSha, priorSha: null };
+  }
+  if (lines.length !== 1) {
+    return { ok: false, error: `origin returned an ambiguous value for ${ref}` };
+  }
+  const [priorSha, remoteRef, ...extra] = lines[0].split(/\s+/);
+  if (!priorSha || remoteRef !== ref || extra.length > 0) {
+    return { ok: false, error: `origin returned an invalid value for ${ref}` };
+  }
+  // `ls-remote` proves the ref value but does not guarantee its object exists
+  // locally. Fetch the advertised ref without moving a local branch so a later
+  // restore can name the exact prior commit.
+  const fetched = git(repoPath, ["fetch", "--no-tags", "origin", ref]);
+  if (fetched.status !== 0) {
+    return { ok: false, error: `could not fetch the exact prior value of ${ref}` };
+  }
+  const priorObject = git(repoPath, ["cat-file", "-e", `${priorSha}^{commit}`]);
+  if (priorObject.status !== 0) {
+    return { ok: false, error: `the exact prior value of ${ref} is unavailable locally` };
+  }
+  // An exact lease must not become permission to rewrite somebody else's
+  // branch. Only a fast-forward from the value we observed may ship.
+  const fastForward = git(repoPath, ["merge-base", "--is-ancestor", priorSha, headSha]);
+  if (fastForward.status !== 0) {
+    return { ok: false, error: `local HEAD is not a descendant of the exact ${ref} value` };
+  }
+  return { ok: true, ref, headSha, priorSha };
+}
+
+function pushWithRemoteRefLease(git, repoPath, args, lease) {
+  const exactLease = `--force-with-lease=${lease.ref}:${lease.priorSha || ""}`;
+  return git(repoPath, [args[0], exactLease, ...args.slice(1)]);
+}
+
+/**
+ * Undo only the ref value written by this run. If another writer has advanced
+ * the branch, the lease fails and their work is left untouched.
+ */
+export function compensateRemoteRef(git, repoPath, lease) {
+  const restore = lease.priorSha ? `${lease.priorSha}:${lease.ref}` : `:${lease.ref}`;
+  let lastPush = null;
+  let lastProbe = null;
+  let repairable = true;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    lastPush = git(repoPath, [
+      "push",
+      `--force-with-lease=${lease.ref}:${lease.headSha}`,
+      "origin",
+      restore,
+    ]);
+    if (lastPush.status === 0) {
+      return { ...lastPush, confirmed: true, repairable: false };
+    }
+
+    // A transport failure can lose the successful response. Read the exact ref
+    // before deciding that rollback failed; repeating the same exact lease is
+    // safe, but a failed response by itself is not proof that Stop completed.
+    lastProbe = git(repoPath, ["ls-remote", "--heads", "origin", lease.ref]);
+    if (lastProbe.status === 0) {
+      const refs = (lastProbe.stdout || "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+      const [remoteSha, remoteRef, ...extra] = refs.length === 1
+        ? refs[0].split(/\s+/)
+        : [];
+      const isExpected = lease.priorSha
+        ? remoteSha === lease.priorSha && remoteRef === lease.ref && extra.length === 0
+        : refs.length === 0;
+      if (isExpected) {
+        return {
+          ...lastPush,
+          status: 0,
+          confirmed: true,
+          repairable: false,
+          verifiedAfterAmbiguousPush: true,
+        };
+      }
+      // Another writer won after our push. The exact lease protects their ref,
+      // so do not keep retrying a restoration that can no longer be ours.
+      if (
+        refs.length !== 1 ||
+        remoteSha !== lease.headSha ||
+        remoteRef !== lease.ref ||
+        extra.length > 0
+      ) {
+        repairable = false;
+        break;
+      }
+    }
+  }
+  return {
+    ...(lastPush || { status: 1, stdout: "", stderr: "compensation did not run" }),
+    confirmed: false,
+    // Replaying this same exact lease can never overwrite another writer. The
+    // receipt below gives the daemon (and its operator) everything needed to
+    // retry or repair without guessing which ref this run owned.
+    repairable,
+    receipt: {
+      ref: lease.ref,
+      headSha: lease.headSha,
+      priorSha: lease.priorSha,
+    },
+    probeError:
+      lastProbe?.status === 0
+        ? null
+        : (lastProbe?.stderr || "could not verify the remote ref after compensation").trim(),
+  };
+}
+
+function stopAfterRemoteRefCompensation(
+  git,
+  repoPath,
+  branch,
+  lease,
+  { closePR, prUrl } = {},
+) {
+  const compensation = compensateRemoteRef(git, repoPath, lease);
+  if (!compensation.confirmed) {
+    return {
+      status: "stop-compensation-pending",
+      branch,
+      compensation: {
+        ...compensation,
+        receipt: { ...compensation.receipt, ...(prUrl ? { prUrl } : {}) },
+      },
+    };
+  }
+  if (prUrl) {
+    let closure = null;
+    if (typeof closePR === "function") {
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+          closure = closePR(repoPath, prUrl);
+        } catch (error) {
+          closure = {
+            status: null,
+            stderr: error instanceof Error ? error.message : String(error),
+          };
+        }
+        if (closure?.status === 0) return { status: "stopped", branch };
+      }
+    }
+    return {
+      status: "stop-compensation-pending",
+      branch,
+      compensation: {
+        confirmed: false,
+        branchRestored: true,
+        prClosed: false,
+        repairable: true,
+        stderr: closure?.stderr || "pull request closure could not be confirmed",
+        receipt: {
+          ref: lease.ref,
+          headSha: lease.headSha,
+          priorSha: lease.priorSha,
+          prUrl,
+        },
+      },
+    };
+  }
+  return { status: "stopped", branch };
+}
+
+async function postFinalReportWithReplay({
+  tool,
+  args,
+  runId,
+  finishStatus,
+  rollbackIfStopped,
+}) {
+  try {
+    return { result: await tool("post_report", args) };
+  } catch (error) {
+    // A transport can lose the successful response after the server atomically
+    // commits a run-bound final report. Re-read Stop before doing anything:
+    // once the person has stopped the run, compensate shipping rather than
+    // replaying or publishing another report.
+    const stopped = await rollbackIfStopped();
+    if (stopped) return { stopped };
+
+    // Run-bound final reports are exact-replay safe in the server RPC. Reuse
+    // the very same object so run id, finish status, receipt, and card identity
+    // cannot drift between the uncertain attempt and its one replay. Legacy
+    // reports have no atomic run settlement and remain single-attempt.
+    if (!runId || !finishStatus) throw error;
+
+    try {
+      return { result: await tool("post_report", args) };
+    } catch (retryError) {
+      const stoppedAfterRetry = await rollbackIfStopped();
+      if (stoppedAfterRetry) return { stopped: stoppedAfterRetry };
+      throw retryError;
+    }
+  }
+}
+
+/**
+ * @param {{ tool: Function, runId: string, expectedIterateTurn: number,
+ *   claimId?: string, recoveryStore?: {
+ *     persist: (record: { runId: string, expectedIterateTurn: number, claimId: string }) => boolean,
+ *     remove: (claimId: string) => boolean
+ *   } }} options
+ */
+export async function claimDaemonIterate({
+  tool,
+  runId,
+  expectedIterateTurn,
+  claimId = randomUUID(),
+  recoveryStore,
+}) {
+  const record = { runId, expectedIterateTurn, claimId };
+  const args = {
+    runId,
+    status: "running",
+    claimIterate: true,
+    expectedIterateTurn,
+    claimId,
+  };
+  // Rolling upgrade compatibility: the preceding server supported the
+  // idempotent claim token but not exact confirm/release. Without a recovery
+  // store (created only when the full schema is advertised), preserve that
+  // bounded same-token replay byte-for-byte and do not enable later guards.
+  if (!recoveryStore) {
+    try {
+      return await tool("update_run", args);
+    } catch {
+      return await tool("update_run", args);
+    }
+  }
+  if (!recoveryStore.persist(record)) {
+    throw new Error("the Iterate claim recovery record could not be persisted");
+  }
+  let lastError;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const result = await tool("update_run", args);
+      if (
+        Number.isSafeInteger(result?.iterateTurn) &&
+        Number(result.iterateTurn) === expectedIterateTurn + 1
+      ) {
+        const claimedTurn = Number(result.iterateTurn);
+        const confirmed = await confirmDaemonIterateClaim({
+          tool,
+          runId,
+          iterateTurn: claimedTurn,
+          claimId,
+        });
+        if (!confirmed) {
+          lastError = new Error("the Iterate claim could not be confirmed");
+          break;
+        }
+        // Keep the exact receipt durable for the whole queue-job lifecycle.
+        // The poller defers reconciliation while this job is active, then
+        // exact-releases (or observes final settlement) before accepting more
+        // work. A crash anywhere before/during the child leaves the receipt for
+        // the next daemon instead of stranding a running generation.
+        return { ...result, claimId };
+      }
+      lastError = new Error("the server did not return the claimed Iterate generation");
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  // Neither bounded response proved execution authority. Hand only this exact
+  // token back; a lost release response leaves the durable record for startup.
+  try {
+    await releaseDaemonIterateClaim({ tool, recoveryStore, record });
+  } catch {
+    /* the durable record is the retry */
+  }
+  throw lastError;
+}
+
+/**
+ * Prove that this worker still owns one exact Iterate generation. Stop,
+ * release, a final report, or a newer generation all make the replay-safe
+ * confirmation return `not-owned` without changing the run.
+ */
+export async function confirmDaemonIterateClaim({ tool, runId, iterateTurn, claimId }) {
+  const args = {
+    runId,
+    confirmIterateClaim: true,
+    expectedIterateTurn: iterateTurn,
+    claimId,
+  };
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const result = await tool("update_run", args);
+      if (
+        result?.iterateClaimKind === "confirmed" &&
+        Number.isSafeInteger(result?.iterateTurn) &&
+        Number(result.iterateTurn) === iterateTurn
+      ) {
+        return true;
+      }
+      return false;
+    } catch {
+      // Read-only and exact-token fenced: one replay is safe. Two missing
+      // responses mean execution authority is unproven, so fail closed.
+    }
+  }
+  return false;
+}
+
+export async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, existingPrUrl, settleId, runId, iterateTurn = 0, provenance = {}, usageArgs = {}, shouldContinue }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
   // `parentId` here is the run's thread root. Terminal outcomes ask the server
@@ -837,6 +1227,7 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       });
       return { status: "nothing-staged", branch };
     }
+    if (shouldContinue && !(await shouldContinue())) return { status: "stopped", branch };
     const commit = deps.git(repoPath, ["commit", "-m", commitMessage(task, provenance)]);
     if (commit.status !== 0) {
       await tool("post_message", {
@@ -847,7 +1238,28 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       });
       return { status: "commit-failed", branch };
     }
-    const push = deps.git(repoPath, ["push", "-u", "origin", branch]);
+    // Re-check at the irreversible external boundary. The final progress poll
+    // is not enough: Stop can land while the local commit is being created.
+    if (shouldContinue && !(await shouldContinue())) return { status: "stopped", branch };
+    const pushLease = captureRemoteRefLease(deps.git, repoPath, branch);
+    if (!pushLease.ok) {
+      await tool("post_message", {
+        channelId,
+        parentId,
+        broadcast: true,
+        body: `Approved, but hilos refused to push because branch ownership could not be established: ${pushLease.error}`,
+      });
+      return { status: "push-ownership-unknown", branch };
+    }
+    // The remote probe may itself take long enough for Stop to arrive. Do not
+    // let a lease captured before that Stop authorize a later push.
+    if (shouldContinue && !(await shouldContinue())) return { status: "stopped", branch };
+    const push = pushWithRemoteRefLease(
+      deps.git,
+      repoPath,
+      ["push", "-u", "origin", branch],
+      pushLease,
+    );
     if (push.status !== 0) {
       await tool("post_message", {
         channelId,
@@ -857,6 +1269,13 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       });
       return { status: "push-failed", branch };
     }
+    // A remote ref update is atomic outside hilos, so Stop cannot interrupt a
+    // push already in flight. Fence the next external effect immediately: a
+    // Stop that landed during push must never go on to create/reuse a PR or
+    // publish a completion report.
+    if (shouldContinue && !(await shouldContinue())) {
+      return stopAfterRemoteRefCompensation(deps.git, repoPath, branch, pushLease);
+    }
     const { title, body } = prTitleBody(task, branch, provenance);
     // Continuing an existing PR (request-changes rework): the push already
     // updated it — reuse its URL instead of opening a duplicate. Otherwise open
@@ -864,12 +1283,34 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     const pr = existingPrUrl
       ? { ok: true, url: existingPrUrl }
       : deps.openPR(repoPath, { title, body, branch, base: cfg.defaultBranch });
+    const rollbackIfStopped = async () => {
+      if (!shouldContinue || (await shouldContinue())) return null;
+      return stopAfterRemoteRefCompensation(deps.git, repoPath, branch, pushLease, {
+        ...(!existingPrUrl && pr.ok && pr.url
+          ? { closePR: deps.closePR, prUrl: pr.url }
+          : {}),
+      });
+    };
+    const stoppedAfterPr = await rollbackIfStopped();
+    if (stoppedAfterPr) return stoppedAfterPr;
     // 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,
+      ...(runId ? { runId } : {}),
+      ...(runId ? { iterateTurn } : {}),
+      ...(runId ? { reportRequestId: randomUUID() } : {}),
+      ...(runId
+        ? {
+            finishStatus: pr.ok && pr.url ? "awaiting_review" : "failed",
+            finishBranch: branch,
+            ...(!(pr.ok && pr.url)
+              ? { finishReason: oneLine((pr.stderr || "GitHub did not return a pull request URL").trim(), 300) }
+              : {}),
+          }
+        : {}),
       title: `Shipped: ${title}`,
       summary:
         pr.ok && pr.url
@@ -887,28 +1328,28 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
     // 0792 — keep the id of the card this run settled onto, so the caller can
     // mark it with the run's transcript. `settleId` is that card when the run
     // streamed onto a live status message; otherwise it is the fresh report.
-    const reportRes = await tool(
-      "post_report",
-      settleId
-        ? { ...reportArgs, messageId: settleId, broadcast: true }
-        : { ...reportArgs, parentId, broadcast: true },
-    );
+    const stoppedBeforeReport = await rollbackIfStopped();
+    if (stoppedBeforeReport) return stoppedBeforeReport;
+    const finalReportArgs = settleId
+      ? { ...reportArgs, messageId: settleId, broadcast: true }
+      : { ...reportArgs, parentId, broadcast: true };
+    const reportAttempt = await postFinalReportWithReplay({
+      tool,
+      args: finalReportArgs,
+      runId,
+      finishStatus: reportArgs.finishStatus,
+      rollbackIfStopped,
+    });
+    if (reportAttempt.stopped) return reportAttempt.stopped;
+    const reportRes = reportAttempt.result;
+    const stoppedAfterReport = await rollbackIfStopped();
+    if (stoppedAfterReport) return stoppedAfterReport;
     const reportMsgId = settleId || reportRes?.messageId || null;
     // 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",
-        // 0792: record the card even when it was a fresh report rather than a
-        // settle — it is the run's card either way, and the transcript upload
-        // falls back to this exact field when it is not handed an id.
-        ...(reportMsgId ? { reportMsgId } : {}),
-      }).catch(() => {});
-    }
+    // The run gate, PR/branch receipt, and report pointer were committed by
+    // post_report under one run-row lock. A second update_run here used to
+    // leave a window where the card existed while Stop still looked current.
     return { status: "pushed", branch, prUrl: pr.ok ? pr.url : null, reportMsgId };
   }
 
@@ -949,14 +1390,34 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
  * switched to `main` would otherwise make `gh` try to open main → main. Used
  * only when NOT gated (bias-to-action).
  */
-async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, settleId, runId, provenance = {}, usageArgs = {} }) {
+export async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, settleId, runId, iterateTurn = 0, provenance = {}, usageArgs = {}, shouldContinue }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
   const currentBranch =
     (deps.git(repoPath, ["symbolic-ref", "--quiet", "--short", "HEAD"]).stdout || "").trim();
   const ship = selfDrivenShipPlan(currentBranch, branch);
-  const push = deps.git(repoPath, ship.pushArgs);
-  let prUrl = deps.findPR ? deps.findPR(repoPath, ship.headBranch) : null;
+  if (shouldContinue && !(await shouldContinue())) return { status: "stopped", branch };
+  const pushLease = captureRemoteRefLease(deps.git, repoPath, ship.headBranch);
+  if (pushLease.ok && shouldContinue && !(await shouldContinue())) {
+    return { status: "stopped", branch };
+  }
+  const push = pushLease.ok
+    ? pushWithRemoteRefLease(deps.git, repoPath, ship.pushArgs, pushLease)
+    : {
+        status: 1,
+        stdout: "",
+        stderr: `hilos refused to push because branch ownership could not be established: ${pushLease.error}`,
+      };
+  if (shouldContinue && !(await shouldContinue())) {
+    if (push.status === 0 && pushLease.ok) {
+      return stopAfterRemoteRefCompensation(deps.git, repoPath, branch, pushLease);
+    }
+    return { status: "stopped", branch };
+  }
+  // A failed/declined push cannot ship an existing PR either: its remote head
+  // is not this run's verified commit.
+  let prUrl = push.status === 0 && deps.findPR ? deps.findPR(repoPath, ship.headBranch) : null;
+  const existingPrUrl = prUrl;
   let prAttempt = null;
   if (!prUrl && push.status === 0) {
     const { title, body } = prTitleBody(task, ship.headBranch, provenance);
@@ -968,6 +1429,16 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
     });
     prUrl = prAttempt.ok && prAttempt.url ? prAttempt.url : null;
   }
+  const rollbackIfStopped = async () => {
+    if (!shouldContinue || (await shouldContinue())) return null;
+    return push.status === 0 && pushLease.ok
+      ? stopAfterRemoteRefCompensation(deps.git, repoPath, branch, pushLease, {
+          ...(!existingPrUrl && prUrl ? { closePR: deps.closePR, prUrl } : {}),
+        })
+      : { status: "stopped", branch };
+  };
+  const stoppedAfterPr = await rollbackIfStopped();
+  if (stoppedAfterPr) return stoppedAfterPr;
   const { title } = prTitleBody(task, ship.headBranch, provenance);
   const recoveredNote = ship.recoveredFrom
     ? ` The child had switched to \`${ship.recoveredFrom}\`; hilos recovered its HEAD onto \`${ship.headBranch}\`.`
@@ -984,6 +1455,23 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
   // Otherwise post a fresh final report.
   const reportArgs = {
     channelId,
+    ...(runId ? { runId } : {}),
+    ...(runId ? { iterateTurn } : {}),
+    ...(runId ? { reportRequestId: randomUUID() } : {}),
+    ...(runId
+      ? {
+          finishStatus: prUrl ? "awaiting_review" : "failed",
+          finishBranch: ship.headBranch,
+          ...(!prUrl
+            ? {
+                finishReason:
+                  push.status !== 0
+                    ? oneLine((push.stderr || "git push failed").trim(), 300)
+                    : prFailure || "GitHub did not return a pull request URL",
+              }
+            : {}),
+        }
+      : {}),
     title: prUrl
       ? `Shipped: ${title}`
       : push.status === 0
@@ -1004,32 +1492,26 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
     // 0787 — an autonomous run's receipt rides its one and only report.
     ...usageArgs,
   };
-  const reportRes = await tool(
-    "post_report",
-    settleId
-      ? { ...reportArgs, messageId: settleId, broadcast: true }
-      : { ...reportArgs, parentId, broadcast: true },
-  );
+  const stoppedBeforeReport = await rollbackIfStopped();
+  if (stoppedBeforeReport) return stoppedBeforeReport;
+  const finalReportArgs = settleId
+    ? { ...reportArgs, messageId: settleId, broadcast: true }
+    : { ...reportArgs, parentId, broadcast: true };
+  const reportAttempt = await postFinalReportWithReplay({
+    tool,
+    args: finalReportArgs,
+    runId,
+    finishStatus: reportArgs.finishStatus,
+    rollbackIfStopped,
+  });
+  if (reportAttempt.stopped) return reportAttempt.stopped;
+  const reportRes = reportAttempt.result;
+  const stoppedAfterReport = await rollbackIfStopped();
+  if (stoppedAfterReport) return stoppedAfterReport;
   // 0792 — the card this run settled onto, for the transcript stamp.
   const reportMsgId = settleId || reportRes?.messageId || null;
   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: prUrl ? "awaiting_review" : "failed",
-      ...(!prUrl
-        ? {
-            reason:
-              push.status !== 0
-                ? oneLine((push.stderr || "git push failed").trim(), 300)
-                : prFailure || "GitHub did not return a pull request URL",
-          }
-        : {}),
-      ...(reportMsgId ? { reportMsgId } : {}),
-    }).catch(() => {});
-  }
+  // post_report atomically bound this card, branch/PR receipt, and final gate.
   const status =
     push.status !== 0 ? "commit-local" : prUrl ? "pushed" : "pr-failed";
   return {
@@ -1117,10 +1599,21 @@ export function dmJudgmentBlock(implicitDm) {
  * `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).
  */
-export async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal, hasActiveRun = false, runCliFn, implicitDm = false }) {
-  const doRun = runCliFn || runCli; // folder mode injects deps.runCli; repo flow uses the import
+export async function routeIntent({
+  name,
+  repoFullName,
+  transcript,
+  workspaceMemory,
+  cfg,
+  signal,
+  hasActiveRun = false,
+  runCliFn,
+  implicitDm = false,
+  cwd = /** @type {string | undefined} */ (undefined),
+}) {
+  const doRun = runCliFn || runCli;
   const cmd = chatCmdFor(cfg);
-  const parts = cmd.split(" ").filter(Boolean);
+  const parts = commandArgv(cmd);
   // 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
@@ -1160,6 +1653,7 @@ export async function routeIntent({ name, repoFullName, transcript, workspaceMem
     timeoutMs: cfg.chatTimeoutMs || cfg.runTimeoutMs,
     label: "thinking",
     signal,
+    cwd,
   });
   if (run.aborted || signal?.aborted) return { aborted: true };
   const raw = (run.stdout || "").trim();
@@ -1342,18 +1836,29 @@ export function planAckPrompt(o) {
  * CLI. Bounded (≤45s) + best-effort: returns trimmed text, or null on
  * empty/timeout/error so the run keeps the instant template and never stalls.
  */
-async function proposePlanAck({ task, transcript, repoFullName, cfg, signal }) {
+export async function proposePlanAck({
+  task,
+  transcript,
+  repoFullName,
+  cfg,
+  signal,
+  cwd = /** @type {string | undefined} */ (undefined),
+  beforeSpawn = /** @type {(() => boolean | Promise<boolean>) | undefined} */ (undefined),
+  runCliFn = runCli,
+}) {
   const cmd = chatCmdFor(cfg);
   if (!cmd) return null;
-  const parts = cmd.split(" ").filter(Boolean);
+  const parts = commandArgv(cmd);
   const prompt = planAckPrompt({ task, transcript, repoFullName });
-  const run = await runCli({
+  const run = await runCliFn({
     cmd: parts[0],
     args: [...parts.slice(1), prompt],
     timeoutMs: Math.min(cfg.chatTimeoutMs || 90000, 45000),
     label: "thinking",
     signal,
+    cwd,
     env: codingChildEnv(cfg),
+    beforeSpawn,
   });
   if (run.aborted || signal?.aborted) return null;
   const text = (run.stdout || "").trim();
@@ -1372,7 +1877,21 @@ async function reactQuietly({ tool, caps, message, emoji }) {
 }
 
 /** Run the FAST chat CLI to produce a reply, using recent channel context. */
-async function respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps = {} }) {
+async function respondConversationally({
+  message,
+  channelId,
+  tool,
+  me,
+  cfg,
+  repoLink,
+  parentId,
+  workspaceMemory,
+  signal,
+  context,
+  caps = {},
+  runCliFn = runCli,
+  pathExistsFn = existsSync,
+}) {
   const implicitDm = message?.implicit === "dm";
   const { transcript } = context || (await fetchContext({ channelId, tool, parentId }));
   const name = me?.agentName || "an assistant";
@@ -1381,10 +1900,20 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   // "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 repoPath = repoLink ? resolveRepoPath(cfg, repoLink.repo_full_name) : null;
+  const mappedProjectPath = repoPath || folderPath || null;
+  const projectCwd =
+    mappedProjectPath && pathExistsFn(mappedProjectPath)
+      ? mappedProjectPath
+      : undefined;
   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.`
+    ? repoPath && !projectCwd
+      ? `This channel is connected to the repository ${repoLink.repo_full_name}, but its configured local checkout ${repoPath} is unavailable on this machine. Answer from the conversation and don't claim you inspected it.`
+      : `This channel is connected to the repository ${repoLink.repo_full_name}; assume that repo for any code work — don't ask which one.`
     : 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.`
+      ? projectCwd
+        ? `This channel is connected to the local folder ${folderPath} on this machine; assume that folder for any file work — don't ask which one.`
+        : `This channel is mapped to the local folder ${folderPath}, but that folder is unavailable on this machine. Answer from the conversation and don't claim you inspected it.`
       : `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 ` +
@@ -1398,7 +1927,7 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   // chatCmd is unset) bounded by chatTimeoutMs, so a casual reply lands in seconds
   // and a stalled model can't dead-air the channel for the full coding timeout.
   const cmd = chatCmdFor(cfg);
-  const parts = cmd.split(" ").filter(Boolean);
+  const parts = commandArgv(cmd);
   const chatVendor = detectVendor(cmd);
   const webArgs = chatWebArgs(chatVendor, parts.slice(1), {
     enabled: cfg.webSearch !== false,
@@ -1431,12 +1960,13 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
 
   let run;
   try {
-    run = await runCli({
+    run = await runCliFn({
       cmd: parts[0],
       args: [...parts.slice(1), ...webArgs, prompt],
       timeoutMs: cfg.chatTimeoutMs || cfg.runTimeoutMs,
       label: "thinking",
       signal,
+      cwd: projectCwd,
       env: codingChildWebEnv(cfg, chatVendor),
     });
   } finally {
@@ -1625,7 +2155,7 @@ async function reviewTask({ message, channelId, tool, me, cfg, workspaceMemory,
   // 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 || chatCmdFor(cfg);
-  const parts = String(cmd).split(" ").filter(Boolean);
+  const parts = commandArgv(String(cmd));
   let sandboxDir = null;
   try {
     sandboxDir = mkdtempSync(join(tmpdir(), "hilos-review-"));
@@ -2022,7 +2552,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
   // 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 parts = commandArgv(cfg.codingCmd);
     const vendor = detectVendor(cfg.codingCmd);
     const streamOn = Boolean(caps.postProgress);
     const streamArgs = streamOn ? codeStreamArgs(vendor) : [];
@@ -2556,7 +3086,7 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
 
 /** 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 = {}) {
+export async function handleTask({ message, channelId, tool, me, caps = {}, iterateClaimRecoveryStore = null }, cfg, depsOverride, opts = {}) {
   if (message.dispatch?.briefMarkdown) {
     message = { ...message, body: `${message.body}\n\n${message.dispatch.briefMarkdown}` };
   }
@@ -2572,12 +3102,32 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // 0860 — an untagged DM wake: addressed by the room, not by an @-handle. The
   // one context where the router/chat prompts offer the quiet option.
   const implicitDm = message.implicit === "dm";
+  // Set only when merge_pr returned the typed 0991 recovery hand-off. It turns
+  // the same human merge instruction into an existing-PR coding turn — no
+  // second prompt and no semantic router are allowed between those two facts.
+  // A report-card click reaches the same slot through signed list_mentions
+  // metadata instead of first calling merge_pr in this process.
+  let forcedConflictRecovery = null;
 
   const { links = [] } = await tool("get_links", { channelId }).catch(() => ({ links: [] }));
   // 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);
+  if (message.conflictRecovery) {
+    forcedConflictRecovery = validConflictRecovery(
+      message.conflictRecovery,
+      repoLink?.repo_full_name,
+    );
+    if (!forcedConflictRecovery) {
+      await tool("post_message", {
+        channelId,
+        parentId,
+        body: "I couldn't verify the conflict-repair target, so I left the repository unchanged.",
+      }).catch(() => {});
+      return { status: "conflict-target-refused" };
+    }
+  }
   // Workspace memory ("soul") — shared project context the agent should know.
   const { memory: workspaceMemory = null } = await tool("get_workspace_memory", {}).catch(() => ({
     memory: null,
@@ -2634,7 +3184,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       mode,
       // A manager-routed dispatch is a brief to implement, not an instruction to
       // land something — its body is assembled text, never a person's sentence.
-      canRelay: Boolean(caps.prActions) && !message.dispatch,
+      canRelay: Boolean(caps.prActions) && !message.dispatch && !forcedConflictRecovery,
     });
     if (relay.relay) {
       const verb = relay.action;
@@ -2650,7 +3200,15 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       if (reply.post) {
         await tool("post_message", { channelId, parentId, body: reply.post }).catch(() => {});
       }
-      return { status: reply.ok ? `pr-${verb}d` : "pr-action-refused", action: verb };
+      const recovery = validConflictRecovery(reply.conflict, repoLink?.repo_full_name);
+      if (verb === "merge" && recovery) {
+        forcedConflictRecovery = recovery;
+        console.log(
+          `  merge → PR #${recovery.prNumber} conflicts with ${recovery.baseBranch}; continuing as a repair run`,
+        );
+      } else {
+        return { status: reply.ok ? `pr-${verb}d` : "pr-action-refused", action: verb };
+      }
     }
   }
 
@@ -2660,6 +3218,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   if (!repoLink) {
     const folderPath = resolveFolderPath(cfg, channelId);
     if (folderPath) {
+      const folderCwd = deps.pathExists(folderPath) ? folderPath : undefined;
       // Durable report-card fallback: list_mentions projects a still-pending
       // in-place decision into the queue. Deploy only while that decision
       // remains pending; a settled report is a silent no-op, which prevents a
@@ -2756,15 +3315,16 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       // CLI router. There is still no keyword/regex intent list.
       if (!routed) {
         routed = await routeIntent({
-                name: me?.agentName || "an assistant",
-                repoFullName: folderPath,
-                transcript: context.transcript,
-                workspaceMemory,
-                cfg,
-                signal,
-                runCliFn: deps.runCli,
-                implicitDm,
-              });
+          name: me?.agentName || "an assistant",
+          repoFullName: folderPath,
+          transcript: context.transcript,
+          workspaceMemory,
+          cfg,
+          signal,
+          runCliFn: deps.runCli,
+          implicitDm,
+          cwd: folderCwd,
+        });
       }
       if (routed.aborted || signal?.aborted) {
         await tool("post_message", { channelId, parentId, body: "Stopped." });
@@ -2795,13 +3355,46 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       // Not a coding task → the classifier is finished. The separate responder
       // below owns the answer and keeps its normal tools.
     }
-    await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps });
+    await respondConversationally({
+      message,
+      channelId,
+      tool,
+      me,
+      cfg,
+      repoLink,
+      parentId,
+      workspaceMemory,
+      signal,
+      context,
+      caps,
+      runCliFn: deps.runCli,
+      pathExistsFn: deps.pathExists,
+    });
     return { status: "chat" };
   }
   const repoFullName = repoLink.repo_full_name;
+  const mappedRepoPath = resolveRepoPath(cfg, repoFullName);
+  const mappedRepoCwd =
+    mappedRepoPath && deps.pathExists(mappedRepoPath)
+      ? mappedRepoPath
+      : undefined;
 
-  if (mode === "ask") {
-    await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps });
+  if (mode === "ask" && !forcedConflictRecovery) {
+    await respondConversationally({
+      message,
+      channelId,
+      tool,
+      me,
+      cfg,
+      repoLink,
+      parentId,
+      workspaceMemory,
+      signal,
+      context,
+      caps,
+      runCliFn: deps.runCli,
+      pathExistsFn: deps.pathExists,
+    });
     return { status: "chat" };
   }
 
@@ -2832,7 +3425,13 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // 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"
+    forcedConflictRecovery
+      ? {
+          code: true,
+          task: conflictRepairBrief(forcedConflictRecovery),
+          followupSignal: "change",
+        }
+      : mode === "ship"
       ? { code: true, task: message.body, followupSignal: null }
       : await routeIntent({
           name: me?.agentName || "an assistant",
@@ -2842,7 +3441,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           cfg,
           signal,
           hasActiveRun: activeRunOpen,
+          runCliFn: deps.runCli,
           implicitDm,
+          cwd: mappedRepoCwd,
         });
   if (routed.aborted || signal?.aborted) {
     await tool("post_message", { channelId, parentId, body: "Stopped." });
@@ -2865,6 +3466,8 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       signal,
       context,
       caps,
+      runCliFn: deps.runCli,
+      pathExistsFn: deps.pathExists,
     });
     return { status: "chat" };
   }
@@ -2884,7 +3487,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     signal: followupSignal,
   });
 
-  let repoPath = resolveRepoPath(cfg, repoFullName);
+  let repoPath = mappedRepoPath;
   if (!repoPath) {
     // Zero-config path: if the daemon is running INSIDE a checkout of this repo
     // (its origin matches), just use the current directory — no repos map needed.
@@ -2958,6 +3561,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     }
   };
 
+  let activeConflictMerge = null;
   try {
   git(repoPath, ["fetch", "origin", cfg.defaultBranch]);
 
@@ -2974,7 +3578,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   //      settled, still amends THAT PR. Same shape as the server's own anchor
   //      fallback, and it never overrides 1 or 2.
   // Otherwise, a fresh branch off the default (today's behavior).
-  const cont = detectPrContinuation(message.body, repoFullName);
+  const cont = forcedConflictRecovery
+    ? null
+    : detectPrContinuation(message.body, repoFullName);
   const runIterateUrl = (followupMode === "iterate" && activeRun?.prUrl) || null;
   // The anchor is a HYPOTHESIS (its recorded state may be stale or unknown);
   // `gh` is the proof. No proof, no adoption — the run cuts a fresh branch and
@@ -3011,7 +3617,10 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       anchorNote = staleAnchorNote({ reason: decision.reason, anchor: decision.anchor });
     }
   }
-  const iterateUrl = cont?.url || runIterateUrl || anchorAdopt?.prUrl || null;
+  // A typed conflict target is stronger than heuristic text/run/anchor
+  // evidence: GitHub just returned this exact live PR head to merge_pr.
+  const iterateUrl =
+    forcedConflictRecovery?.prUrl || cont?.url || runIterateUrl || anchorAdopt?.prUrl || null;
   let branch = null;
   let continuingPrUrl = null;
   if (iterateUrl && (deps.prHeadRef || anchorAdopt)) {
@@ -3019,6 +3628,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // run's recorded branch is a fallback if gh can't view the PR. An adopted
     // anchor already has its head branch straight from the live PR.
     const headRef =
+      (forcedConflictRecovery?.prUrl === iterateUrl
+        ? forcedConflictRecovery.branch
+        : null) ||
       (anchorAdopt?.prUrl === iterateUrl ? anchorAdopt.branch : null) ||
       deps.prHeadRef?.(repoPath, iterateUrl) ||
       (followupMode === "iterate" ? activeRun?.branch || null : null);
@@ -3047,6 +3659,14 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       }
     }
   }
+  if (forcedConflictRecovery && !continuingPrUrl) {
+    await tool("post_message", {
+      channelId,
+      parentId,
+      body: `PR #${forcedConflictRecovery.prNumber} needs conflict repair, but I couldn't check out its existing branch \`${forcedConflictRecovery.branch}\`. I left the pull request unchanged.`,
+    });
+    return { status: "conflict-checkout-failed" };
+  }
   // 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
@@ -3079,6 +3699,41 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // self-committed".
   const baseRef = (git(repoPath, ["rev-parse", "HEAD"]).stdout || "").trim() || (startRef.ref || cfg.defaultBranch);
 
+  // 0991 — own the Git transition OUTSIDE the model. A merge conflict is a
+  // prepared worktree state, not prose in a prompt. Only after this succeeds do
+  // we post an ack or launch the coding CLI.
+  if (forcedConflictRecovery) {
+    const started = startConflictMerge({
+      git,
+      cwd: repoPath,
+      conflict: forcedConflictRecovery,
+    });
+    if (!started.ok) {
+      await tool("post_message", {
+        channelId,
+        parentId,
+        body: `PR #${forcedConflictRecovery.prNumber} conflicts with \`${forcedConflictRecovery.baseBranch}\`, but I couldn't prepare the repair checkout: ${started.reason} The pull request branch is unchanged.`,
+      });
+      return { status: "conflict-setup-failed" };
+    }
+    if (started.state === "up-to-date") {
+      // The synthetic repair row is durable execution authority, but it is not
+      // a second merge approval. Never cite its compact display body to
+      // `merge_pr`; ask for a fresh click after GitHub recomputes mergeability.
+      await tool("post_message", {
+        channelId,
+        parentId,
+        body: `PR #${forcedConflictRecovery.prNumber} already contains \`${forcedConflictRecovery.baseBranch}\`. GitHub had still refused the merge, so I left it unchanged. Review its current status and approve it again if it is ready.`,
+      }).catch(() => {});
+      return { status: "conflict-already-current", action: "merge" };
+    }
+    activeConflictMerge = {
+      baseBranch: forcedConflictRecovery.baseBranch,
+      files: started.files,
+      prNumber: forcedConflictRecovery.prNumber,
+    };
+  }
+
   // 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…").
@@ -3089,7 +3744,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // 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) {
+  if (activeConflictMerge) {
+    ackBody = `PR #${activeConflictMerge.prNumber} conflicts with \`${activeConflictMerge.baseBranch}\`. I started the merge on \`${branch}\` and I'm resolving it now; the updated PR will come back for review.`;
+  } else 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") {
@@ -3124,6 +3781,16 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // 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 = message.dispatch?.runId ?? (effectiveMode === "iterate" ? activeRun?.runId ?? null : null);
+  // Immutable generation for every report attempt in this daemon turn. A reused
+  // run claims the next value atomically below; fresh and dispatch-adopted rows
+  // begin on the server's current value (normally zero).
+  let iterateTurn = Number.isSafeInteger(message.dispatch?.iterateTurn)
+    ? Number(message.dispatch.iterateTurn)
+    : Number.isSafeInteger(activeRun?.iterateTurn)
+      ? Number(activeRun.iterateTurn)
+      : 0;
+  let iterateClaimId = null;
+  let iterateAuthorityLost = false;
   if (message.dispatch?.runId && caps.runs) {
     // Adopt the dispatch's canonical run. If the server already SETTLED it (the
     // reaper/outbox closed a dispatch we were slow to pick up), leave it alone
@@ -3131,17 +3798,51 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // waiting on. Any OTHER failure (network, an older server without the guard)
     // keeps today's best-effort behavior: proceed with the run.
     try {
-      await tool("update_run", { runId: message.dispatch.runId, status: "running" });
+      const adopted = await tool("update_run", { runId: message.dispatch.runId, status: "running" });
+      if (Number.isSafeInteger(adopted?.iterateTurn)) iterateTurn = Number(adopted.iterateTurn);
     } catch (e) {
-      if (String(e?.message || "").includes("already settled")) {
-        await tool("post_message", {
-          channelId,
-          parentId,
-          body: "This dispatch was already closed on the server, so I left it alone. Approve it again if it's still wanted.",
-        }).catch(() => {});
-        return { status: "dispatch-settled" };
+      const alreadySettled = String(e?.message || "").includes("already settled");
+      await tool("post_message", {
+        channelId,
+        parentId,
+        body: alreadySettled
+          ? "This dispatch was already closed on the server, so I left it alone. Approve it again if it's still wanted."
+          : "I could not confirm this dispatch's current run generation, so I did not start or ship it. Try the dispatch again.",
+      }).catch(() => {});
+      // A dispatch already names the canonical run. Continuing after an
+      // uncertain adoption would report with a guessed turn (usually zero)
+      // and can push before the exact-generation fence refuses the card.
+      return {
+        status: alreadySettled ? "dispatch-settled" : "dispatch-adoption-uncertain",
+        runId: message.dispatch.runId,
+      };
+    }
+  }
+  if (caps.runs && effectiveMode === "iterate" && runId && !message.dispatch?.runId) {
+    try {
+      const claimed = await claimDaemonIterate({
+        tool,
+        runId,
+        expectedIterateTurn: iterateTurn,
+        recoveryStore: iterateClaimRecoveryStore,
+      });
+      const claimedTurn = claimed?.iterateTurn;
+      if (!Number.isSafeInteger(claimedTurn) || Number(claimedTurn) !== iterateTurn + 1) {
+        throw new Error("the server did not return the claimed Iterate generation");
       }
-      /* older server or a transient error — proceed best-effort */
+      iterateTurn = Number(claimedTurn);
+      iterateClaimId = claimed.claimId;
+    } catch {
+      // Unlike optional bookkeeping, the generation claim is execution
+      // authority. Continuing after losing it would let two daemons ship one
+      // reused PR and let an old report settle the winner's newer work.
+      await tool("post_message", {
+        channelId,
+        parentId: threadRoot,
+        broadcast: true,
+        body: "This Iterate turn was already claimed or left its review gate, so I did not run or ship it. Re-mention me from the current report if the change is still needed.",
+      }).catch(() => {});
+      return { status: "iterate-claim-lost", runId };
     }
   }
   if (caps.runs && threadRoot && effectiveMode !== "iterate" && !message.dispatch?.runId) {
@@ -3166,12 +3867,48 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           const v = detectVendor(cfg.codingCmd);
           return v === "unknown" ? null : v;
         })(),
+        // 1182 — this daemon takes a room direction at its next turn: it reads
+        // `pendingInputs` off its heartbeat and runs one more CLI turn with
+        // them after the coding turn. Declared only when the server can take
+        // the receipt, so the room never offers a composer nothing will read.
+        ...(caps.runInputs ? { inputTransport: "next_turn" } : {}),
       });
       runId = r?.runId ?? null;
+      if (Number.isSafeInteger(r?.iterateTurn)) iterateTurn = Number(r.iterateTurn);
     } catch {
       /* never break the run on a run-record failure */
     }
   }
+  // 1182 — the run's direction inbox, fed by every heartbeat reply. Only a run
+  // the server knows (start_run answered) and only when it can take the
+  // receipt; otherwise there is no door and nothing is ever listed.
+  const directions =
+    caps.runInputs && runId
+      ? createDirectionInbox({ tool, runId, log: (line) => console.log(line) })
+      : null;
+  // All subprocesses launched after an Iterate claim — including the fast plan
+  // acknowledgement — share this exact authority fence. Non-Iterate runs take
+  // the true fast path and preserve their existing behavior.
+  const beforeCodingSpawn = async () => {
+    if (signal?.aborted) return false;
+    if (!iterateClaimId) return true;
+    const ownsClaim = await confirmDaemonIterateClaim({
+      tool,
+      runId,
+      iterateTurn,
+      claimId: iterateClaimId,
+    });
+    if (!ownsClaim) iterateAuthorityLost = true;
+    return ownsClaim && !signal?.aborted;
+  };
+  const settleConflictFailure = async (reason) => {
+    if (!activeConflictMerge || !runId || !caps.runs) return;
+    await tool("update_run", {
+      runId,
+      status: effectiveMode === "iterate" ? "awaiting_review" : "failed",
+      reason,
+    }).catch(() => {});
+  };
   // 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 (
@@ -3190,6 +3927,8 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       repoFullName,
       cfg,
       signal,
+      cwd: repoPath,
+      beforeSpawn: beforeCodingSpawn,
     }).catch(() => null);
     if (plan && !signal?.aborted) await tool("edit_message", { messageId: ackId, body: plan }).catch(() => {});
   }
@@ -3321,11 +4060,32 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
    * heartbeat does (the room hears who stopped it; the job's signal aborts).
    */
   const stoppedBeforeShip = async (state = "done") => {
+    if (iterateClaimId) {
+      const ownsClaim = await confirmDaemonIterateClaim({
+        tool,
+        runId,
+        iterateTurn,
+        claimId: iterateClaimId,
+      });
+      if (!ownsClaim) {
+        iterateAuthorityLost = true;
+        return true;
+      }
+    }
     // Only the streaming card carries progress metadata. The legacy heartbeat's
     // message is plain text, and stamping a lifecycle onto it would turn a
     // status line into a run card — so that path simply has no pre-ship check.
     if (!streamOn || !progressId) return false;
-    const sender = createProgressSender({ tool, statusId: progressId, runId, onStopRequested });
+    // 1182 — this is the one beat between the last turn and the ship, so it
+    // is also where a direction typed during the review wait is harvested;
+    // the inbox then answers it at close, before the report.
+    const sender = createProgressSender({
+      tool,
+      statusId: progressId,
+      runId,
+      onStopRequested,
+      ...(directions ? { onPendingInputs: (list) => directions.absorb(list) } : {}),
+    });
     return await sender.poll(state);
   };
   // Once the run ends, retire the "still working…" progress reply so it doesn't
@@ -3348,15 +4108,25 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   const settleRunUsage = async () => {
     const args = reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId });
     if (!args.usage || !progressId) return;
-    await tool("post_progress", {
+    // 1182 — a run-bound beat like any other: a direction it lists is handed
+    // to the inbox (which answers it at close, right after this on the exits
+    // that call it), so no beat throws a listing away.
+    const res = await tool("post_progress", {
       messageId: progressId,
       ...(runId ? { runId } : {}),
       progress: { state: lastTerminalState },
       usage: args.usage,
-    }).catch(() => {});
+    }).catch(() => null);
+    if (directions && res) {
+      try {
+        directions.absorb(readPendingInputs(res));
+      } catch {
+        /* never break the settlement over a listing */
+      }
+    }
   };
 
-  const parts = cfg.codingCmd.split(" ").filter(Boolean);
+  const parts = commandArgv(cfg.codingCmd);
   // 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.
@@ -3402,7 +4172,13 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       // the sender also carries the stop signal home on this same beat, bound
       // to THIS run's id so a stop can't be read off a neighbouring thread.
       const sender = statusId
-        ? createProgressSender({ tool, statusId, runId, onStopRequested })
+        ? createProgressSender({
+            tool,
+            statusId,
+            runId,
+            onStopRequested,
+            ...(directions ? { onPendingInputs: (list) => directions.absorb(list) } : {}),
+          })
         : null;
       // The emitter is built whether or not the status card posted (0787). The
       // stream flags are already on the argv either way, so the CLI is speaking
@@ -3466,7 +4242,24 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     const codeArgs = streamOn
       ? [...parts.slice(1), ...webArgs, ...modelArgs, ...dirArgs, ...imageArgs, ...resumeArgs, ...streamArgs]
       : [...parts.slice(1), ...webArgs, ...modelArgs, ...dirArgs, ...imageArgs, ...resumeArgs];
+    // One HEP stream per spawned coding-runtime process. This projection is
+    // automatic but deliberately best-effort: it is bounded, secret-redacted
+    // again on the server, and can never interrupt the coding process.
+    const harnessEmitter =
+      caps.hepEvents &&
+      runId &&
+      me?.agentId &&
+      ["claude_code", "codex", "cursor", "opencode"].includes(vendor)
+        ? createLocalHarnessEmitter({
+            tool,
+            runId,
+            runtime: vendor,
+            streamId: randomUUID(),
+            actorId: me.agentId,
+          })
+        : null;
     const handleCliData = (c) => {
+      harnessEmitter?.push(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];
@@ -3494,6 +4287,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // live card has always read this; the transcript has to as well, or a gated
     // run uploads a page of narration with no execution anywhere in it.
     const handleCliEvent = (ev) => {
+      harnessEmitter?.pushEvent(ev);
       if (transcriptTap) {
         try {
           transcriptTap.pushEvent(ev);
@@ -3566,6 +4360,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           env: scrubHilosEnv(codingChildWebEnv(cfg, vendor) || process.env),
           onData: handleCliData,
           onEvent: handleCliEvent,
+          beforeSpawn: beforeCodingSpawn,
           ...openCodePermissionCallbacks({
             tool,
             channelId,
@@ -3588,6 +4383,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           // after this scrub and dies with the process group.
           env: scrubHilosEnv(codingChildWebEnv(cfg, vendor) || process.env),
           onData: handleCliData,
+          beforeSpawn: beforeCodingSpawn,
           ...openCodePermissionCallbacks({
             tool,
             channelId,
@@ -3612,6 +4408,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           signal,
           onData: handleCliData,
           onEvent: handleCliEvent,
+          beforeSpawn: beforeCodingSpawn,
           permissionCallbacks: openCodePermissionCallbacks({
             tool,
             channelId,
@@ -3634,6 +4431,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           cwd: repoPath,
           signal,
           onData: handleCliData,
+          beforeSpawn: beforeCodingSpawn,
           sessionId: resume ? resumeSessionId ?? "" : "",
           resolveSessionId: () => emitter?.snapshot()?.sessionId ?? null,
           permissionCallbacks: openCodePermissionCallbacks({
@@ -3659,6 +4457,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           signal,
           env: codingChildWebEnv(cfg, vendor),
           onData: handleCliData,
+          beforeSpawn: beforeCodingSpawn,
         });
       }
       // 0785 — the gate was expected here and the CLI couldn't hold it. Say so
@@ -3668,6 +4467,11 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       stopHeartbeat();
       stopPoller?.stop();
       if (run?.sessionId) runSessionId = run.sessionId;
+      try {
+        await harnessEmitter?.drain();
+      } catch {
+        /* runtime exhaust must never break the run */
+      }
       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,
@@ -3735,7 +4539,53 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       return { aborted: true };
     }
     if (run.error) console.log(`  ! ${parts[0]} failed to start: ${run.error.message}`);
-    git(repoPath, ["add", "-A"]);
+    if (activeConflictMerge) {
+      const mergeState = validateConflictMergeState({
+        git,
+        cwd: repoPath,
+        baseBranch: activeConflictMerge.baseBranch,
+      });
+      if (!mergeState.ok) {
+        console.log(`  code → ${mergeState.reason}; refusing to stage`);
+        return {
+          conflicted: true,
+          mergeStateInvalid: true,
+          files: [mergeState.reason],
+          failed: true,
+        };
+      }
+      const unresolved = remainingConflictFiles({
+        git,
+        cwd: repoPath,
+        knownFiles: activeConflictMerge.files,
+      });
+      if (unresolved.length) {
+        console.log(`  code → ${unresolved.length} merge conflict(s) remain; refusing to stage`);
+        return {
+          conflicted: true,
+          files: unresolved,
+          failed: Boolean(run.error) || run.status !== 0,
+        };
+      }
+    }
+    const add = git(repoPath, ["add", "-A"]);
+    if (activeConflictMerge) {
+      const unmergedAfterAdd = String(
+        git(repoPath, ["diff", "--name-only", "--diff-filter=U"]).stdout || "",
+      )
+        .split("\n")
+        .map((file) => file.trim())
+        .filter(Boolean);
+      if (add.status !== 0 || unmergedAfterAdd.length) {
+        return {
+          conflicted: true,
+          files: unmergedAfterAdd.length
+            ? unmergedAfterAdd
+            : ["Git could not stage the resolved merge"],
+          failed: true,
+        };
+      }
+    }
     const diff = git(repoPath, ["diff", "--cached"]).stdout || "";
     if (!diff.trim()) {
       // An empty diff after a FAILED run (timeout / non-zero exit / spawn error)
@@ -3903,9 +4753,12 @@ 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 lead = iterateAuthorityLost
+      ? "This Iterate turn no longer owns its run, so I did not start or ship it"
+      : "Stopped";
     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}.`;
+      ? `${lead} — discarded \`${branch}\`.`
+      : `${lead}, 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,
@@ -3919,6 +4772,30 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     return { status: "cancelled", branch };
   };
 
+  const postStopCompensationPending = async (result) => {
+    const receipt = result?.compensation?.receipt;
+    const ref = receipt?.ref || `refs/heads/${branch}`;
+    const reason = result?.compensation?.probeError
+      || result?.compensation?.stderr
+      || "the remote ref could not be verified";
+    const repairGuidance = result?.compensation?.repairable
+      ? "The exact-lease repair is safe to retry"
+      : "The remote ref changed again, so it needs manual reconciliation";
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: true,
+      body:
+        `Stop was received, but hilos could not confirm restoration of \`${ref}\`: ` +
+        `${oneLine(String(reason), 200)}. ${repairGuidance}; ` +
+        `the local branch \`${branch}\` was kept for recovery.`,
+    });
+    await finalizeProgress(`Stop needs remote branch repair on \`${branch}\` — see the note below.`);
+    await updateChannelMarker(compactRunMarker("run-failed", branch));
+    await settleRunUsage();
+    return result;
+  };
+
   // 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
@@ -3944,21 +4821,119 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
 
   const codePrompt =
     (teamMemoryBlock ? teamMemoryBlock + "\n\n" : "") +
-    codeTaskPrompt({ message, context, brief: routed.task, repoFullName, ...codeImagePromptArgs });
+    codeTaskPrompt({ message, context, brief: routed.task, repoFullName, ...codeImagePromptArgs }) +
+    (activeConflictMerge
+      ? `\n\n${conflictPromptBlock(activeConflictMerge)}`
+      : "");
   let staged = await runAndStage(codePrompt);
   if (staged.aborted) return await postStopped();
+  // One focused retry, in the same prepared merge, with the remaining paths
+  // named explicitly. This is recovery owned by the run — never another human
+  // prompt. A second failure stops safely and pushes nothing.
+  if (activeConflictMerge && staged.conflicted) {
+    if (staged.mergeStateInvalid) {
+      await tool("post_message", {
+        channelId,
+        parentId: threadRoot,
+        broadcast: true,
+        body:
+          `I couldn't safely finish the conflict repair on PR #${activeConflictMerge.prNumber}. ` +
+          `${staged.files[0]}. I left its remote branch unchanged.`,
+      });
+      await finalizeProgress(`Conflict repair stopped on \`${branch}\` — nothing was pushed.`);
+      await updateChannelMarker(compactRunMarker("run-failed", branch));
+      await settleConflictFailure("conflict merge state was aborted or replaced");
+      await settleRunUsage();
+      return { status: "conflict-state-invalid", branch };
+    }
+    const retryPrompt =
+      `${codePrompt}\n\nYour first pass left unresolved merge conflicts. ` +
+      `Resolve every remaining file now and leave no conflict marker behind:\n` +
+      staged.files.map((file) => `- ${file}`).join("\n");
+    staged = await runAndStage(retryPrompt, { resume: false });
+    if (staged.aborted) return await postStopped();
+    if (staged.conflicted) {
+      await tool("post_message", {
+        channelId,
+        parentId: threadRoot,
+        broadcast: true,
+        body:
+          `I couldn't safely finish the conflict repair on PR #${activeConflictMerge.prNumber}. ` +
+          `I left its remote branch unchanged; unresolved files were:\n` +
+          staged.files.map((file) => `- ${file}`).join("\n"),
+      });
+      await finalizeProgress(`Conflict repair stopped on \`${branch}\` — nothing was pushed.`);
+      await updateChannelMarker(compactRunMarker("run-failed", branch));
+      await settleConflictFailure(`unresolved conflicts: ${staged.files.join(", ")}`);
+      await settleRunUsage();
+      return { status: "conflicts-unresolved", branch, files: staged.files };
+    }
+  }
   // 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) {
+  if (resumeSessionId && staged.empty && staged.failed && !activeConflictMerge) {
     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;
   }
+  // 1182 — directions a person added from the card while the CLI worked. The
+  // coding turn is over; each batch gets one more turn with the same task and
+  // the directions, on the same working tree (the shape the gate's feedback
+  // rounds use), then its receipt: the turn's own command id and the pass it
+  // went into. Bounded, so a room that keeps typing waits for the next pass.
+  // The inbox stays open through the gate's review rounds (each folds what
+  // arrived into its prompt) and closes only when no further turn can run.
+  const settleDirectionTurn = async (batch, applied, commandId) => {
+    if (!directionTurnRan(applied)) {
+      // No runtime ever saw the prompt (the command did not spawn): no
+      // receipt. The server keeps listing; the run's end tells the room.
+      console.log(`  direction → the turn did not start; ${batch.length} direction(s) left unsettled`);
+      return;
+    }
+    // The runtime took the directions into a command: delivered, whatever
+    // the turn then produced (its outcome is the report's to tell).
+    const delivered = await directions.acknowledge(batch, { ackId: commandId, turn: iterateTurn });
+    console.log(`  direction → ${delivered}/${batch.length} receipt(s) recorded`);
+  };
+  // Runs while directions are held and turns remain; called after the coding
+  // turn and after each review round (a direction listed mid-round arrives
+  // after that round's prompt was built). Never before a ship: the exits are
+  // derived from the tree the last turn left, and a turn would change it.
+  // Reports `stopped` when a person stopped the run mid-turn.
+  let directionTurns = 0;
+  const runDirectionTurns = async () => {
+    const outcome = { stopped: false, advanced: false };
+    // A conflict repair owns the tree until it settles; directions wait and
+    // are answered at close.
+    if (!directions || activeConflictMerge) return outcome;
+    while (!signal?.aborted && directions.size() > 0 && directionTurns < MAX_DIRECTION_TURNS) {
+      const batch = directions.take();
+      directionTurns += 1;
+      console.log(`  direction → running one more turn with ${batch.length} direction(s) from the room`);
+      const commandId = `direction-turn:${randomUUID()}`;
+      const applied = await runAndStage(directionTurnPrompt(codePrompt, batch), { resume: false });
+      if (applied.aborted) {
+        outcome.stopped = true;
+        return outcome;
+      }
+      await settleDirectionTurn(batch, applied, commandId);
+      // `staged` always describes the repo after the last turn that ran, so
+      // every exit below (self-committed, no changes, proposal, ship) is
+      // derived from what the tree holds now, never from a stale snapshot.
+      if (directionTurnRan(applied)) {
+        staged = applied;
+        outcome.advanced = true;
+      }
+    }
+    return outcome;
+  };
+  const afterCoding = await runDirectionTurns();
+  if (afterCoding.stopped) return await postStopped();
   // 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);
@@ -3968,30 +4943,38 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   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.
+  // Approve-before-push: a self-pushing CLI already bypassed the gate; be
+  // honest and let the human review instead of auto-shipping. Leave the
+  // branch. A closure, because a direction turn inside a review round can
+  // end the same way (1182).
+  const finishSelfCommittedGated = async () => {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: true,
+      body:
+        `The coding agent committed on \`${branch}\` itself on its last turn (I asked it to only edit files). ` +
+        `Under approve-before-push I won't auto-push it — review \`${branch}\` locally, then ` +
+        `re-mention me to ship or discard.`,
+    });
+    await finalizeProgress(`\`${branch}\` has the agent's own commits — needs review.`);
+    await updateChannelMarker(compactRunMarker("changes", branch));
+    await settleRunUsage(); // no report on this exit (0787)
+    // 1182 — no turn is left in this pass: what is held is answered now.
+    if (directions) await directions.close();
+    return { status: "self-committed-gated", branch };
+  };
   if (staged.empty && !staged.failed && staged.ahead > 0) {
-    if (cfg.gate) {
-      // Approve-before-push: a self-pushing CLI already bypassed the gate; be
-      // honest and let the human review instead of auto-shipping. Leave the branch.
-      await tool("post_message", {
-        channelId,
-        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 ` +
-          `re-mention me to ship or discard.`,
-      });
-      await finalizeProgress(`\`${branch}\` has the agent's own commits — needs review.`);
-      await updateChannelMarker(compactRunMarker("changes", branch));
-      await settleRunUsage(); // no report on this exit (0787)
-      return { status: "self-committed-gated", branch };
-    }
+    if (cfg.gate && !activeConflictMerge) return await finishSelfCommittedGated();
     // 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).
     if (signal?.aborted || (await stoppedBeforeShip())) return await postStopped();
     const selfSettleId = streamOn && progressId ? progressId : null;
     if (!selfSettleId) await finalizeProgress(`Agent shipped \`${branch}\` itself — report below.`);
+    // 1182 — closed before the report ends the pass on the server (see the
+    // ungated ship below for why).
+    if (directions) await directions.close();
     const selfResult = await shipSelfDriven({
       repoPath,
       branch,
@@ -4004,15 +4987,24 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       parentId: threadRoot,
       settleId: selfSettleId,
       runId,
+      iterateTurn,
       provenance: githubProvenance({ cfg, me, message, channelId, runId, summary: staged.summary }),
       usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
+      shouldContinue: async () => !signal?.aborted && !(await stoppedBeforeShip()),
     });
+    if (selfResult.status === "stopped") return await postStopped();
+    if (selfResult.status === "stop-compensation-pending") {
+      return await postStopCompensationPending(selfResult);
+    }
     await recordSession(selfResult.prUrl);
     await uploadTranscript(selfResult.reportMsgId);
     await updateChannelMarker(compactRunMarker(selfResult.status, selfResult.branch));
     return selfResult;
   }
-  if (staged.empty) {
+  // The tree holds nothing to propose: report why and leave or clean the
+  // branch. A closure, because a direction turn inside a review round can
+  // leave the tree this way too (1182); it always reads the current `staged`.
+  const finishEmptyTree = async ({ afterDirection = false } = {}) => {
     // 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}\`.`;
@@ -4030,6 +5022,12 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           : "";
       const tail = staged.stderrTail ? `: ${staged.stderrTail}` : "";
       body = `The run didn't finish${why}${tail}.${retryTail}`;
+    } else if (afterDirection) {
+      // A direction turn inside a review round left nothing staged: say so,
+      // since a proposal card showing a diff may still be standing.
+      body = continuingPrUrl
+        ? `The direction from the room left no changes — \`${branch}\` is unchanged.`
+        : `The direction from the room left no changes on \`${branch}\`.${cleanupNote}`;
     } else {
       body = continuingPrUrl
         ? `That feedback produced no further changes — \`${branch}\` is unchanged.`
@@ -4047,13 +5045,16 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       compactRunMarker(staged.failed ? "run-failed" : "no-changes", branch),
     );
     await settleRunUsage(); // "no changes" is not "no spend" (0787)
+    // 1182 — no turn is left in this pass: what is held is answered now.
+    if (directions) await directions.close();
     return { status: staged.failed ? "run-failed" : "no-changes" };
-  }
+  };
+  if (staged.empty) return await finishEmptyTree({ afterDirection: afterCoding.advanced });
 
   // Bias to action (default): commit, push, and open a PR for review now — the
   // report card's Approve merges it. `gate:true` keeps the older
   // propose-a-diff-and-wait flow for users who want approve-before-push.
-  if (!cfg.gate) {
+  if (!cfg.gate || activeConflictMerge) {
     // A "stop" that lands between the run finishing and the ship must still win.
     // The signal covers a stop we already heard; the server check covers one that
     // landed while the CLI was silent and nothing was carrying it home.
@@ -4065,13 +5066,23 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // 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;
+    // 1182 — the inbox closes BEFORE the report: the report ends the pass on
+    // the server, and the server's run-end rule would otherwise speak first,
+    // with a notice meant for a run that stopped and before a lost receipt
+    // could be retried. No extra turn here: the exits above were derived
+    // from the tree the last turn left, and a turn now would change it.
+    if (directions) await directions.close();
     const result = await applyDecision({
       decision: { kind: "approved" },
       repoPath,
       branch,
       // 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,
+      task: activeConflictMerge
+        ? conflictCommitTitle(activeConflictMerge.baseBranch)
+        : continuingPrUrl
+          ? routed.task || message.body
+          : message.body,
       requester: message.author,
       cfg,
       tool,
@@ -4081,9 +5092,15 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       existingPrUrl: continuingPrUrl,
       settleId,
       runId,
+      iterateTurn,
       provenance: githubProvenance({ cfg, me, message, channelId, runId, summary: staged.summary }),
       usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
+      shouldContinue: async () => !signal?.aborted && !(await stoppedBeforeShip()),
     });
+    if (result.status === "stopped") return await postStopped();
+    if (result.status === "stop-compensation-pending") {
+      return await postStopCompensationPending(result);
+    }
     // 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.
@@ -4108,11 +5125,45 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       parentId: threadRoot,
       body: `Revising with your feedback${decision.note ? `: ${decision.note}` : ""} (round ${round + 1}/${maxRounds}).`,
     });
+    // 1182 — a direction that arrived while the reviewer was deciding rides
+    // this round's prompt, after the feedback, and gets this round's receipt.
+    const roundDirections = directions ? directions.take() : [];
+    const roundCommandId = `direction-turn:${randomUUID()}`;
+    const roundPrompt = `${message.body}\n\nReviewer feedback to address: ${decision.note || "(see the channel)"}`;
     const refined = await runAndStage(
-      `${message.body}\n\nReviewer feedback to address: ${decision.note || "(see the channel)"}`,
+      roundDirections.length > 0 ? directionTurnPrompt(roundPrompt, roundDirections) : roundPrompt,
     );
     if (refined.aborted) return await postStopped();
-    if (refined.empty) {
+    if (roundDirections.length > 0) await settleDirectionTurn(roundDirections, refined, roundCommandId);
+    // The round's own turn is a turn that ran: `staged` follows it (1182
+    // round 5), so the invariant holds for every turn, not only direction
+    // turns. Then a direction listed during this round (it arrived after the
+    // prompt was built) gets its turn, and whichever tree is newest is what
+    // the reviewer sees: the proposal card is the gate, and it shows what
+    // will ship.
+    if (!directionTurnRan(refined)) {
+      // The round's command never started: nothing changed and nothing was
+      // seen, so the earlier proposal stands, said plainly, never re-posted.
+      await tool("post_message", {
+        channelId,
+        parentId: threadRoot,
+        broadcast: true,
+        body: `I couldn't start \`${cfg.codingCmd}\` for this round — leaving \`${branch}\` as proposed.`,
+      });
+      break;
+    }
+    staged = refined;
+    const afterRound = await runDirectionTurns();
+    if (afterRound.stopped) return await postStopped();
+    if (staged.empty) {
+      // Nothing staged after this round's turns. The CLI's own commits end
+      // the pass the way they would after the coding turn (approve-before-
+      // push never auto-ships them, whether a feedback round or a direction
+      // turn made them); a direction turn that left the tree clean ends it as
+      // no changes; a feedback round alone that produced nothing leaves the
+      // earlier proposal standing, as it always has.
+      if (!staged.failed && staged.ahead > 0) return await finishSelfCommittedGated();
+      if (afterRound.advanced) return await finishEmptyTree({ afterDirection: true });
       await tool("post_message", {
         channelId,
         parentId: threadRoot,
@@ -4121,7 +5172,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       });
       break;
     }
-    proposal = await postProposal(refined);
+    proposal = await postProposal(staged);
     decision = await awaitDecision({ tool, channelId, reportMessageId: proposal.reportMessageId, cfg, deps, parentId: threadRoot, signal });
     if (decision.kind === "cancelled") return await postStopped();
     round += 1;
@@ -4129,6 +5180,10 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
 
   // A stop during the final wait, too — don't ship a cancelled run.
   if (signal?.aborted || (await stoppedBeforeShip())) return await postStopped();
+  // 1182 — closed before the report ends the pass on the server (see the
+  // ungated ship above for why). The reviewer approved this tree; no further
+  // turn may change it.
+  if (directions) await directions.close();
   const result = await applyDecision({
     decision,
     repoPath,
@@ -4144,11 +5199,17 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     parentId: threadRoot,
     existingPrUrl: continuingPrUrl,
     runId,
+    iterateTurn,
     provenance: githubProvenance({ cfg, me, message, channelId, runId, summary: staged.summary }),
     // Normally {} — a gated run already reported its spend on the proposal card
     // it is now shipping. Anything the CLI spent after that still comes home.
     usageArgs: reportUsageArgs(runUsage, { vendor, modelId: resolvedModelId, runId }),
+    shouldContinue: async () => !signal?.aborted && !(await stoppedBeforeShip()),
   });
+  if (result.status === "stopped") return await postStopped();
+  if (result.status === "stop-compensation-pending") {
+    return await postStopCompensationPending(result);
+  }
   await finalizeProgress(`Done on \`${branch}\` — see the report below.`);
   await recordSession(result.prUrl);
   // The gated lane's shipped report is a fresh message; `result.reportMsgId`
@@ -4157,6 +5218,15 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   await updateChannelMarker(compactRunMarker(result.status, result.branch));
   return { ...result, reportMessageId: proposal.reportMessageId, stat: proposal.stat, rounds: round, sessionId: runSessionId };
   } finally {
+    // Any early exit while Git is still mid-merge must leave the user's checkout
+    // clean enough to switch back and restore their stash. A successful merge
+    // commit has already removed MERGE_HEAD, so this is a no-op on the happy path.
+    if (
+      activeConflictMerge &&
+      git(repoPath, ["rev-parse", "-q", "--verify", "MERGE_HEAD"]).status === 0
+    ) {
+      git(repoPath, ["merge", "--abort"]);
+    }
     // Whatever happened, give the user their uncommitted work back.
     await restoreStash();
   }