@evident-ai/cli 3.0.1-dev.fffc02d → 3.1.1-dev.14c6359

package/dist/index.js

@@ -285,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);
@@ -302,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
@@ -376,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();
     }
@@ -706,7 +706,7 @@ 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" };
 }
@@ -1078,6 +1078,84 @@ async function getSessionMessages(port, sessionId) {
     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()) {
@@ -1095,17 +1173,113 @@ async function createOpenCodeSession(port, directory) {
   const data = await response.json();
   return data.id;
 }
+async function getModelAttachmentCapability(port, model) {
+  try {
+    const res = await fetch(`${opencodeBase(port)}/config/providers`);
+    if (!res.ok) {
+      console.error(
+        `[getModelAttachmentCapability] GET /config/providers returned HTTP ${res.status} (port ${port})`
+      );
+      return null;
+    }
+    const body = await res.json();
+    const providers = Array.isArray(body?.providers) ? body.providers : null;
+    if (!providers) {
+      console.error(
+        `[getModelAttachmentCapability] GET /config/providers body had no providers array (port ${port})`
+      );
+      return null;
+    }
+    const slash = model ? model.indexOf("/") : -1;
+    const providerId = slash > 0 ? model.slice(0, slash) : void 0;
+    let modelId = slash > 0 ? model.slice(slash + 1) : void 0;
+    const defaults2 = body?.default && typeof body.default === "object" ? body.default : void 0;
+    let provider = providerId ? providers.find((p) => p?.id === providerId) : void 0;
+    if (!provider && !providerId) {
+      const defaultProviderIds = defaults2 ? Object.keys(defaults2) : [];
+      if (defaultProviderIds.length === 1) {
+        provider = providers.find((p) => p?.id === defaultProviderIds[0]);
+      }
+    }
+    if (!provider || !provider.models) return null;
+    if (!modelId && defaults2 && typeof provider.id === "string") {
+      const def = defaults2[provider.id];
+      if (typeof def === "string") modelId = def;
+    }
+    if (!modelId) {
+      if (providerId) {
+        const keys = Object.keys(provider.models);
+        if (keys.length === 1) modelId = keys[0];
+      }
+      if (!modelId) return null;
+    }
+    const entry = provider.models[modelId];
+    if (!entry || typeof entry !== "object") return null;
+    return typeof entry.attachment === "boolean" ? entry.attachment : null;
+  } catch (err) {
+    console.error(
+      `[getModelAttachmentCapability] GET /config/providers failed (port ${port}): ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
+  }
+}
+async function buildFileParts(attachments, capable) {
+  const outcomes = [];
+  const parts = [];
+  const capabilityUnknown = capable === null;
+  if (capable !== true) {
+    for (const a of attachments.inputs) {
+      outcomes.push({ index: a.index, mime: a.mime, filename: a.filename, status: "skipped" });
+    }
+    return { parts, outcomes, capabilityUnknown };
+  }
+  for (const a of attachments.inputs) {
+    let dataUrl = null;
+    try {
+      dataUrl = await attachments.fetchDataUrl(a.index);
+    } catch (err) {
+      console.error(
+        `[buildFileParts] attachment ${a.index} (${a.mime}) fetch threw \u2014 omitting: ${err instanceof Error ? err.message : String(err)}`
+      );
+      dataUrl = null;
+    }
+    if (dataUrl == null) {
+      outcomes.push({ index: a.index, mime: a.mime, filename: a.filename, status: "failed" });
+      continue;
+    }
+    parts.push({
+      type: "file",
+      mime: a.mime,
+      url: dataUrl,
+      ...a.filename ? { filename: a.filename } : {}
+    });
+    outcomes.push({ index: a.index, mime: a.mime, filename: a.filename, status: "sent" });
+  }
+  return { parts, outcomes, capabilityUnknown };
+}
 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) {
+async function sendPromptAsync(port, sessionId, content, options, attachments) {
   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 parts = [{ type: "text", text: content }];
+  let pendingOutcomes = null;
+  if (attachments && attachments.inputs.length > 0) {
+    const capable = await getModelAttachmentCapability(port, options?.model);
+    const {
+      parts: fileParts,
+      outcomes,
+      capabilityUnknown
+    } = await buildFileParts(attachments, capable);
+    parts.push(...fileParts);
+    if (attachments.onOutcomes) pendingOutcomes = { outcomes, capabilityUnknown };
+  }
   const body = {
-    parts: [{ type: "text", text: content }]
+    parts
   };
   if (options?.agent) {
     body.agent = options.agent;
@@ -1144,10 +1318,13 @@ async function sendPromptAsync(port, sessionId, content, options) {
           best = { id, created };
         }
       }
-      if (best) return best.id;
+      if (best) {
+        if (pendingOutcomes && attachments?.onOutcomes) attachments.onOutcomes(pendingOutcomes);
+        return best.id;
+      }
     }
     if (attempt < READ_BACK_ATTEMPTS - 1) {
-      await new Promise((resolve) => setTimeout(resolve, READ_BACK_DELAY_MS));
+      await new Promise((resolve2) => setTimeout(resolve2, READ_BACK_DELAY_MS));
     }
   }
   return null;
@@ -1193,6 +1370,72 @@ function findLastAssistantReplyFor(messages, userMessageId) {
   }
   return lastOk ?? last;
 }
+function messageUsage(messages, userMessageId) {
+  if (!messages || messages.length === 0) return null;
+  const byParentAll = messages.filter(
+    (m) => roleOf(m) === "assistant" && parentIdOf(m) === userMessageId
+  );
+  const byParentNonErrored = byParentAll.filter((m) => errorOf(m) == null);
+  const byParent = byParentNonErrored.length > 0 ? byParentNonErrored : byParentAll;
+  let correlated;
+  if (byParent.length > 0) {
+    correlated = byParent;
+  } else {
+    const reply = findAssistantReplyAfter(messages, userMessageId);
+    correlated = reply ? [reply] : [];
+  }
+  if (correlated.length === 0) return null;
+  let sawAnyUsage = false;
+  let inputSum = 0;
+  let outputSum = 0;
+  let reasoningSum = 0;
+  let cacheReadSum = 0;
+  let cacheWriteSum = 0;
+  let costSum = 0;
+  let sawCost = false;
+  let modelId = null;
+  let providerId = null;
+  for (const m of correlated) {
+    const info = m.info;
+    if (!info) continue;
+    const tokens = info.tokens;
+    if (tokens) {
+      sawAnyUsage = true;
+      inputSum += tokens.input ?? 0;
+      outputSum += tokens.output ?? 0;
+      reasoningSum += tokens.reasoning ?? 0;
+      cacheReadSum += tokens.cache?.read ?? 0;
+      cacheWriteSum += tokens.cache?.write ?? 0;
+    }
+    if (typeof info.cost === "number") {
+      sawAnyUsage = true;
+      sawCost = true;
+      costSum += info.cost;
+    }
+    if (typeof info.modelID === "string") {
+      sawAnyUsage = true;
+      modelId = info.modelID;
+    }
+    if (typeof info.providerID === "string") {
+      sawAnyUsage = true;
+      providerId = info.providerID;
+    }
+  }
+  if (!sawAnyUsage) return null;
+  return {
+    usage_provider_id: providerId,
+    usage_model_id: modelId,
+    usage_tokens_input: inputSum,
+    usage_tokens_output: outputSum,
+    usage_tokens_reasoning: reasoningSum,
+    usage_tokens_cache_read: cacheReadSum,
+    usage_tokens_cache_write: cacheWriteSum,
+    // NULL means "OpenCode never reported a cost" (never inferred from
+    // tokens) — distinct from a genuine 0-cost turn, which would set
+    // `sawCost` true with `costSum === 0`.
+    usage_cost_usd: sawCost ? costSum : null
+  };
+}
 function messageRunState(messages, userMessageId) {
   if (!messages || messages.length === 0) return "unknown";
   const hasUser = messages.some((m) => idOf(m) === userMessageId);
@@ -1204,6 +1447,11 @@ function messageRunState(messages, userMessageId) {
   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);
@@ -1224,6 +1472,110 @@ function hasRunningAssistantExcept(messages, exceptUserMessageId) {
   );
 }
 
+// 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 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 {
+      maxAgeMs = parseDurationMs(maxAgeRaw);
+    } catch (err) {
+      warnings.push(
+        `Ignoring invalid --session-cleanup-max-age: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  let maxCount;
+  if (maxCountRaw !== void 0) {
+    try {
+      maxCount = parseMaxCount(maxCountRaw);
+    } catch (err) {
+      warnings.push(
+        `Ignoring invalid --session-cleanup-max-count: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  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
 import WebSocket2 from "ws";
 
@@ -1314,12 +1666,12 @@ var StreamForwarder = class {
     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));
         };
       });
     }
@@ -1437,7 +1789,7 @@ function connectTunnel(options) {
   } = 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
@@ -1502,7 +1854,7 @@ function connectTunnel(options) {
           clearTimeout(connectionTimeout);
           const connectedAgentId = message.agent_id ?? agentId;
           onConnected?.(connectedAgentId);
-          resolve({
+          resolve2({
             ws,
             close: () => ws.close(1e3, "CLI shutdown")
           });
@@ -1624,6 +1976,17 @@ function messageIdOf(m) {
   const infoId = m.info?.id;
   return typeof infoId === "string" ? infoId : void 0;
 }
+function cleanImageMime(contentType) {
+  if (!contentType) return null;
+  const media = contentType.split(";")[0].trim().toLowerCase();
+  return /^image\/[a-z0-9.+-]+$/.test(media) ? media : null;
+}
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
 var DEFAULT_RETRY_POLICY = {
   maxAttempts: 6,
   baseDelayMs: 500,
@@ -1632,6 +1995,9 @@ var DEFAULT_RETRY_POLICY = {
 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);
@@ -1728,6 +2094,15 @@ var ChannelDriver = class {
    * 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
@@ -1742,6 +2117,15 @@ var ChannelDriver = class {
    * so the NEXT tick may retry exactly once more).
    */
   awaitingReadopt = /* @__PURE__ */ new Set();
+  /**
+   * "Already signalled `attachments_skipped` for this Evident message id" (#376).
+   * The in-thread skip note is an OUTCOME, so it must fire AT MOST ONCE per message
+   * — never re-post on a re-dispatch of the same row (`forceReadoptRun` or the
+   * next-tick null-id retry both re-run `sendPromptAsync`, which re-fires
+   * `onOutcomes`). Mirrors `readoptPollUnresolvedSignalled`: a local dedup on the
+   * outcome, not the dispatch. Not cleared (a message is signalled once for life).
+   */
+  attachmentsSkippedSignalled = /* @__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
@@ -1759,6 +2143,16 @@ var ChannelDriver = class {
    * entry = not yet resolved; `null` = resolved root (stop walking).
    */
   sessionParents = /* @__PURE__ */ new Map();
+  /**
+   * Per-session OpenCode title cache (#310), keyed by sessionId. Only a resolved
+   * NON-EMPTY name is stored (terminal — a real session name won't later un-name),
+   * so we do NOT re-GET `/session/:id` every tick. A missing entry = not yet
+   * resolved OR resolved-but-still-empty → re-fetch on next need, since OpenCode
+   * names sessions asynchronously mid-turn. Driver-level (not per-watcher) so both
+   * the watcher completion path AND the restart-recovery re-adopt path (which has
+   * no watcher) can resolve the title.
+   */
+  sessionTitles = /* @__PURE__ */ new Map();
   /** Serialises drains so a reconnect during a drain doesn't double-process. */
   draining = false;
   /**
@@ -1796,9 +2190,6 @@ var ChannelDriver = class {
   get opencodeBase() {
     return `http://127.0.0.1:${this.port}`;
   }
-  // -------------------------------------------------------------------------
-  // Public API
-  // -------------------------------------------------------------------------
   /**
    * Drain all pending channel conversations once: poll → dispatch → register.
    * Called on tunnel `connected` (WI-CHAN-4) and on each poll tick by `run.ts`.
@@ -1854,6 +2245,28 @@ var ChannelDriver = class {
     }
     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
@@ -1918,9 +2331,7 @@ var ChannelDriver = class {
       if (!stillLive) return;
     }
   }
-  // -------------------------------------------------------------------------
   // 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
@@ -1952,13 +2363,24 @@ var ChannelDriver = class {
           conversation_id: conv.id,
           message_id: message.id
         });
+        const sendAttachments = this.buildSendAttachments(conv, message);
         opencodeMessageId = await this.dispatchLocked(
           sessionId,
-          () => sendPromptAsync(this.port, sessionId, message.content, options)
+          () => sendPromptAsync(this.port, sessionId, message.content, options, sendAttachments)
         );
       } 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: "warn",
+            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({
@@ -1971,7 +2393,7 @@ var ChannelDriver = class {
       }
       if (opencodeMessageId === null) {
         this.log({
-          level: "error",
+          level: "warn",
           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
@@ -1985,7 +2407,7 @@ var ChannelDriver = class {
     }
     if (messages.length > 0 && dispatched === 0 && skippedAlreadyDispatched === messages.length) {
       this.log({
-        level: "error",
+        level: "warn",
         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
       });
@@ -1994,16 +2416,33 @@ var ChannelDriver = class {
     return dispatched;
   }
   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 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: "debug",
+          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(conv.id, sessionId);
-    await this.persistSession(conv.id, sessionId).catch(() => {
+    this.sessions.set(conversationId, sessionId);
+    await this.persistSession(conversationId, sessionId).catch(() => {
     });
     return sessionId;
   }
@@ -2017,15 +2456,13 @@ var ChannelDriver = class {
     this.opencodeDirectory = await getOpenCodeDirectory(this.port);
     if (!this.opencodeDirectory) {
       this.log({
-        level: "info",
+        level: "warn",
         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
@@ -2045,6 +2482,103 @@ var ChannelDriver = class {
     );
     return run2;
   }
+  // Inbound image attachments (#255, WI-8)
+  /**
+   * Build the `SendAttachmentsInput` for a message's inbound images, or
+   * `undefined` when the message has none (so a text-only turn is unchanged).
+   *
+   * The driver OWNS the two channel-facing concerns the session module cannot:
+   *   - the AUTHENTICATED byte fetch through Evident's WI-6 endpoint
+   *     (`fetchAttachmentDataUrl`), using the SAME `getAuthHeader()` as every
+   *     other combinedAuth callback — the CLI NEVER talks to Slack directly;
+   *   - the in-thread SKIP NOTE (`signalAttachmentsSkipped`) posted over the
+   *     existing callback surface when any image was skipped/failed.
+   * `sendPromptAsync` applies the capability gate + appends the `file` parts and
+   * reports outcomes back via `onOutcomes`.
+   */
+  buildSendAttachments(conv, message) {
+    const refs = message.attachments;
+    if (!refs || refs.length === 0) return void 0;
+    return {
+      inputs: refs.map((a, index) => ({
+        index,
+        mime: a.mime,
+        ...a.filename ? { filename: a.filename } : {}
+      })),
+      fetchDataUrl: (index) => this.fetchAttachmentDataUrl(message.id, index, refs[index].mime),
+      onOutcomes: ({ outcomes, capabilityUnknown }) => this.signalAttachmentsSkipped(conv.id, message.id, outcomes, capabilityUnknown)
+    };
+  }
+  /**
+   * Fetch ONE inbound image's bytes through Evident's WI-6 endpoint
+   * (`GET {apiUrl}/agents/{agentId}/attachments/{messageId}/{index}`) using the
+   * existing authenticated fetch, and base64-encode into a
+   * `data:<mime>;base64,<…>` URL for the opencode `file` part's `url`.
+   *
+   * The endpoint streams the source bytes verbatim (200), or returns 404
+   * (not-owned / out-of-range / deleted-at-source / workspace gone) / 413
+   * (over-cap). On ANY non-2xx or thrown failure we return `null` so the caller
+   * OMITS that one image and the text turn still sends — NEVER throws the turn.
+   * Failures are logged with context (no silent swallow).
+   */
+  async fetchAttachmentDataUrl(messageId, index, mime) {
+    try {
+      const res = await this.fetchImpl(
+        `${this.apiUrl}/agents/${this.agentId}/attachments/${messageId}/${index}`,
+        { headers: { Authorization: this.getAuthHeader() } }
+      );
+      if (!res.ok) {
+        this.log({
+          level: "error",
+          message: `Attachment fetch for message ${messageId.slice(0, 8)} index ${index} returned HTTP ${res.status} \u2014 omitting this image (text turn proceeds)`,
+          message_id: messageId
+        });
+        return null;
+      }
+      const buf = await res.arrayBuffer();
+      const base64 = Buffer.from(buf).toString("base64");
+      const dataMime = cleanImageMime(res.headers.get("content-type")) || mime;
+      return `data:${dataMime};base64,${base64}`;
+    } catch (err) {
+      this.log({
+        level: "error",
+        message: `Attachment fetch for message ${messageId.slice(0, 8)} index ${index} failed \u2014 omitting this image (text turn proceeds): ${err instanceof Error ? err.message : String(err)}`,
+        message_id: messageId
+      });
+      return null;
+    }
+  }
+  /**
+   * On any skipped/failed image, post an in-thread note to Evident over the
+   * EXISTING combinedAuth callback surface — the CLI NEVER posts to Slack directly.
+   * Evident routes the note to source via `conversation.deliver`.
+   *
+   * The `POST .../messages/:id/signal` route accepts `attachments_skipped` (in
+   * `messageSignalSchema`) and turns it into an in-thread note delivered through
+   * `conversation.deliver` (e.g. "N image(s) couldn't be forwarded"), so the note
+   * reaches the channel.
+   *
+   * Fire-and-forget: never throws into the send/tick (logs its own failure).
+   */
+  signalAttachmentsSkipped(conversationId, messageId, outcomes, capabilityUnknown) {
+    const skipped = outcomes.filter((o) => o.status === "skipped").length;
+    const failed = outcomes.filter((o) => o.status === "failed").length;
+    if (skipped === 0 && failed === 0) return;
+    if (this.attachmentsSkippedSignalled.has(messageId)) return;
+    this.attachmentsSkippedSignalled.add(messageId);
+    const skippedReason = capabilityUnknown ? "unknown" : "unsupported";
+    this.log({
+      level: "info",
+      message: `Message ${messageId.slice(0, 8)}: ${skipped} image(s) skipped (${capabilityUnknown ? "capability was unreadable \u2014 failed open to text-only" : "model not attachment-capable"}), ${failed} image(s) unavailable (deleted-at-source or fetch failure) \u2014 noting to Evident`,
+      conversation_id: conversationId,
+      message_id: messageId
+    });
+    void this.postSignal(conversationId, messageId, "attachments_skipped", {
+      skipped,
+      failed,
+      ...skipped > 0 ? { skipped_reason: skippedReason } : {}
+    });
+  }
   /** Register a freshly-dispatched message with its session's watcher state. */
   registerInFlight(conv, sessionId, message, opencodeMessageId) {
     let watcher = this.watchers.get(sessionId);
@@ -2054,7 +2588,9 @@ var ChannelDriver = class {
         inFlight: /* @__PURE__ */ new Map(),
         loop: null,
         reportedQuestions: /* @__PURE__ */ new Set(),
-        reportedPermissions: /* @__PURE__ */ new Set()
+        reportedPermissions: /* @__PURE__ */ new Set(),
+        lastGoodPollAt: this.now(),
+        hadUsablePoll: false
       };
       this.watchers.set(sessionId, watcher);
     }
@@ -2064,20 +2600,37 @@ var ChannelDriver = class {
       opencodeMessageId,
       message,
       dispatchedAt: now,
+      processingAnchorMs: now,
       deadline: now + this.pausedMaxWaitMs,
       started: false,
       done: false,
-      stuckReported: 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`: a row already `processing` for e.g. 5 min must give up ~5 min from now
-   * (10 min after `processed_at`), not 10 min from now — otherwise its deadline
-   * lands ~15 min after `processed_at`, coinciding with the cron reset →
-   * double-drive race. `dispatchedAt` stays `now` (only the appear-guard uses it).
+   * `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
@@ -2095,7 +2648,9 @@ var ChannelDriver = class {
         inFlight: /* @__PURE__ */ new Map(),
         loop: null,
         reportedQuestions: /* @__PURE__ */ new Set(),
-        reportedPermissions: /* @__PURE__ */ new Set()
+        reportedPermissions: /* @__PURE__ */ new Set(),
+        lastGoodPollAt: this.now(),
+        hadUsablePoll: false
       };
       this.watchers.set(sessionId, watcher);
     }
@@ -2104,6 +2659,10 @@ var ChannelDriver = class {
       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,
@@ -2113,7 +2672,20 @@ var ChannelDriver = class {
       // 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
+      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
     });
   }
   /**
@@ -2164,12 +2736,30 @@ var ChannelDriver = class {
             messages = Array.isArray(body) ? body : null;
           }
         } catch {
-          continue;
         }
+        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);
+          await this.serviceInFlightMessage(
+            sessionId,
+            watcher,
+            inFlight,
+            messages,
+            openQuestions,
+            openPermissions,
+            questionsPolledOk,
+            permissionsPolledOk
+          );
         }
-        await this.pollInteractions(sessionId, watcher, messages);
       }
     } catch (err) {
       if (err instanceof ChannelAuthError) {
@@ -2191,28 +2781,55 @@ var ChannelDriver = class {
       });
     }
   }
+  /**
+   * 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) {
+  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) {
+      const title = await this.resolveSessionTitle(sessionId, watcher.conv.id);
       let claimed;
       try {
         claimed = await this.markProcessing(
           conv.id,
           inFlight.evidentMessageId,
           sessionId,
-          inFlight.opencodeMessageId
+          inFlight.opencodeMessageId,
+          title
         );
       } catch (err) {
         if (err instanceof ChannelAuthError) throw err;
         this.log({
-          level: "error",
+          level: "warn",
           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
@@ -2222,7 +2839,7 @@ var ChannelDriver = class {
       inFlight.started = true;
       if (!claimed) {
         this.log({
-          level: "info",
+          level: "debug",
           message: `Message ${inFlight.evidentMessageId.slice(0, 8)} already marked processing \u2014 continuing`,
           conversation_id: conv.id,
           message_id: inFlight.evidentMessageId
@@ -2230,6 +2847,7 @@ var ChannelDriver = class {
       }
     }
     if (state === "done") {
+      this.anchorDeliveryDeadline(inFlight);
       if (!inFlight.done) {
         this.log({
           level: "info",
@@ -2237,18 +2855,22 @@ var ChannelDriver = class {
           conversation_id: conv.id,
           message_id: inFlight.evidentMessageId
         });
+        const title = await this.resolveSessionTitle(sessionId, watcher.conv.id);
+        const usage = messageUsage(messages, inFlight.opencodeMessageId);
         try {
           await this.markDone(
             conv.id,
             inFlight.evidentMessageId,
             sessionId,
-            inFlight.opencodeMessageId
+            inFlight.opencodeMessageId,
+            title,
+            usage
           );
         } catch (err) {
           if (err instanceof ChannelAuthError) throw err;
           if (err instanceof ChannelTerminalError) {
             this.log({
-              level: "error",
+              level: "warn",
               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
@@ -2258,7 +2880,7 @@ var ChannelDriver = class {
           }
           if (this.now() >= inFlight.deadline) {
             this.log({
-              level: "error",
+              level: "warn",
               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
@@ -2267,7 +2889,7 @@ var ChannelDriver = class {
             return;
           }
           this.log({
-            level: "error",
+            level: "warn",
             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
@@ -2280,6 +2902,7 @@ var ChannelDriver = class {
       return;
     }
     if (state === "failed") {
+      this.anchorDeliveryDeadline(inFlight);
       if (!inFlight.done) {
         const error2 = messageError(messages, inFlight.opencodeMessageId) ?? void 0;
         this.log({
@@ -2288,13 +2911,14 @@ var ChannelDriver = class {
           conversation_id: conv.id,
           message_id: inFlight.evidentMessageId
         });
+        const usage = messageUsage(messages, inFlight.opencodeMessageId);
         try {
-          await this.markFailed(conv.id, inFlight.evidentMessageId, sessionId, error2);
+          await this.markFailed(conv.id, inFlight.evidentMessageId, sessionId, error2, usage);
         } catch (err) {
           if (err instanceof ChannelAuthError) throw err;
           if (err instanceof ChannelTerminalError) {
             this.log({
-              level: "error",
+              level: "warn",
               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
@@ -2304,7 +2928,7 @@ var ChannelDriver = class {
           }
           if (this.now() >= inFlight.deadline) {
             this.log({
-              level: "error",
+              level: "warn",
               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
@@ -2313,7 +2937,7 @@ var ChannelDriver = class {
             return;
           }
           this.log({
-            level: "error",
+            level: "warn",
             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
@@ -2333,9 +2957,53 @@ var ChannelDriver = class {
         stuck_for_ms: this.now() - inFlight.dispatchedAt
       });
     }
-    if (this.now() >= inFlight.deadline) {
+    const activelyRunning = state === "running" && !awaitingHuman;
+    if (activelyRunning && this.now() - inFlight.processingAnchorMs >= ABSOLUTE_MAX_PROCESSING_MS) {
       this.log({
-        level: "info",
+        level: "warn",
+        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: "debug",
         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
@@ -2346,9 +3014,7 @@ var ChannelDriver = class {
       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).
    *
@@ -2365,15 +3031,20 @@ var ChannelDriver = class {
    */
   async readoptProcessing() {
     const rows = await this.getProcessingMessages();
-    if (this.dontRedispatch.size > 0 || this.doneUndeliverable.size > 0) {
+    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]) {
+      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",
+              level: "debug",
               message: `Re-adopt: message ${id.slice(0, 8)} left the processing list (cron reset) \u2014 cleared gave-up marker`,
               message_id: id
             });
@@ -2386,7 +3057,7 @@ var ChannelDriver = class {
     for (const row of rows) {
       if (!row.opencode_session_id) {
         this.log({
-          level: "error",
+          level: "warn",
           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
@@ -2403,7 +3074,7 @@ var ChannelDriver = class {
         const res = await this.fetchImpl(`${this.opencodeBase}/session/${sessionId}/message`);
         if (!res.ok) {
           this.log({
-            level: "error",
+            level: "warn",
             message: `Re-adopt: polling session ${sessionId.slice(0, 8)} returned HTTP ${res.status} \u2014 skipping this session this tick`
           });
           continue;
@@ -2411,7 +3082,7 @@ var ChannelDriver = class {
         const body = await res.json();
         if (!Array.isArray(body)) {
           this.log({
-            level: "error",
+            level: "warn",
             message: `Re-adopt: polling session ${sessionId.slice(0, 8)} returned a non-array message body \u2014 skipping this session this tick`
           });
           continue;
@@ -2419,13 +3090,15 @@ var ChannelDriver = class {
         messages = body;
       } catch (err) {
         this.log({
-          level: "error",
+          level: "warn",
           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);
+        await this.readoptOne(sessionId, row, messages, sessionOngoing);
       }
     }
   }
@@ -2447,10 +3120,10 @@ var ChannelDriver = class {
    *
    * Only `ChannelAuthError` propagates.
    */
-  async readoptOne(sessionId, row, messages) {
+  async readoptOne(sessionId, row, messages, sessionOngoing) {
     if (this.isTracked(sessionId, row.id)) {
       this.log({
-        level: "info",
+        level: "debug",
         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
@@ -2462,7 +3135,7 @@ var ChannelDriver = class {
     if (state === "done") {
       if (this.doneUndeliverable.has(row.id)) {
         this.log({
-          level: "info",
+          level: "debug",
           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
@@ -2476,21 +3149,24 @@ var ChannelDriver = class {
         message_id: row.id
       });
       try {
-        await this.markDone(row.conversation_id, row.id, sessionId, ocId);
+        const title = await this.resolveSessionTitle(sessionId, row.conversation_id);
+        const usage = messageUsage(messages, ocId ?? "");
+        await this.markDone(row.conversation_id, row.id, sessionId, ocId, title, usage);
       } catch (err) {
         if (err instanceof ChannelAuthError) throw err;
         if (err instanceof ChannelTerminalError) {
           this.doneUndeliverable.add(row.id);
           this.log({
-            level: "error",
+            level: "warn",
             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",
+          level: "warn",
           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
@@ -2498,10 +3174,12 @@ var ChannelDriver = class {
         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;
+      const usage = messageUsage(messages, ocId ?? "");
       this.log({
         level: "error",
         message: `Re-adopt: message ${row.id.slice(0, 8)} errored while unwatched \u2014 marking failed: ${error2 ?? "(no error text)"}`,
@@ -2509,21 +3187,22 @@ var ChannelDriver = class {
         message_id: row.id
       });
       try {
-        await this.markFailed(row.conversation_id, row.id, sessionId, error2);
+        await this.markFailed(row.conversation_id, row.id, sessionId, error2, usage);
       } catch (err) {
         if (err instanceof ChannelAuthError) throw err;
         if (err instanceof ChannelTerminalError) {
           this.doneUndeliverable.add(row.id);
           this.log({
-            level: "error",
+            level: "warn",
             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",
+          level: "warn",
           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
@@ -2531,17 +3210,83 @@ var ChannelDriver = class {
         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",
+        level: "debug",
         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: "debug",
+          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: "debug",
+            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: "debug",
+          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: "debug",
+          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);
@@ -2550,11 +3295,12 @@ var ChannelDriver = class {
       this.readopted.add(row.id);
       this.ensureWatcherRunning(sessionId);
       this.log({
-        level: "info",
+        level: "debug",
         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);
@@ -2583,7 +3329,7 @@ var ChannelDriver = class {
   async forceReadoptRun(sessionId, row) {
     if (this.stopped) {
       this.log({
-        level: "info",
+        level: "debug",
         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
@@ -2592,7 +3338,7 @@ var ChannelDriver = class {
     }
     if (this.awaitingReadopt.has(row.id)) {
       this.log({
-        level: "info",
+        level: "debug",
         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
@@ -2602,11 +3348,12 @@ var ChannelDriver = class {
     if (this.processedAtMs(row) + this.pausedMaxWaitMs <= this.now()) {
       this.dontRedispatch.add(row.id);
       this.log({
-        level: "info",
+        level: "debug",
         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 = {
@@ -2620,40 +3367,44 @@ var ChannelDriver = class {
       message_id: row.id
     });
     this.awaitingReadopt.add(row.id);
+    const readoptConv = this.convForRow(sessionId, row);
+    const readoptMessage = this.queuedMessageForRow(row);
+    const sendAttachments = this.buildSendAttachments(readoptConv, readoptMessage);
     let ocId;
     try {
       ocId = await this.dispatchLocked(
         sessionId,
-        () => sendPromptAsync(this.port, sessionId, row.content, options)
+        () => sendPromptAsync(this.port, sessionId, row.content, options, sendAttachments)
       );
     } catch (err) {
       this.awaitingReadopt.delete(row.id);
       if (err instanceof ChannelAuthError) throw err;
       this.log({
-        level: "error",
+        level: "warn",
         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",
+        level: "warn",
         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.registerReadopted(readoptConv, sessionId, readoptMessage, 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");
   }
   /**
    * True if `evidentMessageId` is already being driven — either in the
@@ -2702,7 +3453,8 @@ var ChannelDriver = class {
       opencode_agent: row.opencode_agent,
       opencode_model: row.opencode_model,
       source_message_id: row.source_message_id,
-      slack_user_id: row.slack_user_id
+      slack_user_id: row.slack_user_id,
+      attachments: row.attachments ?? null
     };
   }
   /**
@@ -2723,7 +3475,7 @@ var ChannelDriver = class {
     if (this.readopted.delete(evidentMessageId) && inFlight && !inFlight.done) {
       this.dontRedispatch.add(evidentMessageId);
       this.log({
-        level: "info",
+        level: "debug",
         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
@@ -2745,21 +3497,41 @@ var ChannelDriver = class {
    * 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();
-        questions = Array.isArray(body) ? body : [];
+        if (Array.isArray(body)) {
+          questions = body;
+        } else {
+          questionsPolledOk = false;
+        }
+      } else {
+        questionsPolledOk = false;
       }
     } catch {
+      questionsPolledOk = false;
     }
     for (const q of questions) {
-      if (watcher.reportedQuestions.has(q.id)) continue;
       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",
@@ -2773,14 +3545,22 @@ var ChannelDriver = class {
       const res = await this.fetchImpl(`${this.opencodeBase}/permission`);
       if (res.ok) {
         const body = await res.json();
-        permissions = Array.isArray(body) ? body : [];
+        if (Array.isArray(body)) {
+          permissions = body;
+        } else {
+          permissionsPolledOk = false;
+        }
+      } else {
+        permissionsPolledOk = false;
       }
     } catch {
+      permissionsPolledOk = false;
     }
     for (const p of permissions) {
-      if (watcher.reportedPermissions.has(p.id)) continue;
       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",
@@ -2789,6 +3569,7 @@ var ChannelDriver = class {
       );
       if (reported) watcher.reportedPermissions.add(p.id);
     }
+    return { openQuestions, openPermissions, questionsPolledOk, permissionsPolledOk };
   }
   /**
    * True when `sessionId` is the `rootSessionId` itself OR a descendant of it —
@@ -2834,6 +3615,128 @@ var ChannelDriver = class {
     if (parent !== void 0) this.sessionParents.set(sessionId, parent);
     return parent;
   }
+  /**
+   * Resolve (and cache in `sessionTitles`) the OpenCode session TITLE (#310) so the
+   * status PATCH can carry it into the "Live sessions" list. Driver-level cache so
+   * BOTH the watcher completion path and the restart-recovery re-adopt path (which
+   * has no watcher) can use it. `conversationId` is passed only for log context.
+   * Best-effort:
+   *   - a resolved NON-EMPTY title is cached and terminal (a real session name
+   *     won't later un-name), so we do NOT re-GET `/session/:id` every tick;
+   *   - while the title is still absent/empty we do NOT latch it — OpenCode names
+   *     sessions asynchronously mid-turn, so an early call (e.g. at `processing`)
+   *     must leave the cache unresolved and re-fetch on the next need so a later
+   *     call (e.g. at `done`) picks up the name assigned in the meantime. Such a
+   *     call returns `null` (omit the title on THIS PATCH) without caching;
+   *   - a failed request likewise leaves the cache unresolved (retry next need)
+   *     and returns `null` — it must NEVER throw or block completion.
+   * A failure is logged with agent/session context (no silent catch).
+   */
+  async resolveSessionTitle(sessionId, conversationId) {
+    const cached = this.sessionTitles.get(sessionId);
+    if (cached != null) return cached;
+    try {
+      const res = await this.fetchImpl(`${this.opencodeBase}/session/${sessionId}`);
+      if (res.ok) {
+        const body = await res.json();
+        const title = body && typeof body.title === "string" ? body.title.trim() : "";
+        if (title.length > 0) {
+          this.sessionTitles.set(sessionId, title);
+          return title;
+        }
+        return null;
+      }
+      this.log({
+        level: "debug",
+        message: `Session title fetch for session ${sessionId.slice(0, 8)} (agent ${this.agentId.slice(0, 8)}) returned HTTP ${res.status} \u2014 omitting title`,
+        conversation_id: conversationId
+      });
+    } catch (err) {
+      this.log({
+        level: "debug",
+        message: `Best-effort session title fetch failed for session ${sessionId.slice(0, 8)} (agent ${this.agentId.slice(0, 8)}) \u2014 omitting title: ${err instanceof Error ? err.message : String(err)}`,
+        conversation_id: conversationId
+      });
+    }
+    return null;
+  }
+  /**
+   * 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: "warn",
+        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).
    *
@@ -2884,9 +3787,7 @@ var ChannelDriver = class {
     }
     return inFlight.sort(byOldest)[0];
   }
-  // -------------------------------------------------------------------------
   // Evident API calls (combinedAuth thread routes)
-  // -------------------------------------------------------------------------
   async getPendingConversations() {
     const res = await this.fetchImpl(
       `${this.apiUrl}/agents/${this.agentId}/conversations/pending`,
@@ -2966,7 +3867,7 @@ var ChannelDriver = class {
    * 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) {
+  async markProcessing(conversationId, messageId, sessionId, opencodeMessageId, title) {
     const res = await this.fetchImpl(
       `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
       {
@@ -2975,7 +3876,8 @@ var ChannelDriver = class {
         body: JSON.stringify({
           status: "processing",
           opencode_session_id: sessionId,
-          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {}
+          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {},
+          ...title ? { title } : {}
         })
       }
     );
@@ -3014,7 +3916,7 @@ var ChannelDriver = class {
    *                                    watcher retries next tick within the
    *                                    deadline, Finding 4).
    */
-  async markDone(conversationId, messageId, sessionId, opencodeMessageId) {
+  async markDone(conversationId, messageId, sessionId, opencodeMessageId, title, usage) {
     const res = await this.fetchImpl(
       `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
       {
@@ -3023,7 +3925,9 @@ var ChannelDriver = class {
         body: JSON.stringify({
           status: "done",
           opencode_session_id: sessionId,
-          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {}
+          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {},
+          ...title ? { title } : {},
+          ...usage ? usage : {}
         })
       }
     );
@@ -3041,10 +3945,11 @@ var ChannelDriver = class {
    * OpenCode turn sends `{status:'failed', opencode_session_id, error}` so the
    * failure reason reaches the channel.
    */
-  async markFailed(conversationId, messageId, sessionId, error2) {
+  async markFailed(conversationId, messageId, sessionId, error2, usage) {
     const body = { status: "failed" };
     if (sessionId !== void 0) body.opencode_session_id = sessionId;
     if (error2 !== void 0) body.error = error2;
+    if (usage) Object.assign(body, usage);
     await this.callWithRetry(
       "marking message as failed",
       () => this.fetchImpl(
@@ -3065,6 +3970,12 @@ var ChannelDriver = class {
    * 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 {
@@ -3078,19 +3989,22 @@ var ChannelDriver = class {
       );
       if (!res.ok) {
         this.log({
-          level: "error",
+          level: "warn",
           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",
+        level: "warn",
         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) {
@@ -3147,9 +4061,7 @@ var ChannelDriver = class {
       return false;
     }
   }
-  // -------------------------------------------------------------------------
   // Retry wrapper
-  // -------------------------------------------------------------------------
   /**
    * Invoke an Evident API call, retrying on transient failures (5xx / 429 /
    * network errors) with exponential backoff + jitter (capped). Auth failures
@@ -3348,7 +4260,7 @@ async function resolveAgentIdFromKey(authHeader) {
     if (!response.ok) {
       const serverMessage = await readErrorMessage(response);
       return {
-        error: `Failed to resolve agent from key (HTTP ${response.status})${serverMessage ? `: ${serverMessage}` : ""}`
+        error: `Failed to resolve runner from key (HTTP ${response.status})${serverMessage ? `: ${serverMessage}` : ""}`
       };
     }
     const data = await response.json();
@@ -3356,11 +4268,11 @@ async function resolveAgentIdFromKey(authHeader) {
       return { agent_id: data.agent_id };
     }
     return {
-      error: "Cannot resolve agent ID: auth type is not agent_key. Please provide --agent explicitly."
+      error: "Cannot resolve runner ID: auth type is not agent_key. Please provide --agent explicitly."
     };
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : "Unknown error";
-    return { error: `Failed to resolve agent from key: ${message}` };
+    return { error: `Failed to resolve runner from key: ${message}` };
   }
 }
 async function notifyAgentDisconnected(agentId, authHeader) {
@@ -3396,12 +4308,12 @@ async function getAgentInfo(agentId, authHeader) {
       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)."
+        error: serverMessage ?? "You do not have access to this runner (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` };
+      return { valid: false, error: serverMessage ?? `Runner ${agentId} not found` };
     }
     if (!response.ok) {
       const serverMessage = await readErrorMessage(response);
@@ -3414,13 +4326,13 @@ async function getAgentInfo(agentId, authHeader) {
     if (agent.agent_type !== "local") {
       return {
         valid: false,
-        error: `Agent is type '${agent.agent_type}', must be 'local' for CLI connection`
+        error: `Runner is type '${agent.agent_type}', must be 'local' for CLI connection`
       };
     }
     return { valid: true, agent };
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : "Unknown error";
-    return { valid: false, error: `Failed to validate agent: ${message}` };
+    return { valid: false, error: `Failed to validate runner: ${message}` };
   }
 }
 
@@ -3429,23 +4341,53 @@ var MAX_ACTIVITY_LOG_ENTRIES = 10;
 var CHANNEL_POLL_INTERVAL_MS = Number(process.env.EVIDENT_CHANNEL_POLL_INTERVAL_MS) || 2e3;
 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) {
+function resolveLogLevel(options) {
+  const accepted = Object.keys(LOG_LEVELS);
+  const validate = (value, source) => {
+    const normalized = value.trim().toLowerCase();
+    if (!accepted.includes(normalized)) {
+      throw new Error(
+        `Invalid log level "${value}"${source}; expected one of ${accepted.join(", ")}`
+      );
+    }
+    return normalized;
+  };
+  if (options.logLevel !== void 0) {
+    return validate(options.logLevel, " (--log-level)");
+  }
+  if (options.verbose) {
+    return "debug";
+  }
+  const env = process.env.EVIDENT_LOG_LEVEL;
+  if (env !== void 0 && env !== "") {
+    return validate(env, " (EVIDENT_LOG_LEVEL)");
+  }
+  return "info";
+}
+function meetsThreshold(state, level) {
+  return LOG_LEVELS[level] >= LOG_LEVELS[state.logLevel];
+}
+function log2(state, message, level = "info") {
+  if (!meetsThreshold(state, level)) return;
   if (state.json) {
     console.log(
       JSON.stringify({
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        level: isError ? "error" : "info",
+        level,
         message
       })
     );
   } else if (!state.interactive) {
-    const prefix = isError ? chalk6.red("\u2717") : chalk6.green("\u2022");
+    const prefix = level === "error" ? chalk6.red("\u2717") : level === "warn" ? chalk6.yellow("!") : level === "debug" ? chalk6.dim("\xB7") : chalk6.green("\u2022");
     console.log(`${prefix} ${message}`);
   }
 }
 function logActivity(state, entry) {
+  const level = entry.level ?? (entry.type === "error" ? "error" : "info");
+  if (!meetsThreshold(state, level)) return;
   const fullEntry = {
     ...entry,
+    level,
     timestamp: /* @__PURE__ */ new Date()
   };
   state.activityLog.push(fullEntry);
@@ -3454,9 +4396,9 @@ function logActivity(state, entry) {
   }
   if (!state.interactive) {
     if (entry.type === "error") {
-      log2(state, entry.error ?? "Unknown error", true);
-    } else if (entry.type === "info" && entry.message) {
-      log2(state, entry.message);
+      log2(state, entry.error ?? "Unknown error", level);
+    } else if (entry.message) {
+      log2(state, entry.message, level);
     }
   }
 }
@@ -3583,7 +4525,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) {
@@ -3594,6 +4536,81 @@ async function driveChannels(state, driver) {
     }
   }
 }
+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", level: "warn", 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) {
@@ -3602,7 +4619,7 @@ async function notifyOffline(state) {
   }
   const result = await notifyAgentDisconnected(state.agentId, state.authHeader);
   if (result.ok) {
-    log2(state, "Notified Evident the agent is going offline");
+    log2(state, "Notified Evident the runner is going offline");
   } else {
     logActivity(state, {
       type: "error",
@@ -3613,6 +4630,11 @@ async function notifyOffline(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...");
@@ -3647,6 +4669,20 @@ async function cleanup(state, opts = {}) {
 }
 async function run(options) {
   const interactive = isInteractive(options.json);
+  let logLevel;
+  try {
+    logLevel = resolveLogLevel(options);
+  } catch (error2) {
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    if (options.json) {
+      console.log(JSON.stringify({ status: "error", error: message }));
+    } else {
+      printError(message);
+    }
+    await shutdownTelemetry();
+    process.exit(1);
+    return;
+  }
   const state = {
     agentId: options.agent || "",
     agentName: null,
@@ -3655,6 +4691,7 @@ async function run(options) {
     idleTimeout: options.idleTimeout ?? null,
     json: options.json ?? false,
     interactive,
+    logLevel,
     connected: false,
     opencodeConnected: false,
     opencodeVersion: null,
@@ -3666,13 +4703,14 @@ async function run(options) {
     activityLog: [],
     messageCount: 0,
     lastProxiedActivityAt: null,
+    sessionCleanupTimers: [],
     authHeader: ""
   };
   if (state.idleTimeout === null && (process.env.GITHUB_ACTIONS || process.env.CI)) {
     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
+      "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.",
+      "warn"
     );
   }
   const handleSignal = async () => {
@@ -3715,15 +4753,15 @@ async function run(options) {
         const resolved = await resolveAgentIdFromKey(state.authHeader);
         if (resolved.agent_id) {
           state.agentId = resolved.agent_id;
-          log2(state, `Resolved agent ID from key: ${state.agentId}`);
+          log2(state, `Resolved runner ID from key: ${state.agentId}`);
           if (state.interactive && !state.json) {
             logActivity(state, {
               type: "info",
-              message: `Agent ID resolved from key: ${state.agentId}`
+              message: `Runner ID resolved from key: ${state.agentId}`
             });
           }
         } else {
-          printError(resolved.error || "Failed to resolve agent ID from key");
+          printError(resolved.error || "Failed to resolve runner ID from key");
           process.exit(1);
         }
       } else {
@@ -3751,7 +4789,7 @@ async function run(options) {
       console.log(chalk6.bold("Evident Run"));
       console.log(chalk6.dim("-".repeat(40)));
     }
-    const spinner = interactive && !state.json ? ora3("Validating agent...").start() : null;
+    const spinner = interactive && !state.json ? ora3("Validating runner...").start() : null;
     let validation = await getAgentInfo(state.agentId, state.authHeader);
     if (!validation.valid && validation.authFailed && interactive) {
       spinner?.fail("Authentication failed");
@@ -3763,14 +4801,14 @@ async function run(options) {
         "Login successful! Retrying..."
       );
       state.authHeader = getAuthHeader(credentials2);
-      spinner?.start("Validating agent...");
+      spinner?.start("Validating runner...");
       validation = await getAgentInfo(state.agentId, state.authHeader);
     }
     if (!validation.valid) {
-      spinner?.fail(`Agent validation failed: ${validation.error}`);
+      spinner?.fail(`Runner validation failed: ${validation.error}`);
       throw new Error(validation.error);
     }
-    spinner?.succeed(`Agent: ${validation.agent.name || state.agentId}`);
+    spinner?.succeed(`Runner: ${validation.agent.name || state.agentId}`);
     state.agentName = validation.agent.name;
     const ocSpinner = interactive && !state.json ? ora3("Checking OpenCode...").start() : null;
     try {
@@ -3788,9 +4826,9 @@ async function run(options) {
       ocSpinner?.succeed(`OpenCode running on port ${state.port}${version2}`);
       const versionWarning = buildOpenCodeVersionWarning(state.opencodeVersion);
       if (versionWarning) {
-        log2(state, versionWarning, false);
+        log2(state, versionWarning, "warn");
         if (state.interactive && !state.json) {
-          logActivity(state, { type: "info", message: versionWarning });
+          logActivity(state, { type: "info", level: "warn", message: versionWarning });
         }
       }
     } catch (error2) {
@@ -3805,11 +4843,17 @@ async function run(options) {
       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
-      })
+      log: (entry) => (
+        // Thread the driver's real level straight through so `debug`/`warn`
+        // survive the sink filter (they no longer collapse to info). `type`
+        // stays the coarse error/non-error split the activity log renders with.
+        logActivity(state, {
+          type: entry.level === "error" ? "error" : "info",
+          level: entry.level,
+          message: entry.message,
+          error: entry.level === "error" ? entry.message : void 0
+        })
+      )
     });
     state.channelDriver = channelDriver;
     const connection = new RunnerConnection({
@@ -3823,7 +4867,7 @@ async function run(options) {
           state.agentId = agentId;
           logActivity(state, {
             type: "info",
-            message: `Tunnel ${isReconnect ? "reconnected" : "connected"} (agent: ${agentId})`
+            message: `Tunnel ${isReconnect ? "reconnected" : "connected"} (runner: ${agentId})`
           });
           emitAgentConnected(state.agentId, {
             port: state.port,
@@ -3908,6 +4952,7 @@ async function run(options) {
       if (error2.message === "Unauthorized") tunnelSpinner?.fail("Unauthorized");
       throw error2;
     }
+    scheduleSessionCleanup(state, channelDriver, options);
     if (!interactive || state.json) {
       log2(state, "Driving channel messages...");
     }
@@ -3962,15 +5007,34 @@ 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 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]", "Runner ID to connect to (optional when EVIDENT_AGENT_KEY is set)").option("-p, --port <port>", "OpenCode port (default: 4096)", "4096").option(
+  "--log-level <level>",
+  "Log verbosity: debug | info | warn | error (default: info). Env: EVIDENT_LOG_LEVEL"
+).option("-v, --verbose", "Alias for --log-level debug (ignored if --log-level is set)").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,
       port: parseInt(options.port, 10),
+      // Raw string — validation/precedence is single-sourced in run.ts's
+      // resolveLogLevel (flag > -v > EVIDENT_LOG_LEVEL > info).
+      logLevel: options.logLevel,
       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
     });
   }
 );