hilos-agent 0.6.0 → 0.9.0

package/src/handler.mjs

@@ -25,12 +25,37 @@ import {
   prTitleBody,
   mentionHandle,
   detectPrContinuation,
+  selfDrivenShipPlan,
 } from "./daemon.mjs";
-import { runCli, buildHeartbeat, ackText, oneLine, fmtElapsed, minimalEnv } from "./cli.mjs";
+import {
+  runCli,
+  buildHeartbeat,
+  ackText,
+  oneLine,
+  fmtElapsed,
+  minimalEnv,
+  scrubHilosEnv,
+  envForCwd,
+} from "./cli.mjs";
 import { makeStreamParser } from "./agent-events.mjs";
-import { detectVendor, codeStreamArgs, createProgressEmitter, fastChatCmd } from "./progress-emitter.mjs";
+import {
+  detectVendor,
+  codeStreamArgs,
+  codeDirArgs,
+  codeProjectKey,
+  attachTarget,
+  createProgressEmitter,
+  fastChatCmd,
+} from "./progress-emitter.mjs";
 import { resolveFollowupMode, classifyFollowupCue, normalizeSignal } from "./followup.mjs";
-import { buildResumeArgs, readStateEntry, writeState, HILOS_DIR } from "./resume.mjs";
+import {
+  anchorIterateDecision,
+  confirmAnchorOpen,
+  prActionRelayDecision,
+  prActionReply,
+  staleAnchorNote,
+} from "./thread-pr.mjs";
+import { buildResumeArgs, resumeDecision, readStateEntry, writeState, HILOS_DIR } from "./resume.mjs";
 import { createModelArgsResolver } from "./model-resolve.mjs";
 import {
   buildReviewPrompt,
@@ -40,6 +65,8 @@ import {
 } from "./review.mjs";
 import { buildMemoryBlock } from "./memory.mjs";
 import { deployFolder, resolveDeployTarget } from "./deploy.mjs";
+import { runOpenCodeHttpSession } from "./opencode-session.mjs";
+import { runAcpSession } from "./acp-session.mjs";
 
 /**
  * The environment for a coding/chat CLI run. runCli always strips HILOS_* on top
@@ -120,14 +147,21 @@ function compactRunMarker(status, branch) {
   return `Failed:${b}`;
 }
 
+// Every helper below runs a tool in a directory we choose, so each one hands
+// the child a PWD that matches that directory instead of the daemon's launch
+// dir (0615). git and gh both use the real cwd, so this is hygiene rather than
+// a fix — but a child whose env contradicts its cwd is wrong on any tool.
+const cwdEnv = (cwd) => envForCwd(process.env, cwd);
+
 function defaultDeps() {
   return {
     git: (cwd, args) =>
-      spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 50 * 1024 * 1024 }),
-    // The async CLI runner, injectable so folder mode (and tests) can drive the
-    // coding run without spawning a real process. The repo flow still uses the
-    // imported runCli directly (unchanged); only folder mode goes through deps.
+      spawnSync("git", args, { cwd, env: cwdEnv(cwd), encoding: "utf8", maxBuffer: 50 * 1024 * 1024 }),
+    // Async coding runners are injectable so handler-level tests can prove the
+    // selected trust boundary without spawning a real model process.
     runCli: (opts) => runCli(opts),
+    runOpenCodeHttpSession: (opts) => runOpenCodeHttpSession(opts),
+    runAcpSession: (opts) => runAcpSession(opts),
     // Does a path exist on disk? Injectable so folder mode's "missing folder"
     // guard is unit-testable without touching the real filesystem.
     pathExists: (p) => existsSync(p),
@@ -137,10 +171,10 @@ function defaultDeps() {
       const r = spawnSync(
         "gh",
         ["pr", "create", "--title", title, "--body", body, "--head", branch, "--base", base],
-        { cwd, encoding: "utf8" },
+        { cwd, env: cwdEnv(cwd), encoding: "utf8" },
       );
       const url = (r.stdout || "").trim().split("\n").filter(Boolean).pop() || null;
-      return { ok: r.status === 0, url, stderr: r.stderr || "" };
+      return { ok: r.status === 0, url, stdout: r.stdout || "", stderr: r.stderr || "" };
     },
     // 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.
@@ -148,7 +182,7 @@ function defaultDeps() {
       const r = spawnSync(
         "gh",
         ["pr", "list", "--head", branch, "--state", "open", "--json", "url", "--jq", ".[0].url // empty"],
-        { cwd, encoding: "utf8" },
+        { cwd, env: cwdEnv(cwd), encoding: "utf8" },
       );
       const url = (r.stdout || "").trim();
       return r.status === 0 && url ? url : null;
@@ -160,16 +194,160 @@ function defaultDeps() {
       const r = spawnSync(
         "gh",
         ["pr", "view", String(ref), "--json", "headRefName", "--jq", ".headRefName // empty"],
-        { cwd, encoding: "utf8" },
+        { cwd, env: cwdEnv(cwd), encoding: "utf8" },
       );
       const out = (r.stdout || "").trim();
       return r.status === 0 && out ? out : null;
     },
+    // The live state of a PR (0704): is it still OPEN, what is its head branch,
+    // and does that head live in the base repo? The staleness guard for adopting
+    // the thread's pull request — a merged/closed anchor must never take a push,
+    // and a fork head is another repository's branch. Returns null when `gh`
+    // can't answer, which the caller reads as "no proof, no adoption".
+    prState: (cwd, ref) => {
+      const r = spawnSync(
+        "gh",
+        [
+          "pr",
+          "view",
+          String(ref),
+          "--json",
+          "state,headRefName,headRepository,headRepositoryOwner",
+        ],
+        { cwd, env: cwdEnv(cwd), encoding: "utf8" },
+      );
+      if (r.status !== 0) return null;
+      try {
+        const j = JSON.parse(r.stdout || "{}");
+        const owner = j.headRepositoryOwner?.login || j.headRepositoryOwner?.name || null;
+        const repo = j.headRepository?.name || null;
+        return {
+          state: typeof j.state === "string" ? j.state : "",
+          headRefName: typeof j.headRefName === "string" ? j.headRefName : null,
+          headRepoFullName: owner && repo ? `${owner}/${repo}` : null,
+        };
+      } catch {
+        return null;
+      }
+    },
     sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
     now: () => Date.now(),
   };
 }
 
+/**
+ * Bind one OpenCode HTTP session to hilos's vendor-neutral permission tools.
+ * Both repo and direct-folder runs use this exact callback contract so neither
+ * path can accidentally become the ungated exception.
+ */
+function openCodePermissionCallbacks({
+  tool,
+  channelId,
+  threadRoot,
+  runId = null,
+  provider = "opencode",
+}) {
+  return {
+    requestPermission: async (request) => {
+      const detail =
+        request.metadata && typeof request.metadata === "object"
+          ? request.metadata
+          : {};
+      const title = [
+        detail.title,
+        detail.description,
+        detail.command,
+        request.resources?.[0],
+      ].find((value) => typeof value === "string" && value.trim());
+      return tool("request_permission", {
+        channelId,
+        threadRootId: threadRoot,
+        ...(runId ? { runId } : {}),
+        provider,
+        vendorSessionId: request.sessionId,
+        vendorRequestId: request.vendorRequestId,
+        action: request.action,
+        title: title || `${request.action} permission`,
+        resources: request.resources,
+        suggestedSave: request.suggestedSave,
+        metadata: detail,
+        ...(request.source ? { source: request.source } : {}),
+      });
+    },
+    getPermissionDecision: async (handle, { request, failClosed = false }) => {
+      const requestId =
+        handle &&
+        typeof handle === "object" &&
+        typeof handle.requestId === "string"
+          ? handle.requestId
+          : null;
+      if (!requestId) {
+        throw new Error(
+          "hilos returned a pending permission without a request id",
+        );
+      }
+      return tool("get_permission_decision", {
+        requestId,
+        provider,
+        vendorSessionId: request.sessionId,
+        vendorRequestId: request.vendorRequestId,
+        ...(failClosed ? { failClosed: true } : {}),
+      });
+    },
+  };
+}
+
+/** The local HTTP bridge can own only a local OpenCode server. An explicit
+ * `--attach` remains on OpenCode's CLI responder, which rejects unanswered asks
+ * fail closed; taking over a remote server requires a separate authenticated
+ * transport contract. Shared by repo and direct-folder runs. */
+export function shouldUseRuntimePermissionBridge({
+  vendor,
+  runtimePermissions,
+  codeArgs,
+  codingCmd,
+}) {
+  return (
+    vendor === "opencode" &&
+    runtimePermissions === true &&
+    !codeArgs.includes("--auto") &&
+    attachTarget(codingCmd) === null
+  );
+}
+
+/** ACP transport opt-in (0759; slice 1 opencode, slice 2 cursor). Only runs
+ * the workspace already gates with runtime permissions qualify, PLUS the
+ * operator's explicit acpTransport flag, and only when the vendor's own
+ * auto-allow escape hatches are absent — over ACP, hilos must be the one
+ * answering asks, so a run configured to never ask has nothing to gate here.
+ * Resumed runs stay on the existing paths: their session continuity contract
+ * is argv/HTTP-shaped and the ACP path does not carry it yet. */
+export function shouldUseAcpTransport({
+  vendor,
+  acpTransport,
+  runtimePermissions,
+  codeArgs,
+  codingCmd,
+  resumeSessionId = /** @type {string | null} */ (null),
+}) {
+  if (acpTransport !== true || resumeSessionId != null) return false;
+  if (runtimePermissions !== true) return false;
+  if (vendor === "opencode") {
+    return shouldUseRuntimePermissionBridge({
+      vendor,
+      runtimePermissions,
+      codeArgs,
+      codingCmd,
+    });
+  }
+  if (vendor === "cursor") {
+    // -f/--force is cursor's "allow everything" switch — the exact analog of
+    // opencode's --auto.
+    return !codeArgs.includes("-f") && !codeArgs.includes("--force");
+  }
+  return false;
+}
+
 async function awaitDecision({ tool, channelId, reportMessageId, cfg, deps, parentId, signal }) {
   if (!reportMessageId) return { kind: "timeout" };
   const deadline = deps.now() + cfg.decisionTimeoutMs;
@@ -333,37 +511,63 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
  * The coding CLI committed the work itself (autonomous run with skip-permissions
  * in a repo whose docs prescribe a commit+PR flow), so the working tree is clean
  * and the daemon's diff is empty. Don't claim "no changes": adopt what it did —
- * push the branch it's on (no-op if already pushed), reuse the PR it opened or
- * open one, and report it. Used only when NOT gated (bias-to-action).
+ * push its HEAD under the daemon-owned task branch, reuse the PR it opened or
+ * open one, and report it. Keeping the intended head matters: a child that
+ * 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 }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
-  // The agent may have committed on the daemon's branch or switched to one of its
-  // own — push whatever HEAD is on now.
-  const cur =
-    (deps.git(repoPath, ["symbolic-ref", "--quiet", "--short", "HEAD"]).stdout || "").trim() || branch;
-  const push = deps.git(repoPath, ["push", "-u", "origin", cur]);
-  let prUrl = deps.findPR ? deps.findPR(repoPath, cur) : null;
+  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;
+  let prAttempt = null;
   if (!prUrl && push.status === 0) {
-    const { title, body } = prTitleBody(task, cur);
-    const pr = deps.openPR(repoPath, { title, body, branch: cur, base: cfg.defaultBranch });
-    prUrl = pr.ok && pr.url ? pr.url : null;
+    const { title, body } = prTitleBody(task, ship.headBranch);
+    prAttempt = deps.openPR(repoPath, {
+      title,
+      body,
+      branch: ship.headBranch,
+      base: cfg.defaultBranch,
+    });
+    prUrl = prAttempt.ok && prAttempt.url ? prAttempt.url : null;
   }
-  const { title } = prTitleBody(task, cur);
+  const { title } = prTitleBody(task, ship.headBranch);
+  const recoveredNote = ship.recoveredFrom
+    ? ` The child had switched to \`${ship.recoveredFrom}\`; hilos recovered its HEAD onto \`${ship.headBranch}\`.`
+    : "";
+  const prFailure =
+    prAttempt && !prUrl
+      ? oneLine(
+          (prAttempt.stderr || prAttempt.stdout || "gh did not return a pull request URL").trim(),
+          200,
+        )
+      : "";
   // Seamless single card (0289): settle onto the live status message when one was
   // streaming this run; the workspace setting decides channel visibility.
   // Otherwise post a fresh final report.
   const reportArgs = {
     channelId,
-    title: `Shipped: ${title}`,
+    title: prUrl
+      ? `Shipped: ${title}`
+      : push.status === 0
+        ? `PR failed: ${title}`
+        : `Push failed: ${title}`,
     summary: prUrl
-      ? `${lead}the coding agent committed on \`${cur}\` and opened a pull request.`
+      ? `${lead}the coding agent committed the work itself and opened a pull request from \`${ship.headBranch}\`.${recoveredNote}`
       : push.status === 0
-        ? `${lead}the coding agent committed and pushed \`${cur}\`. Open a PR manually — \`gh\` didn't return one.`
-        : `${lead}the coding agent committed on \`${cur}\` locally, but pushing it failed.`,
+        ? `${lead}the coding agent committed and pushed \`${ship.headBranch}\`, but GitHub rejected PR creation.${recoveredNote}`
+        : `${lead}the coding agent committed locally, but pushing \`${ship.headBranch}\` failed.${recoveredNote}`,
     prUrl: prUrl || undefined,
-    caveats: push.status === 0 ? [] : [`git push failed: ${(push.stderr || "").trim().slice(0, 200)}`],
+    caveats:
+      push.status !== 0
+        ? [`git push failed: ${(push.stderr || "").trim().slice(0, 200)}`]
+        : prFailure
+          ? [`gh pr create failed: ${prFailure}`]
+          : [],
   };
   await tool(
     "post_report",
@@ -377,11 +581,25 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
     await tool("update_run", {
       runId,
       ...(prUrl ? { prUrl } : {}),
-      status: "awaiting_review",
+      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",
+          }
+        : {}),
       ...(settleId ? { reportMsgId: settleId } : {}),
     }).catch(() => {});
   }
-  return { status: push.status === 0 ? "pushed" : "commit-local", branch: cur, prUrl };
+  const status =
+    push.status !== 0 ? "commit-local" : prUrl ? "pushed" : "pr-failed";
+  return {
+    status,
+    branch: ship.headBranch,
+    prUrl,
+  };
 }
 
 // Sentinel the router model emits when the latest message is a request to change
@@ -1279,34 +1497,98 @@ async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps,
     let run;
     // Model preset (0504): same run-time resolution as the repo path.
     const modelArgs = await modelArgsFor(cfg, vendor);
+    // Project pin (0608): opencode reads its project from PWD, so without this
+    // a folder run could edit the daemon's launch directory instead of the
+    // folder the channel is linked to. [] for every other vendor.
+    const dirArgs = codeDirArgs(vendor, folderPath, cfg.codingCmd);
+    const codeArgs = [
+      ...parts.slice(1),
+      ...modelArgs,
+      ...dirArgs,
+      ...streamArgs,
+    ];
+    const handleCliData = (c) => {
+      const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
+      if (lines.length) lastLine = lines[lines.length - 1];
+      if (resultParser) {
+        try {
+          foldResultEvents(resultParser.push(String(c)));
+        } catch {
+          /* result extraction must never break the run */
+        }
+      }
+      if (emitter) {
+        try {
+          emitter.feed(c);
+        } catch {
+          /* a progress fold must never break the run */
+        }
+      }
+    };
     try {
-      run = await deps.runCli({
-        cmd: parts[0],
-        args: [...parts.slice(1), ...modelArgs, ...streamArgs, memoryPreamble(workspaceMemory) + promptText],
-        cwd: folderPath,
-        timeoutMs: cfg.runTimeoutMs,
-        label: "coding",
-        signal,
-        env: codingChildEnv(cfg),
-        onData: (c) => {
-          const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
-          if (lines.length) lastLine = lines[lines.length - 1];
-          if (resultParser) {
-            try {
-              foldResultEvents(resultParser.push(String(c)));
-            } catch {
-              /* result extraction must never break the run */
-            }
-          }
-          if (emitter) {
-            try {
-              emitter.feed(c);
-            } catch {
-              /* a progress fold must never break the run */
-            }
-          }
-        },
+      const useAcpTransport = shouldUseAcpTransport({
+        vendor,
+        acpTransport: cfg.acpTransport,
+        runtimePermissions: caps.runtimePermissions,
+        codeArgs,
+        codingCmd: cfg.codingCmd,
       });
+      const useRuntimePermissionBridge =
+        !useAcpTransport &&
+        shouldUseRuntimePermissionBridge({
+          vendor,
+          runtimePermissions: caps.runtimePermissions,
+          codeArgs,
+          codingCmd: cfg.codingCmd,
+        });
+      if (useAcpTransport) {
+        run = await deps.runAcpSession({
+          cmd: parts[0],
+          vendor,
+          cwd: folderPath,
+          prompt: memoryPreamble(workspaceMemory) + promptText,
+          timeoutMs: cfg.runTimeoutMs,
+          signal,
+          env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
+          onData: handleCliData,
+          ...openCodePermissionCallbacks({
+            tool,
+            channelId,
+            threadRoot,
+            provider: vendor,
+          }),
+        });
+      } else if (useRuntimePermissionBridge) {
+        run = await deps.runOpenCodeHttpSession({
+          cmd: parts[0],
+          args: codeArgs,
+          cwd: folderPath,
+          prompt: memoryPreamble(workspaceMemory) + promptText,
+          timeoutMs: cfg.runTimeoutMs,
+          signal,
+          env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
+          onData: handleCliData,
+          ...openCodePermissionCallbacks({
+            tool,
+            channelId,
+            threadRoot,
+          }),
+        });
+      } else {
+        run = await deps.runCli({
+          cmd: parts[0],
+          args: [
+            ...codeArgs,
+            memoryPreamble(workspaceMemory) + promptText,
+          ],
+          cwd: folderPath,
+          timeoutMs: cfg.runTimeoutMs,
+          label: "coding",
+          signal,
+          env: codingChildEnv(cfg),
+          onData: handleCliData,
+        });
+      }
     } finally {
       stopHeartbeat();
       if (emitter) {
@@ -1602,6 +1884,43 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     }
   }
 
+  // MERGE / CLOSE RELAY (0704): "merge it" in a PR thread used to get an answer
+  // describing the button a human should press. Now it is executed — through the
+  // server, which is the authority: merge_pr / close_pr take the id of the human
+  // message that asked, re-classify that text with a forced-tool model call, and
+  // check the author's workspace role before spending the App's write token. The
+  // daemon carries no new trust; it only stops swallowing the request.
+  //
+  // Runs BEFORE the chat/code split for the same reason the server runs it before
+  // the coding gates: a merge instruction must never be read as a request to
+  // start a new run. Every "no" here falls through to today's behavior.
+  {
+    const relay = prActionRelayDecision({
+      body: message.body,
+      threadPr: message.threadPr,
+      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,
+    });
+    if (relay.relay) {
+      const verb = relay.action;
+      console.log(`  ${verb} → relaying PR #${relay.anchor.prNumber} to the server (it decides)`);
+      const result = await tool(verb === "merge" ? "merge_pr" : "close_pr", {
+        channelId,
+        // The mention itself is the instruction on record. The server verifies
+        // it is a human's message, in this channel, from an owner or admin, and
+        // that it really asks for THIS action — citing anything else fails.
+        instructionMessageId: message.id,
+      }).catch((e) => ({ ok: false, error: `I couldn't reach hilos to ${verb} that pull request: ${e?.message || e}` }));
+      const reply = prActionReply(result);
+      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 };
+    }
+  }
+
   // No repo linked → either FOLDER mode (0322: a channel mapped to a plain local
   // folder can still get coding work done) or, failing that, just reply. A linked
   // repo always wins — the folder map is only consulted when there's no repo link.
@@ -1898,22 +2217,65 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   git(repoPath, ["fetch", "origin", cfg.defaultBranch]);
 
   // Same-branch iteration: continue an existing PR on its own branch and push
-  // onto it, so the PR updates in place instead of a duplicate opening. Two ways
+  // onto it, so the PR updates in place instead of a duplicate opening. Three ways
   // in, and an explicit token WINS when both apply (they agree — same PR):
   //   1. detectPrContinuation — an explicit "PR <url>" in the text (the server's
   //      "request changes" rework ping, or a person naming a PR). The fallback.
   //   2. the run resolver's 'iterate' (0281) — a plain follow-up reply in a thread
   //      whose run already owns an OPEN PR. The PRIMARY path.
+  //   3. the THREAD ANCHOR (0704) — no active run owns this thread, but the server
+  //      says (on list_mentions, as `threadPr`) that the thread is about a pull
+  //      request: a second agent asked here, or a reply long after the first run
+  //      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 iterateUrl = cont?.url || (followupMode === "iterate" && activeRun?.prUrl) || null;
+  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
+  // says so on the status card rather than pushing onto a merged PR.
+  let anchorAdopt = null;
+  let anchorNote = "";
+  if (!cont?.url && !runIterateUrl) {
+    const decision = anchorIterateDecision({
+      threadPr: message.threadPr,
+      repoFullName,
+      signal: followupSignal,
+    });
+    if (decision.adopt && deps.prState) {
+      const live = deps.prState(repoPath, decision.anchor.prUrl);
+      const confirmed = confirmAnchorOpen({ live, anchor: decision.anchor });
+      if (confirmed.ok) {
+        anchorAdopt = {
+          prUrl: decision.anchor.prUrl,
+          prNumber: decision.anchor.prNumber,
+          branch: confirmed.branch,
+        };
+        console.log(
+          `  code → thread anchor: PR #${decision.anchor.prNumber} is open on \`${confirmed.branch}\` — adopting it`,
+        );
+      } else {
+        anchorNote = staleAnchorNote({ reason: confirmed.reason, anchor: decision.anchor });
+        console.log(
+          `  ! thread anchor PR #${decision.anchor.prNumber} not adopted (${confirmed.reason}) — new branch`,
+        );
+      }
+    } else if (decision.adopt) {
+      anchorNote = staleAnchorNote({ reason: "unverified", anchor: decision.anchor });
+    } else if (decision.reason === "anchor-merged" || decision.reason === "anchor-closed") {
+      anchorNote = staleAnchorNote({ reason: decision.reason, anchor: decision.anchor });
+    }
+  }
+  const iterateUrl = cont?.url || runIterateUrl || anchorAdopt?.prUrl || null;
   let branch = null;
   let continuingPrUrl = null;
-  if (iterateUrl && deps.prHeadRef) {
+  if (iterateUrl && (deps.prHeadRef || anchorAdopt)) {
     // Resolve the PR's head branch (source of truth); for a run-based iterate the
-    // run's recorded branch is a fallback if gh can't view the PR.
+    // 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 =
-      deps.prHeadRef(repoPath, iterateUrl) ||
+      (anchorAdopt?.prUrl === iterateUrl ? anchorAdopt.branch : null) ||
+      deps.prHeadRef?.(repoPath, iterateUrl) ||
       (followupMode === "iterate" ? activeRun?.branch || null : null);
     if (headRef) {
       // Fetch the PR branch, then point a local branch at its tip via FETCH_HEAD
@@ -1931,6 +2293,12 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         console.log(
           `  ! couldn't check out PR branch \`${headRef}\` (falling back to a new branch): ${(sw.stderr || "").trim().slice(0, 200)}`,
         );
+        // An adopted anchor that can't be checked out is the same broken promise
+        // as a stale one — the thread asked about a PR and gets a new branch, so
+        // the status card has to say it.
+        if (anchorAdopt?.prUrl === iterateUrl) {
+          anchorNote = staleAnchorNote({ reason: "checkout-failed", anchor: anchorAdopt });
+        }
       }
     }
   }
@@ -1982,6 +2350,12 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   } else if (effectiveMode === "redirect") {
     const n = activeRun?.prNumber || prNumberFromUrl(activeRun?.prUrl);
     ackBody = `Starting a new PR${n ? ` (separate from #${n})` : ""} on \`${branch}\`.`;
+  } else if (anchorNote) {
+    // The thread is about a pull request this run could NOT adopt (0704). Say it
+    // on the status card itself — silence here would read as "pushing to my PR"
+    // while a fresh branch is being cut. Still one card, per the run-output
+    // contract: no extra chat message.
+    ackBody = `${anchorNote} ${ackBody}`;
   }
   const ack = await tool("post_message", { channelId, parentId, body: ackBody });
   const ackId = ack?.messageId ?? null;
@@ -2037,7 +2411,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
         branch,
         // Map an unrecognized command to null rather than the off-vocabulary
         // "unknown" — provider is documented as
-        // claude_code|codex|cursor|antigravity|hermes|hilos.
+        // claude_code|codex|cursor|opencode|antigravity|hermes|hilos.
         provider: (() => {
           const v = detectVendor(cfg.codingCmd);
           return v === "unknown" ? null : v;
@@ -2050,7 +2424,14 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   }
   // Keep the inspectable continuation/redirect statement (don't overwrite it with
   // an LLM plan) so a human can correct the routing before code lands.
-  if (ackId && caps.editMessage && chatCmdFor(cfg) && !continuingPrUrl && effectiveMode !== "redirect") {
+  if (
+    ackId &&
+    caps.editMessage &&
+    chatCmdFor(cfg) &&
+    !continuingPrUrl &&
+    !anchorNote &&
+    effectiveMode !== "redirect"
+  ) {
     // Feed the ack the router's distilled brief AND the conversation — not the raw
     // mention — so it states a real plan instead of "what's the task?".
     const plan = await proposePlanAck({
@@ -2085,9 +2466,13 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // (get_active_run) with no local match means the session likely lives on another
   // machine/instance — a bad `--resume` id makes claude error → empty diff → a failed
   // run, so we DON'T resume and degrade to today's branch+feedback (never worse).
-  // claude_code + cursor have proven resume flags (0282/0573); codex/unknown → [].
+  // claude_code + cursor + opencode have proven resume flags (0282/0573/0608);
+  // codex/unknown → []. The gate itself is pure (resumeDecision in resume.mjs):
+  // vendor, machine, project and server agreement all have to line up, and any
+  // "no" degrades to the branch+feedback iterate rather than risking a bad id.
+  const projectKey = codeProjectKey(vendor, repoPath, cfg.codingCmd);
   let resumeSessionId = null;
-  if (effectiveMode === "iterate" && (vendor === "claude_code" || vendor === "cursor")) {
+  if (effectiveMode === "iterate") {
     const local = (() => {
       try {
         return readStateEntry(HILOS_DIR, threadRoot);
@@ -2096,14 +2481,18 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       }
     })();
     const serverSid = activeRun?.providerSessionId || null;
-    // Confidence = a local record, for THIS machine, with a session id. If the server
-    // also has one it must AGREE (a mismatch means the run moved — don't resume a
-    // stale/foreign id). A server-only id (no local record) is never resumed.
-    if (local && local.machine === machine && local.sessionId && (!serverSid || serverSid === local.sessionId)) {
-      resumeSessionId = local.sessionId;
-      console.log(`  code → resuming session ${local.sessionId} for this iterate (local + machine match)`);
-    } else if (serverSid) {
-      console.log("  code → not resuming (session recorded on another machine or unverified locally); using branch + feedback");
+    const decision = resumeDecision({
+      vendor,
+      entry: local,
+      serverSessionId: serverSid,
+      machine,
+      projectKey,
+    });
+    if (decision.sessionId) {
+      resumeSessionId = decision.sessionId;
+      console.log(`  code → resuming session ${decision.sessionId} for this iterate (local + machine match)`);
+    } else if (local?.sessionId || serverSid) {
+      console.log(`  code → not resuming (${decision.reason}); using branch + feedback`);
     }
   }
 
@@ -2220,34 +2609,103 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // list (cursor only today) — [] when unset/unresolvable, so the tool's
     // default stands. Inserted before resume/stream flags, after the base.
     const modelArgs = await modelArgsFor(cfg, vendor);
+    // Project pin (0608, opencode only): the CLI resolves its project from PWD,
+    // not the spawn cwd, and its sessions are per project — `--dir` makes both
+    // deterministic. [] for every other vendor (and for an `--attach`ed run,
+    // where the project lives on the remote server), so their ARGV is unchanged.
+    // The spawned PWD now matches the cwd too (0615); `--dir` stays as the
+    // CLI's own explicit contract, and to keep attach runs off our local path.
+    const dirArgs = codeDirArgs(vendor, repoPath, cfg.codingCmd);
     const codeArgs = streamOn
-      ? [...parts.slice(1), ...modelArgs, ...resumeArgs, ...streamArgs]
-      : [...parts.slice(1), ...modelArgs, ...resumeArgs];
+      ? [...parts.slice(1), ...modelArgs, ...dirArgs, ...resumeArgs, ...streamArgs]
+      : [...parts.slice(1), ...modelArgs, ...dirArgs, ...resumeArgs];
+    const handleCliData = (c) => {
+      // Keep tracking lastLine as a fallback (legacy heartbeat / honesty).
+      const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
+      if (lines.length) lastLine = lines[lines.length - 1];
+      if (emitter) {
+        try {
+          emitter.feed(c);
+        } catch {
+          /* a progress fold must never break the run */
+        }
+      }
+    };
     let run;
     try {
-      run = await runCli({
-        cmd: parts[0],
-        args: [...codeArgs, memoryPreamble(workspaceMemory) + promptText],
-        cwd: repoPath,
-        timeoutMs: cfg.runTimeoutMs,
-        label: "coding",
-        signal,
-        env: codingChildEnv(cfg),
-        onData: (c) => {
-          // Keep tracking lastLine as a fallback (legacy heartbeat / honesty).
-          const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
-          if (lines.length) lastLine = lines[lines.length - 1];
-          if (emitter) {
-            try {
-              emitter.feed(c);
-            } catch {
-              /* a progress fold must never break the run */
-            }
-          }
-        },
+      // OpenCode's own non-interactive CLI auto-rejects every permission ask
+      // unless --auto is present. For the gated tiers, bypass that responder
+      // and own the authenticated HTTP session + SSE stream directly so hilos
+      // is the sole authority answering the paused tool call (0593).
+      const useAcpTransport = shouldUseAcpTransport({
+        vendor,
+        acpTransport: cfg.acpTransport,
+        runtimePermissions: caps.runtimePermissions,
+        codeArgs,
+        codingCmd: cfg.codingCmd,
+        resumeSessionId: resume ? resumeSessionId : null,
       });
+      const useRuntimePermissionBridge =
+        !useAcpTransport &&
+        shouldUseRuntimePermissionBridge({
+          vendor,
+          runtimePermissions: caps.runtimePermissions,
+          codeArgs,
+          codingCmd: cfg.codingCmd,
+        });
+      if (useAcpTransport) {
+        run = await deps.runAcpSession({
+          cmd: parts[0],
+          vendor,
+          cwd: repoPath,
+          prompt: memoryPreamble(workspaceMemory) + promptText,
+          timeoutMs: cfg.runTimeoutMs,
+          signal,
+          env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
+          onData: handleCliData,
+          ...openCodePermissionCallbacks({
+            tool,
+            channelId,
+            threadRoot,
+            runId,
+            provider: vendor,
+          }),
+        });
+      } else if (useRuntimePermissionBridge) {
+        run = await deps.runOpenCodeHttpSession({
+          cmd: parts[0],
+          args: codeArgs,
+          cwd: repoPath,
+          prompt: memoryPreamble(workspaceMemory) + promptText,
+          timeoutMs: cfg.runTimeoutMs,
+          signal,
+          // A model running inside the server must never inherit the daemon's
+          // hilos bearer token. The bridge's random loopback password is added
+          // after this scrub and dies with the process group.
+          env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
+          onData: handleCliData,
+          ...openCodePermissionCallbacks({
+            tool,
+            channelId,
+            threadRoot,
+            runId,
+          }),
+        });
+      } else {
+        run = await runCli({
+          cmd: parts[0],
+          args: [...codeArgs, memoryPreamble(workspaceMemory) + promptText],
+          cwd: repoPath,
+          timeoutMs: cfg.runTimeoutMs,
+          label: "coding",
+          signal,
+          env: codingChildEnv(cfg),
+          onData: handleCliData,
+        });
+      }
     } finally {
       stopHeartbeat();
+      if (run?.sessionId) runSessionId = run.sessionId;
       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,
@@ -2355,6 +2813,11 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           prUrl: prUrl || continuingPrUrl || null,
           sessionId: sid,
           machine,
+          // The CLI that created the session (a `ses_…` is meaningless to
+          // claude's `--resume`) and the project it belongs to — opencode
+          // scopes sessions per project. The gate above requires both (0608).
+          vendor,
+          cwd: projectKey,
           updatedAt: new Date().toISOString(),
         });
       }