@evident-ai/cli 3.0.1-dev.ff1c4ac → 3.1.0

package/dist/index.js

@@ -11,8 +11,8 @@ import chalk2 from "chalk";
 
 // src/lib/config.ts
 import Conf from "conf";
-import { homedir } from "os";
-import { join } from "path";
+import { chmodSync, existsSync, statSync } from "fs";
+import { dirname } from "path";
 var PRODUCTION_API_URL = "https://api.production.evident.run/v1";
 var PRODUCTION_TUNNEL_URL = "wss://tunnel.production.evident.run";
 var defaults = {
@@ -47,8 +47,35 @@ var credentials = new Conf({
   projectName: "evident",
   projectSuffix: "",
   configName: "credentials",
-  defaults: {}
+  defaults: {},
+  configFileMode: 384
 });
+var CREDENTIALS_FILE_MODE = 384;
+var CREDENTIALS_DIR_MODE = 448;
+var permissionWarningEmitted = false;
+function hardenCredentialsPermissions() {
+  if (process.platform === "win32") {
+    return;
+  }
+  const file = credentials.path;
+  for (const [path, mode] of [
+    [file, CREDENTIALS_FILE_MODE],
+    [dirname(file), CREDENTIALS_DIR_MODE]
+  ]) {
+    try {
+      if (existsSync(path) && (statSync(path).mode & 511) !== mode) {
+        chmodSync(path, mode);
+      }
+    } catch (err) {
+      if (!permissionWarningEmitted) {
+        permissionWarningEmitted = true;
+        console.error(
+          `[config] could not restrict permissions on ${path}; the credentials file may be readable by other users on this machine: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+}
 function getApiUrlConfig() {
   return getApiUrl();
 }
@@ -59,6 +86,7 @@ function credentialsKey() {
   return getApiUrl();
 }
 function getCredentials() {
+  hardenCredentialsPermissions();
   const byEndpoint = credentials.get("byEndpoint") ?? {};
   return byEndpoint[credentialsKey()] ?? {};
 }
@@ -70,14 +98,17 @@ function setCredentials(creds) {
     expiresAt: creds.expiresAt
   };
   credentials.set("byEndpoint", byEndpoint);
+  hardenCredentialsPermissions();
 }
 function clearCredentials() {
   const byEndpoint = credentials.get("byEndpoint") ?? {};
   delete byEndpoint[credentialsKey()];
   credentials.set("byEndpoint", byEndpoint);
+  hardenCredentialsPermissions();
 }
 function clearAllCredentials() {
   credentials.clear();
+  hardenCredentialsPermissions();
 }
 function getCliName() {
   const argv1 = process.argv[1] || "";
@@ -285,14 +316,14 @@ function blank() {
   console.log();
 }
 function waitForEnter(prompt = "Press Enter to continue...") {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     process.stdout.write(chalk.dim(prompt));
     const handler = () => {
       process.stdin.removeListener("data", handler);
       process.stdin.setRawMode?.(false);
       process.stdin.pause();
       console.log();
-      resolve2();
+      resolve3();
     };
     if (process.stdin.isTTY) {
       process.stdin.setRawMode?.(true);
@@ -302,7 +333,7 @@ function waitForEnter(prompt = "Press Enter to continue...") {
   });
 }
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 
 // src/commands/login.ts
@@ -373,22 +404,23 @@ async function deviceFlowLogin(options) {
 }
 async function tokenLogin() {
   console.log("Token login mode.");
-  console.log("Visit your Evident dashboard to generate a CLI token.");
+  console.log("Run `evident login` on a machine with a browser to get a token.");
+  console.log("Manage or revoke existing tokens under Settings \u2192 CLI tokens.");
   blank();
   process.stdout.write("Paste token: ");
-  const token = await new Promise((resolve2) => {
+  const token = await new Promise((resolve3) => {
     let data = "";
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
     process.stdin.on("end", () => {
-      resolve2(data.trim());
+      resolve3(data.trim());
     });
     if (process.stdin.isTTY) {
       process.stdin.once("data", (chunk) => {
         process.stdin.pause();
-        resolve2(chunk.toString().trim());
+        resolve3(chunk.toString().trim());
       });
       process.stdin.resume();
     }
@@ -467,9 +499,9 @@ async function whoami() {
 }
 
 // src/commands/run.ts
+import { homedir as homedir2 } from "os";
+import { isAbsolute as isAbsolute2, join as join2, parse, resolve as resolvePath } from "path";
 import chalk6 from "chalk";
-import ora3 from "ora";
-import { select as select3 } from "@inquirer/prompts";
 
 // ../../packages/types/src/telemetry/index.ts
 var TelemetryEventTypes = {
@@ -485,6 +517,10 @@ var TelemetryEventTypes = {
 var MAX_FRAME_BYTES = 256 * 1024;
 var TUNNEL_DRAIN_PING_PATH = "/__evident/drain";
 
+// ../../packages/types/src/runner-files.ts
+var MAX_FILE_PUSH_BYTES = 64 * 1024;
+var MAX_FILE_SYNC_DIRECTORIES = 16;
+
 // ../../packages/types/src/logging/index.ts
 var CORRELATION_ID_HEADER = "x-evident-correlation-id";
 function log(level, event, fields) {
@@ -499,6 +535,12 @@ function log(level, event, fields) {
     );
   }
 }
+function errorFields(err) {
+  if (err instanceof Error) {
+    return { error: err.message, error_name: err.name };
+  }
+  return { error: String(err) };
+}
 function stripQuery(url) {
   try {
     return new URL(url).pathname;
@@ -508,6 +550,10 @@ function stripQuery(url) {
   }
 }
 
+// src/commands/run.ts
+import ora3 from "ora";
+import { select as select3 } from "@inquirer/prompts";
+
 // src/lib/telemetry.ts
 var CLI_VERSION = (true ? "3.0.0" : void 0) ?? process.env.npm_package_version ?? "unknown";
 function getCliVersion() {
@@ -645,14 +691,27 @@ var EventTypes = {
   // CLI lifecycle
   CLI_STARTED: "cli.started",
   CLI_COMMAND: "cli.command",
-  CLI_ERROR: "cli.error"
+  CLI_ERROR: "cli.error",
+  // Deprecation telemetry (#412) — usage of the old `--agent`/`EVIDENT_AGENT_KEY`
+  // names instead of the preferred `--runner`/`EVIDENT_RUNNER_KEY` (#409).
+  DEPRECATED_AGENT_FLAG_USED: "cli.deprecated_agent_flag_used",
+  DEPRECATED_AGENT_KEY_ENV_USED: "cli.deprecated_agent_key_env_used"
 };
 
 // src/lib/auth.ts
 async function getAuthCredentials() {
+  const runnerKey = process.env.EVIDENT_RUNNER_KEY;
   const agentKey = process.env.EVIDENT_AGENT_KEY;
+  if (runnerKey) {
+    return {
+      token: runnerKey,
+      authType: "agent_key",
+      keySource: "runner_key",
+      notice: agentKey ? "Both EVIDENT_RUNNER_KEY and EVIDENT_AGENT_KEY are set; using EVIDENT_RUNNER_KEY." : void 0
+    };
+  }
   if (agentKey) {
-    return { token: agentKey, authType: "agent_key" };
+    return { token: agentKey, authType: "agent_key", keySource: "agent_key" };
   }
   const userToken = process.env.EVIDENT_TOKEN;
   if (userToken) {
@@ -706,7 +765,7 @@ async function waitForOpenCodeHealth(port, timeoutMs = 3e4) {
     if (health.healthy) {
       return health;
     }
-    await new Promise((resolve2) => setTimeout(resolve2, 1e3));
+    await new Promise((resolve3) => setTimeout(resolve3, 1e3));
   }
   return { healthy: false, error: "Timeout waiting for OpenCode to be healthy" };
 }
@@ -721,7 +780,7 @@ function buildOpenCodeVersionWarning(version2) {
   if (isQueueValidatedVersion(version2)) return null;
   const detected = version2 ? `v${version2}` : "unknown";
   const validated = QUEUE_VALIDATED_OPENCODE_VERSIONS.map((v) => `v${v}`).join(", ");
-  return `Warning: opencode ${detected} is not a queue-validated version (validated: ${validated}). Native message queuing \u2014 which channel (Slack/WhatsApp) message handling relies on \u2014 is unverified on this version; queued/follow-up messages may behave unexpectedly. Continuing anyway. Bumping the validated set requires re-running the queue validation.`;
+  return `Warning: opencode ${detected} is not a queue-validated version (validated: ${validated}). Native message queuing \u2014 which channel (Slack) message handling relies on \u2014 is unverified on this version; queued/follow-up messages may behave unexpectedly. Continuing anyway. Bumping the validated set requires re-running the queue validation.`;
 }
 
 // src/lib/opencode/process.ts
@@ -1013,6 +1072,12 @@ async function promptOpenCodeInstall(interactive) {
   return action;
 }
 
+// src/lib/opencode/provider-check.ts
+function buildNoProviderWarning(hasProvider) {
+  if (hasProvider !== false) return null;
+  return "Warning: opencode has no authenticated model provider configured, so it won't be able to answer prompts. Run `opencode auth login` to set one up (see https://opencode.ai for details).";
+}
+
 // src/lib/opencode/session.ts
 function opencodeBase(port) {
   return `http://127.0.0.1:${port}`;
@@ -1173,17 +1238,128 @@ 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;
+    if (entry.capabilities && typeof entry.capabilities === "object") {
+      if (typeof entry.capabilities.attachment === "boolean") {
+        return entry.capabilities.attachment;
+      }
+    }
+    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 && typeof dataUrl === "object") {
+      outcomes.push({
+        index: a.index,
+        mime: a.mime,
+        filename: a.filename,
+        status: "failed",
+        reason: "needs_reauth"
+      });
+      continue;
+    }
+    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;
@@ -1222,10 +1398,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((resolve2) => setTimeout(resolve2, READ_BACK_DELAY_MS));
+      await new Promise((resolve3) => setTimeout(resolve3, READ_BACK_DELAY_MS));
     }
   }
   return null;
@@ -1271,6 +1450,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);
@@ -1287,6 +1532,9 @@ function isPreamblePinnedRunning(messages, userMessageId) {
   const reply = findLastAssistantReplyFor(messages, userMessageId);
   return completedOf(reply) != null && finishOf(reply) === "tool-calls";
 }
+function isB2AbandonmentConfirmed(params) {
+  return params.pinnedForMs >= params.minPinnedMs && params.descendantOngoing === false;
+}
 function messageError(messages, userMessageId) {
   const reply = findLastAssistantReplyFor(messages, userMessageId);
   const error2 = errorOf(reply);
@@ -1306,6 +1554,37 @@ function hasRunningAssistantExcept(messages, exceptUserMessageId) {
     (m) => roleOf(m) === "assistant" && parentIdOf(m) !== exceptUserMessageId && isAssistantInFlight(m)
   );
 }
+async function hasAnyConfiguredProvider(port) {
+  try {
+    const res = await fetch(`${opencodeBase(port)}/config/providers`);
+    if (!res.ok) {
+      console.error(
+        `[hasAnyConfiguredProvider] GET /config/providers returned HTTP ${res.status} (port ${port})`
+      );
+      return null;
+    }
+    const body = await res.json();
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+      console.error(
+        `[hasAnyConfiguredProvider] GET /config/providers body was not a plain object (port ${port})`
+      );
+      return null;
+    }
+    const defaults2 = body.default;
+    if (!defaults2 || typeof defaults2 !== "object" || Array.isArray(defaults2)) {
+      console.error(
+        `[hasAnyConfiguredProvider] GET /config/providers body had no \`default\` object (port ${port})`
+      );
+      return null;
+    }
+    return Object.keys(defaults2).length > 0;
+  } catch (err) {
+    console.error(
+      `[hasAnyConfiguredProvider] GET /config/providers failed (port ${port}): ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
+  }
+}
 
 // src/lib/opencode/session-cleanup.ts
 var DURATION_UNIT_MS = {
@@ -1464,10 +1743,11 @@ var StreamForwarder = class {
    * Abort every in-flight stream (e.g. on WebSocket close).
    */
   abortAll() {
-    for (const stream of this.inflight.values()) {
+    for (const [sid, stream] of this.inflight.entries()) {
       try {
         stream.abort();
-      } catch {
+      } catch (err) {
+        log("error", "forwarder_abort_failed", { sid, ...errorFields(err) });
       }
     }
     this.inflight.clear();
@@ -1501,12 +1781,12 @@ var StreamForwarder = class {
     let endBody;
     if (has_body) {
       const chunks = [];
-      bodyPromise = new Promise((resolve2) => {
+      bodyPromise = new Promise((resolve3) => {
         pushBody = (buf) => {
           chunks.push(buf);
         };
         endBody = () => {
-          resolve2(Buffer.concat(chunks));
+          resolve3(Buffer.concat(chunks));
         };
       });
     }
@@ -1617,31 +1897,20 @@ function connectTunnel(options) {
     onConnected,
     onDisconnected,
     onError,
-    onRequest,
     onResponse,
     onInfo,
     onDrainPing
   } = options;
   const tunnelUrl = getTunnelUrlConfig();
   const url = `${tunnelUrl}/tunnel/${agentId}/connect`;
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const ws = new WebSocket2(url, {
       headers: {
         Authorization: authHeader
       }
     });
-    const streamStartTimes = /* @__PURE__ */ new Map();
     const forwarder = new StreamForwarder(ws, port, {
-      onOpen: (sid, method, path) => {
-        if (path === TUNNEL_DRAIN_PING_PATH) return;
-        streamStartTimes.set(sid, Date.now());
-        onRequest?.(method, path, sid);
-      },
-      onHead: (sid, status) => {
-        const startedAt = streamStartTimes.get(sid);
-        streamStartTimes.delete(sid);
-        onResponse?.(status, startedAt ? Date.now() - startedAt : 0, sid);
-      },
+      onHead: () => onResponse?.(),
       onDrainPing: () => onDrainPing?.()
     });
     const connectionTimeout = setTimeout(() => {
@@ -1689,7 +1958,7 @@ function connectTunnel(options) {
           clearTimeout(connectionTimeout);
           const connectedAgentId = message.agent_id ?? agentId;
           onConnected?.(connectedAgentId);
-          resolve2({
+          resolve3({
             ws,
             close: () => ws.close(1e3, "CLI shutdown")
           });
@@ -1717,7 +1986,6 @@ function connectTunnel(options) {
     ws.on("close", (code, reason) => {
       const reasonStr = reason.toString() || upgradeRejection || (code === 1006 ? "abnormal closure" : "No reason provided");
       forwarder.abortAll();
-      streamStartTimes.clear();
       onDisconnected?.(code, reasonStr);
     });
   });
@@ -1752,7 +2020,11 @@ var RunnerConnection = class {
     if (this.connection) {
       try {
         this.connection.close();
-      } catch {
+      } catch (err) {
+        log("error", "runner_connection_close_failed", {
+          agent_id: this.resolvedAgentId,
+          ...errorFields(err)
+        });
       }
       this.connection = null;
     }
@@ -1804,6 +2076,404 @@ var RunnerConnection = class {
   }
 };
 
+// src/lib/channels/driver.ts
+import { homedir } from "os";
+
+// src/lib/file-push.ts
+import { randomUUID } from "crypto";
+import { chmod, mkdir, open as open2, realpath, rename, unlink } from "fs/promises";
+import { basename, dirname as dirname2, isAbsolute, join, relative, resolve as resolve2, sep } from "path";
+var FILE_MODE = 384;
+var DIRECTORY_MODE = 448;
+async function writePushedFile(request) {
+  const { requestedPath, content, allowedDirectories, homeDir } = request;
+  const bytes = content.byteLength;
+  if (allowedDirectories.length === 0) {
+    return refuse("file_sync_disabled", "File sync is not enabled on this runner.", {
+      path: requestedPath,
+      bytes
+    });
+  }
+  if (bytes > MAX_FILE_PUSH_BYTES) {
+    return refuse(
+      "file_too_large",
+      `File is ${bytes} bytes; the limit is ${MAX_FILE_PUSH_BYTES}.`,
+      {
+        path: requestedPath,
+        bytes
+      }
+    );
+  }
+  const candidate = expandAndValidate(requestedPath, homeDir);
+  if (candidate === null) {
+    return refuse("invalid_path", "The requested path is not a valid absolute file path.", {
+      path: requestedPath,
+      bytes
+    });
+  }
+  try {
+    const { existingAncestor, missingSegments } = await resolveNearestExistingAncestor(
+      dirname2(candidate)
+    );
+    const realTarget = join(existingAncestor, ...missingSegments, basename(candidate));
+    const allowedDirectory = await findContainingAllowedDirectory(allowedDirectories, realTarget);
+    if (allowedDirectory === null) {
+      return refuse("path_not_allowed", "The runner does not allow writing to that location.", {
+        path: realTarget,
+        bytes
+      });
+    }
+    if (missingSegments.length > 0) {
+      await createMissingDirectories(existingAncestor, missingSegments);
+      const realParent = await realpath(dirname2(realTarget));
+      if (realParent !== dirname2(realTarget) || !contains(allowedDirectory, realTarget)) {
+        return refuse("path_not_allowed", "The runner does not allow writing to that location.", {
+          path: realTarget,
+          bytes,
+          reason: "parent_changed_after_create"
+        });
+      }
+    }
+    await writeAtomically(realTarget, content);
+    log("info", "file_push_written", { path: realTarget, bytes });
+    return { ok: true, path: realTarget };
+  } catch (err) {
+    const errno = err.code ?? "UNKNOWN";
+    return refuse("write_failed", `The runner could not write the file (${errno}).`, {
+      path: candidate,
+      bytes,
+      errno,
+      ...errorFields(err)
+    });
+  }
+}
+function expandAndValidate(requestedPath, homeDir) {
+  if (requestedPath.trim() === "" || requestedPath.includes("\0")) {
+    return null;
+  }
+  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join(homeDir, requestedPath.slice(2)) : requestedPath;
+  if (expanded.split(/[/\\]/).includes("..")) {
+    return null;
+  }
+  if (!isAbsolute(expanded)) {
+    return null;
+  }
+  const candidate = resolve2(expanded);
+  const name = basename(candidate);
+  return name === "" || name === "." || name === ".." ? null : candidate;
+}
+async function resolveNearestExistingAncestor(directory) {
+  const missingSegments = [];
+  let current = directory;
+  for (; ; ) {
+    try {
+      return { existingAncestor: await realpath(current), missingSegments };
+    } catch (err) {
+      const parent = dirname2(current);
+      if (err.code !== "ENOENT" || parent === current) {
+        throw err;
+      }
+      missingSegments.unshift(basename(current));
+      current = parent;
+    }
+  }
+}
+async function findContainingAllowedDirectory(allowedDirectories, realTarget) {
+  for (const directory of allowedDirectories) {
+    if (!isAbsolute(directory)) {
+      log("warn", "file_push_allowed_directory_skipped", { directory, reason: "not_absolute" });
+      continue;
+    }
+    const realDirectory = await realpathCreatingIfMissing(directory);
+    if (realDirectory !== null && contains(realDirectory, realTarget)) {
+      return realDirectory;
+    }
+  }
+  return null;
+}
+async function realpathCreatingIfMissing(directory) {
+  try {
+    return await realpath(directory);
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      log("warn", "file_push_allowed_directory_skipped", {
+        directory,
+        reason: "unresolvable",
+        ...errorFields(err)
+      });
+      return null;
+    }
+  }
+  try {
+    await mkdir(directory, { recursive: true, mode: DIRECTORY_MODE });
+    await chmod(directory, DIRECTORY_MODE);
+    return await realpath(directory);
+  } catch (err) {
+    log("warn", "file_push_allowed_directory_skipped", {
+      directory,
+      reason: "create_failed",
+      ...errorFields(err)
+    });
+    return null;
+  }
+}
+function contains(realDirectory, realTarget) {
+  const rel = relative(realDirectory, realTarget);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+async function createMissingDirectories(existingAncestor, missingSegments) {
+  let current = existingAncestor;
+  for (const segment of missingSegments) {
+    current = join(current, segment);
+    await mkdir(current, { recursive: true, mode: DIRECTORY_MODE });
+    await chmod(current, DIRECTORY_MODE);
+  }
+}
+async function writeAtomically(realTarget, content) {
+  const temporaryPath = join(dirname2(realTarget), `.evident-push-${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await open2(temporaryPath, "wx", FILE_MODE);
+    await handle.writeFile(content);
+    await handle.chmod(FILE_MODE);
+    await handle.close();
+    handle = void 0;
+    await rename(temporaryPath, realTarget);
+  } catch (err) {
+    await discardTemporaryFile(temporaryPath, handle);
+    throw err;
+  }
+}
+async function discardTemporaryFile(temporaryPath, handle) {
+  try {
+    await handle?.close();
+  } catch (err) {
+    log("warn", "file_push_temp_close_failed", { path: temporaryPath, ...errorFields(err) });
+  }
+  try {
+    await unlink(temporaryPath);
+  } catch (err) {
+    const errno = err.code;
+    if (errno !== "ENOENT" && errno !== "ENOTDIR") {
+      log("warn", "file_push_temp_cleanup_failed", { path: temporaryPath, ...errorFields(err) });
+    }
+  }
+}
+function refuse(code, message, fields) {
+  log(code === "write_failed" ? "error" : "warn", "file_push_refused", { code, ...fields });
+  return { ok: false, code, message };
+}
+
+// src/lib/runner-file-sync.ts
+var MAX_ACK_ATTEMPTS = 5;
+async function syncPendingRunnerFiles(options) {
+  const pending = await listPendingFiles(options);
+  const pendingIds = new Set(pending.map((file) => file.id));
+  for (const id of options.ackFailures.keys()) {
+    if (!pendingIds.has(id)) options.ackFailures.delete(id);
+  }
+  if (pending.length === 0) return 0;
+  options.log({
+    level: "info",
+    message: `Runner file sync: ${pending.length} file(s) queued for this runner`
+  });
+  let applied = 0;
+  for (const file of pending) {
+    if ((options.ackFailures.get(file.id) ?? 0) >= MAX_ACK_ATTEMPTS) continue;
+    if (await applyOne(options, file)) applied += 1;
+  }
+  return applied;
+}
+async function listPendingFiles(options) {
+  let res;
+  try {
+    res = await options.fetchImpl(`${options.apiUrl}/runners/${options.agentId}/files/pending`, {
+      headers: { Authorization: options.getAuthHeader() }
+    });
+  } catch (err) {
+    options.log({
+      level: "warn",
+      message: `Could not list pending runner files \u2014 retrying on the next drain: ${describe(err)}`
+    });
+    return [];
+  }
+  if (!res.ok) {
+    options.log({
+      level: res.status === 404 ? "debug" : "warn",
+      message: `Listing pending runner files returned HTTP ${res.status} \u2014 retrying on the next drain`
+    });
+    return [];
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch (err) {
+    options.log({
+      level: "warn",
+      message: `Pending runner file list was not readable JSON \u2014 retrying on the next drain: ${describe(err)}`
+    });
+    return [];
+  }
+  if (!Array.isArray(body)) {
+    options.log({
+      level: "warn",
+      message: "Pending runner file list was not an array \u2014 ignoring it for this drain"
+    });
+    return [];
+  }
+  const files = [];
+  for (const entry of body) {
+    const file = asPendingFile(entry);
+    if (file === null) {
+      options.log({
+        level: "warn",
+        message: "Ignoring a malformed pending runner file entry (expected id, path and size)"
+      });
+      continue;
+    }
+    files.push(file);
+  }
+  return files;
+}
+function asPendingFile(entry) {
+  if (entry === null || typeof entry !== "object") return null;
+  const { id, path, size } = entry;
+  if (typeof id !== "string" || id === "") return null;
+  if (typeof path !== "string" || path === "") return null;
+  if (typeof size !== "number" || !Number.isFinite(size) || size < 0) return null;
+  return { id, path, size };
+}
+async function applyOne(options, file) {
+  const label = `${file.id.slice(0, 8)} (${file.path})`;
+  if (options.allowedDirectories.length === 0) {
+    options.log({
+      level: "warn",
+      message: `Runner file ${label} rejected: file sync is not enabled on this runner (start it with --enable-file-sync-to)`
+    });
+    await ack(options, file, "rejected", "file_sync_disabled");
+    return false;
+  }
+  if (file.size > MAX_FILE_PUSH_BYTES) {
+    options.log({
+      level: "warn",
+      message: `Runner file ${label} rejected: declared ${file.size} bytes, the limit is ${MAX_FILE_PUSH_BYTES}`
+    });
+    await ack(options, file, "rejected", "file_too_large");
+    return false;
+  }
+  const download = await downloadContent(options, file, label);
+  if (!download.ok) {
+    if (download.terminal) await ack(options, file, "rejected", download.code);
+    return false;
+  }
+  let outcome;
+  try {
+    outcome = await writePushedFile({
+      requestedPath: file.path,
+      content: download.content,
+      allowedDirectories: options.allowedDirectories,
+      homeDir: options.homeDir
+    });
+  } catch (err) {
+    options.log({
+      level: "error",
+      message: `Runner file ${label} could not be written: ${describe(err)}`
+    });
+    await ack(options, file, "rejected", "write_failed");
+    return false;
+  }
+  if (!outcome.ok) {
+    options.log({
+      level: "warn",
+      message: `Runner file ${label} rejected (${outcome.code}): ${outcome.message}`
+    });
+    await ack(options, file, "rejected", outcome.code);
+    return false;
+  }
+  options.log({
+    level: "info",
+    message: `Runner file ${label} applied (${download.content.byteLength} bytes)`
+  });
+  await ack(options, file, "applied");
+  return true;
+}
+function durableDownloadCode(status) {
+  return status === 413 ? "file_too_large" : "write_failed";
+}
+async function downloadContent(options, file, label) {
+  try {
+    const res = await options.fetchImpl(
+      `${options.apiUrl}/runners/${options.agentId}/files/${file.id}/content`,
+      { headers: { Authorization: options.getAuthHeader() } }
+    );
+    if (!res.ok) {
+      const terminal = res.status >= 400 && res.status < 500 && res.status !== 401 && res.status !== 403 && res.status !== 408 && res.status !== 429;
+      if (!terminal) {
+        options.log({
+          level: "warn",
+          message: `Downloading runner file ${label} returned HTTP ${res.status} \u2014 retrying on the next drain`
+        });
+        return { ok: false, terminal: false };
+      }
+      const code = durableDownloadCode(res.status);
+      options.log({
+        level: "error",
+        message: `Downloading runner file ${label} returned HTTP ${res.status} \u2014 rejecting it as ${code} (the bytes never reached the writer)`
+      });
+      return { ok: false, terminal: true, code };
+    }
+    return { ok: true, content: Buffer.from(await res.arrayBuffer()) };
+  } catch (err) {
+    options.log({
+      level: "warn",
+      message: `Downloading runner file ${label} failed \u2014 retrying on the next drain: ${describe(err)}`
+    });
+    return { ok: false, terminal: false };
+  }
+}
+async function ack(options, file, status, reason) {
+  const outcome = `${status}${reason ? ` (${reason})` : ""}`;
+  try {
+    const res = await options.fetchImpl(
+      `${options.apiUrl}/runners/${options.agentId}/files/${file.id}/ack`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: options.getAuthHeader(),
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(reason ? { status, reason } : { status })
+      }
+    );
+    if (!res.ok) {
+      recordAckFailure(
+        options,
+        file,
+        `Acking runner file ${file.id.slice(0, 8)} as ${outcome} returned HTTP ${res.status}`
+      );
+      return;
+    }
+    options.ackFailures.delete(file.id);
+  } catch (err) {
+    recordAckFailure(
+      options,
+      file,
+      `Acking runner file ${file.id.slice(0, 8)} as ${outcome} failed: ${describe(err)}`
+    );
+  }
+}
+function recordAckFailure(options, file, what) {
+  const attempts = (options.ackFailures.get(file.id) ?? 0) + 1;
+  options.ackFailures.set(file.id, attempts);
+  options.log({
+    level: "error",
+    message: attempts >= MAX_ACK_ATTEMPTS ? `${what} \u2014 giving up after ${attempts} attempts. It stays pending until the server expires it; restart the runner to retry.` : `${what} \u2014 it stays pending until a later drain re-acks it (attempt ${attempts} of ${MAX_ACK_ATTEMPTS})`
+  });
+}
+function describe(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/lib/channels/driver.ts
 function messageIdOf(m) {
   if (!m || typeof m !== "object") return void 0;
@@ -1811,6 +2481,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,
@@ -1821,7 +2502,10 @@ 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 B2_ABANDONMENT_MIN_PINNED_MS = 3 * 6e4;
+var B2_ABANDONMENT_RECHECK_MS = HEARTBEAT_MS;
 var POLL_MISS_GRACE_MS = HEARTBEAT_MS;
+var MAX_SUPERSEDED_CONVERSATIONS = 256;
 var ChannelAuthError = class extends Error {
   constructor(message) {
     super(message);
@@ -1844,7 +2528,7 @@ function backoffDelay(attempt, policy) {
 function isRetryableStatus(status) {
   return status === 429 || status >= 500 && status <= 599;
 }
-var ChannelDriver = class {
+var ChannelDriver = class _ChannelDriver {
   agentId;
   port;
   apiUrl;
@@ -1858,8 +2542,38 @@ var ChannelDriver = class {
   pausedMaxWaitMs;
   stuckQueuedMs;
   now;
+  fileSyncDirectories;
+  homeDir;
   /** Cache of conversationId → opencode sessionId. */
   sessions = /* @__PURE__ */ new Map();
+  /**
+   * conversationId → the opencode session this runner has ABANDONED as that
+   * conversation's binding (#553), after a genuine (`sessionExists === true`)
+   * dispatch failure: the session still exists but is wedged, so #485's self-heal
+   * must bind a fresh one.
+   *
+   * Dropping the local binding + clearing the server row is not enough on its own:
+   * a SIBLING message dispatched earlier in the same drain is still in-flight under
+   * the same session, and its watcher's routine status writes carry
+   * `opencode_session_id`, RESURRECTING the wedged id server-side after the clear —
+   * and `ensureSession`'s persisted-id fallback then reuses it, defeating the
+   * self-heal. This map makes the runner authoritative instead of racing those
+   * writes: *`ensureSession` never reuses an abandoned id for that conversation,
+   * whatever the server row says* — which holds even when the resurrecting write
+   * is one we deliberately keep (see `markDone`).
+   *
+   * Bounded by construction, on both axes: keyed by CONVERSATION, so N failures on
+   * one conversation hold ONE entry (the newest abandonment replaces the older), and
+   * hard-capped at `MAX_SUPERSEDED_CONVERSATIONS` with FIFO eviction. Only the
+   * NEWEST abandoned id per conversation is guarded: after a second abandonment a
+   * late sibling of the FIRST session can write that id back and `ensureSession`
+   * will reuse it — costing ONE repeat failure, which re-supersedes it. Deliberately
+   * NOT dropped when the session's watcher tears down: `markDone` still writes the
+   * abandoned id back (it must, or the reply is lost), so the guard has to outlive
+   * the turn that resurrects it. In-memory only — a restart forgets it, at the same
+   * bounded cost.
+   */
+  supersededSessions = /* @__PURE__ */ new Map();
   /**
    * Per-opencode-session dispatch lock (Task 2.1a). `sendPromptAsync` is no
    * longer idempotent (no caller-supplied `messageID`), and its read-back picks
@@ -1941,6 +2655,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
@@ -1958,8 +2681,39 @@ 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, non-placeholder name is stored (terminal — a real session name
+   * won't later un-name), so we do NOT re-GET `/session/:id` every tick. "Non-empty"
+   * excludes OpenCode's synchronous default title (see
+   * `OPENCODE_DEFAULT_TITLE_PREFIX`, #549) — that placeholder is treated the same
+   * as an empty title so it never latches. A missing entry = not yet resolved OR
+   * resolved-but-still-empty/placeholder → 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;
+  /**
+   * Serialises runner-file syncs (#559) so the ~2s poll tick and a concurrent
+   * drain ping don't download, write and ack the same file twice.
+   */
+  syncingFiles = false;
+  /**
+   * Consecutive failed acks per pending file (#559). Lives on the driver so it
+   * survives across drains — without it, a file whose ack keeps failing is
+   * re-downloaded and re-written every ~2s until the server expires it.
+   */
+  fileAckFailures = /* @__PURE__ */ new Map();
+  /**
+   * Monotonic count of files this runner has pulled and written (#559). Only
+   * ever increases, so `run.ts` detects work by comparing it against the value
+   * it saw on the previous cycle — including work that landed mid-sleep, the
+   * same trick `lastProxiedActivityAt` uses.
+   */
+  appliedFileCount = 0;
   /**
    * The currently-executing `drainPending()` promise, or null when idle. Lets a
    * graceful shutdown (`waitForInFlight`) await an in-progress drain so a turn it
@@ -1990,14 +2744,13 @@ var ChannelDriver = class {
     this.pausedMaxWaitMs = config2.pausedMaxWaitMs ?? DEFAULT_PAUSED_MAX_WAIT_MS;
     this.stuckQueuedMs = config2.stuckQueuedMs ?? DEFAULT_STUCK_QUEUED_MS;
     this.now = config2.now ?? (() => Date.now());
+    this.fileSyncDirectories = config2.fileSyncDirectories ?? [];
+    this.homeDir = config2.homeDir ?? homedir();
   }
   /** The IPv4-loopback base URL for the local `opencode serve`. */
   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`.
@@ -2020,6 +2773,47 @@ var ChannelDriver = class {
     );
     return run2;
   }
+  /**
+   * Pull-and-apply any files Evident has queued for this runner (#559), riding
+   * the EXISTING drain cycle — `run.ts` calls it from the same ~2s channel poll
+   * and drain ping that call `drainPending()`. There is deliberately no channel,
+   * control frame or poll loop of its own: worst-case latency is one poll tick.
+   *
+   * NEVER throws and never surfaces a `ChannelAuthError`: a file failure must not
+   * cost a conversation turn. Failures are logged and either acked as a terminal
+   * outcome or left pending for the next drain (see `runner-file-sync.ts`).
+   *
+   * Re-entrant calls are skipped (the poll tick and a drain ping can overlap).
+   *
+   * @returns the number of files written to disk.
+   */
+  async syncPendingFiles() {
+    if (this.stopped) return 0;
+    if (this.syncingFiles) return 0;
+    this.syncingFiles = true;
+    try {
+      const applied = await syncPendingRunnerFiles({
+        agentId: this.agentId,
+        apiUrl: this.apiUrl,
+        getAuthHeader: this.getAuthHeader,
+        fetchImpl: this.fetchImpl,
+        allowedDirectories: this.fileSyncDirectories,
+        homeDir: this.homeDir,
+        ackFailures: this.fileAckFailures,
+        log: this.log
+      });
+      this.appliedFileCount += applied;
+      return applied;
+    } catch (err) {
+      this.log({
+        level: "error",
+        message: `Runner file sync failed unexpectedly (message processing is unaffected): ${err instanceof Error ? err.message : String(err)}`
+      });
+      return 0;
+    } finally {
+      this.syncingFiles = false;
+    }
+  }
   async runDrain() {
     let dispatched = 0;
     try {
@@ -2053,6 +2847,28 @@ var ChannelDriver = class {
     }
     return false;
   }
+  /**
+   * File-pull work, for `run.ts`'s idle accounting (#559).
+   *
+   * Pulling a file is real work that `drainPending()` knows nothing about, so
+   * without this a near-idle runner counts a credential pull as an empty tick
+   * and `--idle-timeout` can `process.exit` mid-pull — leaving a
+   * `.evident-push-*.tmp` behind — or immediately after the write, before the
+   * browser has run the authorize/callback that activates it (the user then sees
+   * `saved_not_activated` for a runner that was fine).
+   *
+   * Two signals because one cannot cover both cases: `inFlight` is the pull
+   * happening RIGHT NOW (it may outlive the tick that started it), and
+   * `appliedFiles` is monotonic so a pull that started AND finished between two
+   * idle checks still shows up as an advance.
+   *
+   * CALLER CONTRACT: sample `inFlight` BEFORE calling `syncPendingFiles()` for
+   * the cycle. `syncPendingFiles` sets the flag synchronously, so a caller that
+   * samples afterwards reads `true` every single cycle and can never idle out.
+   */
+  fileSyncActivity() {
+    return { appliedFiles: this.appliedFileCount, inFlight: this.syncingFiles };
+  }
   /**
    * 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
@@ -2114,7 +2930,7 @@ var ChannelDriver = class {
         await this.sleep(step);
       }
     }
-    while (this.hasInFlightWatchers()) {
+    while (this.hasInFlightWatchers() || this.syncingFiles) {
       if (this.now() >= deadline) return false;
       await this.sleep(step);
     }
@@ -2139,9 +2955,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
@@ -2151,10 +2965,15 @@ var ChannelDriver = class {
    * @returns the count of messages NEWLY dispatched (not already in-flight).
    */
   async processConversation(conv) {
-    const sessionId = await this.ensureSession(conv);
+    const { sessionId, refusedSessionId } = await this.ensureSession(conv);
     const messages = await this.getPendingMessages(conv.id);
     let dispatched = 0;
     let skippedAlreadyDispatched = 0;
+    if (refusedSessionId && messages.length > 0) {
+      void this.postSignal(conv.id, messages[0].id, "session_superseded", {
+        superseded_session_id: refusedSessionId
+      });
+    }
     for (const message of messages) {
       if (this.stopped) break;
       if (this.dispatched.has(message.id)) {
@@ -2173,36 +2992,62 @@ 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) {
+        const exists = await sessionExists(this.port, sessionId);
+        if (exists === false) {
           this.sessions.delete(conv.id);
           this.log({
-            level: "info",
+            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(() => {
+        if (exists === null) {
+          this.log({
+            level: "warn",
+            message: `Message ${message.id.slice(0, 8)} dispatch failed and session (${sessionId.slice(0, 8)}) existence could not be confirmed (opencode momentarily unreachable) \u2014 deferring this and later messages for conversation ${conv.id.slice(0, 8)} to the next tick rather than treating it as a genuine failure.`,
+            conversation_id: conv.id,
+            message_id: message.id
+          });
+          break;
+        }
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        this.sessions.delete(conv.id);
+        this.supersede(conv.id, sessionId);
+        this.log({
+          level: "warn",
+          message: `Abandoning OpenCode session ${sessionId.slice(0, 8)} as the binding for conversation ${conv.id.slice(0, 8)} (it exists but failed to run a turn) \u2014 a fresh session is created on the next tick, whatever the persisted binding says by then.`,
+          conversation_id: conv.id,
+          message_id: message.id
+        });
+        await this.markFailed(conv.id, message.id, null, errorMessage).catch((markErr) => {
+          this.log({
+            level: "warn",
+            message: `markFailed PATCH for message ${message.id.slice(0, 8)} (conversation ${conv.id.slice(0, 8)}) failed (best-effort, not retried): ${markErr instanceof Error ? markErr.message : String(markErr)}`,
+            conversation_id: conv.id,
+            message_id: message.id
+          });
         });
         this.log({
           level: "error",
-          message: `Message ${message.id.slice(0, 8)} dispatch failed: ${err instanceof Error ? err.message : String(err)}`,
+          message: `Message ${message.id.slice(0, 8)} dispatch failed: ${errorMessage}`,
           conversation_id: conv.id,
           message_id: message.id
         });
-        continue;
+        break;
       }
       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
@@ -2216,7 +3061,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
       });
@@ -2224,23 +3069,57 @@ var ChannelDriver = class {
     this.ensureWatcherRunning(sessionId);
     return dispatched;
   }
+  /**
+   * Record that `sessionId` is no longer a valid binding for `conversationId`
+   * (#553). Keyed by conversation and hard-capped, so it cannot grow with the
+   * number of failures — see the `supersededSessions` field doc.
+   */
+  supersede(conversationId, sessionId) {
+    this.supersededSessions.delete(conversationId);
+    this.supersededSessions.set(conversationId, sessionId);
+    while (this.supersededSessions.size > MAX_SUPERSEDED_CONVERSATIONS) {
+      const oldest = this.supersededSessions.keys().next().value;
+      if (oldest === void 0) return;
+      this.supersededSessions.delete(oldest);
+    }
+  }
+  /** Whether `sessionId` is the session this conversation has abandoned (#553). */
+  isSuperseded(conversationId, sessionId) {
+    return this.supersededSessions.get(conversationId) === sessionId;
+  }
+  /**
+   * Resolve the opencode session to run this conversation's turns in.
+   *
+   * `refusedSessionId` is set when the #553 guard fired — i.e. the persisted
+   * binding was an id this runner had abandoned, so a resurrection genuinely
+   * happened and a fresh session was bound instead. The caller reports it.
+   */
   async ensureSession(conv) {
     const bound = this.sessions.get(conv.id) ?? conv.opencode_session_id ?? null;
+    if (bound && this.isSuperseded(conv.id, bound)) {
+      this.log({
+        level: "warn",
+        message: `OpenCode session ${bound.slice(0, 8)} was abandoned for conversation ${conv.id.slice(0, 8)} after a failed dispatch but is still bound to it (the persisted id was written back by a turn already in flight) \u2014 ignoring it and binding a fresh session.`,
+        conversation_id: conv.id
+      });
+      this.sessions.delete(conv.id);
+      return { sessionId: await this.createAndBindSession(conv.id), refusedSessionId: bound };
+    }
     if (bound) {
       const exists = await sessionExists(this.port, bound);
       if (exists === false) {
         this.log({
-          level: "info",
+          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);
+        return { sessionId: await this.createAndBindSession(conv.id) };
       }
       this.sessions.set(conv.id, bound);
-      return bound;
+      return { sessionId: bound };
     }
-    return this.createAndBindSession(conv.id);
+    return { sessionId: await this.createAndBindSession(conv.id) };
   }
   /**
    * Create a fresh OpenCode session for a conversation, cache the binding, and
@@ -2265,15 +3144,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
@@ -2293,6 +3170,130 @@ 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}/runners/{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.
+   * A 404 body carrying `{ reason: 'needs_reauth' }` (#547 — the server CONFIRMED
+   * a Slack `files:read` scope problem via `files.info`) instead resolves the
+   * `AttachmentFetchNeedsReauth` sentinel, so the in-thread note can steer the
+   * user to reconnect Slack instead of a generic "unavailable". Failures are
+   * logged with context (no silent swallow).
+   */
+  async fetchAttachmentDataUrl(messageId, index, mime) {
+    try {
+      const res = await this.fetchImpl(
+        `${this.apiUrl}/runners/${this.agentId}/attachments/${messageId}/${index}`,
+        { headers: { Authorization: this.getAuthHeader() } }
+      );
+      if (!res.ok) {
+        let reason;
+        try {
+          const body = await res.json();
+          if (body && typeof body.reason === "string") reason = body.reason;
+        } catch (parseErr) {
+          this.log({
+            level: "debug",
+            message: `Attachment fetch for message ${messageId.slice(0, 8)} index ${index}: error body was not JSON (${parseErr instanceof Error ? parseErr.message : String(parseErr)}) \u2014 treating as a plain failure`,
+            message_id: messageId
+          });
+        }
+        if (reason === "needs_reauth") {
+          this.log({
+            level: "error",
+            message: `Attachment fetch for message ${messageId.slice(0, 8)} index ${index} returned HTTP ${res.status} \u2014 server confirmed a Slack reauth/scope problem \u2014 omitting this image (text turn proceeds)`,
+            message_id: messageId
+          });
+          return { needsReauth: true };
+        }
+        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";
+    const failedReason = outcomes.some(
+      (o) => o.status === "failed" && o.reason === "needs_reauth"
+    ) ? "needs_reauth" : void 0;
+    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 } : {},
+      ...failedReason ? { failed_reason: failedReason } : {}
+    });
+  }
   /** Register a freshly-dispatched message with its session's watcher state. */
   registerInFlight(conv, sessionId, message, opencodeMessageId) {
     let watcher = this.watchers.get(sessionId);
@@ -2321,12 +3322,17 @@ var ChannelDriver = class {
       stuckReported: false,
       lastAliveAt: 0,
       aliveInFlight: false,
+      titleSynced: false,
+      titleSyncInFlight: false,
       awaitingHumanLatched: false,
       pausedOnQuestion: false,
       pausedOnPermission: false,
       pausedClearConfirmed: false,
       pausedInFlight: false,
-      deliveryDeadlineAnchored: false
+      deliveryDeadlineAnchored: false,
+      b2PinnedSinceMs: 0,
+      b2LastDescendantCheckMs: 0,
+      b2AbandonedSignalled: false
     });
   }
   /**
@@ -2394,12 +3400,17 @@ var ChannelDriver = class {
       // with no extra `re_adopted` signal needed (folds old WI-6).
       lastAliveAt: 0,
       aliveInFlight: false,
+      titleSynced: false,
+      titleSyncInFlight: false,
       awaitingHumanLatched: false,
       pausedOnQuestion: false,
       pausedOnPermission: false,
       pausedClearConfirmed: false,
       pausedInFlight: false,
-      deliveryDeadlineAnchored: false
+      deliveryDeadlineAnchored: false,
+      b2PinnedSinceMs: 0,
+      b2LastDescendantCheckMs: 0,
+      b2AbandonedSignalled: false
     });
   }
   /**
@@ -2530,18 +3541,20 @@ var ChannelDriver = class {
     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
@@ -2551,7 +3564,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
@@ -2559,54 +3572,7 @@ var ChannelDriver = class {
       }
     }
     if (state === "done") {
-      this.anchorDeliveryDeadline(inFlight);
-      if (!inFlight.done) {
-        this.log({
-          level: "info",
-          message: `Message ${inFlight.evidentMessageId.slice(0, 8)} completed \u2014 marking done`,
-          conversation_id: conv.id,
-          message_id: inFlight.evidentMessageId
-        });
-        try {
-          await this.markDone(
-            conv.id,
-            inFlight.evidentMessageId,
-            sessionId,
-            inFlight.opencodeMessageId
-          );
-        } catch (err) {
-          if (err instanceof ChannelAuthError) throw err;
-          if (err instanceof ChannelTerminalError) {
-            this.log({
-              level: "error",
-              message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} done (terminal HTTP ${err.status}) \u2014 leaving for the cron safety net: ${err.message}`,
-              conversation_id: conv.id,
-              message_id: inFlight.evidentMessageId
-            });
-            this.removeInFlight(watcher, inFlight.evidentMessageId);
-            return;
-          }
-          if (this.now() >= inFlight.deadline) {
-            this.log({
-              level: "error",
-              message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} done within the watch window \u2014 leaving for the cron safety net: ${err instanceof Error ? err.message : String(err)}`,
-              conversation_id: conv.id,
-              message_id: inFlight.evidentMessageId
-            });
-            this.removeInFlight(watcher, inFlight.evidentMessageId);
-            return;
-          }
-          this.log({
-            level: "error",
-            message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} done (will retry next tick): ${err instanceof Error ? err.message : String(err)}`,
-            conversation_id: conv.id,
-            message_id: inFlight.evidentMessageId
-          });
-          return;
-        }
-        inFlight.done = true;
-      }
-      this.removeInFlight(watcher, inFlight.evidentMessageId);
+      await this.settleMessageDone(sessionId, watcher, inFlight, messages);
       return;
     }
     if (state === "failed") {
@@ -2619,13 +3585,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
@@ -2635,7 +3602,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
@@ -2644,7 +3611,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
@@ -2665,9 +3632,47 @@ var ChannelDriver = class {
       });
     }
     const activelyRunning = state === "running" && !awaitingHuman;
+    const pinnedNow = activelyRunning && isPreamblePinnedRunning(messages, inFlight.opencodeMessageId);
+    const snapshotReadable = messages != null && messages.length > 0;
+    if (!pinnedNow) {
+      if (snapshotReadable) {
+        inFlight.b2PinnedSinceMs = 0;
+        inFlight.b2LastDescendantCheckMs = 0;
+        inFlight.b2AbandonedSignalled = false;
+      }
+    } else {
+      if (inFlight.b2AbandonedSignalled) {
+        await this.settleMessageDone(sessionId, watcher, inFlight, messages);
+        return;
+      }
+      if (inFlight.b2PinnedSinceMs === 0) inFlight.b2PinnedSinceMs = this.now();
+      const pinnedForMs = this.now() - inFlight.b2PinnedSinceMs;
+      if (pinnedForMs >= B2_ABANDONMENT_MIN_PINNED_MS && this.now() - inFlight.b2LastDescendantCheckMs >= B2_ABANDONMENT_RECHECK_MS) {
+        inFlight.b2LastDescendantCheckMs = this.now();
+        const descendantOngoing = await this.isAnyDescendantSessionOngoing(sessionId);
+        if (isB2AbandonmentConfirmed({
+          pinnedForMs,
+          minPinnedMs: B2_ABANDONMENT_MIN_PINNED_MS,
+          descendantOngoing
+        })) {
+          inFlight.b2AbandonedSignalled = true;
+          this.log({
+            level: "warn",
+            message: `Message ${id.slice(0, 8)} b2-pinned for ${Math.round(pinnedForMs / 1e3)}s with no ongoing descendant sub-agent session (status-map confirmed) \u2014 treating the delegated/tool turn as abandoned, resolving done`,
+            conversation_id: conv.id,
+            message_id: id
+          });
+          void this.postSignal(conv.id, id, "b2_abandoned_resolved", {
+            watched_for_ms: pinnedForMs
+          });
+          await this.settleMessageDone(sessionId, watcher, inFlight, messages);
+          return;
+        }
+      }
+    }
     if (activelyRunning && this.now() - inFlight.processingAnchorMs >= ABSOLUTE_MAX_PROCESSING_MS) {
       this.log({
-        level: "error",
+        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
@@ -2684,6 +3689,18 @@ var ChannelDriver = class {
         inFlight.aliveInFlight = false;
         if (ok) inFlight.lastAliveAt = this.now();
       });
+      if (!inFlight.titleSynced && !inFlight.titleSyncInFlight) {
+        inFlight.titleSyncInFlight = true;
+        void this.resolveSessionTitle(sessionId, conv.id).then(async (title) => {
+          if (!title) {
+            inFlight.titleSyncInFlight = false;
+            return;
+          }
+          const ok = await this.patchConversationTitle(conv.id, title);
+          inFlight.titleSyncInFlight = false;
+          if (ok) inFlight.titleSynced = true;
+        });
+      }
     }
     if (awaitingHuman) {
       if (!inFlight.awaitingHumanLatched) {
@@ -2710,7 +3727,7 @@ var ChannelDriver = class {
     const queuedBehindRunningSibling = state === "queued" && hasActivelyRunningSibling;
     if (!activelyRunning && !queuedBehindRunningSibling && this.now() >= inFlight.deadline) {
       this.log({
-        level: "info",
+        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
@@ -2721,9 +3738,71 @@ var ChannelDriver = class {
       this.removeInFlight(watcher, inFlight.evidentMessageId);
     }
   }
-  // -------------------------------------------------------------------------
+  /**
+   * Settle a message whose run-state has resolved `'done'` — extracted verbatim
+   * (pure refactor, no behavior change) from `serviceInFlightMessage`'s former
+   * inline `state === 'done'` branch body, so a SECOND caller (the #721
+   * b2-abandonment resolution) can reach the exact same completion behavior
+   * (delivery-deadline anchoring, title resolution, usage extraction, and
+   * `markDone`'s auth/terminal/transient-retry discipline) without duplicating it
+   * and risking the two copies silently drifting apart.
+   */
+  async settleMessageDone(sessionId, watcher, inFlight, messages) {
+    const conv = watcher.conv;
+    this.anchorDeliveryDeadline(inFlight);
+    if (!inFlight.done) {
+      this.log({
+        level: "info",
+        message: `Message ${inFlight.evidentMessageId.slice(0, 8)} completed \u2014 marking done`,
+        conversation_id: conv.id,
+        message_id: inFlight.evidentMessageId
+      });
+      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,
+          title,
+          usage
+        );
+      } catch (err) {
+        if (err instanceof ChannelAuthError) throw err;
+        if (err instanceof ChannelTerminalError) {
+          this.log({
+            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
+          });
+          this.removeInFlight(watcher, inFlight.evidentMessageId);
+          return;
+        }
+        if (this.now() >= inFlight.deadline) {
+          this.log({
+            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
+          });
+          this.removeInFlight(watcher, inFlight.evidentMessageId);
+          return;
+        }
+        this.log({
+          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
+        });
+        return;
+      }
+      inFlight.done = true;
+    }
+    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).
    *
@@ -2753,7 +3832,7 @@ var ChannelDriver = class {
           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
             });
@@ -2766,7 +3845,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
@@ -2783,7 +3862,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;
@@ -2791,7 +3870,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;
@@ -2799,7 +3878,7 @@ 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;
@@ -2832,7 +3911,7 @@ var ChannelDriver = class {
   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
@@ -2844,7 +3923,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
@@ -2858,13 +3937,15 @@ 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
@@ -2873,7 +3954,7 @@ var ChannelDriver = class {
           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
@@ -2886,6 +3967,7 @@ var ChannelDriver = class {
     }
     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)"}`,
@@ -2893,13 +3975,13 @@ 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
@@ -2908,7 +3990,7 @@ var ChannelDriver = class {
           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
@@ -2921,7 +4003,7 @@ var ChannelDriver = class {
     }
     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
@@ -2946,7 +4028,7 @@ var ChannelDriver = class {
       }
       if (ongoing === true) {
         this.log({
-          level: "info",
+          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
@@ -2954,7 +4036,7 @@ var ChannelDriver = class {
       } else {
         if (shape === "b1") {
           this.log({
-            level: "info",
+            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
@@ -2966,7 +4048,7 @@ var ChannelDriver = class {
           return;
         }
         this.log({
-          level: "info",
+          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
@@ -2977,7 +4059,7 @@ var ChannelDriver = class {
       const descendantAlive = await this.isAnyDescendantSessionAlive(sessionId);
       if (descendantAlive === true) {
         this.log({
-          level: "info",
+          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
@@ -3001,7 +4083,7 @@ 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
@@ -3035,7 +4117,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
@@ -3044,7 +4126,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
@@ -3054,7 +4136,7 @@ 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
@@ -3073,17 +4155,20 @@ 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
@@ -3094,7 +4179,7 @@ var ChannelDriver = class {
     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
@@ -3102,9 +4187,7 @@ var ChannelDriver = class {
       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);
@@ -3158,7 +4241,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
     };
   }
   /**
@@ -3179,7 +4263,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
@@ -3297,6 +4381,47 @@ var ChannelDriver = class {
     }
     return false;
   }
+  /**
+   * Tri-state variant of the upward parentID membership walk (#721), used ONLY
+   * by `isAnyDescendantSessionOngoing`. Walks the SAME cached
+   * `resolveSessionParent` chain `sessionBelongsTo` uses above, but — unlike
+   * `sessionBelongsTo`, which deliberately collapses "confirmed not a
+   * descendant" and "the walk's fetch failed" into the same `false` (safe for
+   * its OTHER callers: interaction attribution and the recovery-path
+   * `isAnyDescendantSessionAlive`, both of which just retry next tick with no
+   * safety consequence either way) — this variant keeps those two outcomes
+   * SEPARATE, because `isAnyDescendantSessionOngoing`'s caller
+   * (`isB2AbandonmentConfirmed`) must never treat "couldn't tell" as "confirmed
+   * not ongoing".
+   *
+   * Return contract:
+   *  - `true`  → the walk reached `rootSessionId` — `sessionId` IS a descendant.
+   *  - `false` → the walk reached a definitive, parent-less root session
+   *              WITHOUT ever matching `rootSessionId` — `sessionId` is
+   *              CONFIRMED NOT a descendant of it.
+   *  - `null`  → INDETERMINATE: a `GET /session/:id` fetch failed partway
+   *              through the walk (`resolveSessionParent` returned `undefined`),
+   *              or the depth cap (32) was hit without a definitive answer (a
+   *              pathological/cyclic chain proves nothing either way). NEVER
+   *              treat this the same as `false` — see `sessionBelongsTo`'s own
+   *              doc comment above for why that collapse is safe THERE but not
+   *              here.
+   *
+   * `sessionBelongsTo` itself is UNCHANGED — this is an additive helper scoped
+   * to the live-path descendant check, not a modification of shared code used
+   * by interaction attribution or the recovery path.
+   */
+  async resolveSessionMembership(sessionId, rootSessionId) {
+    let current = sessionId;
+    for (let depth = 0; current && depth < 32; depth++) {
+      if (current === rootSessionId) return true;
+      const parent = await this.resolveSessionParent(current);
+      if (parent === void 0) return null;
+      if (parent === null) return false;
+      current = parent;
+    }
+    return null;
+  }
   /**
    * Resolve (and cache) a session's `parentID` via `GET /session/:id`. Returns
    * `null` for a root session (no parent) and `undefined` when opencode is
@@ -3319,6 +4444,116 @@ var ChannelDriver = class {
     if (parent !== void 0) this.sessionParents.set(sessionId, parent);
     return parent;
   }
+  /**
+   * OpenCode's synchronous default session title (e.g.
+   * `"New session - 1737800000000"`), assigned immediately when a session is
+   * created — before OpenCode's async LLM-based auto-titling later renames it
+   * mid-turn (#549). Matched by this literal, case-sensitive prefix only; the
+   * timestamp suffix's exact format is deliberately NOT matched, since the prefix
+   * alone is the stable, cheap signal and over-anchoring on the timestamp
+   * representation risks silently breaking if OpenCode ever changes it. Accepted
+   * trade-off: a genuine LLM-assigned title that happens to literally start with
+   * this prefix would also fail to latch (see `resolveSessionTitle`) —
+   * vanishingly unlikely in practice, and deliberately not engineered around.
+   */
+  static OPENCODE_DEFAULT_TITLE_PREFIX = /^New session - /;
+  /**
+   * 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 that does NOT match
+   *     `OPENCODE_DEFAULT_TITLE_PREFIX` 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, or matches the OpenCode
+   *     placeholder prefix (#549) 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. If a session is
+   *     never renamed, the title is omitted forever rather than ever persisting
+   *     the placeholder as a last resort;
+   *   - 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 && !_ChannelDriver.OPENCODE_DEFAULT_TITLE_PREFIX.test(title)) {
+          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;
+  }
+  /**
+   * Best-effort mid-turn title sync (#711 follow-up): PATCH a resolved OpenCode
+   * session title onto the conversation via the PLAIN conversation-update
+   * endpoint (`PATCH /runners/:agentId/conversations/:conversationId`) — NOT the
+   * message-status endpoint `markProcessing`/`markDone` use. Deliberately a
+   * separate, lighter call: it carries no `status`, so it cannot re-trigger the
+   * `processing`/`done` transition side effects (Slack notices, activity-log
+   * rows, delivery jobs) those PATCHes gate on `transitioned` — this call only
+   * ever touches `conversations.title`. That route (`routes/conversations.ts`)
+   * skips a title write matching the stored value, so a redundant call with the
+   * same title is a real no-op — it does not bump `updated_at`, which the
+   * conversation list sorts and paginates on. (Note this is a DIFFERENT guard
+   * from `threads.ts`'s "non-empty AND changed" one, which only covers the
+   * message-status PATCH; the non-empty half is enforced here instead, by
+   * `resolveSessionTitle` never returning an empty/placeholder title.)
+   *
+   * Telemetry-only / never blocks the caller, mirroring `postSignal`: a failure
+   * is logged and the title is simply retried on the next heartbeat tick (the
+   * caller only latches `titleSynced` on `true`).
+   */
+  async patchConversationTitle(conversationId, title) {
+    try {
+      const res = await this.fetchImpl(
+        `${this.apiUrl}/runners/${this.agentId}/conversations/${conversationId}`,
+        {
+          method: "PATCH",
+          headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
+          body: JSON.stringify({ title })
+        }
+      );
+      if (!res.ok) {
+        this.log({
+          level: "debug",
+          message: `Mid-turn title sync PATCH for conversation ${conversationId.slice(0, 8)} returned HTTP ${res.status} (best-effort, will retry next heartbeat)`,
+          conversation_id: conversationId
+        });
+        return false;
+      }
+      return true;
+    } catch (err) {
+      this.log({
+        level: "debug",
+        message: `Best-effort mid-turn title sync PATCH failed for conversation ${conversationId.slice(0, 8)} (will retry next heartbeat): ${err instanceof Error ? err.message : String(err)}`,
+        conversation_id: conversationId
+      });
+      return false;
+    }
+  }
   /**
    * DEFENSIVE cross-check for the restart-recovery path (WI-2): is any descendant
    * (`task` sub-agent) session under `rootSessionId` still genuinely doing work?
@@ -3362,7 +4597,7 @@ var ChannelDriver = class {
     const sessions = await listSessions(this.port);
     if (!sessions) {
       this.log({
-        level: "error",
+        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;
@@ -3377,6 +4612,84 @@ var ChannelDriver = class {
     }
     return false;
   }
+  /**
+   * LIVE-PATH descendant-liveness check (#721): is any descendant (`task`
+   * sub-agent) session under `rootSessionId` currently ONGOING per OpenCode's own
+   * in-memory status map (`isSessionOngoing` — `busy`/`retry`)?
+   *
+   * Deliberately NOT `isAnyDescendantSessionAlive` (the RECOVERY-path
+   * cross-check above): that method judges liveness from the child's OWN
+   * TRANSCRIPT (`isSessionActivelyGenerating`), which is the right (only) option
+   * on the recovery path because a restart WIPES `SessionStatus`. On the LIVE
+   * path the local opencode server IS running, so its in-memory status map is
+   * live and authoritative — and per ADR-0047 §4a ("the child has its own entry
+   * [in the map]"), a `task` descendant's OWN busy/retry entry reflects its
+   * ENTIRE turn (including any tool call it is itself executing), not a
+   * per-message transcript snapshot. This sidesteps the "child's own tool is
+   * executing, between its step's completion and the next generation step"
+   * transcript gap that a transcript-based check would need a second,
+   * sustained-window bound to guard against — it is simply not derived from
+   * message timestamps at all.
+   *
+   * Why not just check `isSessionOngoing(port, rootSessionId)` (the ROOT's own
+   * status, as the recovery path does per §4a)? Because on the LIVE path the
+   * root session can be shared: a SECOND, unrelated user message can land on the
+   * SAME session (issue #721's own root cause) and keep the root `busy` for a
+   * reason that has nothing to do with THIS message's delegation. A `task`
+   * descendant session is spawned for exactly one delegated turn and never
+   * reused, so its OWN status-map entry is unambiguous evidence about that one
+   * delegation — which the root's status is not.
+   *
+   * Why membership is checked via `resolveSessionMembership`, NOT
+   * `sessionBelongsTo`: `sessionBelongsTo` collapses a transient
+   * `GET /session/:id` fetch failure into "not a descendant", which would
+   * silently drop a genuinely-live candidate from consideration on the one
+   * unlucky tick its membership-walk fetch hiccups (#721).
+   * `resolveSessionMembership` keeps that failure mode as a distinct `null`
+   * (indeterminate) so it is folded into THIS method's own `indeterminate` flag
+   * instead.
+   *
+   * Return contract (note the DIFFERENT judge vs. `isAnyDescendantSessionAlive`):
+   *  - `true`  → some descendant session is `busy`/`retry` (genuinely ongoing).
+   *  - `false` → enumeration succeeded, EVERY candidate's MEMBERSHIP was
+   *              confirmed either way (`resolveSessionMembership` never
+   *              returned `null`), and every CONFIRMED descendant's status read
+   *              succeeded and is not ongoing (includes "no descendant session
+   *              exists at all" — e.g. a plain, non-`task` tool call).
+   *  - `null`  → INDETERMINATE: `listSessions` failed, OR at least one
+   *              candidate's MEMBERSHIP could not be confirmed
+   *              (`resolveSessionMembership` returned `null` — a fetch failure
+   *              or pathological chain partway through the parent walk), OR at
+   *              least one CONFIRMED descendant's `isSessionOngoing` read
+   *              failed — and no OTHER candidate was already confirmed `true`.
+   *              The caller MUST NOT treat `null` the same as `false` here
+   *              (unlike the recovery cross-check's contract) — see
+   *              `isB2AbandonmentConfirmed`.
+   */
+  async isAnyDescendantSessionOngoing(rootSessionId) {
+    const sessions = await listSessions(this.port);
+    if (!sessions) {
+      this.log({
+        level: "warn",
+        message: `Could not enumerate sessions to check descendant liveness for root ${rootSessionId} (listSessions failed) \u2014 treating descendant liveness as indeterminate`
+      });
+      return null;
+    }
+    let indeterminate = false;
+    for (const candidate of sessions) {
+      if (!candidate?.id || candidate.id === rootSessionId) continue;
+      const membership = await this.resolveSessionMembership(candidate.id, rootSessionId);
+      if (membership === null) {
+        indeterminate = true;
+        continue;
+      }
+      if (membership === false) continue;
+      const ongoing = await isSessionOngoing(this.port, candidate.id);
+      if (ongoing === true) return true;
+      if (ongoing === null) indeterminate = true;
+    }
+    return indeterminate ? null : 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.
@@ -3446,12 +4759,10 @@ 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`,
+      `${this.apiUrl}/runners/${this.agentId}/conversations/pending`,
       {
         headers: { Authorization: this.getAuthHeader() }
       }
@@ -3469,7 +4780,7 @@ var ChannelDriver = class {
   }
   async getPendingMessages(conversationId) {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages?status=pending`,
+      `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages?status=pending`,
       { headers: { Authorization: this.getAuthHeader() } }
     );
     this.assertAuth(res, "fetching pending messages");
@@ -3493,7 +4804,7 @@ var ChannelDriver = class {
    */
   async getProcessingMessages() {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/conversations/processing`,
+      `${this.apiUrl}/runners/${this.agentId}/conversations/processing`,
       { headers: { Authorization: this.getAuthHeader() } }
     );
     this.assertAuth(res, "fetching processing messages");
@@ -3507,6 +4818,32 @@ var ChannelDriver = class {
     }
     return messages;
   }
+  /**
+   * The `opencode_session_id` fragment of a status PATCH body — `{}` when this
+   * conversation has ABANDONED that session (#553). The field is optional
+   * server-side and an absent one leaves the persisted binding untouched, so
+   * omitting it is how a routine status write stops resurrecting it.
+   *
+   * ONLY for writes whose sole cost is a lost deep link. The `processing` notice
+   * degrades to no "View in Evident" link (the reaction swap still fires) and the
+   * turn-failure notice is built from the PATCH's own `error` text with a link off
+   * the persisted row — neither loses content the user came for. `markDone`
+   * deliberately does NOT use this helper: the server fetches the reply text
+   * THROUGH the session id it is given, so suppressing there would replace the
+   * agent's answer with a bare "✅ Done!" (the #183/#187 failure). The
+   * `ensureSession` guard, not this suppression, is what makes the self-heal
+   * stick.
+   */
+  sessionIdBody(sessionId, conversationId, messageId, status) {
+    if (!this.isSuperseded(conversationId, sessionId)) return { opencode_session_id: sessionId };
+    this.log({
+      level: "debug",
+      message: `Omitting the abandoned OpenCode session ${sessionId.slice(0, 8)} from the '${status}' update for message ${messageId.slice(0, 8)} so it is not re-bound to conversation ${conversationId.slice(0, 8)}`,
+      conversation_id: conversationId,
+      message_id: messageId
+    });
+    return {};
+  }
   /**
    * EXISTING combinedAuth route — now fired by the watcher on queued→running
    * (Task 3.3), NOT at dispatch/claim time. `{status:'processing',
@@ -3528,16 +4865,17 @@ 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}`,
+      `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
       {
         method: "PATCH",
         headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
         body: JSON.stringify({
           status: "processing",
-          opencode_session_id: sessionId,
-          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {}
+          ...this.sessionIdBody(sessionId, conversationId, messageId, "processing"),
+          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {},
+          ...title ? { title } : {}
         })
       }
     );
@@ -3576,16 +4914,23 @@ 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}`,
+      `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
       {
         method: "PATCH",
         headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
         body: JSON.stringify({
           status: "done",
+          // ALWAYS sent, even for a session this conversation has abandoned
+          // (#553): the server reads the reply text back out of THIS session id
+          // to deliver it. Omitting it would leave the user with "✅ Done!"
+          // instead of the answer — a worse regression than the resurrection it
+          // would prevent, which `ensureSession`'s guard handles anyway.
           opencode_session_id: sessionId,
-          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {}
+          ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {},
+          ...title ? { title } : {},
+          ...usage ? usage : {}
         })
       }
     );
@@ -3598,19 +4943,29 @@ var ChannelDriver = class {
   }
   /**
    * Mark a message `failed`. `sessionId` / `error` are threaded to the API ONLY
-   * when provided (issue #182): a bare `markFailed(conv, msg)` sends
-   * `{status:'failed'}` unchanged (the dispatch-failure path), while an errored
-   * OpenCode turn sends `{status:'failed', opencode_session_id, error}` so the
-   * failure reason reaches the channel.
+   * when provided (issue #182). Three states for `sessionId`:
+   *   - omitted (`undefined`)  → don't send the field, leave the persisted
+   *     session untouched (unused today; kept for API symmetry).
+   *   - a real id (`string`)   → send it, update the persisted session (the
+   *     turn-failure call sites: an errored OpenCode turn).
+   *   - explicit `null`        → send it, CLEAR the persisted session (issue
+   *     #485's dispatch-handoff-failure call site: the session id still
+   *     exists but is wedged, so the next attempt must get a fresh one
+   *     instead of reusing it — see WI-1's server-side null-clearing PATCH).
    */
-  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 (sessionId === null) {
+      body.opencode_session_id = null;
+    } else if (sessionId !== void 0) {
+      Object.assign(body, this.sessionIdBody(sessionId, conversationId, messageId, "failed"));
+    }
     if (error2 !== void 0) body.error = error2;
+    if (usage) Object.assign(body, usage);
     await this.callWithRetry(
       "marking message as failed",
       () => this.fetchImpl(
-        `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
+        `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
         {
           method: "PATCH",
           headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -3637,7 +4992,7 @@ var ChannelDriver = class {
   async postSignal(conversationId, messageId, signal, extra) {
     try {
       const res = await this.fetchImpl(
-        `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}/signal`,
+        `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages/${messageId}/signal`,
         {
           method: "POST",
           headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -3646,7 +5001,7 @@ 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
@@ -3656,7 +5011,7 @@ var ChannelDriver = class {
       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
@@ -3666,7 +5021,7 @@ var ChannelDriver = class {
   }
   async persistSession(conversationId, sessionId) {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}`,
+      `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}`,
       {
         method: "PATCH",
         headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -3692,7 +5047,7 @@ var ChannelDriver = class {
       await this.callWithRetry(
         "reporting interactive event",
         () => this.fetchImpl(
-          `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/interactive-event`,
+          `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/interactive-event`,
           {
             method: "POST",
             headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -3718,9 +5073,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
@@ -3919,7 +5272,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();
@@ -3927,19 +5280,21 @@ 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}` };
   }
 }
+var BEST_EFFORT_NOTIFY_TIMEOUT_MS = 2e3;
 async function notifyAgentDisconnected(agentId, authHeader) {
   const apiUrl = getApiUrlConfig();
   try {
-    const response = await fetch(`${apiUrl}/agents/${agentId}/disconnect`, {
+    const response = await fetch(`${apiUrl}/runners/${agentId}/disconnect`, {
       method: "POST",
-      headers: { Authorization: authHeader }
+      headers: { Authorization: authHeader },
+      signal: AbortSignal.timeout(BEST_EFFORT_NOTIFY_TIMEOUT_MS)
     });
     if (!response.ok) {
       const serverMessage = await readErrorMessage(response);
@@ -3950,13 +5305,41 @@ async function notifyAgentDisconnected(agentId, authHeader) {
     }
     return { ok: true };
   } catch (error2) {
-    return { ok: false, error: error2 instanceof Error ? error2.message : String(error2) };
+    return { ok: false, error: describeBestEffortError(error2) };
+  }
+}
+function describeBestEffortError(error2) {
+  const name = error2?.name;
+  if (name === "TimeoutError" || name === "AbortError") {
+    return `timed out after ${BEST_EFFORT_NOTIFY_TIMEOUT_MS}ms`;
+  }
+  return error2 instanceof Error ? error2.message : String(error2);
+}
+async function reportMicrovmId(agentId, authHeader, microvmId) {
+  try {
+    const apiUrl = getApiUrlConfig();
+    const response = await fetch(`${apiUrl}/runners/${agentId}/microvm`, {
+      method: "POST",
+      headers: { Authorization: authHeader, "Content-Type": "application/json" },
+      body: JSON.stringify({ microvm_id: microvmId }),
+      signal: AbortSignal.timeout(BEST_EFFORT_NOTIFY_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      const serverMessage = await readErrorMessage(response);
+      return {
+        ok: false,
+        error: `HTTP ${response.status}${serverMessage ? `: ${serverMessage}` : ""}`
+      };
+    }
+    return { ok: true };
+  } catch (error2) {
+    return { ok: false, error: describeBestEffortError(error2) };
   }
 }
 async function getAgentInfo(agentId, authHeader) {
   const apiUrl = getApiUrlConfig();
   try {
-    const response = await fetch(`${apiUrl}/agents/${agentId}`, {
+    const response = await fetch(`${apiUrl}/runners/${agentId}`, {
       headers: { Authorization: authHeader }
     });
     if (response.status === 401) {
@@ -3967,12 +5350,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);
@@ -3985,13 +5368,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}` };
   }
 }
 
@@ -4000,23 +5383,82 @@ 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) {
+var TELEMETRY_SHUTDOWN_TIMEOUT_MS = 5e3;
+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 resolveFileSyncDirectories(raw, homeDir) {
+  const directories = [];
+  for (const entry of raw ?? []) {
+    const trimmed = entry.trim();
+    if (trimmed === "") {
+      throw new Error("--enable-file-sync-to requires a directory path (got an empty value)");
+    }
+    const expanded = trimmed === "~" ? homeDir : trimmed.startsWith("~/") ? join2(homeDir, trimmed.slice(2)) : trimmed;
+    if (!isAbsolute2(expanded)) {
+      throw new Error(`--enable-file-sync-to requires an absolute directory path; got "${entry}"`);
+    }
+    const normalized = resolvePath(expanded);
+    if (parse(normalized).root === normalized) {
+      throw new Error(
+        `--enable-file-sync-to will not allow-list the filesystem root ("${entry}"); name the specific directory the credentials belong in (for example ~/.claude)`
+      );
+    }
+    if (!directories.includes(normalized)) {
+      directories.push(normalized);
+    }
+  }
+  if (directories.length > MAX_FILE_SYNC_DIRECTORIES) {
+    throw new Error(
+      `--enable-file-sync-to accepts at most ${MAX_FILE_SYNC_DIRECTORIES} directories; got ${directories.length}`
+    );
+  }
+  return directories;
+}
+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);
@@ -4025,9 +5467,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);
     }
   }
 }
@@ -4114,18 +5556,29 @@ async function handleAuthError(state, error2) {
 async function driveChannels(state, driver) {
   let idlePolls = 0;
   let lastSeenProxiedActivityAt = state.lastProxiedActivityAt;
+  let lastSeenAppliedFiles = driver.fileSyncActivity().appliedFiles;
   while (state.running) {
     if (state.connection?.reconnecting && state.connection.reconnectPromise) {
       logActivity(state, { type: "info", message: "Waiting for tunnel reconnection..." });
       if (state.interactive) displayStatus(state);
       await state.connection.reconnectPromise;
     }
+    const carriedOverFileSync = driver.fileSyncActivity().inFlight;
+    void driver.syncPendingFiles().catch(
+      (error2) => logActivity(state, {
+        type: "error",
+        error: `Runner file sync failed: ${error2 instanceof Error ? error2.message : String(error2)}`
+      })
+    );
     try {
       const processed = await driver.drainPending();
       state.messageCount += processed;
       const proxiedActivity = state.lastProxiedActivityAt !== lastSeenProxiedActivityAt;
       lastSeenProxiedActivityAt = state.lastProxiedActivityAt;
-      if (processed > 0 || driver.hasInFlightWatchers() || proxiedActivity) {
+      const appliedFiles = driver.fileSyncActivity().appliedFiles;
+      const fileActivity = carriedOverFileSync || appliedFiles !== lastSeenAppliedFiles;
+      lastSeenAppliedFiles = appliedFiles;
+      if (processed > 0 || driver.hasInFlightWatchers() || proxiedActivity || fileActivity) {
         idlePolls = 0;
         if (processed > 0 && state.interactive) displayStatus(state);
       } else if (state.idleTimeout !== null) {
@@ -4154,7 +5607,7 @@ async function driveChannels(state, driver) {
       logActivity(state, { type: "error", error: `Channel processing error: ${errorMessage}` });
       if (state.interactive) displayStatus(state);
     }
-    await new Promise((resolve2) => setTimeout(resolve2, CHANNEL_POLL_INTERVAL_MS));
+    await new Promise((resolve3) => setTimeout(resolve3, CHANNEL_POLL_INTERVAL_MS));
     if (state.idleTimeout !== null && idlePolls >= 2) {
       const idleMs = idlePolls * CHANNEL_POLL_INTERVAL_MS;
       if (idleMs > state.idleTimeout * 1e3) {
@@ -4226,7 +5679,7 @@ function scheduleSessionCleanup(state, driver, options) {
     process.env
   );
   for (const warning2 of config2.warnings) {
-    logActivity(state, { type: "info", message: `Session cleanup: ${warning2}` });
+    logActivity(state, { type: "info", level: "warn", message: `Session cleanup: ${warning2}` });
   }
   if (!config2.enabled) return;
   logActivity(state, {
@@ -4248,7 +5701,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",
@@ -4257,7 +5710,18 @@ async function notifyOffline(state) {
     if (state.interactive) displayStatus(state);
   }
 }
+async function timeShutdownPhase(state, durations, name, run2) {
+  const startedAt = Date.now();
+  try {
+    return await run2();
+  } finally {
+    const elapsedMs = Date.now() - startedAt;
+    durations[name] = elapsedMs;
+    log2(state, `Shutdown phase ${name}: ${elapsedMs}ms`);
+  }
+}
 async function cleanup(state, opts = {}) {
+  const durations = {};
   state.running = false;
   for (const timer of state.sessionCleanupTimers) {
     clearInterval(timer);
@@ -4271,7 +5735,13 @@ async function cleanup(state, opts = {}) {
       logActivity(state, { type: "info", message: "Draining in-flight work before shutdown..." });
       displayStatus(state);
     }
-    const settled = await state.channelDriver.waitForInFlight(SHUTDOWN_DRAIN_TIMEOUT_MS);
+    const driver = state.channelDriver;
+    const settled = await timeShutdownPhase(
+      state,
+      durations,
+      "drain",
+      () => driver.waitForInFlight(SHUTDOWN_DRAIN_TIMEOUT_MS)
+    );
     if (!settled) {
       logActivity(state, {
         type: "info",
@@ -4280,13 +5750,15 @@ async function cleanup(state, opts = {}) {
       if (state.interactive) displayStatus(state);
     }
   }
-  await notifyOffline(state);
+  await timeShutdownPhase(state, durations, "offline_notify", () => notifyOffline(state));
   if (state.connection) {
-    state.connection.close();
+    const connection = state.connection;
+    await timeShutdownPhase(state, durations, "tunnel_close", () => connection.close());
     state.connection = null;
   }
   if (state.opencodeProcess) {
-    stopOpenCode(state.opencodeProcess);
+    const opencodeProcess = state.opencodeProcess;
+    await timeShutdownPhase(state, durations, "opencode_stop", () => stopOpenCode(opencodeProcess));
     if (state.interactive) {
       logActivity(state, { type: "info", message: "Stopped OpenCode process" });
       displayStatus(state);
@@ -4295,17 +5767,35 @@ async function cleanup(state, opts = {}) {
     }
     state.opencodeProcess = null;
   }
+  return durations;
 }
 async function run(options) {
   const interactive = isInteractive(options.json);
+  let logLevel;
+  let fileSyncDirectories;
+  try {
+    logLevel = resolveLogLevel(options);
+    fileSyncDirectories = resolveFileSyncDirectories(options.enableFileSyncTo, homedir2());
+  } 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 || "",
+    agentId: options.runner || options.agent || "",
     agentName: null,
     port: options.port ?? 4096,
     conversationFilter: options.conversation ?? null,
     idleTimeout: options.idleTimeout ?? null,
     json: options.json ?? false,
     interactive,
+    logLevel,
     connected: false,
     opencodeConnected: false,
     opencodeVersion: null,
@@ -4320,24 +5810,66 @@ async function run(options) {
     sessionCleanupTimers: [],
     authHeader: ""
   };
+  if (fileSyncDirectories.length > 0) {
+    log2(state, `File sync enabled for: ${fileSyncDirectories.join(", ")}`);
+  } else {
+    log2(state, "File sync is disabled (no --enable-file-sync-to given)", "debug");
+  }
+  if (!options.runner && options.agent) {
+    telemetry.info(
+      EventTypes.DEPRECATED_AGENT_FLAG_USED,
+      "Deprecated --agent flag used instead of --runner",
+      { command: "run" },
+      state.agentId
+    );
+    const agentFlagNotice = "--agent is deprecated, use --runner instead; will be removed in a future release.";
+    log2(state, agentFlagNotice, "warn");
+    if (state.interactive && !state.json) {
+      logActivity(state, { type: "info", level: "warn", message: agentFlagNotice });
+    }
+  }
   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 () => {
     if (state.shuttingDown) return;
     state.shuttingDown = true;
+    const shutdownStartedAt = Date.now();
     if (state.interactive) {
       logActivity(state, { type: "info", message: "Shutting down..." });
       displayStatus(state);
     } else {
       log2(state, "Shutting down...");
     }
-    await cleanup(state, { graceful: true });
-    await shutdownTelemetry();
+    const durations = await cleanup(state, { graceful: true });
+    const telemetryBudgetMs = Number(process.env.EVIDENT_TELEMETRY_SHUTDOWN_MS) || TELEMETRY_SHUTDOWN_TIMEOUT_MS;
+    await timeShutdownPhase(state, durations, "telemetry_flush", async () => {
+      let timer;
+      const flushed = shutdownTelemetry().then(
+        () => true,
+        (error2) => {
+          log2(
+            state,
+            `Telemetry flush failed during shutdown: ${error2 instanceof Error ? error2.message : String(error2)}`,
+            "warn"
+          );
+          return true;
+        }
+      );
+      const timedOut = new Promise((resolve3) => {
+        timer = setTimeout(() => resolve3(false), telemetryBudgetMs);
+      });
+      if (!await Promise.race([flushed, timedOut])) {
+        log2(state, `Telemetry flush exceeded ${telemetryBudgetMs}ms \u2014 exiting anyway`, "warn");
+      }
+      clearTimeout(timer);
+    });
+    const breakdown = Object.entries(durations).map(([phase, ms]) => `${phase}=${ms}ms`).join(" ");
+    log2(state, `Shutdown complete in ${Date.now() - shutdownStartedAt}ms (${breakdown})`);
     process.exit(0);
   };
   process.on("SIGINT", handleSignal);
@@ -4348,7 +5880,9 @@ async function run(options) {
       if (!interactive) {
         printError("Authentication required");
         blank();
-        console.log(chalk6.dim("Set EVIDENT_AGENT_KEY environment variable for CI"));
+        console.log(
+          chalk6.dim("Set EVIDENT_RUNNER_KEY (or EVIDENT_AGENT_KEY) environment variable for CI")
+        );
         console.log(chalk6.dim("Or run `evident login` for interactive authentication"));
         blank();
         process.exit(1);
@@ -4362,26 +5896,51 @@ async function run(options) {
       );
     }
     state.authHeader = getAuthHeader(credentials2);
+    if (credentials2.notice) {
+      log2(state, credentials2.notice, "warn");
+      if (state.interactive && !state.json) {
+        logActivity(state, { type: "info", level: "warn", message: credentials2.notice });
+      }
+    }
+    if (credentials2.keySource === "agent_key") {
+      telemetry.info(
+        EventTypes.DEPRECATED_AGENT_KEY_ENV_USED,
+        "Deprecated EVIDENT_AGENT_KEY env var used instead of EVIDENT_RUNNER_KEY",
+        { command: "run" },
+        state.agentId
+      );
+      const agentKeyNotice = "EVIDENT_AGENT_KEY is deprecated, use EVIDENT_RUNNER_KEY instead; will be removed in a future release.";
+      log2(state, agentKeyNotice, "warn");
+      if (state.interactive && !state.json) {
+        logActivity(state, { type: "info", level: "warn", message: agentKeyNotice });
+      }
+    }
     if (!state.agentId) {
       if (credentials2.authType === "agent_key") {
         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 {
-        printError("--agent is required when not using EVIDENT_AGENT_KEY");
+        printError(
+          "--runner (or --agent) is required when not using EVIDENT_RUNNER_KEY or EVIDENT_AGENT_KEY"
+        );
         blank();
-        console.log(chalk6.dim("Either provide --agent <id> or set EVIDENT_AGENT_KEY"));
+        console.log(
+          chalk6.dim(
+            "Either provide --runner/--agent <id> or set EVIDENT_RUNNER_KEY/EVIDENT_AGENT_KEY"
+          )
+        );
         blank();
         process.exit(1);
       }
@@ -4403,7 +5962,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");
@@ -4415,15 +5974,30 @@ 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 microvmId = process.env.MICROVM_ID?.trim();
+    if (microvmId) {
+      const reported = await reportMicrovmId(state.agentId, state.authHeader, microvmId);
+      if (reported.ok) {
+        log2(state, "Reported MicroVM identity so this runner can be resumed rather than restarted");
+      } else {
+        const message = `Could not report MicroVM identity (future wakes will cold-start): ${reported.error}`;
+        log2(state, message, "warn");
+        if (state.interactive && !state.json) {
+          logActivity(state, { type: "info", level: "warn", message });
+        }
+      }
+    } else {
+      log2(state, "Not running in a MicroVM (MICROVM_ID unset) \u2014 nothing to report", "debug");
+    }
     const ocSpinner = interactive && !state.json ? ora3("Checking OpenCode...").start() : null;
     try {
       const oc = await ensureOpenCodeRunning({
@@ -4440,9 +6014,24 @@ 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 });
+        }
+      }
+      const noProviderWarning = buildNoProviderWarning(await hasAnyConfiguredProvider(state.port));
+      if (noProviderWarning) {
+        log2(state, noProviderWarning, "warn");
+        if (state.interactive && !state.json) {
+          logActivity(state, { type: "info", level: "warn", message: noProviderWarning });
+          blank();
+          console.log(chalk6.yellow("\u26A0 No OpenCode model provider is configured."));
+          console.log(
+            chalk6.dim(
+              `Run ${chalk6.cyan("opencode auth login")} to set one up \u2014 messages will fail until then.`
+            )
+          );
+          blank();
         }
       }
     } catch (error2) {
@@ -4457,11 +6046,21 @@ 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
-      })
+      // #559: the `--enable-file-sync-to` allow-list. Empty ⇒ pending files are
+      // REJECTED with `file_sync_disabled` on the ack, not silently ignored.
+      fileSyncDirectories,
+      homeDir: homedir2(),
+      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({
@@ -4475,7 +6074,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,
@@ -4532,6 +6131,12 @@ async function run(options) {
         onDrainPing: () => {
           if (!state.running) return;
           logActivity(state, { type: "info", message: "Drain ping received \u2014 draining" });
+          void channelDriver.syncPendingFiles().catch(
+            (error2) => logActivity(state, {
+              type: "error",
+              error: `Runner file sync failed on ping: ${error2 instanceof Error ? error2.message : String(error2)}`
+            })
+          );
           channelDriver.drainPending().then((processed) => {
             if (processed > 0) {
               state.messageCount += processed;
@@ -4590,7 +6195,7 @@ async function run(options) {
     }
     telemetry.error(EventTypes.CLI_ERROR, `Run command failed: ${message}`, {
       command: "run",
-      agentId: options.agent
+      agentId: options.runner || options.agent
     });
     await shutdownTelemetry();
     process.exit(1);
@@ -4615,7 +6220,13 @@ 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").option(
+program.command("run").description("Connect to Evident and process messages").option("--runner [id]", "Runner ID to connect to (optional when EVIDENT_RUNNER_KEY is set)").option(
+  "-a, --agent [id]",
+  "Deprecated alias for --runner (still supported; --runner wins if both are given)"
+).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(
@@ -4624,11 +6235,20 @@ program.command("run").description("Connect to Evident and process messages").op
 ).option(
   "--session-cleanup-interval <duration>",
   "How often the cleanup sweep runs (default: 1h). Env: EVIDENT_SESSION_CLEANUP_INTERVAL"
+).option(
+  "--enable-file-sync-to <dir>",
+  "Allow Evident to write files into this directory (repeatable). Omit to disable file sync entirely.",
+  (value, previous) => previous.concat([value]),
+  []
 ).action(
   (options) => {
     run({
       agent: options.agent,
+      runner: options.runner,
       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,
@@ -4636,7 +6256,10 @@ program.command("run").description("Connect to Evident and process messages").op
       // Raw strings — the resolver in run.ts single-sources parsing (M1).
       sessionCleanupMaxAge: options.sessionCleanupMaxAge,
       sessionCleanupMaxCount: options.sessionCleanupMaxCount,
-      sessionCleanupInterval: options.sessionCleanupInterval
+      sessionCleanupInterval: options.sessionCleanupInterval,
+      // Raw values — expansion/validation is single-sourced in run.ts's
+      // resolveFileSyncDirectories.
+      enableFileSyncTo: options.enableFileSyncTo
     });
   }
 );