@evident-ai/cli 3.1.1-dev.51bb5fa → 3.1.1-dev.5a3c6a5

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() {
@@ -719,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" };
 }
@@ -1267,6 +1313,16 @@ async function buildFileParts(attachments, capable) {
       );
       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;
@@ -1348,7 +1404,7 @@ async function sendPromptAsync(port, sessionId, content, options, attachments) {
       }
     }
     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;
@@ -1684,10 +1740,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();
@@ -1721,12 +1778,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));
         };
       });
     }
@@ -1843,7 +1900,7 @@ function connectTunnel(options) {
   } = 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
@@ -1898,7 +1955,7 @@ function connectTunnel(options) {
           clearTimeout(connectionTimeout);
           const connectedAgentId = message.agent_id ?? agentId;
           onConnected?.(connectedAgentId);
-          resolve2({
+          resolve3({
             ws,
             close: () => ws.close(1e3, "CLI shutdown")
           });
@@ -1960,7 +2017,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;
     }
@@ -2012,6 +2073,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;
@@ -2041,6 +2500,7 @@ var DEFAULT_STUCK_QUEUED_MS = 6e4;
 var HEARTBEAT_MS = 6e4;
 var ABSOLUTE_MAX_PROCESSING_MS = 6 * 60 * 60 * 1e3;
 var POLL_MISS_GRACE_MS = HEARTBEAT_MS;
+var MAX_SUPERSEDED_CONVERSATIONS = 256;
 var ChannelAuthError = class extends Error {
   constructor(message) {
     super(message);
@@ -2077,8 +2537,38 @@ var ChannelDriver = class _ChannelDriver {
   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
@@ -2201,6 +2691,24 @@ var ChannelDriver = class _ChannelDriver {
   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
@@ -2231,6 +2739,8 @@ var ChannelDriver = class _ChannelDriver {
     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() {
@@ -2258,6 +2768,47 @@ var ChannelDriver = class _ChannelDriver {
     );
     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 {
@@ -2291,6 +2842,28 @@ var ChannelDriver = class _ChannelDriver {
     }
     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
@@ -2352,7 +2925,7 @@ var ChannelDriver = class _ChannelDriver {
         await this.sleep(step);
       }
     }
-    while (this.hasInFlightWatchers()) {
+    while (this.hasInFlightWatchers() || this.syncingFiles) {
       if (this.now() >= deadline) return false;
       await this.sleep(step);
     }
@@ -2387,10 +2960,15 @@ var ChannelDriver = class _ChannelDriver {
    * @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)) {
@@ -2417,7 +2995,8 @@ var ChannelDriver = class _ChannelDriver {
       } 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: "warn",
@@ -2427,15 +3006,39 @@ var ChannelDriver = class _ChannelDriver {
           });
           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({
@@ -2461,8 +3064,42 @@ var ChannelDriver = class _ChannelDriver {
     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) {
@@ -2472,12 +3109,12 @@ var ChannelDriver = class _ChannelDriver {
           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
@@ -2565,7 +3202,11 @@ var ChannelDriver = class _ChannelDriver {
    * (not-owned / out-of-range / deleted-at-source / workspace gone) / 413
    * (over-cap). On ANY non-2xx or thrown failure we return `null` so the caller
    * OMITS that one image and the text turn still sends — NEVER throws the turn.
-   * Failures are logged with context (no silent swallow).
+   * 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 {
@@ -2574,6 +3215,25 @@ var ChannelDriver = class _ChannelDriver {
         { 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)`,
@@ -2613,6 +3273,9 @@ var ChannelDriver = class _ChannelDriver {
     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`,
@@ -2622,7 +3285,8 @@ var ChannelDriver = class _ChannelDriver {
     void this.postSignal(conversationId, messageId, "attachments_skipped", {
       skipped,
       failed,
-      ...skipped > 0 ? { skipped_reason: skippedReason } : {}
+      ...skipped > 0 ? { skipped_reason: skippedReason } : {},
+      ...failedReason ? { failed_reason: failedReason } : {}
     });
   }
   /** Register a freshly-dispatched message with its session's watcher state. */
@@ -3909,6 +4573,32 @@ var ChannelDriver = class _ChannelDriver {
     }
     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',
@@ -3938,7 +4628,7 @@ var ChannelDriver = class _ChannelDriver {
         headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
         body: JSON.stringify({
           status: "processing",
-          opencode_session_id: sessionId,
+          ...this.sessionIdBody(sessionId, conversationId, messageId, "processing"),
           ...opencodeMessageId ? { opencode_message_id: opencodeMessageId } : {},
           ...title ? { title } : {}
         })
@@ -3987,6 +4677,11 @@ var ChannelDriver = class _ChannelDriver {
         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 } : {},
           ...title ? { title } : {},
@@ -4003,14 +4698,23 @@ var ChannelDriver = class _ChannelDriver {
   }
   /**
    * 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, 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(
@@ -4427,6 +5131,34 @@ function resolveLogLevel(options) {
   }
   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];
 }
@@ -4548,18 +5280,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) {
@@ -4588,7 +5331,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) {
@@ -4733,8 +5476,10 @@ async function cleanup(state, opts = {}) {
 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) {
@@ -4769,6 +5514,11 @@ 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,
@@ -4961,6 +5711,10 @@ async function run(options) {
       getAuthHeader: () => state.authHeader,
       conversationFilter: state.conversationFilter,
       stuckQueuedMs: CHANNEL_STUCK_QUEUED_MS,
+      // #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`
@@ -5042,6 +5796,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;
@@ -5125,7 +5885,10 @@ 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]", "Runner ID to connect to (optional when EVIDENT_AGENT_KEY is set)").option("--runner [id]", "Alias for --agent (preferred name; wins if both are given)").option("-p, --port <port>", "OpenCode port (default: 4096)", "4096").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(
@@ -5137,6 +5900,11 @@ 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({
@@ -5153,7 +5921,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
     });
   }
 );