@evident-ai/cli 3.0.0 → 3.0.1-dev.0385cc8

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { createRequire } from "module";
 import { Command } from "commander";
 
 // src/commands/login.ts
@@ -32,10 +33,10 @@ function setTunnelUrl(url) {
   tunnelOverride = url ? url.replace(/\/+$/, "") : void 0;
 }
 function getApiUrl() {
-  return process.env.EVIDENT_API_URL ?? endpointOverride ?? defaults.apiUrl;
+  return endpointOverride ?? process.env.EVIDENT_API_URL ?? defaults.apiUrl;
 }
 function getTunnelUrl() {
-  return process.env.EVIDENT_TUNNEL_URL ?? tunnelOverride ?? defaults.tunnelUrl;
+  return tunnelOverride ?? process.env.EVIDENT_TUNNEL_URL ?? defaults.tunnelUrl;
 }
 var config = new Conf({
   projectName: "evident",
@@ -54,19 +55,28 @@ function getApiUrlConfig() {
 function getTunnelUrlConfig() {
   return getTunnelUrl();
 }
+function credentialsKey() {
+  return getApiUrl();
+}
 function getCredentials() {
-  return {
-    token: credentials.get("token"),
-    user: credentials.get("user"),
-    expiresAt: credentials.get("expiresAt")
-  };
+  const byEndpoint = credentials.get("byEndpoint") ?? {};
+  return byEndpoint[credentialsKey()] ?? {};
 }
 function setCredentials(creds) {
-  if (creds.token) credentials.set("token", creds.token);
-  if (creds.user) credentials.set("user", creds.user);
-  if (creds.expiresAt) credentials.set("expiresAt", creds.expiresAt);
+  const byEndpoint = credentials.get("byEndpoint") ?? {};
+  byEndpoint[credentialsKey()] = {
+    token: creds.token,
+    user: creds.user,
+    expiresAt: creds.expiresAt
+  };
+  credentials.set("byEndpoint", byEndpoint);
 }
 function clearCredentials() {
+  const byEndpoint = credentials.get("byEndpoint") ?? {};
+  delete byEndpoint[credentialsKey()];
+  credentials.set("byEndpoint", byEndpoint);
+}
+function clearAllCredentials() {
   credentials.clear();
 }
 function getCliName() {
@@ -176,7 +186,6 @@ var api = {
 
 // src/lib/keychain.ts
 var SERVICE_NAME = "evident-cli";
-var ACCOUNT_NAME = "default";
 async function getKeytar() {
   try {
     const keytar = await import("keytar");
@@ -188,10 +197,13 @@ async function getKeytar() {
     return null;
   }
 }
+function keychainAccount() {
+  return getApiUrlConfig();
+}
 async function storeToken(credentials2) {
   const keytar = await getKeytar();
   if (keytar) {
-    await keytar.setPassword(SERVICE_NAME, ACCOUNT_NAME, JSON.stringify(credentials2));
+    await keytar.setPassword(SERVICE_NAME, keychainAccount(), JSON.stringify(credentials2));
   } else {
     setCredentials({
       token: credentials2.token,
@@ -203,12 +215,13 @@ async function storeToken(credentials2) {
 async function getToken() {
   const keytar = await getKeytar();
   if (keytar) {
-    const stored = await keytar.getPassword(SERVICE_NAME, ACCOUNT_NAME);
+    const account = keychainAccount();
+    const stored = await keytar.getPassword(SERVICE_NAME, account);
     if (stored) {
       try {
         return JSON.parse(stored);
       } catch {
-        await keytar.deletePassword(SERVICE_NAME, ACCOUNT_NAME);
+        await keytar.deletePassword(SERVICE_NAME, account);
         return null;
       }
     }
@@ -223,12 +236,26 @@ async function getToken() {
   }
   return null;
 }
-async function deleteToken() {
+async function deleteToken(options = {}) {
   const keytar = await getKeytar();
   if (keytar) {
-    await keytar.deletePassword(SERVICE_NAME, ACCOUNT_NAME);
+    if (options.all) {
+      const all = await keytar.findCredentials(SERVICE_NAME).catch(() => []);
+      await Promise.all(
+        all.map(
+          (entry) => keytar.deletePassword(SERVICE_NAME, entry.account).catch(() => {
+          })
+        )
+      );
+    } else {
+      await keytar.deletePassword(SERVICE_NAME, keychainAccount());
+    }
+  }
+  if (options.all) {
+    clearAllCredentials();
+  } else {
+    clearCredentials();
   }
-  clearCredentials();
 }
 
 // src/utils/ui.ts
@@ -258,14 +285,14 @@ function blank() {
   console.log();
 }
 function waitForEnter(prompt = "Press Enter to continue...") {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     process.stdout.write(chalk.dim(prompt));
     const handler = () => {
       process.stdin.removeListener("data", handler);
       process.stdin.setRawMode?.(false);
       process.stdin.pause();
       console.log();
-      resolve();
+      resolve2();
     };
     if (process.stdin.isTTY) {
       process.stdin.setRawMode?.(true);
@@ -275,7 +302,7 @@ function waitForEnter(prompt = "Press Enter to continue...") {
   });
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
 // src/commands/login.ts
@@ -349,19 +376,19 @@ async function tokenLogin() {
   console.log("Visit your Evident dashboard to generate a CLI token.");
   blank();
   process.stdout.write("Paste token: ");
-  const token = await new Promise((resolve) => {
+  const token = await new Promise((resolve2) => {
     let data = "";
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
     process.stdin.on("end", () => {
-      resolve(data.trim());
+      resolve2(data.trim());
     });
     if (process.stdin.isTTY) {
       process.stdin.once("data", (chunk) => {
         process.stdin.pause();
-        resolve(chunk.toString().trim());
+        resolve2(chunk.toString().trim());
       });
       process.stdin.resume();
     }
@@ -396,25 +423,32 @@ async function login(options) {
 }
 
 // src/commands/logout.ts
-async function logout() {
+async function logout(options = {}) {
+  if (options.all) {
+    await deleteToken({ all: true });
+    printSuccess("Logged out of all endpoints.");
+    return;
+  }
   const credentials2 = await getToken();
   if (!credentials2) {
-    printWarning("You are not logged in.");
+    printWarning(`You are not logged in to ${getApiUrlConfig()}.`);
     return;
   }
   await deleteToken();
-  printSuccess("Logged out successfully.");
+  printSuccess(`Logged out of ${getApiUrlConfig()}.`);
 }
 
 // src/commands/whoami.ts
 import chalk3 from "chalk";
 async function whoami() {
+  const apiUrl = getApiUrlConfig();
   const credentials2 = await getToken();
   if (!credentials2) {
-    printError("Not logged in. Run the `login` command to authenticate.");
+    printError(`Not logged in to ${apiUrl}. Run the \`login\` command to authenticate.`);
     process.exit(1);
   }
   blank();
+  console.log(keyValue("Endpoint", apiUrl));
   console.log(keyValue("User", chalk3.bold(credentials2.user.email)));
   console.log(keyValue("User ID", credentials2.user.id));
   if (credentials2.expiresAt) {
@@ -449,9 +483,36 @@ var TelemetryEventTypes = {
 
 // ../../packages/types/src/tunnel/index.ts
 var MAX_FRAME_BYTES = 256 * 1024;
+var TUNNEL_DRAIN_PING_PATH = "/__evident/drain";
+
+// ../../packages/types/src/logging/index.ts
+var CORRELATION_ID_HEADER = "x-evident-correlation-id";
+function log(level, event, fields) {
+  const method = level === "debug" ? "log" : level;
+  try {
+    console[method]("[evident]", JSON.stringify({ level, event, ...fields }));
+  } catch (err) {
+    console.error(
+      "[evident] log_serialize_failed",
+      event,
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+function stripQuery(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    const q = url.indexOf("?");
+    return q === -1 ? url : url.slice(0, q);
+  }
+}
 
 // src/lib/telemetry.ts
-var CLI_VERSION = process.env.npm_package_version || "unknown";
+var CLI_VERSION = (true ? "3.0.0" : void 0) ?? process.env.npm_package_version ?? "unknown";
+function getCliVersion() {
+  return CLI_VERSION;
+}
 var eventBuffer = [];
 var flushTimeout = null;
 var isShuttingDown = false;
@@ -645,11 +706,24 @@ async function waitForOpenCodeHealth(port, timeoutMs = 3e4) {
     if (health.healthy) {
       return health;
     }
-    await new Promise((resolve) => setTimeout(resolve, 1e3));
+    await new Promise((resolve2) => setTimeout(resolve2, 1e3));
   }
   return { healthy: false, error: "Timeout waiting for OpenCode to be healthy" };
 }
 
+// src/lib/opencode/opencode-version-gate.ts
+var QUEUE_VALIDATED_OPENCODE_VERSIONS = ["1.17.11", "1.18.3"];
+function isQueueValidatedVersion(version2) {
+  if (!version2) return false;
+  return QUEUE_VALIDATED_OPENCODE_VERSIONS.includes(version2);
+}
+function buildOpenCodeVersionWarning(version2) {
+  if (isQueueValidatedVersion(version2)) return null;
+  const detected = version2 ? `v${version2}` : "unknown";
+  const validated = QUEUE_VALIDATED_OPENCODE_VERSIONS.map((v) => `v${v}`).join(", ");
+  return `Warning: opencode ${detected} is not a queue-validated version (validated: ${validated}). Native message queuing \u2014 which channel (Slack/WhatsApp) message handling relies on \u2014 is unverified on this version; queued/follow-up messages may behave unexpectedly. Continuing anyway. Bumping the validated set requires re-running the queue validation.`;
+}
+
 // src/lib/opencode/process.ts
 import { execSync, spawn } from "child_process";
 var OPENCODE_PORT_RANGE = [4096, 4097, 4098, 4099, 4100];
@@ -940,19 +1014,174 @@ async function promptOpenCodeInstall(interactive) {
 }
 
 // src/lib/opencode/session.ts
-async function createOpenCodeSession(port) {
-  const response = await fetch(`http://localhost:${port}/session`, {
+function opencodeBase(port) {
+  return `http://127.0.0.1:${port}`;
+}
+async function getOpenCodeDirectory(port) {
+  try {
+    const res = await fetch(`${opencodeBase(port)}/path`);
+    if (!res.ok) return null;
+    const body = await res.json();
+    const dir = typeof body.directory === "string" && body.directory || typeof body.worktree === "string" && body.worktree || typeof body.path?.cwd === "string" && body.path.cwd || typeof body.path?.directory === "string" && body.path.directory || null;
+    return dir && dir.trim() ? dir.trim() : null;
+  } catch {
+    return null;
+  }
+}
+function roleOf(m) {
+  if (!m || typeof m !== "object") return void 0;
+  if (typeof m.role === "string") return m.role;
+  const infoRole = m.info?.role;
+  return typeof infoRole === "string" ? infoRole : void 0;
+}
+function completedOf(m) {
+  if (!m || typeof m !== "object") return void 0;
+  return m.info?.time?.completed ?? m.time?.completed;
+}
+function createdOf(m) {
+  if (!m || typeof m !== "object") return void 0;
+  return m.info?.time?.created ?? m.time?.created;
+}
+function idOf(m) {
+  if (!m || typeof m !== "object") return void 0;
+  if (typeof m.id === "string") return m.id;
+  const infoId = m.info?.id;
+  return typeof infoId === "string" ? infoId : void 0;
+}
+function parentIdOf(m) {
+  if (!m || typeof m !== "object") return void 0;
+  if (typeof m.parentID === "string") return m.parentID;
+  const infoParent = m.info?.parentID;
+  return typeof infoParent === "string" ? infoParent : void 0;
+}
+function finishOf(m) {
+  if (!m || typeof m !== "object") return void 0;
+  if (typeof m.finish === "string") return m.finish;
+  const infoFinish = m.info?.finish;
+  return typeof infoFinish === "string" ? infoFinish : void 0;
+}
+function errorOf(m) {
+  if (!m || typeof m !== "object") return void 0;
+  return m.info?.error ?? m.error;
+}
+function isAssistantInFlight(m) {
+  if (completedOf(m) == null) return true;
+  return finishOf(m) === "tool-calls";
+}
+async function getSessionMessages(port, sessionId) {
+  try {
+    const res = await fetch(`${opencodeBase(port)}/session/${sessionId}/message`);
+    if (!res.ok) return null;
+    const body = await res.json();
+    return Array.isArray(body) ? body : null;
+  } catch {
+    return null;
+  }
+}
+function isSessionActivelyGenerating(messages) {
+  if (!messages || messages.length === 0) return false;
+  const last = messages[messages.length - 1];
+  if (roleOf(last) !== "assistant") return false;
+  return completedOf(last) == null;
+}
+function sessionLastActivityMs(session) {
+  const candidates = [
+    session.time?.updated,
+    session.time?.created,
+    session.time_updated,
+    session.time_created,
+    session.updated,
+    session.created
+  ];
+  for (const c of candidates) {
+    if (typeof c === "number" && Number.isFinite(c)) return c;
+  }
+  return null;
+}
+async function listSessions(port) {
+  try {
+    const res = await fetch(`${opencodeBase(port)}/session`);
+    if (!res.ok) return null;
+    const body = await res.json();
+    return Array.isArray(body) ? body : null;
+  } catch {
+    return null;
+  }
+}
+async function deleteSession(port, id) {
+  try {
+    const res = await fetch(`${opencodeBase(port)}/session/${id}`, { method: "DELETE" });
+    return res.status >= 200 && res.status < 300;
+  } catch {
+    return false;
+  }
+}
+async function sessionExists(port, id) {
+  try {
+    const res = await fetch(`${opencodeBase(port)}/session/${id}`);
+    if (res.status >= 200 && res.status < 300) return true;
+    if (res.status === 404) return false;
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function getSessionStatuses(port) {
+  try {
+    const res = await fetch(`${opencodeBase(port)}/session/status`);
+    if (!res.ok) {
+      console.error(
+        `[getSessionStatuses] GET /session/status returned HTTP ${res.status} (port ${port})`
+      );
+      return null;
+    }
+    const body = await res.json();
+    if (body == null || typeof body !== "object" || Array.isArray(body)) {
+      console.error(
+        `[getSessionStatuses] GET /session/status body was not a plain object (port ${port})`
+      );
+      return null;
+    }
+    return body;
+  } catch (err) {
+    console.error(
+      `[getSessionStatuses] GET /session/status failed (port ${port}): ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
+  }
+}
+async function isSessionOngoing(port, id) {
+  const map = await getSessionStatuses(port);
+  if (map == null) return null;
+  const entry = map[id];
+  return entry != null && entry.type !== "idle";
+}
+async function createOpenCodeSession(port, directory) {
+  const url = new URL(`${opencodeBase(port)}/session`);
+  if (directory && directory.trim()) {
+    url.searchParams.set("directory", directory.trim());
+  }
+  const response = await fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({})
   });
   if (!response.ok) {
-    throw new Error(`Failed to create session: HTTP ${response.status}`);
+    const text = await response.text().catch(() => "");
+    throw new Error(`Failed to create session: HTTP ${response.status}${text ? `: ${text}` : ""}`);
   }
   const data = await response.json();
   return data.id;
 }
-async function sendMessageToOpenCode(port, sessionId, content, options, hooks, maxWaitMs = 10 * 60 * 1e3) {
+function messageText(m) {
+  if (!m || !Array.isArray(m.parts)) return "";
+  return m.parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text).join("");
+}
+async function sendPromptAsync(port, sessionId, content, options) {
+  const before = await getSessionMessages(port, sessionId);
+  const knownUserIds = new Set(
+    (before ?? []).filter((m) => roleOf(m) === "user").map((m) => idOf(m)).filter((id) => typeof id === "string")
+  );
   const body = {
     parts: [{ type: "text", text: content }]
   };
@@ -968,76 +1197,218 @@ async function sendMessageToOpenCode(port, sessionId, content, options, hooks, m
       };
     }
   }
-  let pollDone = false;
-  const reportedQuestions = /* @__PURE__ */ new Set();
-  const reportedPermissions = /* @__PURE__ */ new Set();
-  const pollInteractive = async () => {
-    while (!pollDone) {
-      await new Promise((resolve) => setTimeout(resolve, 1e3));
-      if (pollDone) break;
-      if (hooks?.onQuestion) {
-        try {
-          const res = await fetch(`http://localhost:${port}/question`);
-          if (res.ok) {
-            const questions = await res.json();
-            for (const q of questions) {
-              if (q.sessionID === sessionId && !reportedQuestions.has(q.id)) {
-                reportedQuestions.add(q.id);
-                await hooks.onQuestion(q);
-              }
-            }
-          }
-        } catch {
-        }
-      }
-      if (hooks?.onPermission) {
-        try {
-          const res = await fetch(`http://localhost:${port}/permission`);
-          if (res.ok) {
-            const permissions = await res.json();
-            for (const p of permissions) {
-              if (p.sessionID === sessionId && !reportedPermissions.has(p.id)) {
-                reportedPermissions.add(p.id);
-                await hooks.onPermission(p);
-              }
-            }
-          }
-        } catch {
+  const res = await fetch(`${opencodeBase(port)}/session/${sessionId}/prompt_async`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (res.status < 200 || res.status >= 300) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`OpenCode prompt_async failed: HTTP ${res.status}${text ? `: ${text}` : ""}`);
+  }
+  const READ_BACK_ATTEMPTS = 5;
+  const READ_BACK_DELAY_MS = 150;
+  for (let attempt = 0; attempt < READ_BACK_ATTEMPTS; attempt++) {
+    const after = await getSessionMessages(port, sessionId);
+    if (after) {
+      let best = null;
+      for (const m of after) {
+        if (roleOf(m) !== "user") continue;
+        const id = idOf(m);
+        if (typeof id !== "string" || knownUserIds.has(id)) continue;
+        if (messageText(m) !== content) continue;
+        const created = createdOf(m) ?? 0;
+        if (best === null || created > best.created) {
+          best = { id, created };
         }
       }
+      if (best) return best.id;
+    }
+    if (attempt < READ_BACK_ATTEMPTS - 1) {
+      await new Promise((resolve2) => setTimeout(resolve2, READ_BACK_DELAY_MS));
+    }
+  }
+  return null;
+}
+function findAssistantReplyAfter(messages, userMessageId) {
+  if (!messages || messages.length === 0) return null;
+  const byParent = messages.find(
+    (m) => roleOf(m) === "assistant" && parentIdOf(m) === userMessageId
+  );
+  if (byParent) return byParent;
+  const userIndex = messages.findIndex((m) => idOf(m) === userMessageId);
+  if (userIndex === -1) return null;
+  for (let i = userIndex + 1; i < messages.length; i++) {
+    if (roleOf(messages[i]) === "assistant") return messages[i];
+  }
+  return null;
+}
+function findLastAssistantReplyFor(messages, userMessageId) {
+  if (!messages || messages.length === 0) return null;
+  let lastCorrelated = null;
+  let lastNonErrored = null;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (roleOf(m) !== "assistant" || parentIdOf(m) !== userMessageId) continue;
+    if (lastCorrelated === null) lastCorrelated = m;
+    if (errorOf(m) == null) {
+      lastNonErrored = m;
+      break;
+    }
+  }
+  if (lastCorrelated) return lastNonErrored ?? lastCorrelated;
+  const userIndex = messages.findIndex((m) => idOf(m) === userMessageId);
+  if (userIndex === -1) return null;
+  let last = null;
+  let lastOk = null;
+  for (let i = userIndex + 1; i < messages.length; i++) {
+    const role = roleOf(messages[i]);
+    if (role === "user") break;
+    if (role === "assistant") {
+      last = messages[i];
+      if (errorOf(messages[i]) == null) lastOk = messages[i];
     }
+  }
+  return lastOk ?? last;
+}
+function messageRunState(messages, userMessageId) {
+  if (!messages || messages.length === 0) return "unknown";
+  const hasUser = messages.some((m) => idOf(m) === userMessageId);
+  const reply = findLastAssistantReplyFor(messages, userMessageId);
+  if (!hasUser) {
+    if (!reply) return "unknown";
+  }
+  if (!reply) return "queued";
+  if (isAssistantInFlight(reply)) return "running";
+  return errorOf(reply) != null ? "failed" : "done";
+}
+function isPreamblePinnedRunning(messages, userMessageId) {
+  if (messageRunState(messages, userMessageId) !== "running") return false;
+  const reply = findLastAssistantReplyFor(messages, userMessageId);
+  return completedOf(reply) != null && finishOf(reply) === "tool-calls";
+}
+function messageError(messages, userMessageId) {
+  const reply = findLastAssistantReplyFor(messages, userMessageId);
+  const error2 = errorOf(reply);
+  if (error2 == null) return null;
+  if (typeof error2 === "string") return error2;
+  if (typeof error2 === "object") {
+    const e = error2;
+    const dataMessage = e.data?.message;
+    if (typeof dataMessage === "string") return dataMessage;
+    if (typeof e.message === "string") return e.message;
+  }
+  return "The agent run failed.";
+}
+function hasRunningAssistantExcept(messages, exceptUserMessageId) {
+  if (!messages || messages.length === 0) return false;
+  return messages.some(
+    (m) => roleOf(m) === "assistant" && parentIdOf(m) !== exceptUserMessageId && isAssistantInFlight(m)
+  );
+}
+
+// src/lib/opencode/session-cleanup.ts
+var DURATION_UNIT_MS = {
+  s: 1e3,
+  m: 60 * 1e3,
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3
+};
+function parseDurationMs(input) {
+  const trimmed = input.trim();
+  const match = /^(\d+)([smhd])$/.exec(trimmed);
+  if (!match) {
+    throw new Error(
+      `Invalid duration "${input}": expected <number><unit> where unit is one of s, m, h, d (e.g. "7d", "24h", "30m", "90s").`
+    );
+  }
+  const value = Number(match[1]);
+  if (value <= 0) {
+    throw new Error(`Invalid duration "${input}": must be a positive value.`);
+  }
+  return value * DURATION_UNIT_MS[match[2]];
+}
+function selectSessionsToDelete(sessions, opts) {
+  const { maxAgeMs, maxCount, nowMs, protectedIds } = opts;
+  if (maxAgeMs === void 0 && maxCount === void 0) return [];
+  const ageEligible = (s) => {
+    if (maxAgeMs === void 0) return false;
+    if (s.lastActivityMs === null) return true;
+    return nowMs - s.lastActivityMs > maxAgeMs;
   };
-  const sendMessage = async () => {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), maxWaitMs);
+  const countEligibleIds = /* @__PURE__ */ new Set();
+  if (maxCount !== void 0) {
+    const byActivityDesc = [...sessions].sort(
+      (a, b) => (b.lastActivityMs ?? -Infinity) - (a.lastActivityMs ?? -Infinity)
+    );
+    for (const s of byActivityDesc.slice(maxCount)) {
+      countEligibleIds.add(s.id);
+    }
+  }
+  const toDelete = [];
+  for (const s of sessions) {
+    if (protectedIds.has(s.id)) continue;
+    if (ageEligible(s) || countEligibleIds.has(s.id)) {
+      toDelete.push(s.id);
+    }
+  }
+  return toDelete;
+}
+var DEFAULT_INTERVAL = "1h";
+function resolve(flag, envValue, fallback) {
+  return flag ?? envValue ?? fallback;
+}
+function parseMaxCount(input) {
+  const trimmed = input.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new Error(`Invalid max-count "${input}": expected a positive integer.`);
+  }
+  const value = Number(trimmed);
+  if (value <= 0) {
+    throw new Error(`Invalid max-count "${input}": must be greater than 0.`);
+  }
+  return value;
+}
+function resolveSessionCleanupConfig(flags, env = process.env) {
+  const warnings = [];
+  const maxAgeRaw = resolve(flags.maxAge, env.EVIDENT_SESSION_CLEANUP_MAX_AGE);
+  const maxCountRaw = resolve(flags.maxCount, env.EVIDENT_SESSION_CLEANUP_MAX_COUNT);
+  const intervalRaw = resolve(
+    flags.interval,
+    env.EVIDENT_SESSION_CLEANUP_INTERVAL,
+    DEFAULT_INTERVAL
+  );
+  let maxAgeMs;
+  if (maxAgeRaw !== void 0) {
     try {
-      const res = await fetch(`http://localhost:${port}/session/${sessionId}/message`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      if (!res.ok) {
-        const text = await res.text().catch(() => "");
-        throw new Error(`OpenCode message failed: HTTP ${res.status}${text ? `: ${text}` : ""}`);
-      }
-      const sessionRes = await fetch(`http://localhost:${port}/session/${sessionId}`).catch(
-        () => null
+      maxAgeMs = parseDurationMs(maxAgeRaw);
+    } catch (err) {
+      warnings.push(
+        `Ignoring invalid --session-cleanup-max-age: ${err instanceof Error ? err.message : String(err)}`
       );
-      const session = sessionRes?.ok ? await sessionRes.json() : null;
-      return { title: session?.title };
+    }
+  }
+  let maxCount;
+  if (maxCountRaw !== void 0) {
+    try {
+      maxCount = parseMaxCount(maxCountRaw);
     } catch (err) {
-      if (err instanceof Error && err.name === "AbortError") {
-        throw new Error("Message processing timed out");
-      }
-      throw err;
-    } finally {
-      clearTimeout(timer);
-      pollDone = true;
+      warnings.push(
+        `Ignoring invalid --session-cleanup-max-count: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
-  };
-  const [result] = await Promise.all([sendMessage(), pollInteractive()]);
-  return result;
+  }
+  let intervalMs;
+  try {
+    intervalMs = parseDurationMs(intervalRaw ?? DEFAULT_INTERVAL);
+  } catch (err) {
+    warnings.push(
+      `Ignoring invalid --session-cleanup-interval, using default ${DEFAULT_INTERVAL}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    intervalMs = parseDurationMs(DEFAULT_INTERVAL);
+  }
+  const enabled = maxAgeMs !== void 0 || maxCount !== void 0;
+  return { enabled, maxAgeMs, maxCount, intervalMs, warnings };
 }
 
 // src/lib/tunnel/connection.ts
@@ -1108,18 +1479,34 @@ var StreamForwarder = class {
   }
   async handleOpen(frame) {
     const { sid, method, path, headers, has_body } = frame;
+    const correlationId = headers?.[CORRELATION_ID_HEADER];
+    const startedAt = Date.now();
+    if (path === TUNNEL_DRAIN_PING_PATH) {
+      this.callbacks.onDrainPing?.();
+      this.send({ type: "head", sid, status: 204, headers: {} });
+      this.send({ type: "res_end", sid });
+      return;
+    }
+    if (process.env.DEBUG) {
+      log("debug", "agent_request", {
+        correlation_id: correlationId,
+        sid,
+        method,
+        path: stripQuery(path)
+      });
+    }
     const ac = new AbortController();
     let bodyPromise;
     let pushBody;
     let endBody;
     if (has_body) {
       const chunks = [];
-      bodyPromise = new Promise((resolve) => {
+      bodyPromise = new Promise((resolve2) => {
         pushBody = (buf) => {
           chunks.push(buf);
         };
         endBody = () => {
-          resolve(Buffer.concat(chunks));
+          resolve2(Buffer.concat(chunks));
         };
       });
     }
@@ -1154,6 +1541,14 @@ var StreamForwarder = class {
       if (!STRIP_RES.has(key.toLowerCase())) resHeaders[key] = value;
     });
     this.send({ type: "head", sid, status: upstream.status, headers: resHeaders });
+    if (process.env.DEBUG) {
+      log("debug", "agent_response", {
+        correlation_id: correlationId,
+        sid,
+        status: upstream.status,
+        duration_ms: Date.now() - startedAt
+      });
+    }
     this.callbacks.onHead?.(sid, upstream.status);
     try {
       if (upstream.body) {
@@ -1224,11 +1619,12 @@ function connectTunnel(options) {
     onError,
     onRequest,
     onResponse,
-    onInfo
+    onInfo,
+    onDrainPing
   } = options;
   const tunnelUrl = getTunnelUrlConfig();
   const url = `${tunnelUrl}/tunnel/${agentId}/connect`;
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const ws = new WebSocket2(url, {
       headers: {
         Authorization: authHeader
@@ -1237,6 +1633,7 @@ function connectTunnel(options) {
     const streamStartTimes = /* @__PURE__ */ new Map();
     const forwarder = new StreamForwarder(ws, port, {
       onOpen: (sid, method, path) => {
+        if (path === TUNNEL_DRAIN_PING_PATH) return;
         streamStartTimes.set(sid, Date.now());
         onRequest?.(method, path, sid);
       },
@@ -1244,7 +1641,8 @@ function connectTunnel(options) {
         const startedAt = streamStartTimes.get(sid);
         streamStartTimes.delete(sid);
         onResponse?.(status, startedAt ? Date.now() - startedAt : 0, sid);
-      }
+      },
+      onDrainPing: () => onDrainPing?.()
     });
     const connectionTimeout = setTimeout(() => {
       ws.close();
@@ -1291,7 +1689,7 @@ function connectTunnel(options) {
           clearTimeout(connectionTimeout);
           const connectedAgentId = message.agent_id ?? agentId;
           onConnected?.(connectedAgentId);
-          resolve({
+          resolve2({
             ws,
             close: () => ws.close(1e3, "CLI shutdown")
           });
@@ -1386,6 +1784,7 @@ var RunnerConnection = class {
           },
           onError: (error2) => events.onError?.(error2),
           onResponse: () => events.onResponse?.(),
+          onDrainPing: () => events.onDrainPing?.(),
           onInfo: (message) => events.onInfo?.(message)
         });
         return;
@@ -1406,17 +1805,37 @@ var RunnerConnection = class {
 };
 
 // src/lib/channels/driver.ts
+function messageIdOf(m) {
+  if (!m || typeof m !== "object") return void 0;
+  if (typeof m.id === "string") return m.id;
+  const infoId = m.info?.id;
+  return typeof infoId === "string" ? infoId : void 0;
+}
 var DEFAULT_RETRY_POLICY = {
   maxAttempts: 6,
   baseDelayMs: 500,
   maxDelayMs: 3e4
 };
+var DEFAULT_PAUSED_POLL_INTERVAL_MS = 2e3;
+var DEFAULT_PAUSED_MAX_WAIT_MS = 10 * 60 * 1e3;
+var DEFAULT_STUCK_QUEUED_MS = 6e4;
+var HEARTBEAT_MS = 6e4;
+var ABSOLUTE_MAX_PROCESSING_MS = 6 * 60 * 60 * 1e3;
+var POLL_MISS_GRACE_MS = HEARTBEAT_MS;
 var ChannelAuthError = class extends Error {
   constructor(message) {
     super(message);
     this.name = "ChannelAuthError";
   }
 };
+var ChannelTerminalError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "ChannelTerminalError";
+    this.status = status;
+  }
+};
 function backoffDelay(attempt, policy) {
   const exp = policy.baseDelayMs * Math.pow(2, attempt);
   const capped = Math.min(policy.maxDelayMs, exp);
@@ -1435,10 +1854,127 @@ var ChannelDriver = class {
   log;
   fetchImpl;
   sleep;
+  pausedPollIntervalMs;
+  pausedMaxWaitMs;
+  stuckQueuedMs;
+  now;
   /** Cache of conversationId → opencode sessionId. */
   sessions = /* @__PURE__ */ new Map();
+  /**
+   * Per-opencode-session dispatch lock (Task 2.1a). `sendPromptAsync` is no
+   * longer idempotent (no caller-supplied `messageID`), and its read-back picks
+   * "the one new user row" — which is only unambiguous if no OTHER dispatch into
+   * the SAME session interleaves its snapshot→POST→read-back. This map chains each
+   * session's dispatches so they run serially; distinct sessions stay concurrent.
+   */
+  sessionDispatchLocks = /* @__PURE__ */ new Map();
+  /**
+   * Per-SESSION watchers (WI-3), keyed by opencode sessionId. Single-flight per
+   * session: one polling loop services all of that session's in-flight messages.
+   * A session entry exists while it has any in-flight (dispatched-but-not-done)
+   * message; it is removed once its in-flight set empties.
+   */
+  watchers = /* @__PURE__ */ new Map();
+  /**
+   * AUTHORITATIVE local dedup (WI-3): Evident message ids that have been
+   * dispatched and are still in-flight. A message in this set is never
+   * re-`prompt_async`-ed by a subsequent poll tick while it is queued/running.
+   * Backed by a stable minted opencode `messageID` whose duplicate re-enqueue is
+   * idempotent on opencode (PoC fact 9) — so even if this set is lost on restart,
+   * a steady-state-poll re-dispatch will not double-run the message.
+   */
+  dispatched = /* @__PURE__ */ new Set();
+  /**
+   * Re-adopted (ADR-0046) Evident message ids currently tracked by a watcher.
+   * Used only to distinguish a RE-ADOPTED give-up from a normal-dispatch give-up
+   * so the former can be parked in `dontRedispatch` (Bug 2). A row is added when
+   * it is re-adopted and removed when its watcher settles or it is observed off
+   * the processing list.
+   */
+  readopted = /* @__PURE__ */ new Set();
+  /**
+   * "Don't re-DISPATCH / re-attach this orphan again" (Bug 2/5). Set when a
+   * re-adopted running/orphan row's watcher hit its `processed_at`-anchored
+   * deadline (or an orphan whose window already elapsed): the still-`processing`
+   * server row would otherwise be re-adopted (and re-dispatched) on EVERY ~2s
+   * drain until the 15-min cron resets it — spamming new turns.
+   *
+   * CRITICAL (Bugbot #202): this suppresses ONLY the dispatch/re-attach paths, it
+   * does NOT suppress DONE delivery. A row parked here whose reply later COMPLETES
+   * in opencode must still be delivered via `markDone` on the next drain — so
+   * `readoptOne` computes `state` FIRST and this set is checked only on the
+   * non-done path. It is cleared once the row leaves the processing list (cron
+   * reset → it drains normally as `pending`), so it can never leak.
+   */
+  dontRedispatch = /* @__PURE__ */ new Set();
+  /**
+   * "markDone for this row is TERMINALLY undeliverable" (Bug 4). Set ONLY when a
+   * re-adopted DONE row's `markDone` returned a terminal 4xx (a status that will
+   * never succeed). Checked at the TOP of the `done` branch so we do NOT re-attempt
+   * that markDone every ~2s drain while the row stays `processing`. A TRANSIENT
+   * markDone failure must NOT land here (it must still retry next drain). Separate
+   * from `dontRedispatch` because the two concerns are independent: a row can need
+   * "stop re-dispatching" without "stop delivering", and vice versa. Cleared once
+   * the row leaves the processing list, exactly like `dontRedispatch`.
+   */
+  doneUndeliverable = /* @__PURE__ */ new Set();
+  /**
+   * "Already emitted `readopt_poll_unresolved` for this row" (#229). The b1 /
+   * unreadable-status re-evaluate leaf leaves the row UN-tracked so it is re-read
+   * every ~2s drain until the status map becomes readable — but the server-visible
+   * signal is an OUTCOME, so it must fire at most ONCE per row, not once per drain
+   * (Bugbot "Re-adopt signals flood every drain"). Cleared when the row leaves the
+   * processing list, exactly like `dontRedispatch`/`doneUndeliverable`.
+   */
+  readoptPollUnresolvedSignalled = /* @__PURE__ */ new Set();
+  /**
+   * "A null-id re-adopt re-dispatch is in flight, awaiting its read-back" (WI-5
+   * Task 5.4, High-2). Since we no longer send a caller-supplied id, a re-dispatch
+   * is NOT idempotent: if `forceReadoptRun` dispatches on tick N but the read-back +
+   * persist hasn't landed before tick N+1 re-reads the still-null
+   * `row.opencode_message_id`, tick N+1 would dispatch AGAIN → duplicate user turns.
+   * A row is added here right before its `sendPromptAsync` and `forceReadoptRun`
+   * short-circuits while it is present, so a null-id row is re-dispatched AT MOST
+   * ONCE per outstanding read-back. Cleared on a SUCCESSFUL dispatch+read-back (the
+   * row is then tracked in `dispatched`, so `readoptOne`'s early skip prevents
+   * re-entry) OR on a failed/unresolved dispatch (the message is genuinely un-sent,
+   * so the NEXT tick may retry exactly once more).
+   */
+  awaitingReadopt = /* @__PURE__ */ new Set();
+  /**
+   * Cache of the opencode root directory (from `GET /path`). Resolved lazily on
+   * first session creation so drain-created sessions are rooted at the project
+   * directory and thus visible in `opencode web`'s session list. `undefined` =
+   * not yet resolved; `null` = resolved-but-unavailable (don't keep retrying).
+   */
+  opencodeDirectory = void 0;
+  /**
+   * Cache of opencode `sessionId → parentID` (its parent session, or `null` when
+   * the session is a root with no parent). Sub-agents spawned via the `task` tool
+   * run in CHILD sessions whose `parentID` chains up to the Evident-created
+   * (watched) session; we resolve this once per session so a child-session
+   * question/permission can be attributed to the watched session's subtree
+   * (`sessionBelongsTo`) instead of being dropped by an exact-id filter. A missing
+   * entry = not yet resolved; `null` = resolved root (stop walking).
+   */
+  sessionParents = /* @__PURE__ */ new Map();
   /** Serialises drains so a reconnect during a drain doesn't double-process. */
   draining = false;
+  /**
+   * The currently-executing `drainPending()` promise, or null when idle. Lets a
+   * graceful shutdown (`waitForInFlight`) await an in-progress drain so a turn it
+   * is about to dispatch is not missed by the `hasInFlightWatchers()` check (a
+   * drain that entered before `stop()` still registers its watcher).
+   */
+  activeDrain = null;
+  /**
+   * Set by `stop()` on graceful shutdown. Once stopped, `drainPending` no longer
+   * dispatches NEW work (it returns 0 immediately) — but the per-session watcher
+   * loops already running keep going so in-flight turns can finish and deliver
+   * their reply. `run.ts` awaits `waitForInFlight()` before it closes the tunnel
+   * and stops opencode.
+   */
+  stopped = false;
   constructor(config2) {
     this.agentId = config2.agentId;
     this.port = config2.port;
@@ -1450,6 +1986,10 @@ var ChannelDriver = class {
     });
     this.fetchImpl = config2.fetchImpl ?? fetch;
     this.sleep = config2.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    this.pausedPollIntervalMs = config2.pausedPollIntervalMs ?? DEFAULT_PAUSED_POLL_INTERVAL_MS;
+    this.pausedMaxWaitMs = config2.pausedMaxWaitMs ?? DEFAULT_PAUSED_MAX_WAIT_MS;
+    this.stuckQueuedMs = config2.stuckQueuedMs ?? DEFAULT_STUCK_QUEUED_MS;
+    this.now = config2.now ?? (() => Date.now());
   }
   /** The IPv4-loopback base URL for the local `opencode serve`. */
   get opencodeBase() {
@@ -1459,112 +1999,1452 @@ var ChannelDriver = class {
   // Public API
   // -------------------------------------------------------------------------
   /**
-   * Drain all pending channel conversations once: poll → process → callback.
+   * Drain all pending channel conversations once: poll → dispatch → register.
    * Called on tunnel `connected` (WI-CHAN-4) and on each poll tick by `run.ts`.
    * Re-entrant calls while a drain is in flight are skipped (return 0).
    *
-   * @returns the number of messages processed.
+   * @returns the number of messages NEWLY dispatched to opencode's native queue.
    */
   async drainPending() {
+    if (this.stopped) return 0;
     if (this.draining) return 0;
     this.draining = true;
-    let processed = 0;
+    const run2 = this.runDrain();
+    this.activeDrain = run2.then(
+      () => {
+        this.activeDrain = null;
+      },
+      () => {
+        this.activeDrain = null;
+      }
+    );
+    return run2;
+  }
+  async runDrain() {
+    let dispatched = 0;
     try {
       const conversations = await this.getPendingConversations();
+      if (conversations.length > 0) {
+        const total = conversations.reduce((sum, c) => sum + (c.pending_message_count ?? 0), 0);
+        this.log({
+          level: "info",
+          message: `Found ${total} pending message(s) across ${conversations.length} conversation(s) \u2014 draining`
+        });
+      }
       for (const conv of conversations) {
-        processed += await this.processConversation(conv);
+        if (this.stopped) break;
+        dispatched += await this.processConversation(conv);
       }
+      await this.readoptProcessing();
     } finally {
       this.draining = false;
     }
-    return processed;
+    return dispatched;
+  }
+  /**
+   * True while any per-session watcher has a non-empty in-flight dispatched set
+   * (Task 3.7). `run.ts` treats this as NON-idle so `--idle-timeout` cannot exit
+   * the process while a dispatched message is still queued/running — which would
+   * kill the turn and orphan its reply.
+   */
+  hasInFlightWatchers() {
+    for (const watcher of this.watchers.values()) {
+      if (watcher.inFlight.size > 0) return true;
+    }
+    return false;
+  }
+  /**
+   * OpenCode session ids the session-cleanup sweep (issue #190) must NOT delete:
+   * exactly those with a live (dispatched-but-not-done / paused) turn, i.e. a
+   * `watchers` entry whose `inFlight` set is non-empty — the same predicate
+   * `hasInFlightWatchers()` uses, lifted to return the ids.
+   *
+   * Deliberately does NOT include `this.sessions` (the permanent, never-pruned
+   * conversation→session cache). Protecting every bound-but-idle session there
+   * would shield nearly every session and defeat cleanup — AND it is unnecessary:
+   * `ensureSession` is self-healing (it recreates a session whose id no longer
+   * exists), so deleting an idle bound session is harmless — the conversation's
+   * next turn transparently rebinds a fresh one. The only thing worth protecting
+   * is a session with a turn ACTIVELY in flight right now: tearing that down
+   * mid-turn would strand the running `prompt_async`. Idle sessions are fair game.
+   */
+  protectedSessionIds() {
+    const ids = /* @__PURE__ */ new Set();
+    for (const [sessionId, watcher] of this.watchers) {
+      if (watcher.inFlight.size > 0) ids.add(sessionId);
+    }
+    return ids;
+  }
+  /**
+   * Begin a graceful stop: stop accepting NEW channel work. Idempotent. After
+   * this, `drainPending()` is a no-op (returns 0), so no new message is dispatched
+   * — but the watcher loops already tracking in-flight turns keep running, so a
+   * turn that has finished (or is about to) still fires `markDone` and delivers
+   * its reply. Pair with `waitForInFlight()` to bound how long shutdown waits.
+   */
+  stop() {
+    this.stopped = true;
+  }
+  /**
+   * Wait (up to `timeoutMs`) for in-flight watcher work to settle during a
+   * graceful shutdown, so a turn whose reply is ready — or completes within the
+   * window — is delivered before the process exits, instead of being cut off and
+   * left for the ADR-0046 restart-recovery path.
+   *
+   * Bounded on purpose: the watcher's own give-up deadline is up to 10 minutes,
+   * far longer than a shutdown grace period (e.g. Fargate's SIGTERM→SIGKILL
+   * window). We poll `hasInFlightWatchers()` and return as soon as the in-flight
+   * set empties OR the timeout elapses. Anything still in flight at the timeout is
+   * safe to abandon — it stays `processing` server-side and is re-adopted on the
+   * next runner start (ADR-0046).
+   *
+   * @returns true if all in-flight work settled within the window; false if the
+   *          timeout elapsed with work still in flight.
+   */
+  async waitForInFlight(timeoutMs) {
+    const deadline = this.now() + timeoutMs;
+    const step = Math.min(this.pausedPollIntervalMs, 250);
+    if (this.activeDrain) {
+      let drainSettled = false;
+      void this.activeDrain.then(() => {
+        drainSettled = true;
+      });
+      while (!drainSettled) {
+        if (this.now() >= deadline) return false;
+        await this.sleep(step);
+      }
+    }
+    while (this.hasInFlightWatchers()) {
+      if (this.now() >= deadline) return false;
+      await this.sleep(step);
+    }
+    return true;
+  }
+  /**
+   * Await all outstanding per-session watchers (WI-3).
+   *
+   * In production the watcher loops are deliberately started-not-awaited so the
+   * drain loop never blocks on them and process exit is not held up (the cron
+   * recovers any abandoned ones). This helper exists primarily for deterministic
+   * tests that need to observe a watcher's effect (the `processing`/`done` PATCH
+   * or its giving up) after a non-blocking `drainPending`. Watcher loops never
+   * reject, so this resolves.
+   */
+  async flushPausedWatchers() {
+    while (true) {
+      const loops = [...this.watchers.values()].map((w) => w.loop).filter((l) => l != null);
+      if (loops.length === 0) return;
+      await Promise.all(loops);
+      const stillLive = [...this.watchers.values()].some((w) => w.loop != null);
+      if (!stillLive) return;
+    }
   }
   // -------------------------------------------------------------------------
-  // Conversation processing
+  // Conversation processing (WI-3 — async dispatch)
   // -------------------------------------------------------------------------
+  /**
+   * Dispatch each pending message for a conversation to opencode's native queue
+   * via `prompt_async` (Task 3.2) and register it with the conversation's
+   * per-session watcher. Does NOT block on the turn and does NOT call
+   * `markProcessing` here — that fires from the watcher on running-start.
+   *
+   * @returns the count of messages NEWLY dispatched (not already in-flight).
+   */
   async processConversation(conv) {
     const sessionId = await this.ensureSession(conv);
     const messages = await this.getPendingMessages(conv.id);
-    let processed = 0;
+    let dispatched = 0;
+    let skippedAlreadyDispatched = 0;
     for (const message of messages) {
-      const claimed = await this.markProcessing(conv.id, message.id);
-      if (!claimed) {
-        this.log({
-          level: "info",
-          message: `Message ${message.id.slice(0, 8)} already claimed \u2014 skipping`,
-          conversation_id: conv.id,
-          message_id: message.id
-        });
+      if (this.stopped) break;
+      if (this.dispatched.has(message.id)) {
+        skippedAlreadyDispatched += 1;
         continue;
       }
+      const options = {
+        agent: message.opencode_agent ?? void 0,
+        model: message.opencode_model ?? void 0
+      };
+      let opencodeMessageId;
       try {
-        await sendMessageToOpenCode(
-          this.port,
-          sessionId,
-          message.content,
-          {
-            agent: message.opencode_agent ?? void 0,
-            model: message.opencode_model ?? void 0
-          },
-          {
-            onQuestion: (question) => this.reportInteraction(conv.id, "question", question),
-            onPermission: (permission) => this.reportInteraction(conv.id, "permission", permission)
-          }
-        );
-        await this.confirmCompletion(sessionId);
-        await this.markDone(conv.id, message.id, sessionId);
-        processed += 1;
         this.log({
           level: "info",
-          message: `Message ${message.id.slice(0, 8)} processed`,
+          message: `Dispatching message ${message.id.slice(0, 8)} to OpenCode native queue (session ${sessionId.slice(0, 8)})`,
           conversation_id: conv.id,
           message_id: message.id
         });
+        opencodeMessageId = await this.dispatchLocked(
+          sessionId,
+          () => sendPromptAsync(this.port, sessionId, message.content, options)
+        );
       } catch (err) {
         if (err instanceof ChannelAuthError) throw err;
+        this.dispatched.delete(message.id);
+        if (await sessionExists(this.port, sessionId) === false) {
+          this.sessions.delete(conv.id);
+          this.log({
+            level: "info",
+            message: `Message ${message.id.slice(0, 8)} dispatch hit a session (${sessionId.slice(0, 8)}) that was deleted mid-dispatch (cleanup race) \u2014 deferring this and later messages for conversation ${conv.id.slice(0, 8)} to the next tick (recreated then, in order). Already-dispatched turns keep their watcher.`,
+            conversation_id: conv.id,
+            message_id: message.id
+          });
+          break;
+        }
         await this.markFailed(conv.id, message.id).catch(() => {
         });
         this.log({
           level: "error",
-          message: `Message ${message.id.slice(0, 8)} failed: ${err instanceof Error ? err.message : String(err)}`,
+          message: `Message ${message.id.slice(0, 8)} dispatch failed: ${err instanceof Error ? err.message : String(err)}`,
           conversation_id: conv.id,
           message_id: message.id
         });
+        continue;
       }
-    }
-    return processed;
+      if (opencodeMessageId === null) {
+        this.log({
+          level: "error",
+          message: `Message ${message.id.slice(0, 8)} dispatched but its opencode id could not be read back \u2014 leaving un-tracked to retry next tick`,
+          conversation_id: conv.id,
+          message_id: message.id
+        });
+        continue;
+      }
+      this.dispatched.add(message.id);
+      this.registerInFlight(conv, sessionId, message, opencodeMessageId);
+      dispatched += 1;
+      void this.postSignal(conv.id, message.id, "dispatched");
+    }
+    if (messages.length > 0 && dispatched === 0 && skippedAlreadyDispatched === messages.length) {
+      this.log({
+        level: "error",
+        message: `Conversation ${conv.id.slice(0, 8)} has ${messages.length} pending message(s) but ALL are already marked dispatched locally (in-flight set: ${this.dispatched.size}) \u2014 none sent to OpenCode this tick. If this repeats, a message may be stuck acknowledged-but-never-dispatched (its watcher never settled).`,
+        conversation_id: conv.id
+      });
+    }
+    this.ensureWatcherRunning(sessionId);
+    return dispatched;
+  }
+  async ensureSession(conv) {
+    const bound = this.sessions.get(conv.id) ?? conv.opencode_session_id ?? null;
+    if (bound) {
+      const exists = await sessionExists(this.port, bound);
+      if (exists === false) {
+        this.log({
+          level: "info",
+          message: `OpenCode session ${bound} for conversation ${conv.id.slice(0, 8)} no longer exists (deleted or DB reset) \u2014 creating a fresh session and rebinding.`,
+          conversation_id: conv.id
+        });
+        this.sessions.delete(conv.id);
+        return this.createAndBindSession(conv.id);
+      }
+      this.sessions.set(conv.id, bound);
+      return bound;
+    }
+    return this.createAndBindSession(conv.id);
+  }
+  /**
+   * Create a fresh OpenCode session for a conversation, cache the binding, and
+   * best-effort persist it server-side. Shared by the first-ever bind and the
+   * self-heal recreate path in `ensureSession`.
+   */
+  async createAndBindSession(conversationId) {
+    const directory = await this.resolveOpenCodeDirectory();
+    const sessionId = await createOpenCodeSession(this.port, directory);
+    this.sessions.set(conversationId, sessionId);
+    await this.persistSession(conversationId, sessionId).catch(() => {
+    });
+    return sessionId;
+  }
+  /**
+   * Lazily resolve (and cache) opencode's root directory via `GET /path`.
+   * Resolved once per driver: `undefined` until first lookup, then the directory
+   * string or `null` if unavailable (we don't keep retrying a missing `/path`).
+   */
+  async resolveOpenCodeDirectory() {
+    if (this.opencodeDirectory !== void 0) return this.opencodeDirectory;
+    this.opencodeDirectory = await getOpenCodeDirectory(this.port);
+    if (!this.opencodeDirectory) {
+      this.log({
+        level: "info",
+        message: "Could not determine opencode directory (GET /path) \u2014 new sessions may not appear in opencode web"
+      });
+    }
+    return this.opencodeDirectory;
+  }
+  // -------------------------------------------------------------------------
+  // Per-session watcher (WI-3)
+  // -------------------------------------------------------------------------
+  /**
+   * Run one dispatch (`sendPromptAsync` snapshot→POST→read-back) serialized per
+   * opencode session (Task 2.1a), so two dispatches into the SAME session can
+   * never interleave and mis-correlate their read-backs. Distinct sessions run
+   * concurrently. The chained tail intentionally ignores the prior result/error
+   * (each dispatch reports its own outcome to its caller).
+   */
+  dispatchLocked(sessionId, fn) {
+    const prior = this.sessionDispatchLocks.get(sessionId) ?? Promise.resolve();
+    const run2 = prior.then(fn, fn);
+    this.sessionDispatchLocks.set(
+      sessionId,
+      run2.then(
+        () => void 0,
+        () => void 0
+      )
+    );
+    return run2;
+  }
+  /** Register a freshly-dispatched message with its session's watcher state. */
+  registerInFlight(conv, sessionId, message, opencodeMessageId) {
+    let watcher = this.watchers.get(sessionId);
+    if (!watcher) {
+      watcher = {
+        conv,
+        inFlight: /* @__PURE__ */ new Map(),
+        loop: null,
+        reportedQuestions: /* @__PURE__ */ new Set(),
+        reportedPermissions: /* @__PURE__ */ new Set(),
+        lastGoodPollAt: this.now(),
+        hadUsablePoll: false
+      };
+      this.watchers.set(sessionId, watcher);
+    }
+    const now = this.now();
+    watcher.inFlight.set(message.id, {
+      evidentMessageId: message.id,
+      opencodeMessageId,
+      message,
+      dispatchedAt: now,
+      processingAnchorMs: now,
+      deadline: now + this.pausedMaxWaitMs,
+      started: false,
+      done: false,
+      stuckReported: false,
+      lastAliveAt: 0,
+      aliveInFlight: false,
+      awaitingHumanLatched: false,
+      pausedOnQuestion: false,
+      pausedOnPermission: false,
+      pausedClearConfirmed: false,
+      pausedInFlight: false,
+      deliveryDeadlineAnchored: false
+    });
+  }
+  /**
+   * Register a RE-ADOPTED `processing` message with its session watcher
+   * (ADR-0046, WI-4). Mirrors `registerInFlight` but anchors the give-up
+   * `deadline` to the row's SERVER-SIDE `processed_at` (Invariant 1), NEVER to
+   * `now`, so the paused/queued/unreachable cases settle on the same wall-clock a
+   * fresh dispatch would (10 min after `processed_at`, not 10 min from now).
+   *
+   * This re-attaches into the SAME watcher, so the ADR-0047 progressing-vs-paused
+   * give-up (`serviceInFlightMessage`) applies unchanged: a re-adopted turn
+   * opencode reports ACTIVELY `running` is watched to completion (its liveness
+   * heartbeat keeps the cron off its row), while a re-adopted turn that is paused
+   * awaiting a human — or queued/unreachable — is still bounded by `deadline` and
+   * handed to the cron. The old "the `deadline` must settle before the ~15-min
+   * cron or they double-drive" reasoning is superseded: liveness now settles the
+   * actively-running case; `deadline` settles the rest. `dispatchedAt` stays `now`
+   * (only the appear-guard uses it).
+   *
+   * `evidentMessageId` addresses the SERVER row (for markProcessing/markDone);
+   * `opencodeMessageId` is the id the watcher polls for a reply — for the orphan
+   * fresh-run path these differ (a fresh opencode id under the same server row).
+   *
+   * `started` is set true so the watcher does NOT re-`markProcessing` a row the
+   * server already flipped to `processing`; the running/done transitions still
+   * fire from the watcher's normal branches.
+   */
+  registerReadopted(conv, sessionId, message, opencodeMessageId, processedAtMs) {
+    let watcher = this.watchers.get(sessionId);
+    if (!watcher) {
+      watcher = {
+        conv,
+        inFlight: /* @__PURE__ */ new Map(),
+        loop: null,
+        reportedQuestions: /* @__PURE__ */ new Set(),
+        reportedPermissions: /* @__PURE__ */ new Set(),
+        lastGoodPollAt: this.now(),
+        hadUsablePoll: false
+      };
+      this.watchers.set(sessionId, watcher);
+    }
+    watcher.inFlight.set(message.id, {
+      evidentMessageId: message.id,
+      opencodeMessageId,
+      message,
+      dispatchedAt: this.now(),
+      // Anchor the absolute-age ceiling to the SERVER-SIDE `processed_at` (the same
+      // value seeding `deadline`), NOT `dispatchedAt` — so a re-adopted zombie's age
+      // reflects the real turn duration and the ceiling fires on the ORIGINAL turn.
+      processingAnchorMs: processedAtMs,
+      deadline: processedAtMs + this.pausedMaxWaitMs,
+      // The server row is ALREADY `processing`; do not re-fire markProcessing.
+      started: true,
+      done: false,
+      // Not yet reported stuck-queued. The once-guard (`stuckReported`) applies,
+      // AND the stuck-queued observer INCLUDES re-adopted queued wedges: it gates
+      // on `state === 'queued'` (turn produced no reply), not on `started`, so a
+      // re-adopted row left wedged in `queued` still emits the signal once
+      // (#210/#220 observability).
+      stuckReported: false,
+      // Task 5.2: a re-adopted actively-running row re-attaches into the SAME
+      // watcher and so hits the SAME actively-running heartbeat branch in
+      // `serviceInFlightMessage` as a fresh dispatch — monitoring observes "runner
+      // re-adopted and is confirming this row alive" via that `alive` heartbeat,
+      // with no extra `re_adopted` signal needed (folds old WI-6).
+      lastAliveAt: 0,
+      aliveInFlight: false,
+      awaitingHumanLatched: false,
+      pausedOnQuestion: false,
+      pausedOnPermission: false,
+      pausedClearConfirmed: false,
+      pausedInFlight: false,
+      deliveryDeadlineAnchored: false
+    });
+  }
+  /**
+   * Start (but do NOT await) the per-session watcher loop if it has in-flight
+   * work and is not already running. Single-flight per session. The loop is
+   * tracked on the watcher and cleared when it settles; it never rejects (fully
+   * guarded), so a failed poll/callback can never crash the run loop — the cron
+   * stays as the safety net.
+   */
+  ensureWatcherRunning(sessionId) {
+    const watcher = this.watchers.get(sessionId);
+    if (!watcher) return;
+    if (watcher.loop) return;
+    if (watcher.inFlight.size === 0) {
+      this.watchers.delete(sessionId);
+      return;
+    }
+    const loop = this.runWatcherLoop(sessionId, watcher).finally(() => {
+      watcher.loop = null;
+      if (watcher.inFlight.size === 0) {
+        this.watchers.delete(sessionId);
+      }
+    });
+    watcher.loop = loop;
+  }
+  /**
+   * The per-session polling loop (WI-3). Once per tick it:
+   *   1. polls `GET /session/:id/message` once and, per in-flight message,
+   *      computes `messageRunState` and fires markProcessing (queued→running) /
+   *      markDone (done) exactly once per transition;
+   *   2. applies the idle-path re-dispatch guard (a dispatched message that never
+   *      APPEARS → re-dispatch — D1 obligation 2);
+   *   3. polls `/question` + `/permission` (scoped to the session) and surfaces
+   *      NEW ones via `reportInteraction`, carrying the PAUSED message's own
+   *      `source_message_id`;
+   *   4. drops messages that completed or timed out from the in-flight set.
+   * Exits when the in-flight set empties. Never throws.
+   */
+  async runWatcherLoop(sessionId, watcher) {
+    try {
+      while (watcher.inFlight.size > 0) {
+        await this.sleep(this.pausedPollIntervalMs);
+        let messages = null;
+        try {
+          const res = await this.fetchImpl(`${this.opencodeBase}/session/${sessionId}/message`);
+          if (res.ok) {
+            const body = await res.json();
+            messages = Array.isArray(body) ? body : null;
+          }
+        } catch {
+        }
+        if (messages != null && messages.length > 0) {
+          watcher.lastGoodPollAt = this.now();
+          watcher.hadUsablePoll = true;
+        } else {
+          const emptyButReachable = messages != null;
+          const graceApplies = !emptyButReachable || watcher.hadUsablePoll;
+          if (graceApplies && this.now() - watcher.lastGoodPollAt < POLL_MISS_GRACE_MS) {
+            continue;
+          }
+        }
+        const { openQuestions, openPermissions, questionsPolledOk, permissionsPolledOk } = await this.pollInteractions(sessionId, watcher, messages);
+        for (const inFlight of [...watcher.inFlight.values()]) {
+          await this.serviceInFlightMessage(
+            sessionId,
+            watcher,
+            inFlight,
+            messages,
+            openQuestions,
+            openPermissions,
+            questionsPolledOk,
+            permissionsPolledOk
+          );
+        }
+      }
+    } catch (err) {
+      if (err instanceof ChannelAuthError) {
+        this.log({
+          level: "error",
+          message: `Session watcher aborted on auth failure for session ${sessionId.slice(0, 8)} \u2014 clearing in-flight state for re-drive after re-auth: ${err.message}`,
+          conversation_id: watcher.conv.id
+        });
+        for (const evidentMessageId of [...watcher.inFlight.keys()]) {
+          this.readopted.delete(evidentMessageId);
+          this.removeInFlight(watcher, evidentMessageId);
+        }
+        return;
+      }
+      this.log({
+        level: "error",
+        message: `Session watcher failed for session ${sessionId.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`,
+        conversation_id: watcher.conv.id
+      });
+    }
+  }
+  /**
+   * On FIRST observing a terminal (done/failed) state, ensure the delivery
+   * (markDone/markFailed) transient-retry path has a real window. A long
+   * ACTIVELY-running turn is kept past its original `deadline`, so by completion
+   * `now >= deadline` already holds and the retry bound below would fire on the
+   * first transient PATCH failure — dropping the message before its reply lands
+   * (Bugbot "Stale deadline aborts long-turn delivery"). Re-anchor once (latched)
+   * to a fresh `pausedMaxWaitMs` window; only extend if the current deadline is at
+   * or past now, so a still-ample window is left untouched.
+   */
+  anchorDeliveryDeadline(inFlight) {
+    if (inFlight.deliveryDeadlineAnchored) return;
+    inFlight.deliveryDeadlineAnchored = true;
+    if (this.now() >= inFlight.deadline) {
+      inFlight.deadline = this.now() + this.pausedMaxWaitMs;
+    }
+  }
+  /**
+   * Drive ONE in-flight message's lifecycle from the tick's message snapshot.
+   * Fires markProcessing on queued→running and markDone on done (each once),
+   * applies the idle-path re-dispatch guard, and removes the message from the
+   * in-flight set on completion or timeout.
+   */
+  async serviceInFlightMessage(sessionId, watcher, inFlight, messages, openQuestions, openPermissions, questionsPolledOk, permissionsPolledOk) {
+    const conv = watcher.conv;
+    const state = messageRunState(messages, inFlight.opencodeMessageId);
+    const id = inFlight.evidentMessageId;
+    if (openQuestions.has(id)) inFlight.pausedOnQuestion = true;
+    else if (questionsPolledOk) inFlight.pausedOnQuestion = false;
+    if (openPermissions.has(id)) inFlight.pausedOnPermission = true;
+    else if (permissionsPolledOk) inFlight.pausedOnPermission = false;
+    const observedOpen = openQuestions.has(id) || openPermissions.has(id);
+    const latchedPaused = inFlight.pausedOnQuestion || inFlight.pausedOnPermission;
+    const awaitingHuman = observedOpen || latchedPaused;
+    if ((state === "running" || state === "done" || state === "failed") && !inFlight.started) {
+      let claimed;
+      try {
+        claimed = await this.markProcessing(
+          conv.id,
+          inFlight.evidentMessageId,
+          sessionId,
+          inFlight.opencodeMessageId
+        );
+      } catch (err) {
+        if (err instanceof ChannelAuthError) throw err;
+        this.log({
+          level: "error",
+          message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} processing (will retry next tick): ${err instanceof Error ? err.message : String(err)}`,
+          conversation_id: conv.id,
+          message_id: inFlight.evidentMessageId
+        });
+        return;
+      }
+      inFlight.started = true;
+      if (!claimed) {
+        this.log({
+          level: "info",
+          message: `Message ${inFlight.evidentMessageId.slice(0, 8)} already marked processing \u2014 continuing`,
+          conversation_id: conv.id,
+          message_id: inFlight.evidentMessageId
+        });
+      }
+    }
+    if (state === "done") {
+      this.anchorDeliveryDeadline(inFlight);
+      if (!inFlight.done) {
+        this.log({
+          level: "info",
+          message: `Message ${inFlight.evidentMessageId.slice(0, 8)} completed \u2014 marking done`,
+          conversation_id: conv.id,
+          message_id: inFlight.evidentMessageId
+        });
+        try {
+          await this.markDone(
+            conv.id,
+            inFlight.evidentMessageId,
+            sessionId,
+            inFlight.opencodeMessageId
+          );
+        } catch (err) {
+          if (err instanceof ChannelAuthError) throw err;
+          if (err instanceof ChannelTerminalError) {
+            this.log({
+              level: "error",
+              message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} done (terminal HTTP ${err.status}) \u2014 leaving for the cron safety net: ${err.message}`,
+              conversation_id: conv.id,
+              message_id: inFlight.evidentMessageId
+            });
+            this.removeInFlight(watcher, inFlight.evidentMessageId);
+            return;
+          }
+          if (this.now() >= inFlight.deadline) {
+            this.log({
+              level: "error",
+              message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} done within the watch window \u2014 leaving for the cron safety net: ${err instanceof Error ? err.message : String(err)}`,
+              conversation_id: conv.id,
+              message_id: inFlight.evidentMessageId
+            });
+            this.removeInFlight(watcher, inFlight.evidentMessageId);
+            return;
+          }
+          this.log({
+            level: "error",
+            message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} done (will retry next tick): ${err instanceof Error ? err.message : String(err)}`,
+            conversation_id: conv.id,
+            message_id: inFlight.evidentMessageId
+          });
+          return;
+        }
+        inFlight.done = true;
+      }
+      this.removeInFlight(watcher, inFlight.evidentMessageId);
+      return;
+    }
+    if (state === "failed") {
+      this.anchorDeliveryDeadline(inFlight);
+      if (!inFlight.done) {
+        const error2 = messageError(messages, inFlight.opencodeMessageId) ?? void 0;
+        this.log({
+          level: "error",
+          message: `Message ${inFlight.evidentMessageId.slice(0, 8)} errored \u2014 marking failed: ${error2 ?? "(no error text)"}`,
+          conversation_id: conv.id,
+          message_id: inFlight.evidentMessageId
+        });
+        try {
+          await this.markFailed(conv.id, inFlight.evidentMessageId, sessionId, error2);
+        } catch (err) {
+          if (err instanceof ChannelAuthError) throw err;
+          if (err instanceof ChannelTerminalError) {
+            this.log({
+              level: "error",
+              message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} failed (terminal HTTP ${err.status}) \u2014 leaving for the cron safety net: ${err.message}`,
+              conversation_id: conv.id,
+              message_id: inFlight.evidentMessageId
+            });
+            this.removeInFlight(watcher, inFlight.evidentMessageId);
+            return;
+          }
+          if (this.now() >= inFlight.deadline) {
+            this.log({
+              level: "error",
+              message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} failed within the watch window \u2014 leaving for the cron safety net: ${err instanceof Error ? err.message : String(err)}`,
+              conversation_id: conv.id,
+              message_id: inFlight.evidentMessageId
+            });
+            this.removeInFlight(watcher, inFlight.evidentMessageId);
+            return;
+          }
+          this.log({
+            level: "error",
+            message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} failed (will retry next tick): ${err instanceof Error ? err.message : String(err)}`,
+            conversation_id: conv.id,
+            message_id: inFlight.evidentMessageId
+          });
+          return;
+        }
+        inFlight.done = true;
+      }
+      this.removeInFlight(watcher, inFlight.evidentMessageId);
+      return;
+    }
+    const pastStuckBound = this.now() - inFlight.dispatchedAt >= this.stuckQueuedMs;
+    const sessionIdle = state === "queued" && !hasRunningAssistantExcept(messages, inFlight.opencodeMessageId);
+    if (state === "queued" && pastStuckBound && sessionIdle && !inFlight.stuckReported) {
+      inFlight.stuckReported = true;
+      void this.postSignal(conv.id, inFlight.evidentMessageId, "stuck_queued", {
+        stuck_for_ms: this.now() - inFlight.dispatchedAt
+      });
+    }
+    const activelyRunning = state === "running" && !awaitingHuman;
+    if (activelyRunning && this.now() - inFlight.processingAnchorMs >= ABSOLUTE_MAX_PROCESSING_MS) {
+      this.log({
+        level: "error",
+        message: `Message ${inFlight.evidentMessageId.slice(0, 8)} exceeded the absolute processing ceiling (${Math.round((this.now() - inFlight.processingAnchorMs) / 6e4)}min, session ${sessionId}) while still actively running \u2014 releasing so the cron can reclaim it`,
+        conversation_id: conv.id,
+        message_id: inFlight.evidentMessageId
+      });
+      void this.postSignal(conv.id, inFlight.evidentMessageId, "gave_up", {
+        watched_for_ms: this.now() - inFlight.processingAnchorMs
+      });
+      this.removeInFlight(watcher, inFlight.evidentMessageId);
+      return;
+    }
+    if (activelyRunning && !inFlight.awaitingHumanLatched && !inFlight.aliveInFlight && this.now() - inFlight.lastAliveAt >= HEARTBEAT_MS) {
+      inFlight.aliveInFlight = true;
+      void this.postSignal(conv.id, inFlight.evidentMessageId, "alive").then((ok) => {
+        inFlight.aliveInFlight = false;
+        if (ok) inFlight.lastAliveAt = this.now();
+      });
+    }
+    if (awaitingHuman) {
+      if (!inFlight.awaitingHumanLatched) {
+        inFlight.deadline = this.now() + this.pausedMaxWaitMs;
+        inFlight.awaitingHumanLatched = true;
+      }
+      if (!inFlight.pausedClearConfirmed && !inFlight.pausedInFlight) {
+        inFlight.pausedInFlight = true;
+        void this.postSignal(conv.id, inFlight.evidentMessageId, "paused").then((ok) => {
+          inFlight.pausedInFlight = false;
+          if (ok && inFlight.awaitingHumanLatched) inFlight.pausedClearConfirmed = true;
+        });
+      }
+    } else if (inFlight.awaitingHumanLatched) {
+      inFlight.awaitingHumanLatched = false;
+      inFlight.pausedOnQuestion = false;
+      inFlight.pausedOnPermission = false;
+      inFlight.pausedClearConfirmed = false;
+    }
+    const siblingPaused = (sib) => openQuestions.has(sib.evidentMessageId) || openPermissions.has(sib.evidentMessageId) || sib.awaitingHumanLatched || sib.pausedOnQuestion || sib.pausedOnPermission;
+    const hasActivelyRunningSibling = [...watcher.inFlight.values()].some(
+      (sib) => sib.evidentMessageId !== inFlight.evidentMessageId && messageRunState(messages, sib.opencodeMessageId) === "running" && !siblingPaused(sib)
+    );
+    const queuedBehindRunningSibling = state === "queued" && hasActivelyRunningSibling;
+    if (!activelyRunning && !queuedBehindRunningSibling && this.now() >= inFlight.deadline) {
+      this.log({
+        level: "info",
+        message: `Message ${inFlight.evidentMessageId.slice(0, 8)} did not complete within the watch window \u2014 leaving for the cron safety net`,
+        conversation_id: conv.id,
+        message_id: inFlight.evidentMessageId
+      });
+      void this.postSignal(conv.id, inFlight.evidentMessageId, "gave_up", {
+        watched_for_ms: this.now() - inFlight.dispatchedAt
+      });
+      this.removeInFlight(watcher, inFlight.evidentMessageId);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Restart recovery: re-adopt `processing` messages (ADR-0046, WI-3/4/5)
+  // -------------------------------------------------------------------------
+  /**
+   * Re-adopt this agent's `processing` messages on drain (ADR-0046 Decision §1).
+   *
+   * The pending drain only re-drives `pending` rows; a message already flipped to
+   * `processing` before the runner died is watched by nobody until the 15-min
+   * cron resets it. Here we fetch those rows, and per row resolve its correlated
+   * reply against opencode's OWN session store — completing, re-attaching, or
+   * (for an orphan) forcing a genuine fresh run. Runs on EVERY drain tick, so it
+   * is idempotent per message (Invariant 2): a row a watcher already tracks is
+   * skipped in `readoptOne` — one driver, no double-drive.
+   *
+   * Only `ChannelAuthError` propagates (to `drainPending`, like the pending
+   * path); every other early return LOGS a reason with context — no silent drop.
+   */
+  async readoptProcessing() {
+    const rows = await this.getProcessingMessages();
+    if (this.dontRedispatch.size > 0 || this.doneUndeliverable.size > 0 || this.readoptPollUnresolvedSignalled.size > 0) {
+      const stillProcessing = new Set(rows.map((r) => r.id));
+      for (const id of [
+        ...this.dontRedispatch,
+        ...this.doneUndeliverable,
+        ...this.readoptPollUnresolvedSignalled
+      ]) {
+        if (!stillProcessing.has(id)) {
+          const cleared = this.dontRedispatch.delete(id);
+          const clearedUndeliverable = this.doneUndeliverable.delete(id);
+          this.readoptPollUnresolvedSignalled.delete(id);
+          if (cleared || clearedUndeliverable) {
+            this.log({
+              level: "info",
+              message: `Re-adopt: message ${id.slice(0, 8)} left the processing list (cron reset) \u2014 cleared gave-up marker`,
+              message_id: id
+            });
+          }
+        }
+      }
+    }
+    if (rows.length === 0) return;
+    const bySession = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.opencode_session_id) {
+        this.log({
+          level: "error",
+          message: `Cannot re-adopt processing message ${row.id.slice(0, 8)} \u2014 no opencode session id; leaving for the cron safety net`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+        continue;
+      }
+      const list = bySession.get(row.opencode_session_id) ?? [];
+      list.push(row);
+      bySession.set(row.opencode_session_id, list);
+    }
+    for (const [sessionId, sessionRows] of bySession) {
+      let messages;
+      try {
+        const res = await this.fetchImpl(`${this.opencodeBase}/session/${sessionId}/message`);
+        if (!res.ok) {
+          this.log({
+            level: "error",
+            message: `Re-adopt: polling session ${sessionId.slice(0, 8)} returned HTTP ${res.status} \u2014 skipping this session this tick`
+          });
+          continue;
+        }
+        const body = await res.json();
+        if (!Array.isArray(body)) {
+          this.log({
+            level: "error",
+            message: `Re-adopt: polling session ${sessionId.slice(0, 8)} returned a non-array message body \u2014 skipping this session this tick`
+          });
+          continue;
+        }
+        messages = body;
+      } catch (err) {
+        this.log({
+          level: "error",
+          message: `Re-adopt: failed to poll session ${sessionId.slice(0, 8)} (will retry next drain): ${err instanceof Error ? err.message : String(err)}`
+        });
+        continue;
+      }
+      const anyUntracked = sessionRows.some((row) => !this.isTracked(sessionId, row.id));
+      const sessionOngoing = anyUntracked ? await isSessionOngoing(this.port, sessionId) : null;
+      for (const row of sessionRows) {
+        await this.readoptOne(sessionId, row, messages, sessionOngoing);
+      }
+    }
+  }
+  /**
+   * Re-adopt ONE `processing` row against the tick's session message snapshot
+   * (ADR-0046 Decision §1/§2). Idempotent: skips a row already being driven.
+   *
+   * Branches on `messageRunState(messages, row.opencode_message_id)` — the
+   * opencode-assigned user-message id persisted on the first `processing` PATCH
+   * (#218). A row with a NULL stored id (dispatched but the read-back never landed
+   * before the restart) has no id to correlate → treated as an orphan and
+   * re-dispatched (at most once, see `forceReadoptRun`):
+   *   - `done`             → `markDone` now (guarded like the watcher's done branch);
+   *   - `failed`           → `markFailed` with the surfaced error (issue #182), so an
+   *                          errored turn is reported failed on restart, NOT re-dispatched;
+   *   - `running`/`queued` → re-attach a watcher via `registerReadopted` (no re-dispatch),
+   *                          tracking the stored id so the reply correlates by it;
+   *   - `unknown`/null id  → re-dispatch (opencode assigns a fresh id) + attach a watcher.
+   *
+   * Only `ChannelAuthError` propagates.
+   */
+  async readoptOne(sessionId, row, messages, sessionOngoing) {
+    if (this.isTracked(sessionId, row.id)) {
+      this.log({
+        level: "info",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} already tracked in-flight \u2014 skipping (owned by the watcher loop)`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      return;
+    }
+    const ocId = row.opencode_message_id;
+    const state = messageRunState(messages, ocId ?? "");
+    if (state === "done") {
+      if (this.doneUndeliverable.has(row.id)) {
+        this.log({
+          level: "info",
+          message: `Re-adopt: message ${row.id.slice(0, 8)} markDone is terminally undeliverable \u2014 left to the cron; skipping until it leaves processing`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+        return;
+      }
+      this.log({
+        level: "info",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} completed while unwatched \u2014 marking done`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      try {
+        await this.markDone(row.conversation_id, row.id, sessionId, ocId);
+      } catch (err) {
+        if (err instanceof ChannelAuthError) throw err;
+        if (err instanceof ChannelTerminalError) {
+          this.doneUndeliverable.add(row.id);
+          this.log({
+            level: "error",
+            message: `Re-adopt: failed to mark message ${row.id.slice(0, 8)} done (terminal HTTP ${err.status}) \u2014 parking until it leaves processing; leaving for the cron safety net: ${err.message}`,
+            conversation_id: row.conversation_id,
+            message_id: row.id
+          });
+          void this.postSignal(row.conversation_id, row.id, "readopt_undeliverable");
+          return;
+        }
+        this.log({
+          level: "error",
+          message: `Re-adopt: failed to mark message ${row.id.slice(0, 8)} done (will retry next drain): ${err instanceof Error ? err.message : String(err)}`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+        return;
+      }
+      this.dontRedispatch.delete(row.id);
+      void this.postSignal(row.conversation_id, row.id, "readopt_done");
+      return;
+    }
+    if (state === "failed") {
+      const error2 = messageError(messages, ocId ?? "") ?? void 0;
+      this.log({
+        level: "error",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} errored while unwatched \u2014 marking failed: ${error2 ?? "(no error text)"}`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      try {
+        await this.markFailed(row.conversation_id, row.id, sessionId, error2);
+      } catch (err) {
+        if (err instanceof ChannelAuthError) throw err;
+        if (err instanceof ChannelTerminalError) {
+          this.doneUndeliverable.add(row.id);
+          this.log({
+            level: "error",
+            message: `Re-adopt: failed to mark message ${row.id.slice(0, 8)} failed (terminal HTTP ${err.status}) \u2014 parking until it leaves processing; leaving for the cron safety net: ${err.message}`,
+            conversation_id: row.conversation_id,
+            message_id: row.id
+          });
+          void this.postSignal(row.conversation_id, row.id, "readopt_undeliverable");
+          return;
+        }
+        this.log({
+          level: "error",
+          message: `Re-adopt: failed to mark message ${row.id.slice(0, 8)} failed (will retry next drain): ${err instanceof Error ? err.message : String(err)}`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+        return;
+      }
+      this.dontRedispatch.delete(row.id);
+      void this.postSignal(row.conversation_id, row.id, "readopt_failed");
+      return;
+    }
+    if (this.dontRedispatch.has(row.id)) {
+      this.log({
+        level: "info",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} already gave up \u2014 left to the cron; skipping until it leaves processing`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      return;
+    }
+    let statusReadableOngoing = null;
+    if (state === "running" && ocId) {
+      const reply = findLastAssistantReplyFor(messages, ocId);
+      const shape = this.replyCompletionShape(reply);
+      const ongoing = sessionOngoing;
+      statusReadableOngoing = ongoing;
+      if (ongoing === false) {
+        this.log({
+          level: "info",
+          message: `Re-adopt: message ${row.id.slice(0, 8)} running/${shape} but session ${sessionId.slice(0, 8)} is not-ongoing per GET /session/status (absent/idle) \u2014 re-dispatching from scratch (status-gated recovery)`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+        await this.forceReadoptRun(sessionId, row);
+        return;
+      }
+      if (ongoing === true) {
+        this.log({
+          level: "info",
+          message: `Re-adopt: message ${row.id.slice(0, 8)} running/${shape} and session ${sessionId.slice(0, 8)} is ongoing per GET /session/status (busy/retry) \u2014 re-attaching watcher (no re-dispatch)`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+      } else {
+        if (shape === "b1") {
+          this.log({
+            level: "info",
+            message: `Re-adopt: message ${row.id.slice(0, 8)} running/b1 but GET /session/status was unreadable (null) for session ${sessionId.slice(0, 8)} \u2014 NOT latching a b1 row on a transient status blip; leaving it un-tracked to re-evaluate on the next drain`,
+            conversation_id: row.conversation_id,
+            message_id: row.id
+          });
+          if (!this.readoptPollUnresolvedSignalled.has(row.id)) {
+            this.readoptPollUnresolvedSignalled.add(row.id);
+            void this.postSignal(row.conversation_id, row.id, "readopt_poll_unresolved");
+          }
+          return;
+        }
+        this.log({
+          level: "info",
+          message: `Re-adopt: message ${row.id.slice(0, 8)} running/${shape} but GET /session/status was unreadable (null) for session ${sessionId.slice(0, 8)} \u2014 falling back to the #253 preamble + descendant cross-check`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+      }
+    }
+    if (statusReadableOngoing === null && state === "running" && ocId && isPreamblePinnedRunning(messages, ocId)) {
+      const descendantAlive = await this.isAnyDescendantSessionAlive(sessionId);
+      if (descendantAlive === true) {
+        this.log({
+          level: "info",
+          message: `Re-adopt: message ${row.id.slice(0, 8)} preamble-pinned running (root ${sessionId.slice(0, 8)}) but a live descendant sub-agent session was found \u2014 treating as still running, re-attaching watcher (no re-dispatch)`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+      } else {
+        this.log({
+          level: "info",
+          message: `Re-adopt: message ${row.id.slice(0, 8)} preamble-pinned on recovery (root ${sessionId.slice(0, 8)}), no live descendant runner \u2014 re-dispatching from scratch${descendantAlive === null ? " (descendant liveness indeterminate; a restart guarantees no live runner, so this does NOT block the re-dispatch)" : ""}`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+        await this.forceReadoptRun(sessionId, row);
+        return;
+      }
+    }
+    if ((state === "running" || state === "queued") && ocId) {
+      const conv = this.convForRow(sessionId, row);
+      const message = this.queuedMessageForRow(row);
+      this.registerReadopted(conv, sessionId, message, ocId, this.processedAtMs(row));
+      this.dispatched.add(row.id);
+      this.readopted.add(row.id);
+      this.ensureWatcherRunning(sessionId);
+      this.log({
+        level: "info",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} ${state} \u2014 re-attached watcher (stored id, no re-dispatch)`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      void this.postSignal(row.conversation_id, row.id, "readopt_reattached");
+      return;
+    }
+    await this.forceReadoptRun(sessionId, row);
+  }
+  /**
+   * Re-dispatch an orphaned (`unknown`/null-id) `processing` row (ADR-0046 §2).
+   *
+   * #218/WI-5: the row's user message is absent (never kept, or a null stored id),
+   * so we re-`prompt_async` WITHOUT a caller id (opencode assigns a monotonic one),
+   * read it back, and register the watcher under the assigned id so the reply
+   * correlates server-side.
+   *
+   * ⚠️ AT-MOST-ONCE (High-2): dispatch is no longer idempotent (no caller-supplied
+   * id). Without a guard, if this dispatches on tick N but the read-back+persist
+   * hasn't landed before tick N+1 re-reads the still-null `opencode_message_id`,
+   * tick N+1 would dispatch AGAIN → duplicate user turns. The `awaitingReadopt`
+   * latch makes a null-id row re-dispatched AT MOST ONCE per outstanding read-back:
+   * short-circuit while the row is latched; clear it on a successful dispatch (the
+   * row is then tracked in `dispatched`, so `readoptOne`'s early skip prevents
+   * re-entry) OR on a failed/unresolved dispatch (genuinely un-sent → the next tick
+   * may retry exactly once more).
+   *
+   * `evidentMessageId = row.id` addresses the SERVER row. Deadline anchored to
+   * `processed_at` (Invariant 1).
+   */
+  async forceReadoptRun(sessionId, row) {
+    if (this.stopped) {
+      this.log({
+        level: "info",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} orphaned but the runner is stopping \u2014 not starting a fresh turn; leaving for restart recovery`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      return;
+    }
+    if (this.awaitingReadopt.has(row.id)) {
+      this.log({
+        level: "info",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} already has a re-dispatch awaiting read-back \u2014 skipping (at most once)`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      return;
+    }
+    if (this.processedAtMs(row) + this.pausedMaxWaitMs <= this.now()) {
+      this.dontRedispatch.add(row.id);
+      this.log({
+        level: "info",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} orphaned but its re-adopt window has already elapsed \u2014 not dispatching an unwatchable turn; parking until it leaves processing (cron will reset it)`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      void this.postSignal(row.conversation_id, row.id, "readopt_window_elapsed");
+      return;
+    }
+    const options = {
+      agent: row.opencode_agent ?? void 0,
+      model: row.opencode_model ?? void 0
+    };
+    this.log({
+      level: "info",
+      message: `Re-adopt: message ${row.id.slice(0, 8)} orphaned (user message absent) \u2014 re-dispatching (opencode assigns a fresh id)`,
+      conversation_id: row.conversation_id,
+      message_id: row.id
+    });
+    this.awaitingReadopt.add(row.id);
+    let ocId;
+    try {
+      ocId = await this.dispatchLocked(
+        sessionId,
+        () => sendPromptAsync(this.port, sessionId, row.content, options)
+      );
+    } catch (err) {
+      this.awaitingReadopt.delete(row.id);
+      if (err instanceof ChannelAuthError) throw err;
+      this.log({
+        level: "error",
+        message: `Re-adopt: re-dispatch failed for message ${row.id.slice(0, 8)} (will retry next drain): ${err instanceof Error ? err.message : String(err)}`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      void this.postSignal(row.conversation_id, row.id, "readopt_orphan_unsent");
+      return;
+    }
+    if (ocId === null) {
+      this.awaitingReadopt.delete(row.id);
+      this.log({
+        level: "error",
+        message: `Re-adopt: message ${row.id.slice(0, 8)} re-dispatched but its opencode id could not be read back \u2014 leaving un-tracked to retry next drain`,
+        conversation_id: row.conversation_id,
+        message_id: row.id
+      });
+      void this.postSignal(row.conversation_id, row.id, "readopt_orphan_unsent");
+      return;
+    }
+    const conv = this.convForRow(sessionId, row);
+    const message = this.queuedMessageForRow(row);
+    this.registerReadopted(conv, sessionId, message, ocId, this.processedAtMs(row));
+    this.dispatched.add(row.id);
+    this.readopted.add(row.id);
+    this.awaitingReadopt.delete(row.id);
+    this.ensureWatcherRunning(sessionId);
+    void this.postSignal(row.conversation_id, row.id, "readopt_redispatched");
   }
-  async ensureSession(conv) {
-    const cached = this.sessions.get(conv.id);
-    if (cached) return cached;
-    if (conv.opencode_session_id) {
-      this.sessions.set(conv.id, conv.opencode_session_id);
-      return conv.opencode_session_id;
-    }
-    const sessionId = await createOpenCodeSession(this.port);
-    this.sessions.set(conv.id, sessionId);
-    await this.persistSession(conv.id, sessionId).catch(() => {
+  /**
+   * True if `evidentMessageId` is already being driven — either in the
+   * authoritative `dispatched` set or a live watcher's in-flight set for this
+   * session (Invariant 2, WI-5). Either signal means a watcher owns the row.
+   */
+  isTracked(sessionId, evidentMessageId) {
+    if (this.dispatched.has(evidentMessageId)) return true;
+    const watcher = this.watchers.get(sessionId);
+    return watcher?.inFlight.has(evidentMessageId) ?? false;
+  }
+  /**
+   * Parse a re-adopt row's `processed_at` (ISO string) to epoch ms for the
+   * deadline anchor (Invariant 1). The endpoint guarantees `processed_at` is set
+   * for `processing` rows, but if it is somehow null/unparseable fall back to
+   * `now` (defensive) AND log — a fallback means the anchor is weaker than
+   * intended, which is worth surfacing.
+   */
+  processedAtMs(row) {
+    const parsed = row.processed_at ? Date.parse(row.processed_at) : NaN;
+    if (!Number.isNaN(parsed)) return parsed;
+    this.log({
+      level: "error",
+      message: `Re-adopt: message ${row.id.slice(0, 8)} has null/unparseable processed_at (${String(row.processed_at)}) \u2014 anchoring deadline to now (defensive)`,
+      conversation_id: row.conversation_id,
+      message_id: row.id
     });
-    return sessionId;
+    return this.now();
+  }
+  /** Build the `PendingConversation` shape the watcher needs from a re-adopt row. */
+  convForRow(sessionId, row) {
+    return {
+      id: row.conversation_id,
+      agent_id: this.agentId,
+      opencode_session_id: sessionId,
+      pending_message_count: 0,
+      oldest_pending_at: row.processed_at
+    };
+  }
+  /** Build the `QueuedMessage` shape the watcher/re-dispatch needs from a re-adopt row. */
+  queuedMessageForRow(row) {
+    return {
+      id: row.id,
+      content: row.content,
+      status: "processing",
+      opencode_agent: row.opencode_agent,
+      opencode_model: row.opencode_model,
+      source_message_id: row.source_message_id,
+      slack_user_id: row.slack_user_id
+    };
+  }
+  /**
+   * Remove a message from the in-flight set AND the authoritative dispatched
+   * set. Once the in-flight set empties, the watcher loop's `while` guard exits
+   * and its `.finally` removes the session entry from `this.watchers`.
+   *
+   * Bug 2: if a RE-ADOPTED message is removed WITHOUT having completed
+   * (`!inFlight.done` — i.e. a give-up: deadline reached, or markDone left to the
+   * cron), park it in `dontRedispatch` so the next drain does NOT re-adopt (and
+   * re-dispatch) the still-`processing` row every ~2s until the 15-min cron. A
+   * re-adopted message that completed (`done`) needs no marker — it's leaving
+   * `processing`. This suppresses only re-dispatch: if its reply later completes,
+   * the done branch still delivers it (Bugbot #202).
+   */
+  removeInFlight(watcher, evidentMessageId) {
+    const inFlight = watcher.inFlight.get(evidentMessageId);
+    if (this.readopted.delete(evidentMessageId) && inFlight && !inFlight.done) {
+      this.dontRedispatch.add(evidentMessageId);
+      this.log({
+        level: "info",
+        message: `Re-adopt: message ${evidentMessageId.slice(0, 8)} gave up \u2014 parking until it leaves the processing list (cron reset)`,
+        conversation_id: watcher.conv.id,
+        message_id: evidentMessageId
+      });
+    }
+    watcher.inFlight.delete(evidentMessageId);
+    this.dispatched.delete(evidentMessageId);
+  }
+  /**
+   * Poll `/question` + `/permission` (scoped to the session) and surface NEW ones
+   * via `reportInteraction` (Task 3.5), carrying the PAUSED message's own
+   * `source_message_id` so the server @mentions the correct person under
+   * concurrency. Dedups by interaction id across ticks (reused per-session sets).
+   *
+   * The interaction is attributed to the in-flight message it paused on. opencode
+   * stamps a `messageID` on a permission (and `tool.messageID` on a question) =
+   * the assistant message id, whose `parentID` is the user message id — but the
+   * simplest robust attribution here is: the single in-flight message that is
+   * RUNNING (not done) is the one that paused. With one running message that is
+   * unambiguous; with several we prefer an explicit messageID match, else the
+   * oldest running message.
+   *
+   * Returns the set of in-flight Evident message ids that are paused awaiting a
+   * human — an outstanding (still-open) question/permission is attributed to them.
+   * `serviceInFlightMessage` uses this to keep an actively-running turn watched
+   * forever (ADR-0047) while still bounding a turn merely blocked on a person who
+   * may never answer. Attribution here covers ALL open interactions, not just
+   * NEW (un-deduped) ones — a question stays "awaiting a human" until answered,
+   * even after it was already surfaced to the channel.
+   */
+  async pollInteractions(sessionId, watcher, messages) {
+    const openQuestions = /* @__PURE__ */ new Set();
+    const openPermissions = /* @__PURE__ */ new Set();
+    let questionsPolledOk = true;
+    let permissionsPolledOk = true;
+    let questions = [];
+    try {
+      const res = await this.fetchImpl(`${this.opencodeBase}/question`);
+      if (res.ok) {
+        const body = await res.json();
+        if (Array.isArray(body)) {
+          questions = body;
+        } else {
+          questionsPolledOk = false;
+        }
+      } else {
+        questionsPolledOk = false;
+      }
+    } catch {
+      questionsPolledOk = false;
+    }
+    for (const q of questions) {
+      if (!await this.sessionBelongsTo(q.sessionID, sessionId)) continue;
+      const paused = this.attributeInteraction(watcher, q.tool?.messageID, messages);
+      if (paused) openQuestions.add(paused.evidentMessageId);
+      if (watcher.reportedQuestions.has(q.id)) continue;
+      const reported = await this.reportInteraction(
+        watcher.conv.id,
+        "question",
+        q,
+        paused?.message.source_message_id ?? void 0
+      );
+      if (reported) watcher.reportedQuestions.add(q.id);
+    }
+    let permissions = [];
+    try {
+      const res = await this.fetchImpl(`${this.opencodeBase}/permission`);
+      if (res.ok) {
+        const body = await res.json();
+        if (Array.isArray(body)) {
+          permissions = body;
+        } else {
+          permissionsPolledOk = false;
+        }
+      } else {
+        permissionsPolledOk = false;
+      }
+    } catch {
+      permissionsPolledOk = false;
+    }
+    for (const p of permissions) {
+      if (!await this.sessionBelongsTo(p.sessionID, sessionId)) continue;
+      const paused = this.attributeInteraction(watcher, p.messageID, messages);
+      if (paused) openPermissions.add(paused.evidentMessageId);
+      if (watcher.reportedPermissions.has(p.id)) continue;
+      const reported = await this.reportInteraction(
+        watcher.conv.id,
+        "permission",
+        p,
+        paused?.message.source_message_id ?? void 0
+      );
+      if (reported) watcher.reportedPermissions.add(p.id);
+    }
+    return { openQuestions, openPermissions, questionsPolledOk, permissionsPolledOk };
+  }
+  /**
+   * True when `sessionId` is the `rootSessionId` itself OR a descendant of it —
+   * i.e. its `parentID` chain (resolved via `GET /session/:id`) reaches the
+   * watched root. Sub-agents spawned via the `task` tool run in child sessions,
+   * so their questions/permissions live under a different `sessionID` that must
+   * still be attributed to the root conversation the watcher owns.
+   *
+   * Parents are cached in `sessionParents` so we walk each session at most once;
+   * a bounded depth cap guards against a cycle or a pathological chain, and any
+   * fetch failure is treated as "not a descendant" (best-effort — the interaction
+   * simply isn't surfaced this tick and is retried next tick once resolvable).
+   */
+  async sessionBelongsTo(sessionId, rootSessionId) {
+    let current = sessionId;
+    for (let depth = 0; current && depth < 32; depth++) {
+      if (current === rootSessionId) return true;
+      const parent = await this.resolveSessionParent(current);
+      if (parent === null || parent === void 0) return false;
+      current = parent;
+    }
+    return false;
   }
   /**
-   * Local reconcile: re-query `GET /session/:id` and check `time.completed`.
-   * Best-effort — if opencode is unreachable or the field is absent we proceed
-   * to mark done anyway (the blocking call already returned).
+   * Resolve (and cache) a session's `parentID` via `GET /session/:id`. Returns
+   * `null` for a root session (no parent) and `undefined` when opencode is
+   * unreachable / the session can't be read (so the caller stops walking without
+   * caching a wrong answer — the next tick retries).
    */
-  async confirmCompletion(sessionId) {
+  async resolveSessionParent(sessionId) {
+    const cached = this.sessionParents.get(sessionId);
+    if (cached !== void 0) return cached;
+    let parent = void 0;
     try {
       const res = await this.fetchImpl(`${this.opencodeBase}/session/${sessionId}`);
-      if (!res.ok) return;
-      const session = await res.json();
-      if (session.time && session.time.completed == null) {
-        this.log({
-          level: "info",
-          message: `Session ${sessionId.slice(0, 8)} not marked completed on reconcile \u2014 delivering anyway`
-        });
+      if (res.ok) {
+        const body = await res.json();
+        parent = body && typeof body.parentID === "string" ? body.parentID : null;
       }
     } catch {
+      parent = void 0;
+    }
+    if (parent !== void 0) this.sessionParents.set(sessionId, parent);
+    return parent;
+  }
+  /**
+   * DEFENSIVE cross-check for the restart-recovery path (WI-2): is any descendant
+   * (`task` sub-agent) session under `rootSessionId` still genuinely doing work?
+   *
+   * The PRIMARY recovery trigger is "preamble-pinned on recovery ⇒ idle" — a
+   * runner restart wipes OpenCode's in-memory `SessionStatus`/`Runner`, so a
+   * completed `finish: "tool-calls"` root reply encountered during re-adoption is
+   * idle by OpenCode's own definition and is re-dispatched. This method exists only
+   * so the WI-3 caller can VETO that re-dispatch in the rare case a descendant is
+   * provably in flight at the exact moment of recovery.
+   *
+   * "Alive" criterion (TIGHTENED): a descendant is alive only when it is PROVABLY,
+   * ACTIVELY generating — its LAST message is an assistant still mid-generation
+   * (`completed == null`, via `isSessionActivelyGenerating`). An
+   * INCOMPLETE-BUT-NOT-GENERATING child — last message a user message, or a
+   * completed `finish: "tool-calls"` step — is NOT alive after a restart (nothing
+   * is generating once the runner is gone), so it does NOT veto. (This is
+   * deliberately NOT `!isTurnComplete`, which also matches those dead-but-non-terminal
+   * shapes and would falsely veto — re-hanging the very turn this path recovers.)
+   *
+   * Return contract (encoded so WI-3 need not re-derive it):
+   *  - `true`  → a descendant is provably, actively generating (veto re-dispatch).
+   *  - `false` → descendants exist but none is actively generating (the restart
+   *              case), OR no descendant is found at all.
+   *  - `null`  → liveness is INDETERMINATE (enumeration via `listSessions` failed).
+   *
+   * ⚠️ `null` (UNKNOWN) MUST NOT be treated as "alive": WI-3 treats `null` the same
+   * as `false` and does NOT veto — a restart guarantees no live runner, so an
+   * indeterminate cross-check almost always means "couldn't reach a child that no
+   * longer exists". The inversion lives in the caller; this method just reports
+   * true/false/null faithfully.
+   *
+   * VERIFY-BEFORE-DEPEND: we depend ONLY on (a) `parentID` from `GET /session/:id`
+   * (already proven by the existing child-session interaction tests, via
+   * `resolveSessionParent`/`sessionBelongsTo`) and (b) the child's own message-list
+   * terminal state. We do NOT depend on any session-level `busy`/`idle` field —
+   * there is none on `GET /session/:id`; OpenCode's busy state is in-memory
+   * `SessionStatus` only.
+   */
+  async isAnyDescendantSessionAlive(rootSessionId) {
+    const sessions = await listSessions(this.port);
+    if (!sessions) {
+      this.log({
+        level: "error",
+        message: `Re-adopt: could not enumerate sessions to cross-check descendant liveness for root ${rootSessionId} (listSessions failed) \u2014 treating child liveness as indeterminate`
+      });
+      return null;
+    }
+    for (const candidate of sessions) {
+      if (!candidate?.id || candidate.id === rootSessionId) continue;
+      if (!await this.sessionBelongsTo(candidate.id, rootSessionId)) continue;
+      const childMsgs = await getSessionMessages(this.port, candidate.id);
+      if (isSessionActivelyGenerating(childMsgs)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Cheap decision-telemetry label for a running row's LAST correlated reply
+   * (WI-2 Task 2.2): which running SHAPE it is, for the status-gated recovery log.
+   *   - `b1`    — the reply itself is still in flight (`time.completed == null`) —
+   *               the aborted-in-flight production bug after a restart.
+   *   - `b2`    — a COMPLETED reply pinned running only by `finish === "tool-calls"`
+   *               (the sub-agent preamble — #253's shape).
+   *   - `other` — any other shape (defensive; a running row is normally b1 or b2).
+   * Reads `info.time.completed` / `info.finish` (tolerating the legacy top-level
+   * shape) directly rather than re-importing the module-private `completedOf`/
+   * `finishOf` — this is a display label only, not a correctness predicate.
+   */
+  replyCompletionShape(reply) {
+    if (!reply) return "other";
+    const completed = reply.info?.time?.completed ?? reply.time?.completed;
+    if (completed == null) return "b1";
+    const finish = reply.info?.finish ?? reply.finish;
+    return finish === "tool-calls" ? "b2" : "other";
+  }
+  /**
+   * Attribute a surfaced interaction to the in-flight message it paused on (M-1).
+   *
+   * The interaction carries `interactionMessageId` — the ASSISTANT message id
+   * that raised it (a question's `tool.messageID` / a permission's `messageID`).
+   * That assistant message is the reply to ONE of our minted user messages
+   * (correlated by `parentID`, GATE-B). So when we have the tick's message
+   * snapshot, we resolve each running in-flight message's correlated assistant
+   * reply (`findAssistantReplyAfter`) and match its id against
+   * `interactionMessageId` — giving an EXACT attribution even with several
+   * messages in flight concurrently in one session.
+   *
+   * We fall back to the oldest running message ONLY when no exact match is
+   * possible (the id is absent, the snapshot is missing, or the reply has not yet
+   * been correlated). With a single running message either path is exact. Never
+   * throws.
+   *
+   * Attribution must NOT depend on our own `started` PATCH flag: opencode can
+   * START a turn AND raise a question/permission BEFORE our next tick fires
+   * `markProcessing` (which sets `started`). Relying on `started` would leave the
+   * running set empty in that window and let the server fall back to "newest
+   * processing/pending" — possibly @mentioning a FOLLOW-UP author rather than the
+   * person whose active turn actually paused. So we derive "running" from the
+   * tick's `messages` snapshot via `messageRunState` instead.
+   */
+  attributeInteraction(watcher, interactionMessageId, messages) {
+    const inFlight = [...watcher.inFlight.values()].filter((m) => !m.done);
+    if (inFlight.length === 0) return void 0;
+    if (interactionMessageId && messages) {
+      const exact = inFlight.find((m) => {
+        const reply = findAssistantReplyAfter(messages, m.opencodeMessageId);
+        return reply != null && messageIdOf(reply) === interactionMessageId;
+      });
+      if (exact) return exact;
+    }
+    const byOldest = (a, b) => a.dispatchedAt - b.dispatchedAt;
+    if (messages) {
+      const runningPerSnapshot = inFlight.filter(
+        (m) => messageRunState(messages, m.opencodeMessageId) === "running"
+      );
+      if (runningPerSnapshot.length > 0) {
+        return runningPerSnapshot.sort(byOldest)[0];
+      }
     }
+    const startedRunning = inFlight.filter((m) => m.started);
+    if (startedRunning.length > 0) {
+      return startedRunning.sort(byOldest)[0];
+    }
+    return inFlight.sort(byOldest)[0];
   }
   // -------------------------------------------------------------------------
   // Evident API calls (combinedAuth thread routes)
@@ -1598,49 +3478,191 @@ var ChannelDriver = class {
     }
     return await res.json();
   }
-  async markProcessing(conversationId, messageId) {
+  /**
+   * Fetch this agent's `processing` messages for re-adoption (ADR-0046, WI-1).
+   * The pending path (`getPendingConversations`/`getPendingMessages`) only
+   * surfaces `pending` rows, so a message already `processing` when the runner
+   * died is invisible to it — this dedicated endpoint returns exactly those rows
+   * with the fields the re-adopt path needs (`processed_at`,
+   * `opencode_session_id`, routing).
+   *
+   * Response is an OBJECT WRAPPER `{ messages: [...] }` (snake_case) — NOT a bare
+   * array. Propagates `ChannelAuthError` on 401/403; throws a plain `Error` on
+   * other non-ok so `drainPending`'s try/finally leaves `draining` false and the
+   * next tick retries.
+   */
+  async getProcessingMessages() {
+    const res = await this.fetchImpl(
+      `${this.apiUrl}/agents/${this.agentId}/conversations/processing`,
+      { headers: { Authorization: this.getAuthHeader() } }
+    );
+    this.assertAuth(res, "fetching processing messages");
+    if (!res.ok) {
+      throw new Error(`Failed to get processing messages: HTTP ${res.status}`);
+    }
+    const data = await res.json();
+    let messages = data.messages ?? [];
+    if (this.conversationFilter) {
+      messages = messages.filter((m) => m.conversation_id === this.conversationFilter);
+    }
+    return messages;
+  }
+  /**
+   * EXISTING combinedAuth route — now fired by the watcher on queued→running
+   * (Task 3.3), NOT at dispatch/claim time. `{status:'processing',
+   * opencode_session_id}` → `notifyMessageStarted` (hourglass→runner swap +
+   * deep-linked "View in Evident" notice).
+   *
+   * Return/throw contract (consumed by the watcher's swap-to-running guard):
+   *   - returns `true`  → the server transitioned the row to processing;
+   *   - returns `false` → the server gave a DEFINITIVE "already-processing"
+   *                       answer (a non-retryable, non-auth status — e.g. a
+   *                       conflict because a duplicate already transitioned it),
+   *                       so the caller treats it as already-started and does NOT
+   *                       retry;
+   *   - throws `ChannelAuthError` on 401/403 (terminal auth failure);
+   *   - throws on a TRANSIENT failure (retryable 5xx/429 status, or a
+   *     network-level error from `fetch`) — i.e. NO definitive server response —
+   *     so the caller leaves the message un-started and retries the swap on the
+   *     next tick.
+   * A single attempt (no internal retry): the watcher's per-tick loop is the
+   * retry vehicle for the swap-to-running.
+   */
+  async markProcessing(conversationId, messageId, sessionId, opencodeMessageId) {
     const res = await this.fetchImpl(
       `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
       {
         method: "PATCH",
         headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
-        body: JSON.stringify({ status: "processing" })
+        body: JSON.stringify({
+          status: "processing",
+          opencode_session_id: sessionId,
+          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {}
+        })
       }
     );
     this.assertAuth(res, "marking message as processing");
-    return res.ok;
+    if (res.ok) return true;
+    if (isRetryableStatus(res.status)) {
+      throw new Error(`marking message as processing: HTTP ${res.status}`);
+    }
+    return false;
   }
   /**
-   * EXISTING combinedAuth completion route — idempotent + retried (WI-CHAN-2).
-   * `PATCH .../messages/:id {status:'done', opencode_session_id}`. The server's
+   * EXISTING combinedAuth completion route — idempotent (WI-CHAN-2). `PATCH
+   * .../messages/:id {status:'done', opencode_session_id}`. The server's
    * `queued_conversation_messages.status`/`processed_at` gate makes a re-call
-   * for an already-`done` message a no-op (no double Slack post).
+   * for an already-`done` message a no-op (no double Slack post). Fired by the
+   * watcher on per-message completion (Task 3.4) — no `confirmCompletion`
+   * round-trip (we already observed completion via the message list).
+   *
+   * SINGLE ATTEMPT (no in-call `callWithRetry` backoff). The per-session watcher
+   * services its in-flight messages SEQUENTIALLY within a tick
+   * (`runWatcherLoop` → `serviceInFlightMessage`), so a long multi-attempt
+   * backoff here would BLOCK sibling messages in the SAME session/tick: while
+   * message A's done PATCH burned its internal retries, message B could not be
+   * swapped to running even though opencode had already started it. Instead this
+   * does ONE PATCH and surfaces the SAME outcome contract the watcher's markDone
+   * handler already relies on, leaning on the per-tick retry across ticks
+   * (bounded by `inFlight.deadline`) rather than an in-call retry:
+   *   - resolves (`void`)            → the server transitioned the row to done
+   *                                    (or idempotently confirmed already-done);
+   *   - throws `ChannelAuthError`    → 401/403 (terminal auth failure → loop
+   *                                    cleanup, Finding 1);
+   *   - throws `ChannelTerminalError`→ non-retryable, non-auth 4xx (will never
+   *                                    succeed → straight to the cron, Finding 4);
+   *   - throws a plain `Error`       → TRANSIENT 5xx/429 or a network-level error
+   *                                    (no definitive server response → the
+   *                                    watcher retries next tick within the
+   *                                    deadline, Finding 4).
    */
-  async markDone(conversationId, messageId, sessionId) {
+  async markDone(conversationId, messageId, sessionId, opencodeMessageId) {
+    const res = await this.fetchImpl(
+      `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
+      {
+        method: "PATCH",
+        headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
+        body: JSON.stringify({
+          status: "done",
+          opencode_session_id: sessionId,
+          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {}
+        })
+      }
+    );
+    this.assertAuth(res, "marking message as done");
+    if (res.ok) return;
+    if (isRetryableStatus(res.status)) {
+      throw new Error(`marking message as done: HTTP ${res.status}`);
+    }
+    throw new ChannelTerminalError(`marking message as done: HTTP ${res.status}`, res.status);
+  }
+  /**
+   * Mark a message `failed`. `sessionId` / `error` are threaded to the API ONLY
+   * when provided (issue #182): a bare `markFailed(conv, msg)` sends
+   * `{status:'failed'}` unchanged (the dispatch-failure path), while an errored
+   * OpenCode turn sends `{status:'failed', opencode_session_id, error}` so the
+   * failure reason reaches the channel.
+   */
+  async markFailed(conversationId, messageId, sessionId, error2) {
+    const body = { status: "failed" };
+    if (sessionId !== void 0) body.opencode_session_id = sessionId;
+    if (error2 !== void 0) body.error = error2;
     await this.callWithRetry(
-      "marking message as done",
+      "marking message as failed",
       () => this.fetchImpl(
         `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
         {
           method: "PATCH",
           headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
-          body: JSON.stringify({ status: "done", opencode_session_id: sessionId })
+          body: JSON.stringify(body)
         }
       )
     );
   }
-  async markFailed(conversationId, messageId) {
-    await this.callWithRetry(
-      "marking message as failed",
-      () => this.fetchImpl(
-        `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
+  /**
+   * Best-effort, SINGLE-ATTEMPT runner→server telemetry ping
+   * (queued-followup-redrive). `POST .../messages/:id/signal {signal, ...extra}`
+   * — the server records it via `log()` (no DB write, no notification). This is
+   * fire-and-forget: it MUST NEVER throw into the drain or the watcher tick, and
+   * MUST NOT use `callWithRetry` (a telemetry ping must not block the sequential
+   * watcher tick — one attempt is enough). A failure is SWALLOWED but LOGGED with
+   * context (no silent catch, per development-workflow).
+   *
+   * Returns whether the POST SUCCEEDED (2xx). Most callers ignore this (pure
+   * telemetry), but the `paused` liveness-clear uses it to know whether to
+   * RE-ASSERT on a later tick — a single dropped `paused` POST must not leave a
+   * stale `last_seen_alive_at` on a still-paused row (Bugbot "Failed paused signal
+   * leaves liveness").
+   */
+  async postSignal(conversationId, messageId, signal, extra) {
+    try {
+      const res = await this.fetchImpl(
+        `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}/signal`,
         {
-          method: "PATCH",
+          method: "POST",
           headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
-          body: JSON.stringify({ status: "failed" })
+          body: JSON.stringify({ signal, ...extra })
         }
-      )
-    );
+      );
+      if (!res.ok) {
+        this.log({
+          level: "error",
+          message: `Signal '${signal}' for message ${messageId.slice(0, 8)} returned HTTP ${res.status} (telemetry-only, ignored)`,
+          conversation_id: conversationId,
+          message_id: messageId
+        });
+        return false;
+      }
+      return true;
+    } catch (err) {
+      this.log({
+        level: "error",
+        message: `Signal '${signal}' for message ${messageId.slice(0, 8)} failed (telemetry-only, ignored): ${err instanceof Error ? err.message : String(err)}`,
+        conversation_id: conversationId,
+        message_id: messageId
+      });
+      return false;
+    }
   }
   async persistSession(conversationId, sessionId) {
     const res = await this.fetchImpl(
@@ -1655,10 +3677,17 @@ var ChannelDriver = class {
   }
   /**
    * EXISTING combinedAuth interaction route (WI-CHAN-3) — idempotent + retried.
-   * `POST .../interactive-event {type, data}`. The server persists the
-   * interaction and posts a link to the proxied opencode-web conversation.
+   * `POST .../interactive-event {type, data, source_message_id?}`. The server
+   * persists the interaction and posts a link to the proxied opencode-web
+   * conversation, @mentioning the user who triggered THIS message's turn.
+   *
+   * WI-3 / WI-4 contract: `source_message_id` is the PAUSED message's own Slack
+   * ts (`message.source_message_id`). The server resolves the @mention from that
+   * message's user FIRST (falling back to the old "newest processing" precedence
+   * only when absent), so the correct person is mentioned under concurrency. It
+   * is OPTIONAL for back-compat with older clients / legacy rows.
    */
-  async reportInteraction(conversationId, type, data) {
+  async reportInteraction(conversationId, type, data, sourceMessageId) {
     try {
       await this.callWithRetry(
         "reporting interactive event",
@@ -1667,7 +3696,9 @@ var ChannelDriver = class {
           {
             method: "POST",
             headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
-            body: JSON.stringify({ type, data })
+            body: JSON.stringify(
+              sourceMessageId ? { type, data, source_message_id: sourceMessageId } : { type, data }
+            )
           }
         )
       );
@@ -1676,6 +3707,7 @@ var ChannelDriver = class {
         message: `${type} surfaced to channel (id: ${data.id.slice(0, 8)})`,
         conversation_id: conversationId
       });
+      return true;
     } catch (err) {
       if (err instanceof ChannelAuthError) throw err;
       this.log({
@@ -1683,6 +3715,7 @@ var ChannelDriver = class {
         message: `Failed to surface ${type}: ${err instanceof Error ? err.message : String(err)}`,
         conversation_id: conversationId
       });
+      return false;
     }
   }
   // -------------------------------------------------------------------------
@@ -1721,8 +3754,9 @@ var ChannelDriver = class {
           await this.sleep(backoffDelay(attempt, this.retry));
           continue;
         }
+        break;
       }
-      throw new Error(`${context}: HTTP ${res.status}`);
+      throw new ChannelTerminalError(`${context}: HTTP ${res.status}`, res.status);
     }
     throw lastError instanceof Error ? lastError : new Error(`${context}: exhausted retries`);
   }
@@ -1848,23 +3882,45 @@ Port ${port} is already in use.`));
       spinner.fail("Failed to start OpenCode");
       throw new Error("OpenCode failed to start");
     }
-    spinner.succeed(
-      `OpenCode running on port ${port}${health.version ? ` (v${health.version})` : ""}`
-    );
+    spinner.stop();
     return { port, process: proc, version: health.version ?? null };
   }
   return { port, process: null, version: null };
 }
 
 // src/commands/agent-lookup.ts
+async function readErrorMessage(response) {
+  const text = await response.text().catch(() => "");
+  if (!text) return response.statusText || void 0;
+  try {
+    const data = JSON.parse(text);
+    const message = data.message ?? data.error;
+    if (typeof message === "string" && message.trim()) {
+      return message;
+    }
+  } catch {
+  }
+  return text.trim() || response.statusText || void 0;
+}
+function authFailureHint(apiUrl, serverMessage) {
+  const reason = serverMessage ? `: ${serverMessage}` : "";
+  return `Authentication failed${reason}. Your credentials were rejected by ${apiUrl}. This usually means you logged in against a different environment, or your session expired \u2014 log in again pointing at this endpoint and retry.`;
+}
 async function resolveAgentIdFromKey(authHeader) {
   const apiUrl = getApiUrlConfig();
   try {
     const response = await fetch(`${apiUrl}/me`, {
       headers: { Authorization: authHeader }
     });
+    if (response.status === 401) {
+      const serverMessage = await readErrorMessage(response);
+      return { error: authFailureHint(apiUrl, serverMessage), authFailed: true };
+    }
     if (!response.ok) {
-      return { error: `Failed to resolve agent from key: HTTP ${response.status}` };
+      const serverMessage = await readErrorMessage(response);
+      return {
+        error: `Failed to resolve agent from key (HTTP ${response.status})${serverMessage ? `: ${serverMessage}` : ""}`
+      };
     }
     const data = await response.json();
     if (data.auth_type === "agent_key" && data.agent_id) {
@@ -1878,20 +3934,52 @@ async function resolveAgentIdFromKey(authHeader) {
     return { error: `Failed to resolve agent from key: ${message}` };
   }
 }
+async function notifyAgentDisconnected(agentId, authHeader) {
+  const apiUrl = getApiUrlConfig();
+  try {
+    const response = await fetch(`${apiUrl}/agents/${agentId}/disconnect`, {
+      method: "POST",
+      headers: { Authorization: authHeader }
+    });
+    if (!response.ok) {
+      const serverMessage = await readErrorMessage(response);
+      return {
+        ok: false,
+        error: `HTTP ${response.status}${serverMessage ? `: ${serverMessage}` : ""}`
+      };
+    }
+    return { ok: true };
+  } catch (error2) {
+    return { ok: false, error: error2 instanceof Error ? error2.message : String(error2) };
+  }
+}
 async function getAgentInfo(agentId, authHeader) {
   const apiUrl = getApiUrlConfig();
   try {
     const response = await fetch(`${apiUrl}/agents/${agentId}`, {
       headers: { Authorization: authHeader }
     });
-    if (response.status === 404) {
-      return { valid: false, error: "Agent not found" };
-    }
     if (response.status === 401) {
-      return { valid: false, error: "Authentication failed", authFailed: true };
+      const serverMessage = await readErrorMessage(response);
+      return { valid: false, error: authFailureHint(apiUrl, serverMessage), authFailed: true };
+    }
+    if (response.status === 403) {
+      const serverMessage = await readErrorMessage(response);
+      return {
+        valid: false,
+        error: serverMessage ?? "You do not have access to this agent (it may belong to a different team or organization)."
+      };
+    }
+    if (response.status === 404) {
+      const serverMessage = await readErrorMessage(response);
+      return { valid: false, error: serverMessage ?? `Agent ${agentId} not found` };
     }
     if (!response.ok) {
-      return { valid: false, error: `API error: ${response.status}` };
+      const serverMessage = await readErrorMessage(response);
+      return {
+        valid: false,
+        error: `API error (HTTP ${response.status})${serverMessage ? `: ${serverMessage}` : ""}`
+      };
     }
     const agent = await response.json();
     if (agent.agent_type !== "local") {
@@ -1910,7 +3998,9 @@ async function getAgentInfo(agentId, authHeader) {
 // src/commands/run.ts
 var MAX_ACTIVITY_LOG_ENTRIES = 10;
 var CHANNEL_POLL_INTERVAL_MS = Number(process.env.EVIDENT_CHANNEL_POLL_INTERVAL_MS) || 2e3;
-function log(state, message, isError = false) {
+var CHANNEL_STUCK_QUEUED_MS = Number(process.env.EVIDENT_STUCK_QUEUED_MS) || void 0;
+var SHUTDOWN_DRAIN_TIMEOUT_MS = Number(process.env.EVIDENT_SHUTDOWN_DRAIN_MS) || 25e3;
+function log2(state, message, isError = false) {
   if (state.json) {
     console.log(
       JSON.stringify({
@@ -1935,9 +4025,9 @@ function logActivity(state, entry) {
   }
   if (!state.interactive) {
     if (entry.type === "error") {
-      log(state, entry.error ?? "Unknown error", true);
+      log2(state, entry.error ?? "Unknown error", true);
     } else if (entry.type === "info" && entry.message) {
-      log(state, entry.message);
+      log2(state, entry.message);
     }
   }
 }
@@ -2023,6 +4113,7 @@ async function handleAuthError(state, error2) {
 }
 async function driveChannels(state, driver) {
   let idlePolls = 0;
+  let lastSeenProxiedActivityAt = state.lastProxiedActivityAt;
   while (state.running) {
     if (state.connection?.reconnecting && state.connection.reconnectPromise) {
       logActivity(state, { type: "info", message: "Waiting for tunnel reconnection..." });
@@ -2032,9 +4123,11 @@ async function driveChannels(state, driver) {
     try {
       const processed = await driver.drainPending();
       state.messageCount += processed;
-      if (processed > 0) {
+      const proxiedActivity = state.lastProxiedActivityAt !== lastSeenProxiedActivityAt;
+      lastSeenProxiedActivityAt = state.lastProxiedActivityAt;
+      if (processed > 0 || driver.hasInFlightWatchers() || proxiedActivity) {
         idlePolls = 0;
-        if (state.interactive) displayStatus(state);
+        if (processed > 0 && state.interactive) displayStatus(state);
       } else if (state.idleTimeout !== null) {
         idlePolls++;
         if (idlePolls === 1) {
@@ -2061,7 +4154,7 @@ async function driveChannels(state, driver) {
       logActivity(state, { type: "error", error: `Channel processing error: ${errorMessage}` });
       if (state.interactive) displayStatus(state);
     }
-    await new Promise((resolve) => setTimeout(resolve, CHANNEL_POLL_INTERVAL_MS));
+    await new Promise((resolve2) => setTimeout(resolve2, CHANNEL_POLL_INTERVAL_MS));
     if (state.idleTimeout !== null && idlePolls >= 2) {
       const idleMs = idlePolls * CHANNEL_POLL_INTERVAL_MS;
       if (idleMs > state.idleTimeout * 1e3) {
@@ -2072,8 +4165,122 @@ async function driveChannels(state, driver) {
     }
   }
 }
-async function cleanup(state) {
+var SESSION_CLEANUP_FIRST_SWEEP_MS = 1e4;
+async function runSweep(state, driver, config2) {
+  const mode = `age=${config2.maxAgeMs ?? "\u2014"} count=${config2.maxCount ?? "\u2014"}`;
+  try {
+    const sessions = await listSessions(state.port);
+    if (sessions === null) {
+      logActivity(state, {
+        type: "info",
+        message: `Session cleanup: could not list sessions (opencode unreachable); skipping this sweep (${mode})`
+      });
+      return;
+    }
+    const toDelete = selectSessionsToDelete(
+      sessions.map((s) => ({ id: s.id, lastActivityMs: sessionLastActivityMs(s) })),
+      {
+        maxAgeMs: config2.maxAgeMs,
+        maxCount: config2.maxCount,
+        nowMs: Date.now(),
+        protectedIds: driver.protectedSessionIds()
+      }
+    );
+    const protectedNow = driver.protectedSessionIds();
+    let deleted = 0;
+    let failed = 0;
+    let skippedNewlyActive = 0;
+    for (const id of toDelete) {
+      if (protectedNow.has(id)) {
+        skippedNewlyActive++;
+        logActivity(state, {
+          type: "info",
+          message: `Session cleanup: skipping ${id} \u2014 became active/bound after selection (${mode})`
+        });
+        continue;
+      }
+      if (await deleteSession(state.port, id)) deleted++;
+      else failed++;
+    }
+    const failedNote = failed > 0 ? `, failed ${failed}` : "";
+    const skippedNote = skippedNewlyActive > 0 ? `, skipped ${skippedNewlyActive} newly-active` : "";
+    logActivity(state, {
+      type: "info",
+      message: `Session cleanup: inspected ${sessions.length}, deleted ${deleted}${failedNote}${skippedNote} (${mode})`
+    });
+  } catch (error2) {
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    logActivity(state, {
+      type: "error",
+      error: `Session cleanup sweep failed (non-fatal, ${mode}): ${message}`
+    });
+  }
+}
+function scheduleSessionCleanup(state, driver, options) {
+  const config2 = resolveSessionCleanupConfig(
+    {
+      maxAge: options.sessionCleanupMaxAge,
+      maxCount: options.sessionCleanupMaxCount,
+      interval: options.sessionCleanupInterval
+    },
+    process.env
+  );
+  for (const warning2 of config2.warnings) {
+    logActivity(state, { type: "info", message: `Session cleanup: ${warning2}` });
+  }
+  if (!config2.enabled) return;
+  logActivity(state, {
+    type: "info",
+    message: `Session cleanup enabled (age=${config2.maxAgeMs ?? "\u2014"}, count=${config2.maxCount ?? "\u2014"}, interval=${config2.intervalMs}ms)`
+  });
+  const interval = setInterval(() => void runSweep(state, driver, config2), config2.intervalMs);
+  const firstSweep = setTimeout(
+    () => void runSweep(state, driver, config2),
+    SESSION_CLEANUP_FIRST_SWEEP_MS
+  );
+  state.sessionCleanupTimers.push(interval, firstSweep);
+}
+async function notifyOffline(state) {
+  if (!state.agentId || !state.authHeader) return;
+  if (!state.connected) {
+    log2(state, "Skipping offline signal \u2014 this runner does not hold the live tunnel");
+    return;
+  }
+  const result = await notifyAgentDisconnected(state.agentId, state.authHeader);
+  if (result.ok) {
+    log2(state, "Notified Evident the agent is going offline");
+  } else {
+    logActivity(state, {
+      type: "error",
+      error: `Could not notify Evident of offline status (relay will still report it): ${result.error}`
+    });
+    if (state.interactive) displayStatus(state);
+  }
+}
+async function cleanup(state, opts = {}) {
   state.running = false;
+  for (const timer of state.sessionCleanupTimers) {
+    clearInterval(timer);
+    clearTimeout(timer);
+  }
+  state.sessionCleanupTimers = [];
+  if (opts.graceful && state.channelDriver) {
+    state.channelDriver.stop();
+    log2(state, "Draining in-flight channel work before shutdown...");
+    if (state.interactive) {
+      logActivity(state, { type: "info", message: "Draining in-flight work before shutdown..." });
+      displayStatus(state);
+    }
+    const settled = await state.channelDriver.waitForInFlight(SHUTDOWN_DRAIN_TIMEOUT_MS);
+    if (!settled) {
+      logActivity(state, {
+        type: "info",
+        message: "Shutdown drain timed out with work still in flight \u2014 leaving it for restart recovery"
+      });
+      if (state.interactive) displayStatus(state);
+    }
+  }
+  await notifyOffline(state);
   if (state.connection) {
     state.connection.close();
     state.connection = null;
@@ -2084,7 +4291,7 @@ async function cleanup(state) {
       logActivity(state, { type: "info", message: "Stopped OpenCode process" });
       displayStatus(state);
     } else {
-      log(state, "Stopped OpenCode process");
+      log2(state, "Stopped OpenCode process");
     }
     state.opencodeProcess = null;
   }
@@ -2104,26 +4311,32 @@ async function run(options) {
     opencodeVersion: null,
     opencodeProcess: null,
     connection: null,
+    channelDriver: null,
     running: true,
+    shuttingDown: false,
     activityLog: [],
     messageCount: 0,
+    lastProxiedActivityAt: null,
+    sessionCleanupTimers: [],
     authHeader: ""
   };
   if (state.idleTimeout === null && (process.env.GITHUB_ACTIONS || process.env.CI)) {
-    log(
+    log2(
       state,
       "Warning: No --idle-timeout set in CI environment. The runner will poll indefinitely until the job times out. Consider adding --idle-timeout 30 to avoid wasting runner minutes.",
       false
     );
   }
   const handleSignal = async () => {
+    if (state.shuttingDown) return;
+    state.shuttingDown = true;
     if (state.interactive) {
       logActivity(state, { type: "info", message: "Shutting down..." });
       displayStatus(state);
     } else {
-      log(state, "Shutting down...");
+      log2(state, "Shutting down...");
     }
-    await cleanup(state);
+    await cleanup(state, { graceful: true });
     await shutdownTelemetry();
     process.exit(0);
   };
@@ -2154,7 +4367,7 @@ async function run(options) {
         const resolved = await resolveAgentIdFromKey(state.authHeader);
         if (resolved.agent_id) {
           state.agentId = resolved.agent_id;
-          log(state, `Resolved agent ID from key: ${state.agentId}`);
+          log2(state, `Resolved agent ID from key: ${state.agentId}`);
           if (state.interactive && !state.json) {
             logActivity(state, {
               type: "info",
@@ -2217,14 +4430,21 @@ async function run(options) {
         port: state.port,
         interactive: state.interactive,
         agentId: state.agentId,
-        log: (message) => log(state, message)
+        log: (message) => log2(state, message)
       });
       state.port = oc.port;
       state.opencodeProcess = oc.process;
       state.opencodeVersion = oc.version;
       state.opencodeConnected = oc.process !== null || oc.version !== null;
-      const version = state.opencodeVersion ? ` (v${state.opencodeVersion})` : "";
-      ocSpinner?.succeed(`OpenCode running on port ${state.port}${version}`);
+      const version2 = state.opencodeVersion ? ` (v${state.opencodeVersion})` : "";
+      ocSpinner?.succeed(`OpenCode running on port ${state.port}${version2}`);
+      const versionWarning = buildOpenCodeVersionWarning(state.opencodeVersion);
+      if (versionWarning) {
+        log2(state, versionWarning, false);
+        if (state.interactive && !state.json) {
+          logActivity(state, { type: "info", message: versionWarning });
+        }
+      }
     } catch (error2) {
       ocSpinner?.fail(error2.message);
       throw error2;
@@ -2236,12 +4456,14 @@ async function run(options) {
       apiUrl: getApiUrlConfig(),
       getAuthHeader: () => state.authHeader,
       conversationFilter: state.conversationFilter,
+      stuckQueuedMs: CHANNEL_STUCK_QUEUED_MS,
       log: (entry) => logActivity(state, {
         type: entry.level === "error" ? "error" : "info",
         message: entry.message,
         error: entry.level === "error" ? entry.message : void 0
       })
     });
+    state.channelDriver = channelDriver;
     const connection = new RunnerConnection({
       agentId: state.agentId,
       getAuthHeader: () => state.authHeader,
@@ -2255,10 +4477,29 @@ async function run(options) {
             type: "info",
             message: `Tunnel ${isReconnect ? "reconnected" : "connected"} (agent: ${agentId})`
           });
-          emitAgentConnected(state.agentId, { port: state.port });
+          emitAgentConnected(state.agentId, {
+            port: state.port,
+            cli_version: getCliVersion(),
+            opencode_version: state.opencodeVersion
+          });
           if (!isReconnect) tunnelSpinner?.succeed("Tunnel connected");
           if (state.interactive) displayStatus(state);
-          channelDriver.drainPending().catch(() => {
+          channelDriver.drainPending().then((processed) => {
+            if (processed > 0) {
+              state.messageCount += processed;
+              logActivity(state, {
+                type: "info",
+                message: `Drained ${processed} queued message(s) on connect`
+              });
+              if (state.interactive) displayStatus(state);
+            }
+          }).catch((error2) => {
+            const message = error2 instanceof Error ? error2.message : String(error2);
+            logActivity(state, {
+              type: "error",
+              error: `Failed to drain queued messages on connect: ${message}`
+            });
+            if (state.interactive) displayStatus(state);
           });
         },
         onDisconnected: (code, reason) => {
@@ -2274,9 +4515,40 @@ async function run(options) {
           logActivity(state, { type: "error", error: error2 });
           if (state.interactive) displayStatus(state);
         },
-        // Web traffic is proxied transparently; only note opencode is live.
+        // Web traffic is proxied transparently; note opencode is live and stamp
+        // proxied activity so the idle loop treats interactive proxy use as work.
+        // Fires per forwarded response head (incl. every SSE open) and excludes
+        // the internal drain-ping, so an actively-used proxy keeps the timer
+        // fresh while a lone idle SSE with no follow-up requests still ages out.
         onResponse: () => {
           state.opencodeConnected = true;
+          state.lastProxiedActivityAt = Date.now();
+        },
+        // A channel message was queued and the api-worker pinged us over the
+        // tunnel to drain immediately instead of waiting for the next poll tick.
+        // Best-effort + non-fatal: mirror the on-connect drain block. A failed
+        // drain here is logged and swallowed — the steady-state poll retries, so
+        // a lost/failed ping can never orphan a message (§2 invariant).
+        onDrainPing: () => {
+          if (!state.running) return;
+          logActivity(state, { type: "info", message: "Drain ping received \u2014 draining" });
+          channelDriver.drainPending().then((processed) => {
+            if (processed > 0) {
+              state.messageCount += processed;
+              logActivity(state, {
+                type: "info",
+                message: `Drained ${processed} queued message(s) on ping`
+              });
+              if (state.interactive) displayStatus(state);
+            }
+          }).catch((error2) => {
+            const message = error2 instanceof Error ? error2.message : String(error2);
+            logActivity(state, {
+              type: "error",
+              error: `Failed to drain queued messages on ping: ${message}`
+            });
+            if (state.interactive) displayStatus(state);
+          });
         },
         onInfo: (message) => logActivity(state, { type: "info", message })
       }
@@ -2288,12 +4560,12 @@ async function run(options) {
       if (error2.message === "Unauthorized") tunnelSpinner?.fail("Unauthorized");
       throw error2;
     }
-    if (interactive && !state.json) {
-      displayStatus(state);
-    } else {
-      log(state, "Driving channel messages...");
+    scheduleSessionCleanup(state, channelDriver, options);
+    if (!interactive || state.json) {
+      log2(state, "Driving channel messages...");
     }
     await driveChannels(state, channelDriver);
+    if (state.shuttingDown) return;
     await cleanup(state);
     if (state.json) {
       console.log(
@@ -2303,11 +4575,12 @@ async function run(options) {
         })
       );
     } else if (!interactive) {
-      log(state, `Completed. Processed ${state.messageCount} message(s).`);
+      log2(state, `Completed. Processed ${state.messageCount} message(s).`);
     }
     await shutdownTelemetry();
     process.exit(0);
   } catch (error2) {
+    if (state.shuttingDown) return;
     await cleanup(state);
     const message = error2 instanceof Error ? error2.message : String(error2);
     if (state.json) {
@@ -2325,8 +4598,9 @@ async function run(options) {
 }
 
 // src/index.ts
+var { version } = createRequire(import.meta.url)("../package.json");
 var program = new Command();
-program.name("evident").description("Run OpenCode locally and connect it to Evident").version("0.1.0").option(
+program.name("evident").description("Run OpenCode locally and connect it to Evident").version(version).option(
   "--endpoint <url>",
   "Evident API base URL (default: production; e.g. http://localhost:3001)"
 ).option("--tunnel <url>", "Tunnel WebSocket URL (default: production; e.g. ws://localhost:8787)").hook("preAction", (thisCommand) => {
@@ -2339,9 +4613,18 @@ program.name("evident").description("Run OpenCode locally and connect it to Evid
   }
 });
 program.command("login").description("Authenticate with Evident").option("--token", "Use token-based authentication (for CI/CD)").option("--no-browser", "Do not open the browser automatically").action(login);
-program.command("logout").description("Remove stored credentials").action(logout);
+program.command("logout").description("Remove stored credentials for the current endpoint").option("--all", "Remove stored credentials for all endpoints").action((options) => logout({ all: options.all }));
 program.command("whoami").description("Show the currently logged in user").action(whoami);
-program.command("run").description("Connect to Evident and process messages").option("-a, --agent [id]", "Agent ID to connect to (optional when EVIDENT_AGENT_KEY is set)").option("-p, --port <port>", "OpenCode port (default: 4096)", "4096").option("-v, --verbose", "Show detailed request/response information").option("-c, --conversation <id>", "Process only this specific conversation").option("--idle-timeout <seconds>", "Exit after N seconds idle").option("--json", "Output in JSON format").action(
+program.command("run").description("Connect to Evident and process messages").option("-a, --agent [id]", "Agent ID to connect to (optional when EVIDENT_AGENT_KEY is set)").option("-p, --port <port>", "OpenCode port (default: 4096)", "4096").option("-v, --verbose", "Show detailed request/response information").option("-c, --conversation <id>", "Process only this specific conversation").option("--idle-timeout <seconds>", "Exit after N seconds idle").option("--json", "Output in JSON format").option(
+  "--session-cleanup-max-age <duration>",
+  "Delete OpenCode sessions idle longer than this (e.g. 7d, 24h). Enables cleanup. Env: EVIDENT_SESSION_CLEANUP_MAX_AGE"
+).option(
+  "--session-cleanup-max-count <n>",
+  "Keep only the newest N OpenCode sessions. Enables cleanup. Env: EVIDENT_SESSION_CLEANUP_MAX_COUNT"
+).option(
+  "--session-cleanup-interval <duration>",
+  "How often the cleanup sweep runs (default: 1h). Env: EVIDENT_SESSION_CLEANUP_INTERVAL"
+).action(
   (options) => {
     run({
       agent: options.agent,
@@ -2349,7 +4632,11 @@ program.command("run").description("Connect to Evident and process messages").op
       verbose: options.verbose,
       conversation: options.conversation,
       idleTimeout: options.idleTimeout ? parseInt(options.idleTimeout, 10) : void 0,
-      json: options.json
+      json: options.json,
+      // Raw strings — the resolver in run.ts single-sources parsing (M1).
+      sessionCleanupMaxAge: options.sessionCleanupMaxAge,
+      sessionCleanupMaxCount: options.sessionCleanupMaxCount,
+      sessionCleanupInterval: options.sessionCleanupInterval
     });
   }
 );