@evident-ai/cli 3.1.1-dev.fe0815c → 3.2.1-dev.0fe02fb

package/dist/index.js

@@ -212,6 +212,7 @@ var api = {
 
 // src/lib/keychain.ts
 var SERVICE_NAME = "evident-cli";
+var keytarWarned = false;
 async function getKeytar() {
   try {
     const keytar = await import("keytar");
@@ -219,7 +220,13 @@ async function getKeytar() {
       return null;
     }
     return keytar;
-  } catch {
+  } catch (err) {
+    if (!keytarWarned) {
+      keytarWarned = true;
+      console.warn(
+        `System keychain unavailable, falling back to file-based credential storage: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     return null;
   }
 }
@@ -368,8 +375,9 @@ async function deviceFlowLogin(options) {
     await waitForEnter("Press Enter to open the browser...");
     try {
       await open(verification_uri);
-    } catch {
-      console.log(chalk2.dim("Could not open browser. Please visit the URL manually."));
+    } catch (error2) {
+      const message = error2 instanceof Error ? error2.message : String(error2);
+      console.log(chalk2.dim(`Could not open browser (${message}). Please visit the URL manually.`));
     }
   }
   const spinner = ora("Waiting for authentication...").start();
@@ -797,6 +805,16 @@ async function checkStatus(jsonMode) {
       exitCode: 1
     };
   }
+  if (response.status === 404) {
+    return {
+      ok: false,
+      endpoint: apiUrl,
+      authLabel: authLabelFor(credentials2),
+      reason: "endpoint_not_found",
+      error: `${apiUrl}/me returned HTTP 404 \u2014 that endpoint has no /me route, so it is probably missing the /v1 prefix. The credentials were NOT validated.`,
+      exitCode: 75
+    };
+  }
   if (response.status >= 500) {
     const serverMessage = await readErrorMessage(response);
     return {
@@ -899,14 +917,25 @@ function readClaudeCliCredentials() {
         { encoding: "utf-8", timeout: 2e3, stdio: ["pipe", "pipe", "ignore"] }
       );
       return parseClaudeCliCredentials(raw);
-    } catch {
+    } catch (err) {
+      if (err.status !== 44) {
+        console.warn(
+          `readClaudeCliCredentials: security find-generic-password failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
       return null;
     }
   }
   try {
     const raw = readFileSync(join(homedir(), ".claude", ".credentials.json"), "utf-8");
     return parseClaudeCliCredentials(raw);
-  } catch {
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT" && code !== "ENOTDIR") {
+      console.warn(
+        `readClaudeCliCredentials: reading .claude/.credentials.json failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     return null;
   }
 }
@@ -994,7 +1023,7 @@ async function claudeUsage() {
 
 // src/commands/run.ts
 import { homedir as homedir3 } from "os";
-import { isAbsolute as isAbsolute2, join as join3, parse, resolve as resolvePath } from "path";
+import { isAbsolute as isAbsolute2, join as join4, parse, resolve as resolvePath } from "path";
 import chalk6 from "chalk";
 
 // ../../packages/types/src/agents/index.ts
@@ -1023,6 +1052,7 @@ var MAX_FILE_SYNC_DIRECTORIES = 16;
 
 // ../../packages/types/src/logging/index.ts
 var CORRELATION_ID_HEADER = "x-evident-correlation-id";
+var FORWARD_FAILURE_REASON_HEADER = "X-Evident-Failure-Reason";
 function log(level, event, fields) {
   const method = level === "debug" ? "log" : level;
   try {
@@ -1404,7 +1434,10 @@ function findOpenCodeProcesses() {
               }
             }
           }
-        } catch {
+        } catch (err) {
+          console.warn(
+            `findOpenCodeProcesses: ps fallback failed: ${err instanceof Error ? err.message : String(err)}`
+          );
         }
       }
       for (const pid of pids) {
@@ -1427,7 +1460,10 @@ function findOpenCodeProcesses() {
         }
       }
     }
-  } catch {
+  } catch (err) {
+    console.warn(
+      `findOpenCodeProcesses: process detection failed: ${err instanceof Error ? err.message : String(err)}`
+    );
   }
   return instances;
 }
@@ -1501,7 +1537,12 @@ function stopOpenCode(opencodeProcess) {
     } else {
       process.kill(-opencodeProcess.pid, "SIGTERM");
     }
-  } catch {
+  } catch (err) {
+    if (err.code !== "ESRCH") {
+      console.warn(
+        `stopOpenCode: kill failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
   }
 }
 
@@ -2066,7 +2107,9 @@ function messageRunState(messages, userMessageId) {
   }
   if (!reply) return "queued";
   if (isAssistantInFlight(reply)) return "running";
-  return errorOf(reply) != null ? "failed" : "done";
+  if (errorOf(reply) != null) return "failed";
+  if (isAmbiguousTerminalFinish(reply)) return "running";
+  return "done";
 }
 function isPreamblePinnedRunning(messages, userMessageId) {
   if (messageRunState(messages, userMessageId) !== "running") return false;
@@ -2076,6 +2119,19 @@ function isPreamblePinnedRunning(messages, userMessageId) {
 function isB2AbandonmentConfirmed(params) {
   return params.pinnedForMs >= params.minPinnedMs && params.descendantOngoing === false;
 }
+function isAmbiguousTerminalFinish(m) {
+  if (completedOf(m) == null) return false;
+  if (errorOf(m) != null) return false;
+  const finish = finishOf(m);
+  return finish !== "tool-calls" && finish !== "stop";
+}
+function isAmbiguousFinishPinnedRunning(messages, userMessageId) {
+  const reply = findLastAssistantReplyFor(messages, userMessageId);
+  return isAmbiguousTerminalFinish(reply);
+}
+function isAmbiguousFinishResolved(params) {
+  return params.sessionOngoing === false || params.pinnedForMs >= params.maxPinnedMs;
+}
 function messageError(messages, userMessageId) {
   const reply = findLastAssistantReplyFor(messages, userMessageId);
   const error2 = errorOf(reply);
@@ -2089,6 +2145,21 @@ function messageError(messages, userMessageId) {
   }
   return "The agent run failed.";
 }
+function isAbortedTerminalReply(messages, userMessageId) {
+  const reply = findLastAssistantReplyFor(messages, userMessageId);
+  const error2 = errorOf(reply);
+  if (error2 == null) return false;
+  if (typeof error2 === "string") return error2.trim() === "Aborted";
+  if (typeof error2 === "object") {
+    const e = error2;
+    if (e.name === "MessageAbortedError") return true;
+    if (e.name === "AbortError") return true;
+    const dataMessage = e.data?.message;
+    const rendered = typeof dataMessage === "string" ? dataMessage : typeof e.message === "string" ? e.message : null;
+    return rendered != null && rendered.trim() === "Aborted";
+  }
+  return false;
+}
 function messageFailure(messages, userMessageId) {
   const reply = findLastAssistantReplyFor(messages, userMessageId);
   const error2 = errorOf(reply);
@@ -2267,6 +2338,149 @@ function resolveSessionCleanupConfig(flags, env = process.env) {
   return { enabled, maxAgeMs, maxCount, intervalMs, warnings };
 }
 
+// src/lib/opencode/session-db-size.ts
+import { statSync as statSync2 } from "fs";
+import { join as join2 } from "path";
+var LARGE_DB_THRESHOLD_BYTES = 268435456;
+function statSessionDbBytes(homeDir) {
+  const dbPath = join2(homeDir, ".local", "share", "opencode", "opencode.db");
+  try {
+    return statSync2(dbPath).size;
+  } catch (err) {
+    const isMissingFile = err instanceof Error && "code" in err && err.code === "ENOENT";
+    if (!isMissingFile) {
+      console.error(
+        `[statSessionDbBytes] could not stat ${dbPath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    return null;
+  }
+}
+function buildSessionStoreSizeWarning(input) {
+  const { dbBytes, cleanupEnabled, reclaimSkipReason } = input;
+  if (dbBytes === null || dbBytes <= LARGE_DB_THRESHOLD_BYTES) return null;
+  const mib = Math.round(dbBytes / 1024 / 1024);
+  if (!cleanupEnabled) {
+    return `Session store is large: opencode.db is ${mib} MiB and automatic session cleanup is off. Enable it with --session-cleanup-max-age 24h (env EVIDENT_SESSION_CLEANUP_MAX_AGE) to stop it growing \u2014 a store much larger than this can exceed a hosted runner's session-history restore budget on the next start, losing this runner's session history.`;
+  }
+  if (reclaimSkipReason === "sqlite-unavailable" || reclaimSkipReason === "insufficient-disk-space") {
+    const reasonText = reclaimSkipReason === "sqlite-unavailable" ? "this Node runtime lacks node:sqlite (needs Node >=22.5)" : "there is not enough free disk space to compact it";
+    return `Session store is large: opencode.db is ${mib} MiB. Automatic session cleanup is on, but space cannot currently be reclaimed because ${reasonText} \u2014 a store this large can exceed a hosted runner's session-history restore budget on the next start, losing this runner's session history.`;
+  }
+  return null;
+}
+
+// src/lib/opencode/session-db-reclaim.ts
+import { statSync as statSync3, statfsSync } from "fs";
+import { dirname as dirname2 } from "path";
+function insufficientSpaceReason(dbPath, requiredBytes) {
+  try {
+    const fsStats = statfsSync(dirname2(dbPath));
+    const availableBytes = fsStats.bavail * fsStats.bsize;
+    if (availableBytes < requiredBytes) {
+      return `only ${availableBytes} bytes free, need ${requiredBytes} for a second copy`;
+    }
+    return null;
+  } catch (err) {
+    return `could not check free space (${err instanceof Error ? err.message : String(err)}); refusing to guess`;
+  }
+}
+function readLogicalBytes(db) {
+  const pageCount = db.prepare("PRAGMA page_count").get().page_count;
+  const pageSize = db.prepare("PRAGMA page_size").get().page_size;
+  return pageCount * pageSize;
+}
+function readCheckpointResult(db) {
+  const row = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+  return { busy: row.busy !== 0, log: row.log, checkpointed: row.checkpointed };
+}
+async function probeReclaimAvailability(input) {
+  const { dbPath, requiredBytes } = input;
+  let sqlite;
+  try {
+    sqlite = await import("sqlite");
+  } catch (err) {
+    console.warn(
+      `[probeReclaimAvailability] node:sqlite unavailable for ${dbPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return "sqlite-unavailable";
+  }
+  let autoVacuum = null;
+  try {
+    const db = new sqlite.DatabaseSync(dbPath, { readOnly: true });
+    try {
+      autoVacuum = db.prepare("PRAGMA auto_vacuum").get().auto_vacuum;
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    console.warn(
+      `[probeReclaimAvailability] could not read auto_vacuum mode for ${dbPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (autoVacuum !== 0) return null;
+  return insufficientSpaceReason(dbPath, requiredBytes) !== null ? "insufficient-disk-space" : null;
+}
+async function reclaimSessionDbSpace(input) {
+  const { dbPath, maxPages, allowFullVacuum = true } = input;
+  let sqlite;
+  try {
+    sqlite = await import("sqlite");
+  } catch (err) {
+    console.warn(
+      `[reclaimSessionDbSpace] node:sqlite unavailable (need Node >=22.5, >=22.13 unflagged) for ${dbPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return { ok: false, skipped: "sqlite-unavailable" };
+  }
+  const { DatabaseSync } = sqlite;
+  let db;
+  try {
+    db = new DatabaseSync(dbPath);
+    const autoVacuum = db.prepare("PRAGMA auto_vacuum").get().auto_vacuum;
+    if (autoVacuum === 0) {
+      if (!allowFullVacuum) {
+        console.warn(
+          `[reclaimSessionDbSpace] skipping VACUUM conversion of ${dbPath}: a session turn is live`
+        );
+        return { ok: false, skipped: "full-vacuum-blocked" };
+      }
+      const fileBytesForGuard = statSync3(dbPath).size;
+      const skipReason = insufficientSpaceReason(dbPath, fileBytesForGuard);
+      if (skipReason !== null) {
+        console.warn(
+          `[reclaimSessionDbSpace] skipping VACUUM conversion of ${dbPath}: ${skipReason}`
+        );
+        return { ok: false, skipped: "insufficient-disk-space" };
+      }
+      const beforeBytes = readLogicalBytes(db);
+      db.exec("PRAGMA auto_vacuum=INCREMENTAL");
+      db.exec("VACUUM");
+      const afterBytes = readLogicalBytes(db);
+      const checkpoint = readCheckpointResult(db);
+      return { ok: true, mode: "convert", beforeBytes, afterBytes, checkpoint };
+    }
+    if (autoVacuum === 2) {
+      const beforeBytes = readLogicalBytes(db);
+      const bound = Math.max(0, Math.trunc(maxPages));
+      db.exec(`PRAGMA incremental_vacuum(${bound})`);
+      const afterBytes = readLogicalBytes(db);
+      const checkpoint = readCheckpointResult(db);
+      return { ok: true, mode: "incremental", beforeBytes, afterBytes, checkpoint };
+    }
+    console.warn(
+      `[reclaimSessionDbSpace] ${dbPath} has auto_vacuum=${autoVacuum} (neither NONE nor INCREMENTAL); nothing to reclaim`
+    );
+    return { ok: false, skipped: "auto-vacuum-not-applicable" };
+  } catch (err) {
+    console.error(
+      `[reclaimSessionDbSpace] reclaim failed for ${dbPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return { ok: false, skipped: "reclaim-error" };
+  } finally {
+    db?.close();
+  }
+}
+
 // src/lib/tunnel/connection.ts
 import WebSocket2 from "ws";
 
@@ -2432,6 +2646,17 @@ var StreamForwarder = class {
 };
 
 // src/lib/tunnel/connection.ts
+var FAILURE_REASON_HEADER_LC = FORWARD_FAILURE_REASON_HEADER.toLowerCase();
+var TunnelUpgradeRejectedError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+  }
+};
+function classifyUpgradeRejection(headers) {
+  const value = headers[FAILURE_REASON_HEADER_LC];
+  return value === "do_code_updated" ? "do_code_updated" : "unknown";
+}
 var MAX_RECONNECT_DELAY = 3e4;
 var BASE_RECONNECT_DELAY = 500;
 function getReconnectDelay(attempt) {
@@ -2476,6 +2701,7 @@ function connectTunnel(options) {
     onError,
     onResponse,
     onInfo,
+    onWarning,
     onDrainPing
   } = options;
   const tunnelUrl = getTunnelUrlConfig();
@@ -2495,8 +2721,11 @@ function connectTunnel(options) {
       reject(new Error("Connection timeout"));
     }, 3e4);
     let upgradeRejection = null;
+    let upgradeRejectionReason = null;
     ws.on("unexpected-response", (_req, res) => {
       clearTimeout(connectionTimeout);
+      const reason = classifyUpgradeRejection(res.headers);
+      upgradeRejectionReason = reason;
       const chunks = [];
       res.on("data", (chunk) => chunks.push(chunk));
       res.on("end", () => {
@@ -2510,8 +2739,14 @@ function connectTunnel(options) {
         }
         const statusLine = `HTTP ${res.statusCode}${res.statusMessage ? ` ${res.statusMessage}` : ""}`;
         upgradeRejection = detail ? `${statusLine}: ${detail}` : statusLine;
-        onError?.(`Tunnel refused by relay (${upgradeRejection})`);
-        reject(new Error(`Tunnel handshake rejected: ${upgradeRejection}`));
+        if (reason === "do_code_updated") {
+          onWarning?.("Relay redeployed \u2014 reconnecting");
+        } else {
+          onError?.(`Tunnel refused by relay (${upgradeRejection})`);
+        }
+        reject(
+          new TunnelUpgradeRejectedError(`Tunnel handshake rejected: ${upgradeRejection}`, reason)
+        );
       });
     });
     ws.on("open", () => {
@@ -2557,8 +2792,14 @@ function connectTunnel(options) {
     ws.on("error", (error2) => {
       clearTimeout(connectionTimeout);
       const detail = upgradeRejection ?? describeSocketError(error2, url);
-      onError?.(`Connection error: ${detail}`);
-      reject(upgradeRejection ? new Error(upgradeRejection) : new Error(detail));
+      if (upgradeRejectionReason === "do_code_updated") {
+        onWarning?.("Relay redeployed \u2014 reconnecting");
+      } else {
+        onError?.(`Connection error: ${detail}`);
+      }
+      reject(
+        upgradeRejectionReason !== null ? new TunnelUpgradeRejectedError(detail, upgradeRejectionReason) : new Error(detail)
+      );
     });
     ws.on("close", (code, reason) => {
       const reasonStr = reason.toString() || upgradeRejection || (code === 1006 ? "abnormal closure" : "No reason provided");
@@ -2634,7 +2875,8 @@ var RunnerConnection = class {
           onError: (error2) => events.onError?.(error2),
           onResponse: () => events.onResponse?.(),
           onDrainPing: () => events.onDrainPing?.(),
-          onInfo: (message) => events.onInfo?.(message)
+          onInfo: (message) => events.onInfo?.(message),
+          onWarning: (message) => events.onWarning?.(message)
         });
         return;
       } catch (error2) {
@@ -2645,7 +2887,12 @@ var RunnerConnection = class {
         }
         const delay = getReconnectDelay(this.reconnectAttempt);
         events.onReconnecting?.(this.reconnectAttempt);
-        events.onError?.(`Connection failed, retrying in ${Math.round(delay / 1e3)}s...`);
+        const retryMessage = `Connection failed, retrying in ${Math.round(delay / 1e3)}s...`;
+        if (error2 instanceof TunnelUpgradeRejectedError && error2.reason === "do_code_updated") {
+          events.onWarning?.(retryMessage);
+        } else {
+          events.onError?.(retryMessage);
+        }
         await this.sleep(delay);
       }
     }
@@ -2702,7 +2949,7 @@ import { homedir as homedir2 } 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 as join2, relative, resolve as resolve2, sep } from "path";
+import { basename, dirname as dirname3, isAbsolute, join as join3, relative, resolve as resolve2, sep } from "path";
 var FILE_MODE = 384;
 var DIRECTORY_MODE = 448;
 async function writePushedFile(request) {
@@ -2733,9 +2980,9 @@ async function writePushedFile(request) {
   }
   try {
     const { existingAncestor, missingSegments } = await resolveNearestExistingAncestor(
-      dirname2(candidate)
+      dirname3(candidate)
     );
-    const realTarget = join2(existingAncestor, ...missingSegments, basename(candidate));
+    const realTarget = join3(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.", {
@@ -2745,8 +2992,8 @@ async function writePushedFile(request) {
     }
     if (missingSegments.length > 0) {
       await createMissingDirectories(existingAncestor, missingSegments);
-      const realParent = await realpath(dirname2(realTarget));
-      if (realParent !== dirname2(realTarget) || !contains(allowedDirectory, realTarget)) {
+      const realParent = await realpath(dirname3(realTarget));
+      if (realParent !== dirname3(realTarget) || !contains(allowedDirectory, realTarget)) {
         return refuse("path_not_allowed", "The runner does not allow writing to that location.", {
           path: realTarget,
           bytes,
@@ -2771,7 +3018,7 @@ function expandAndValidate(requestedPath, homeDir) {
   if (requestedPath.trim() === "" || requestedPath.includes("\0")) {
     return null;
   }
-  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join2(homeDir, requestedPath.slice(2)) : requestedPath;
+  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join3(homeDir, requestedPath.slice(2)) : requestedPath;
   if (expanded.split(/[/\\]/).includes("..")) {
     return null;
   }
@@ -2789,7 +3036,7 @@ async function resolveNearestExistingAncestor(directory) {
     try {
       return { existingAncestor: await realpath(current), missingSegments };
     } catch (err) {
-      const parent = dirname2(current);
+      const parent = dirname3(current);
       if (err.code !== "ENOENT" || parent === current) {
         throw err;
       }
@@ -2844,13 +3091,13 @@ function contains(realDirectory, realTarget) {
 async function createMissingDirectories(existingAncestor, missingSegments) {
   let current = existingAncestor;
   for (const segment of missingSegments) {
-    current = join2(current, segment);
+    current = join3(current, segment);
     await mkdir(current, { recursive: true, mode: DIRECTORY_MODE });
     await chmod(current, DIRECTORY_MODE);
   }
 }
 async function writeAtomically(realTarget, content) {
-  const temporaryPath = join2(dirname2(realTarget), `.evident-push-${randomUUID()}.tmp`);
+  const temporaryPath = join3(dirname3(realTarget), `.evident-push-${randomUUID()}.tmp`);
   let handle;
   try {
     handle = await open2(temporaryPath, "wx", FILE_MODE);
@@ -3123,9 +3370,11 @@ 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 AMBIGUOUS_FINISH_MAX_PINNED_MS = 3 * 6e4;
 var B2_ABANDONMENT_RECHECK_MS = HEARTBEAT_MS;
 var POLL_MISS_GRACE_MS = HEARTBEAT_MS;
 var MAX_SUPERSEDED_CONVERSATIONS = 256;
+var MAX_IDENTICAL_REDRIVE_POLL_FAILURES = 5;
 var ChannelAuthError = class extends Error {
   constructor(message) {
     super(message);
@@ -3148,6 +3397,10 @@ function backoffDelay(attempt, policy) {
 function isRetryableStatus(status2) {
   return status2 === 429 || status2 >= 500 && status2 <= 599;
 }
+var VOLATILE_BODY_FIELD_PATTERN = /("(?:ref|requestId|request_id|traceId|trace_id)"\s*:\s*)"[^"]*"/gi;
+function normalizeRedrivePollFailureBody(body) {
+  return body.replace(VOLATILE_BODY_FIELD_PATTERN, '$1"<redacted>"').replace(/\s+/g, " ").trim().slice(0, 200);
+}
 var ChannelDriver = class _ChannelDriver {
   agentId;
   port;
@@ -3164,6 +3417,7 @@ var ChannelDriver = class _ChannelDriver {
   now;
   fileSyncDirectories;
   homeDir;
+  maxActiveSessions;
   /** Cache of conversationId → opencode sessionId. */
   sessions = /* @__PURE__ */ new Map();
   /**
@@ -3279,6 +3533,66 @@ var ChannelDriver = class _ChannelDriver {
    * ADR-0047's own "unreachable ⇒ bounded" rule). Cleared on any other outcome.
    */
   redriveUnresolvedSince = /* @__PURE__ */ new Map();
+  /**
+   * Consecutive-identical-poll-failure streak for the re-drive fence (#1348),
+   * keyed by Evident **message id** (not session) so `clearRedriveUnresolved`
+   * can drop it with the other two trackers and it cannot leak. `sessionId` is
+   * carried inside the entry, not the key: a session change is a different
+   * situation and resets the streak, which gives the `(sessionId, message.id)`
+   * pairing #1348 asks for without a composite map key.
+   */
+  redrivePollFailures = /* @__PURE__ */ new Map();
+  /**
+   * "Already emitted `redrive_outcome_unreported` for THIS (message, outcome)
+   * streak" (Class B, #1340: the runner DECIDED reattach/settle/fail_permanent
+   * but its own PATCH to record it failed — distinct from Class A's
+   * `redrive_poll_failed`, where opencode itself can't be observed). Keyed by
+   * message id, valued by the outcome currently failing to report, so a
+   * change of outcome starts a fresh signal. Cleared by
+   * `clearRedriveUnresolved` the instant either PATCH succeeds.
+   */
+  redriveOutcomeUnreportedSignalled = /* @__PURE__ */ new Map();
+  /**
+   * First `now()` a Class B outcome PATCH (reattach/settle/fail_permanent) was
+   * observed to fail for this message (#1366's failure-window trip arm,
+   * `boundRedriveOutcome`). Duration, not a tick count — bounded by the
+   * existing `pausedMaxWaitMs` window (reusing the knob, not a new constant).
+   * Cleared by `clearRedriveUnresolved` the instant the original PATCH
+   * succeeds.
+   */
+  redriveOutcomeFailingSince = /* @__PURE__ */ new Map();
+  /**
+   * "Already posted `redrive_outcome_abandoned` with `reported: false` for this
+   * row" (#1366) — the bound tripped but the terminal `markFailed` fallback ALSO
+   * failed (the route-level fault of G2), so every following tick re-attempts
+   * the same terminal PATCH. Guards that quiet retry from re-signalling on
+   * every tick. Cleared by `clearRedriveUnresolved`.
+   */
+  redriveOutcomeAbandonedSignalled = /* @__PURE__ */ new Set();
+  /**
+   * "Already emitted `dispatch_not_started` for THIS (message, branch) streak"
+   * (#1340). Valued by the branch currently firing, so a row that moves between
+   * exits re-signals — the move IS the finding. Cleared only on a CONFIRMED
+   * dispatch, never on the fence's decision to dispatch: `clearRedriveUnresolved`
+   * runs on that decision (`resolveRedriveUnresolved`), so clearing there would
+   * re-signal on every one of the 15h of re-dispatch attempts #1110 made.
+   */
+  dispatchNotStartedSignalled = /* @__PURE__ */ new Map();
+  /**
+   * Consecutive-UNCONFIRMED-dispatch streak for a `pending` row with NO stored
+   * `opencode_message_id` yet — i.e. one that has never even reached the
+   * re-drive fence above. `sendPromptAsync`'s POST may 2xx, but its own
+   * read-back retries can never confirm the assigned id when the session's
+   * message list is PERMANENTLY unreadable (e.g. a corrupted local opencode
+   * SQLite DB, #1345/#1348's exact fault, just hit BEFORE the row is ever
+   * dispatched instead of after). Unlike an already-dispatched row, THIS row has
+   * no other safety net at all: the lifecycle cron only reclaims `status =
+   * 'processing'` rows, and a row stuck here never reaches `processing`. Keyed
+   * by message id, carrying `sessionId` so a session change (a fresh one bound
+   * after abandonment) starts a new streak rather than inheriting the old
+   * session's count — same shape as `redrivePollFailures` above.
+   */
+  unconfirmedDispatchFailures = /* @__PURE__ */ new Map();
   /**
    * "A null-id re-adopt re-dispatch is in flight, awaiting its read-back" (WI-5
    * Task 5.4, High-2). Since we no longer send a caller-supplied id, a re-dispatch
@@ -3384,6 +3698,7 @@ var ChannelDriver = class _ChannelDriver {
     this.now = config.now ?? (() => Date.now());
     this.fileSyncDirectories = config.fileSyncDirectories ?? [];
     this.homeDir = config.homeDir ?? homedir2();
+    this.maxActiveSessions = config.maxActiveSessions;
   }
   /** The IPv4-loopback base URL for the local `opencode serve`. */
   get opencodeBase() {
@@ -3463,10 +3778,26 @@ var ChannelDriver = class _ChannelDriver {
           message: `Found ${total} pending message(s) across ${conversations.length} conversation(s) \u2014 draining`
         });
       }
+      let cappedSkips = 0;
       for (const conv of conversations) {
         if (this.stopped) break;
+        if (this.maxActiveSessions !== void 0) {
+          const activeSessionIds = this.activeSessionIdsForCap();
+          const resolvedSessionId = this.sessions.get(conv.id) ?? conv.opencode_session_id;
+          const alreadyActive = resolvedSessionId != null && activeSessionIds.has(resolvedSessionId);
+          if (activeSessionIds.size >= this.maxActiveSessions && !alreadyActive) {
+            cappedSkips++;
+            continue;
+          }
+        }
         dispatched += await this.processConversation(conv);
       }
+      if (cappedSkips > 0) {
+        this.log({
+          level: "warn",
+          message: `max-active-sessions cap (${this.maxActiveSessions}) reached \u2014 skipped ${cappedSkips} pending conversation(s) this tick`
+        });
+      }
       await this.readoptProcessing();
     } finally {
       this.draining = false;
@@ -3485,6 +3816,22 @@ var ChannelDriver = class _ChannelDriver {
     }
     return false;
   }
+  /**
+   * Session ids active *for the `--max-active-sessions` cap*: in-flight work AND
+   * a live watcher loop. Unlike `hasInFlightWatchers()` / `protectedSessionIds()`,
+   * a ZOMBIE watcher (in-flight but `loop === null`, left by a non-auth failure
+   * inside `runWatcherLoop`) does not count here — under a cap it would
+   * permanently consume a slot, whereas cleanup/idle-exit should still treat it
+   * as protected. One call per drain iteration serves both the cap check
+   * (`.size`) and the already-active exemption (`.has`).
+   */
+  activeSessionIdsForCap() {
+    const ids = /* @__PURE__ */ new Set();
+    for (const [sessionId, watcher] of this.watchers) {
+      if (watcher.inFlight.size > 0 && watcher.loop !== null) ids.add(sessionId);
+    }
+    return ids;
+  }
   /**
    * File-pull work, for `run.ts`'s idle accounting (#559).
    *
@@ -3603,7 +3950,7 @@ var ChannelDriver = class _ChannelDriver {
    * @returns the count of messages NEWLY dispatched (not already in-flight).
    */
   async processConversation(conv) {
-    const { sessionId, refusedSessionId } = await this.ensureSession(conv);
+    const { sessionId, refusedSessionId, created: sessionCreated } = await this.ensureSession(conv);
     const messages = await this.getPendingMessages(conv.id);
     let dispatched = 0;
     let skippedAlreadyDispatched = 0;
@@ -3619,7 +3966,10 @@ var ChannelDriver = class _ChannelDriver {
         continue;
       }
       if (message.opencode_message_id) {
-        const outcome = await this.resolveRedrive(conv, sessionId, message, refusedSessionId);
+        const outcome = await this.resolveRedrive(conv, sessionId, message, sessionCreated);
+        if (outcome === "abandoned") {
+          continue;
+        }
         if (outcome !== "dispatch") {
           break;
         }
@@ -3653,6 +4003,7 @@ var ChannelDriver = class _ChannelDriver {
             conversation_id: conv.id,
             message_id: message.id
           });
+          this.signalDispatchNotStarted(conv, message, "session_deleted_race");
           break;
         }
         if (exists === null) {
@@ -3662,6 +4013,7 @@ var ChannelDriver = class _ChannelDriver {
             conversation_id: conv.id,
             message_id: message.id
           });
+          this.signalDispatchNotStarted(conv, message, "session_existence_unknown");
           break;
         }
         const errorMessage = err instanceof Error ? err.message : String(err);
@@ -3680,6 +4032,7 @@ var ChannelDriver = class _ChannelDriver {
             conversation_id: conv.id,
             message_id: message.id
           });
+          this.signalDispatchNotStarted(conv, message, "failure_unreported");
         });
         this.log({
           level: "error",
@@ -3690,14 +4043,40 @@ var ChannelDriver = class _ChannelDriver {
         break;
       }
       if (opencodeMessageId === null) {
+        const streak = this.recordUnconfirmedDispatch(message.id, sessionId);
+        if (streak < MAX_IDENTICAL_REDRIVE_POLL_FAILURES) {
+          this.log({
+            level: "warn",
+            message: `Message ${message.id.slice(0, 8)} dispatched but its opencode id could not be read back (${streak}/${MAX_IDENTICAL_REDRIVE_POLL_FAILURES}) \u2014 leaving un-tracked to retry next tick`,
+            conversation_id: conv.id,
+            message_id: message.id
+          });
+          this.signalDispatchNotStarted(conv, message, "readback_unconfirmed");
+          continue;
+        }
+        this.unconfirmedDispatchFailures.delete(message.id);
+        this.sessions.delete(conv.id);
+        this.supersede(conv.id, sessionId);
+        const errorMessage = `OpenCode accepted this message ${streak} times in a row but never confirmed its assigned id (session ${sessionId.slice(0, 8)}'s message list could not be read back) \u2014 the session was abandoned; a fresh one is used for further messages.`;
         this.log({
-          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`,
+          level: "error",
+          message: errorMessage,
           conversation_id: conv.id,
           message_id: message.id
         });
-        continue;
+        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.signalDispatchNotStarted(conv, message, "abandon_unreported");
+        });
+        break;
       }
+      this.unconfirmedDispatchFailures.delete(message.id);
+      this.dispatchNotStartedSignalled.delete(message.id);
       this.dispatched.add(message.id);
       this.registerInFlight(conv, sessionId, message, opencodeMessageId);
       dispatched += 1;
@@ -3718,21 +4097,29 @@ var ChannelDriver = class _ChannelDriver {
    * INJECTED `fetchImpl` — NOT the imported `getSessionMessages` helper, which
    * hits the global `fetch` and would bypass the same override every other
    * opencode poll in this file respects. Mirrors `readoptProcessing`'s own
-   * snapshot fetch (`:3081-3111`). `null` = unreadable (non-OK response,
-   * non-array body, or a network exception) — treated as "can't observe",
-   * never as "confirmed gone".
+   * snapshot fetch (`:3081-3111`).
+   *
+   * Returns `{ ok: true, messages }` on a readable snapshot, or
+   * `{ ok: false, signature }` on failure — `signature` is a string that
+   * repeats across attempts for the SAME underlying fault (used by the
+   * consecutive-identical-failure bound, #1348), or `null` for a thrown
+   * exception, which is NOT countable toward that bound (a network blip / an
+   * opencode restart also throws identically every tick, and must keep
+   * retrying unbounded rather than ever being treated as permanent).
    */
   async pollSessionMessagesForRedrive(conv, message, sessionId) {
     try {
       const res = await this.fetchImpl(`${this.opencodeBase}/session/${sessionId}/message`);
       if (!res.ok) {
+        const rawBody = await res.text();
+        const normalized = normalizeRedrivePollFailureBody(rawBody);
         this.log({
           level: "warn",
-          message: `Re-drive: polling session ${sessionId.slice(0, 8)} for message ${message.id.slice(0, 8)} returned HTTP ${res.status} \u2014 treating as unreadable this tick`,
+          message: `Re-drive: polling session ${sessionId.slice(0, 8)} for message ${message.id.slice(0, 8)} returned HTTP ${res.status}${normalized ? `: ${normalized}` : ""} \u2014 treating as unreadable this tick`,
           conversation_id: conv.id,
           message_id: message.id
         });
-        return null;
+        return { ok: false, signature: `HTTP ${res.status}${normalized ? `: ${normalized}` : ""}` };
       }
       const body = await res.json();
       if (!Array.isArray(body)) {
@@ -3742,9 +4129,9 @@ var ChannelDriver = class _ChannelDriver {
           conversation_id: conv.id,
           message_id: message.id
         });
-        return null;
+        return { ok: false, signature: "non-array message body" };
       }
-      return body;
+      return { ok: true, messages: body };
     } catch (err) {
       this.log({
         level: "warn",
@@ -3752,7 +4139,7 @@ var ChannelDriver = class _ChannelDriver {
         conversation_id: conv.id,
         message_id: message.id
       });
-      return null;
+      return { ok: false, signature: null };
     }
   }
   /**
@@ -3764,24 +4151,51 @@ var ChannelDriver = class _ChannelDriver {
    * without this fence the drain loop would re-`prompt_async` the SAME turn a
    * second time against live GitHub state. Mirrors `readoptOne`'s job for the
    * `processing` re-adopt path, but simpler: no b1/b2 preamble cross-check is
-   * needed here because `refusedSessionId` already handles the one case
-   * (#553 abandoned session) that path exists for.
+   * needed here because `sessionCreated` already handles the cases (a #553
+   * abandoned session, a #190 vanished one) that path exists for.
    *
-   * Only `ChannelAuthError` propagates; every other failure resolves to
-   * `unresolved` and is retried whole on the next ~2s drain tick.
+   * Only `ChannelAuthError` propagates. A poll that fails identically
+   * `MAX_IDENTICAL_REDRIVE_POLL_FAILURES` times in a row reports the message
+   * failed instead of retrying it (#1348) — SEPARATE from, not a replacement
+   * for, `resolveRedriveUnresolved`'s own `pausedMaxWaitMs` bound below. Every
+   * other failure resolves to `unresolved` and is retried whole on the next
+   * ~2s drain tick.
    */
-  async resolveRedrive(conv, sessionId, message, refusedSessionId) {
+  async resolveRedrive(conv, sessionId, message, sessionCreated) {
     const ocId = message.opencode_message_id ?? null;
-    if (refusedSessionId) {
+    if (sessionCreated) {
       this.clearRedriveUnresolved(message.id);
       void this.postSignal(conv.id, message.id, "redrive_redispatched");
       return "dispatch";
     }
-    const messages = await this.pollSessionMessagesForRedrive(conv, message, sessionId);
-    if (messages == null || messages.length === 0) {
+    const polled = await this.pollSessionMessagesForRedrive(conv, message, sessionId);
+    if (!polled.ok) {
+      const streak = this.recordRedrivePollFailure(message.id, sessionId, polled.signature);
+      if (streak >= MAX_IDENTICAL_REDRIVE_POLL_FAILURES && polled.signature !== null) {
+        return this.failRedrivePollPermanent(conv, sessionId, message, polled.signature, streak);
+      }
+      return this.resolveRedriveUnresolved(conv, message);
+    }
+    this.redrivePollFailures.delete(message.id);
+    const messages = polled.messages;
+    if (messages.length === 0) {
       return this.resolveRedriveUnresolved(conv, message);
     }
     const state = messageRunState(messages, ocId ?? "");
+    if (state === "failed" && isAbortedTerminalReply(messages, ocId ?? "")) {
+      const ongoing = await isSessionOngoing(this.port, sessionId);
+      if (ongoing === false) {
+        this.log({
+          level: "info",
+          message: `Re-drive: message ${message.id.slice(0, 8)} carries an abort-shaped terminal error and session ${sessionId.slice(0, 8)} is not-ongoing per GET /session/status \u2014 restart orphan, re-dispatching instead of marking it permanently failed`,
+          conversation_id: conv.id,
+          message_id: message.id
+        });
+        this.clearRedriveUnresolved(message.id);
+        void this.postSignal(conv.id, message.id, "redrive_redispatched");
+        return "dispatch";
+      }
+    }
     if (state === "done" || state === "failed") {
       return this.settleRedrive(conv, sessionId, message, ocId, messages, state);
     }
@@ -3791,6 +4205,9 @@ var ChannelDriver = class _ChannelDriver {
         return this.reattachRedrive(conv, sessionId, message, ocId);
       }
       if (ongoing === false) {
+        if (state === "running" && isAmbiguousFinishPinnedRunning(messages, ocId ?? "")) {
+          return this.settleRedrive(conv, sessionId, message, ocId, messages, "done");
+        }
         this.clearRedriveUnresolved(message.id);
         void this.postSignal(conv.id, message.id, "redrive_redispatched");
         return "dispatch";
@@ -3825,13 +4242,23 @@ var ChannelDriver = class _ChannelDriver {
       await this.markProcessing(conv.id, message.id, sessionId, ocId, title);
     } catch (err) {
       if (err instanceof ChannelAuthError) throw err;
-      this.log({
-        level: "warn",
-        message: `Re-drive: failed to restore message ${message.id.slice(0, 8)} to processing (will retry next drain): ${err instanceof Error ? err.message : String(err)}`,
-        conversation_id: conv.id,
-        message_id: message.id
-      });
-      return "unresolved";
+      if (err instanceof ChannelTerminalError) {
+        this.log({
+          level: "error",
+          message: `Re-drive: the server definitively refused to restore message ${message.id.slice(0, 8)} to processing (terminal HTTP ${err.status} \u2014 the row is gone or the update was rejected); NOT reporting a re-attach`,
+          conversation_id: conv.id,
+          message_id: message.id
+        });
+      } else {
+        this.log({
+          level: "warn",
+          message: `Re-drive: failed to restore message ${message.id.slice(0, 8)} to processing (will retry next drain): ${err instanceof Error ? err.message : String(err)}`,
+          conversation_id: conv.id,
+          message_id: message.id
+        });
+      }
+      const bound = await this.boundRedriveOutcome(conv, message, "reattach");
+      return bound === "abandoned" ? "abandoned" : "unresolved";
     }
     this.clearRedriveUnresolved(message.id);
     this.registerReadopted(conv, sessionId, message, ocId ?? "", anchorMs);
@@ -3855,7 +4282,9 @@ var ChannelDriver = class _ChannelDriver {
    * errored) while nobody was watching — deliver/report it instead of re-running.
    * Mirrors `readoptOne`'s `done`/`failed` branches' error discipline, simplified
    * (no `doneUndeliverable` park: a terminal PATCH failure here just retries next
-   * drain, same as any other non-auth failure).
+   * drain, same as any other non-auth failure). The restart-abort carve-out that
+   * keeps the two in step for `failed` lives in the caller (`resolveRedrive`, #1310),
+   * so a row reaching this `failed` branch is a GENUINE failure.
    */
   async settleRedrive(conv, sessionId, message, ocId, messages, state) {
     try {
@@ -3889,19 +4318,62 @@ var ChannelDriver = class _ChannelDriver {
         conversation_id: conv.id,
         message_id: message.id
       });
-      return "unresolved";
+      const bound = await this.boundRedriveOutcome(conv, message, "settle");
+      return bound === "abandoned" ? "abandoned" : "unresolved";
     }
     this.clearRedriveUnresolved(message.id);
     void this.postSignal(conv.id, message.id, "redrive_settled");
     return "settled";
   }
+  /**
+   * The permanent-failure outcome (#1348): the fence's own poll of this session
+   * failed with the SAME opencode-answered signature
+   * `MAX_IDENTICAL_REDRIVE_POLL_FAILURES` times in a row — a transient blip
+   * would have varied or eventually cleared (see `pollSessionMessagesForRedrive`
+   * and `recordRedrivePollFailure`), so this is a durable fault (e.g. #1345's
+   * corrupted opencode session) rather than something worth retrying forever.
+   * Mirrors `settleRedrive`'s error discipline: no `usage`/`failure` args to
+   * `markFailed` (no opencode snapshot to extract them from — this poll never
+   * got a readable one).
+   */
+  async failRedrivePollPermanent(conv, sessionId, message, signature, streak) {
+    this.log({
+      level: "error",
+      message: `Re-drive: message ${message.id.slice(0, 8)} (session ${sessionId.slice(0, 8)}) failed to poll with the identical signature "${signature}" ${streak} times in a row \u2014 reporting the message failed instead of retrying forever`,
+      conversation_id: conv.id,
+      message_id: message.id
+    });
+    try {
+      await this.markFailed(
+        conv.id,
+        message.id,
+        sessionId,
+        `The runner could not read this conversation's state from OpenCode (${signature}). The same failure repeated ${streak} times in a row, so the message was not retried further.`
+      );
+    } catch (err) {
+      if (err instanceof ChannelAuthError) throw err;
+      this.log({
+        level: "warn",
+        message: `Re-drive: failed to report message ${message.id.slice(0, 8)} permanently failed (will retry next drain): ${err instanceof Error ? err.message : String(err)}`,
+        conversation_id: conv.id,
+        message_id: message.id
+      });
+      const bound = await this.boundRedriveOutcome(conv, message, "fail_permanent");
+      return bound === "abandoned" ? "abandoned" : "unresolved";
+    }
+    this.clearRedriveUnresolved(message.id);
+    void this.postSignal(conv.id, message.id, "redrive_poll_failed");
+    return "settled";
+  }
   /**
    * The bounded `unresolved` outcome (Task 3.4): opencode's state could not be
    * observed (snapshot unreadable/empty, or `isSessionOngoing` returned `null`).
-   * A `pending` row is invisible to every cron arm (all require `status =
-   * 'processing'`), so an indefinitely-`unresolved` row would be stranded with
-   * nothing driving it — bound it to the existing `pausedMaxWaitMs` window
-   * (reusing the knob, not a new constant) and take `dispatch` once elapsed.
+   * A `pending` row is swept by the server's own `PENDING_MAX_AGE_MS` (24h,
+   * #1368) cron arm, but that is a day-scale backstop — this local bound acts
+   * in minutes so the row (and the conversation it starves, per the ordering
+   * invariant below) isn't left stranded for that long. Bound to the existing
+   * `pausedMaxWaitMs` window (reusing the knob, not a new constant); takes
+   * `dispatch` once elapsed.
    */
   resolveRedriveUnresolved(conv, message) {
     const now = this.now();
@@ -3920,10 +4392,153 @@ var ChannelDriver = class _ChannelDriver {
     }
     return "unresolved";
   }
-  /** Clear both `unresolved`-bound trackers for a row (any non-`unresolved` outcome). */
+  /** Clear all `unresolved`/failure-streak trackers for a row (any non-`unresolved` outcome). */
   clearRedriveUnresolved(messageId) {
     this.redriveUnresolvedSince.delete(messageId);
     this.redriveUnresolvedSignalled.delete(messageId);
+    this.redrivePollFailures.delete(messageId);
+    this.redriveOutcomeUnreportedSignalled.delete(messageId);
+    this.redriveOutcomeFailingSince.delete(messageId);
+    this.redriveOutcomeAbandonedSignalled.delete(messageId);
+  }
+  /**
+   * #1340: the dispatch loop reached a message and did NOT start a turn. Fires at
+   * most once per (message, branch) streak — a wedged row is re-tried every tick,
+   * and the per-tick count is already carried by the co-occurring
+   * `redrive_unresolved`/`redrive_redispatched` signals.
+   */
+  signalDispatchNotStarted(conv, message, branch) {
+    if (this.dispatchNotStartedSignalled.get(message.id) === branch) return;
+    this.dispatchNotStartedSignalled.set(message.id, branch);
+    void this.postSignal(conv.id, message.id, "dispatch_not_started", { branch });
+  }
+  /**
+   * Class B (#1340): the runner DECIDED an outcome (reattach/settle/fail_permanent)
+   * but its own PATCH to record it failed. Fires at most once per (message,
+   * outcome) streak, and only while `boundRedriveOutcome` has not yet tripped —
+   * once it trips, `redrive_outcome_abandoned` takes over reporting for the row
+   * (#1366).
+   */
+  signalRedriveOutcomeUnreported(conv, message, outcome) {
+    if (this.redriveOutcomeUnreportedSignalled.get(message.id) === outcome) return;
+    this.redriveOutcomeUnreportedSignalled.set(message.id, outcome);
+    void this.postSignal(conv.id, message.id, "redrive_outcome_unreported", {
+      attempted_outcome: outcome
+    });
+  }
+  /**
+   * The runner-authored, honest error text for the terminal fallback a tripped
+   * `boundRedriveOutcome` sends. Distinguishable per outcome and truthful about
+   * what actually happened — the `settle`/done case must say the turn finished
+   * but its result could not be recorded, never that the runner stopped
+   * responding (that would be a lie for this shape, see #1366's "why this ships").
+   */
+  static REDRIVE_ABANDON_ERROR = {
+    reattach: "your runner could not record that this message had started, so it was given up on",
+    settle: "your runner finished this message but could not record the result, so the reply could not be delivered",
+    fail_permanent: "the runner could not read this conversation's state from OpenCode, and could not record that failure either, so the message was given up on"
+  };
+  /**
+   * Bound for Class B (#1340, #1366): the runner DECIDED an outcome but its own
+   * PATCH to record it failed. Two independent trip arms (either sufficient):
+   * (1) this failure streak has lasted `pausedMaxWaitMs` — DURATION, not a tick
+   * count, reusing the knob `resolveRedriveUnresolved` already established; (2)
+   * the turn's `processing_started_at` age has crossed
+   * `ABSOLUTE_MAX_PROCESSING_MS` — durable and restart-surviving, since arm (1)'s
+   * in-memory streak resets on a scale-to-zero restart.
+   *
+   * INVARIANT — a tripped bound never suppresses the original outcome attempt;
+   * it only adds a fallback after that attempt has failed again. This is only
+   * ever reached from inside the catch of the ORIGINAL outcome PATCH, which is
+   * attempted first on every tick whether or not this bound tripped before —
+   * there is no give-up latch that would short-circuit it. That is what lets a
+   * route-level fault that heals later still deliver the turn's real
+   * `done`/`failed` payload: once the original PATCH succeeds again, this
+   * helper is never entered and the row settles with its real result.
+   */
+  async boundRedriveOutcome(conv, message, outcome) {
+    const now = this.now();
+    const since = this.redriveOutcomeFailingSince.get(message.id);
+    if (since === void 0) this.redriveOutcomeFailingSince.set(message.id, now);
+    const durationTripped = now - (since ?? now) >= this.pausedMaxWaitMs;
+    const parsed = message.processing_started_at ? Date.parse(message.processing_started_at) : NaN;
+    const absoluteAgeTripped = !Number.isNaN(parsed) && now - parsed >= ABSOLUTE_MAX_PROCESSING_MS;
+    if (!durationTripped && !absoluteAgeTripped) {
+      this.signalRedriveOutcomeUnreported(conv, message, outcome);
+      return "retry";
+    }
+    const arm = durationTripped ? "failure_window" : "absolute_age";
+    try {
+      await this.markFailed(
+        conv.id,
+        message.id,
+        void 0,
+        _ChannelDriver.REDRIVE_ABANDON_ERROR[outcome]
+      );
+    } catch (err) {
+      if (err instanceof ChannelAuthError) throw err;
+      this.log({
+        level: "warn",
+        message: `Re-drive bound: fallback markFailed for message ${message.id.slice(0, 8)} also failed (arm ${arm}, will retry next drain): ${err instanceof Error ? err.message : String(err)}`,
+        conversation_id: conv.id,
+        message_id: message.id
+      });
+      if (!this.redriveOutcomeAbandonedSignalled.has(message.id)) {
+        this.redriveOutcomeAbandonedSignalled.add(message.id);
+        void this.postSignal(conv.id, message.id, "redrive_outcome_abandoned", {
+          attempted_outcome: outcome,
+          reported: false,
+          arm
+        });
+      }
+      return "retry";
+    }
+    this.clearRedriveUnresolved(message.id);
+    void this.postSignal(conv.id, message.id, "redrive_outcome_abandoned", {
+      attempted_outcome: outcome,
+      reported: true,
+      arm
+    });
+    return "abandoned";
+  }
+  /**
+   * Record one poll outcome toward the re-drive fence's consecutive-identical-
+   * failure streak (#1348) and return the resulting count. `signature === null`
+   * (a thrown exception, H1) always clears the streak and returns `0` — it is
+   * never countable. Otherwise the streak continues only when BOTH the session
+   * and the signature match the previous failure; anything else (a different
+   * session, or the same session failing a DIFFERENT way) starts a fresh streak
+   * at `1`.
+   */
+  recordRedrivePollFailure(messageId, sessionId, signature) {
+    if (signature === null) {
+      this.redrivePollFailures.delete(messageId);
+      return 0;
+    }
+    const existing = this.redrivePollFailures.get(messageId);
+    if (existing && existing.sessionId === sessionId && existing.signature === signature) {
+      existing.count += 1;
+      return existing.count;
+    }
+    this.redrivePollFailures.set(messageId, { sessionId, signature, count: 1 });
+    return 1;
+  }
+  /**
+   * Record one UNCONFIRMED-dispatch outcome (a `pending` row with no stored
+   * `opencode_message_id` whose `sendPromptAsync` returned `null`) toward the
+   * bound in `processConversation`'s dispatch loop, and return the resulting
+   * count. Mirrors `recordRedrivePollFailure`'s session-scoping: a session
+   * change starts a fresh streak at `1` rather than inheriting the old one's
+   * count, since a new session is a genuinely different attempt.
+   */
+  recordUnconfirmedDispatch(messageId, sessionId) {
+    const existing = this.unconfirmedDispatchFailures.get(messageId);
+    if (existing && existing.sessionId === sessionId) {
+      existing.count += 1;
+      return existing.count;
+    }
+    this.unconfirmedDispatchFailures.set(messageId, { sessionId, count: 1 });
+    return 1;
   }
   /**
    * Record that `sessionId` is no longer a valid binding for `conversationId`
@@ -3949,6 +4564,13 @@ var ChannelDriver = class _ChannelDriver {
    * `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.
+   *
+   * `created` says the returned session was made JUST NOW, so it provably holds
+   * no prior turn. The re-drive fence needs that as CONTRARY evidence ("nothing
+   * to reconcile against") — distinct from the ambiguous "I polled and saw an
+   * empty transcript", which stays a deferral. Keep it separate from
+   * `refusedSessionId`: only the latter means a #553 resurrection happened, and
+   * only it may drive the `session_superseded` signal.
    */
   async ensureSession(conv) {
     const bound = this.sessions.get(conv.id) ?? conv.opencode_session_id ?? null;
@@ -3959,7 +4581,11 @@ var ChannelDriver = class _ChannelDriver {
         conversation_id: conv.id
       });
       this.sessions.delete(conv.id);
-      return { sessionId: await this.createAndBindSession(conv.id), refusedSessionId: bound };
+      return {
+        sessionId: await this.createAndBindSession(conv.id),
+        refusedSessionId: bound,
+        created: true
+      };
     }
     if (bound) {
       const exists = await sessionExists(this.port, bound);
@@ -3970,12 +4596,12 @@ var ChannelDriver = class _ChannelDriver {
           conversation_id: conv.id
         });
         this.sessions.delete(conv.id);
-        return { sessionId: await this.createAndBindSession(conv.id) };
+        return { sessionId: await this.createAndBindSession(conv.id), created: true };
       }
       this.sessions.set(conv.id, bound);
-      return { sessionId: bound };
+      return { sessionId: bound, created: false };
     }
-    return { sessionId: await this.createAndBindSession(conv.id) };
+    return { sessionId: await this.createAndBindSession(conv.id), created: true };
   }
   /**
    * Create a fresh OpenCode session for a conversation, cache the binding, and
@@ -4193,7 +4819,9 @@ var ChannelDriver = class _ChannelDriver {
       deliveryDeadlineAnchored: false,
       b2PinnedSinceMs: 0,
       b2LastDescendantCheckMs: 0,
-      b2AbandonedSignalled: false
+      b2AbandonedSignalled: false,
+      ambiguousPinnedSinceMs: 0,
+      ambiguousResolved: false
     });
   }
   /**
@@ -4272,7 +4900,9 @@ var ChannelDriver = class _ChannelDriver {
       deliveryDeadlineAnchored: false,
       b2PinnedSinceMs: 0,
       b2LastDescendantCheckMs: 0,
-      b2AbandonedSignalled: false
+      b2AbandonedSignalled: false,
+      ambiguousPinnedSinceMs: 0,
+      ambiguousResolved: false
     });
   }
   /**
@@ -4404,9 +5034,8 @@ var ChannelDriver = class _ChannelDriver {
     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(
+        await this.markProcessing(
           conv.id,
           inFlight.evidentMessageId,
           sessionId,
@@ -4415,23 +5044,24 @@ var ChannelDriver = class _ChannelDriver {
         );
       } catch (err) {
         if (err instanceof ChannelAuthError) throw err;
-        this.log({
-          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
-        });
-        return;
+        if (err instanceof ChannelTerminalError) {
+          this.log({
+            level: "error",
+            message: `Failed to mark message ${inFlight.evidentMessageId.slice(0, 8)} processing (terminal HTTP ${err.status}) \u2014 the server definitively refused the swap`,
+            conversation_id: conv.id,
+            message_id: inFlight.evidentMessageId
+          });
+        } else {
+          this.log({
+            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
+          });
+          return;
+        }
       }
       inFlight.started = true;
-      if (!claimed) {
-        this.log({
-          level: "debug",
-          message: `Message ${inFlight.evidentMessageId.slice(0, 8)} already marked processing \u2014 continuing`,
-          conversation_id: conv.id,
-          message_id: inFlight.evidentMessageId
-        });
-      }
     }
     if (state === "done") {
       await this.settleMessageDone(sessionId, watcher, inFlight, messages);
@@ -4540,6 +5170,49 @@ var ChannelDriver = class _ChannelDriver {
         }
       }
     }
+    const ambiguousPinnedNow = activelyRunning && isAmbiguousFinishPinnedRunning(messages, inFlight.opencodeMessageId);
+    if (!ambiguousPinnedNow) {
+      if (snapshotReadable) {
+        inFlight.ambiguousPinnedSinceMs = 0;
+        inFlight.ambiguousResolved = false;
+      }
+    } else {
+      if (inFlight.ambiguousResolved) {
+        await this.settleMessageDone(sessionId, watcher, inFlight, messages);
+        return;
+      }
+      if (inFlight.ambiguousPinnedSinceMs === 0) {
+        inFlight.ambiguousPinnedSinceMs = this.now();
+        const reply = findLastAssistantReplyFor(messages, inFlight.opencodeMessageId);
+        const finish = reply?.info?.finish ?? reply?.finish;
+        this.log({
+          level: "warn",
+          message: `Message ${id.slice(0, 8)} pinned running by an unrecognised finish ("${finish ?? "(absent)"}") \u2014 corroborating against opencode's session status before settling (issue #1493)`,
+          conversation_id: conv.id,
+          message_id: id
+        });
+      }
+      const pinnedForMs = this.now() - inFlight.ambiguousPinnedSinceMs;
+      const ongoing = await isSessionOngoing(this.port, sessionId);
+      if (isAmbiguousFinishResolved({
+        pinnedForMs,
+        maxPinnedMs: AMBIGUOUS_FINISH_MAX_PINNED_MS,
+        sessionOngoing: ongoing
+      })) {
+        inFlight.ambiguousResolved = true;
+        this.log({
+          level: "warn",
+          message: `Message ${id.slice(0, 8)} ambiguous-finish-pinned for ${Math.round(pinnedForMs / 1e3)}s \u2014 resolved (${ongoing === false ? "session confirmed not-ongoing" : "pin exceeded the no-hang cap"}) \u2014 settling done`,
+          conversation_id: conv.id,
+          message_id: id
+        });
+        void this.postSignal(conv.id, id, "ambiguous_finish_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: "warn",
@@ -4771,7 +5444,10 @@ var ChannelDriver = class _ChannelDriver {
    * re-dispatched (at most once, see `forceReadoptRun`):
    *   - `done`             → `markDone` now (guarded like the watcher's done branch);
    *   - `failed`           → `markFailed` with the surfaced error (issue #182), so an
-   *                          errored turn is reported failed on restart, NOT re-dispatched;
+   *                          errored turn is reported failed on restart, NOT re-dispatched —
+   *                          EXCEPT a restart-ABORTED turn under a not-ongoing session,
+   *                          which is a restart orphan wearing a terminal error and is
+   *                          re-dispatched instead (issue #1310, see the branch below);
    *   - `running`/`queued` → re-attach a watcher via `registerReadopted` (no re-dispatch),
    *                          tracking the stored id so the reply correlates by it;
    *   - `unknown`/null id  → re-dispatch (opencode assigns a fresh id) + attach a watcher.
@@ -4791,51 +5467,19 @@ var ChannelDriver = class _ChannelDriver {
     const ocId = row.opencode_message_id;
     const state = messageRunState(messages, ocId ?? "");
     if (state === "done") {
-      if (this.doneUndeliverable.has(row.id)) {
-        this.log({
-          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
-        });
-        return;
-      }
+      await this.deliverReadoptedDone(sessionId, row, messages, ocId);
+      return;
+    }
+    const restartAborted = state === "failed" && sessionOngoing === false && isAbortedTerminalReply(messages, ocId ?? "");
+    if (restartAborted) {
       this.log({
         level: "info",
-        message: `Re-adopt: message ${row.id.slice(0, 8)} completed while unwatched \u2014 marking done`,
+        message: `Re-adopt: message ${row.id.slice(0, 8)} carries an abort-shaped terminal error and session ${sessionId.slice(0, 8)} is not-ongoing per GET /session/status \u2014 restart orphan, re-dispatching instead of marking it permanently failed`,
         conversation_id: row.conversation_id,
         message_id: row.id
       });
-      try {
-        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: "warn",
-            message: `Re-adopt: failed to mark message ${row.id.slice(0, 8)} done (terminal HTTP ${err.status}) \u2014 parking until it leaves processing; leaving for the cron safety net: ${err.message}`,
-            conversation_id: row.conversation_id,
-            message_id: row.id
-          });
-          void this.postSignal(row.conversation_id, row.id, "readopt_undeliverable");
-          return;
-        }
-        this.log({
-          level: "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
-        });
-        return;
-      }
-      this.dontRedispatch.delete(row.id);
-      void this.postSignal(row.conversation_id, row.id, "readopt_done");
-      return;
     }
-    if (state === "failed") {
+    if (state === "failed" && !restartAborted) {
       const error2 = messageError(messages, ocId ?? "") ?? void 0;
       const usage = messageUsage(messages, ocId ?? "");
       const failure = await this.classifyModelAuthFailure(messages, ocId ?? "");
@@ -4888,6 +5532,17 @@ var ChannelDriver = class _ChannelDriver {
       const ongoing = sessionOngoing;
       statusReadableOngoing = ongoing;
       if (ongoing === false) {
+        if (isAmbiguousFinishPinnedRunning(messages, ocId ?? "")) {
+          const finish = reply?.info?.finish ?? reply?.finish;
+          this.log({
+            level: "info",
+            message: `Re-adopt: message ${row.id.slice(0, 8)} has an ambiguous finish ("${finish ?? "(absent)"}") but session ${sessionId.slice(0, 8)} is confirmed not-ongoing per GET /session/status \u2014 delivering the existing reply instead of re-dispatching`,
+            conversation_id: row.conversation_id,
+            message_id: row.id
+          });
+          await this.deliverReadoptedDone(sessionId, row, messages, ocId);
+          return;
+        }
         this.log({
           level: "info",
           message: `Re-adopt: message ${row.id.slice(0, 8)} running/${shape} but session ${sessionId.slice(0, 8)} is not-ongoing per GET /session/status (absent/idle) \u2014 re-dispatching from scratch (status-gated recovery)`,
@@ -4964,6 +5619,63 @@ var ChannelDriver = class _ChannelDriver {
     }
     await this.forceReadoptRun(sessionId, row);
   }
+  /**
+   * Deliver a `processing` row whose correlated reply already completed while
+   * nobody was watching (ADR-0046) — the `readoptOne` `state === 'done'` body,
+   * extracted (#1493 Task 2.4) so the ambiguous-finish guard above can call the
+   * SAME delivery instead of duplicating it.
+   *
+   * EVEN IF the row was previously parked in `dontRedispatch` (a give-up stops
+   * re-dispatch, not delivery — Bugbot #202). Guarded EXACTLY like the watcher's
+   * `settleMessageDone`: auth re-throws; terminal → park in `doneUndeliverable` +
+   * leave for cron; transient → log + leave for the next drain (the still-
+   * `processing` row is re-read and retried). markDone is idempotent server-side
+   * (status-gated), so a repeat can never double-post.
+   */
+  async deliverReadoptedDone(sessionId, row, messages, ocId) {
+    if (this.doneUndeliverable.has(row.id)) {
+      this.log({
+        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
+      });
+      return;
+    }
+    this.log({
+      level: "info",
+      message: `Re-adopt: message ${row.id.slice(0, 8)} completed while unwatched \u2014 marking done`,
+      conversation_id: row.conversation_id,
+      message_id: row.id
+    });
+    try {
+      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: "warn",
+          message: `Re-adopt: failed to mark message ${row.id.slice(0, 8)} done (terminal HTTP ${err.status}) \u2014 parking until it leaves processing; leaving for the cron safety net: ${err.message}`,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+        void this.postSignal(row.conversation_id, row.id, "readopt_undeliverable");
+        return;
+      }
+      this.log({
+        level: "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
+      });
+      return;
+    }
+    this.dontRedispatch.delete(row.id);
+    void this.postSignal(row.conversation_id, row.id, "readopt_done");
+  }
   /**
    * Re-dispatch an orphaned (`unknown`/null-id) `processing` row (ADR-0046 §2).
    *
@@ -5049,15 +5761,39 @@ var ChannelDriver = class _ChannelDriver {
     }
     if (ocId === null) {
       this.awaitingReadopt.delete(row.id);
+      const streak = this.recordUnconfirmedDispatch(row.id, sessionId);
+      if (streak >= MAX_IDENTICAL_REDRIVE_POLL_FAILURES) {
+        this.unconfirmedDispatchFailures.delete(row.id);
+        this.sessions.delete(readoptConv.id);
+        this.supersede(readoptConv.id, sessionId);
+        const errorMessage = `OpenCode accepted this re-dispatched message ${streak} times in a row but never confirmed its assigned id (session ${sessionId.slice(0, 8)}'s message list could not be read back) \u2014 the session was abandoned; a fresh one is used for further messages.`;
+        this.log({
+          level: "error",
+          message: errorMessage,
+          conversation_id: row.conversation_id,
+          message_id: row.id
+        });
+        await this.markFailed(row.conversation_id, row.id, null, errorMessage).catch((markErr) => {
+          this.log({
+            level: "warn",
+            message: `markFailed PATCH for message ${row.id.slice(0, 8)} (conversation ${row.conversation_id.slice(0, 8)}) failed (best-effort, not retried): ${markErr instanceof Error ? markErr.message : String(markErr)}`,
+            conversation_id: row.conversation_id,
+            message_id: row.id
+          });
+        });
+        void this.postSignal(row.conversation_id, row.id, "readopt_orphan_unsent");
+        return;
+      }
       this.log({
         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`,
+        message: `Re-adopt: message ${row.id.slice(0, 8)} re-dispatched but its opencode id could not be read back (${streak}/${MAX_IDENTICAL_REDRIVE_POLL_FAILURES}) \u2014 leaving un-tracked to retry next drain`,
         conversation_id: row.conversation_id,
         message_id: row.id
       });
       void this.postSignal(row.conversation_id, row.id, "readopt_orphan_unsent");
       return;
     }
+    this.unconfirmedDispatchFailures.delete(row.id);
     this.registerReadopted(readoptConv, sessionId, readoptMessage, ocId, this.processedAtMs(row));
     this.dispatched.add(row.id);
     this.readopted.add(row.id);
@@ -5569,17 +6305,25 @@ var ChannelDriver = class _ChannelDriver {
    *               the aborted-in-flight production bug after a restart.
    *   - `b2`    — a COMPLETED reply pinned running only by `finish === "tool-calls"`
    *               (the sub-agent preamble — #253's shape).
-   *   - `other` — any other shape (defensive; a running row is normally b1 or b2).
-   * Reads `info.time.completed` / `info.finish` (tolerating the legacy top-level
-   * shape) directly rather than re-importing the module-private `completedOf`/
-   * `finishOf` — this is a display label only, not a correctness predicate.
+   *   - `ambiguous` — a COMPLETED, non-errored reply whose `finish` is neither
+   *               "tool-calls" nor "stop" (issue #1493, class 4 — see
+   *               `isAmbiguousFinishPinnedRunning`/Task 2.4).
+   *   - `other` — any other shape (defensive; a running row is normally b1, b2 or
+   *               ambiguous).
+   * Reads `info.time.completed` / `info.finish` / `info.error` (tolerating the
+   * legacy top-level shape) directly rather than re-importing the module-private
+   * `completedOf`/`finishOf`/`errorOf` — this is a display label only, not a
+   * correctness predicate (that is `isAmbiguousFinishPinnedRunning`'s job).
    */
   replyCompletionShape(reply) {
     if (!reply) return "other";
     const completed = reply.info?.time?.completed ?? reply.time?.completed;
     if (completed == null) return "b1";
     const finish = reply.info?.finish ?? reply.finish;
-    return finish === "tool-calls" ? "b2" : "other";
+    if (finish === "tool-calls") return "b2";
+    const error2 = reply.info?.error ?? reply.error;
+    if (finish !== "stop" && error2 == null) return "ambiguous";
+    return "other";
   }
   /**
    * Attribute a surfaced interaction to the in-flight message it paused on (M-1).
@@ -5722,18 +6466,22 @@ var ChannelDriver = class _ChannelDriver {
    * opencode_session_id}` → `notifyMessageStarted` (hourglass→runner swap +
    * deep-linked "View in Evident" notice).
    *
-   * Return/throw contract (consumed by the watcher's swap-to-running guard):
-   *   - returns `true`  → the server transitioned the row to processing;
-   *   - returns `false` → the server gave a DEFINITIVE "already-processing"
-   *                       answer (a non-retryable, non-auth status — e.g. a
-   *                       conflict because a duplicate already transitioned it),
-   *                       so the caller treats it as already-started and does NOT
-   *                       retry;
-   *   - throws `ChannelAuthError` on 401/403 (terminal auth failure);
-   *   - throws on a TRANSIENT failure (retryable 5xx/429 status, or a
-   *     network-level error from `fetch`) — i.e. NO definitive server response —
-   *     so the caller leaves the message un-started and retries the swap on the
-   *     next tick.
+   * Outcome contract (consumed by the watcher's swap-to-running guard):
+   *   - resolves (`void`)             → the server transitioned the row to
+   *                                     processing (or idempotently confirmed
+   *                                     already-processing — that answer is
+   *                                     still a 200, never a refusal);
+   *   - throws `ChannelAuthError`     → 401/403 (terminal auth failure);
+   *   - throws `ChannelTerminalError` → a definitive non-retryable, non-auth 4xx
+   *                                     (404 the row or its conversation is
+   *                                     gone, 400 the update was rejected).
+   *                                     Retrying cannot help;
+   *   - throws a plain `Error`       → a TRANSIENT failure (retryable 5xx/429
+   *                                     status, or a network-level error from
+   *                                     `fetch`) — i.e. NO definitive server
+   *                                     response — so the caller leaves the
+   *                                     message un-started and retries the swap
+   *                                     on the next tick.
    * A single attempt (no internal retry): the watcher's per-tick loop is the
    * retry vehicle for the swap-to-running.
    */
@@ -5752,11 +6500,11 @@ var ChannelDriver = class _ChannelDriver {
       }
     );
     this.assertAuth(res, "marking message as processing");
-    if (res.ok) return true;
+    if (res.ok) return;
     if (isRetryableStatus(res.status)) {
       throw new Error(`marking message as processing: HTTP ${res.status}`);
     }
-    return false;
+    throw new ChannelTerminalError(`marking message as processing: HTTP ${res.status}`, res.status);
   }
   /**
    * EXISTING combinedAuth completion route — idempotent (WI-CHAN-2). `PATCH
@@ -6192,7 +6940,7 @@ function resolveFileSyncDirectories(raw, homeDir) {
     if (trimmed === "") {
       throw new Error("--enable-file-sync-to requires a directory path (got an empty value)");
     }
-    const expanded = trimmed === "~" ? homeDir : trimmed.startsWith("~/") ? join3(homeDir, trimmed.slice(2)) : trimmed;
+    const expanded = trimmed === "~" ? homeDir : trimmed.startsWith("~/") ? join4(homeDir, trimmed.slice(2)) : trimmed;
     if (!isAbsolute2(expanded)) {
       throw new Error(`--enable-file-sync-to requires an absolute directory path; got "${entry}"`);
     }
@@ -6242,6 +6990,32 @@ function resolveOpenCodeStartTimeoutMs(options, env = process.env) {
   }
   return { timeoutMs: seconds * 1e3, warnings: [] };
 }
+var MAX_ACTIVE_SESSIONS_ENV = "EVIDENT_MAX_ACTIVE_SESSIONS";
+function resolveMaxActiveSessions(options, env = process.env) {
+  let raw;
+  let source;
+  if (options.maxActiveSessions !== void 0) {
+    raw = options.maxActiveSessions;
+    source = "--max-active-sessions";
+  } else if (env[MAX_ACTIVE_SESSIONS_ENV] !== void 0 && env[MAX_ACTIVE_SESSIONS_ENV] !== "") {
+    raw = env[MAX_ACTIVE_SESSIONS_ENV];
+    source = MAX_ACTIVE_SESSIONS_ENV;
+  } else {
+    return { value: void 0, warnings: [] };
+  }
+  const trimmed = raw.trim();
+  const count = Number(trimmed);
+  const isPositiveInteger = /^\d+$/.test(trimmed) && Number.isInteger(count) && count > 0;
+  if (!isPositiveInteger) {
+    return {
+      value: void 0,
+      warnings: [
+        `Ignoring invalid ${source} "${raw}": expected a positive integer; using unlimited`
+      ]
+    };
+  }
+  return { value: count, warnings: [] };
+}
 function meetsThreshold(state, level) {
   return LOG_LEVELS[level] >= LOG_LEVELS[state.logLevel];
 }
@@ -6360,7 +7134,9 @@ async function handleAuthError(state, error2) {
     );
     const newAuthHeader = getAuthHeader(credentials2);
     return { success: true, newAuthHeader };
-  } catch {
+  } catch (error3) {
+    const message = error3 instanceof Error ? error3.message : String(error3);
+    logActivity(state, { type: "error", error: `Re-authentication failed: ${message}` });
     return { success: false };
   }
 }
@@ -6465,6 +7241,10 @@ async function driveChannels(state, driver) {
   }
 }
 var SESSION_CLEANUP_FIRST_SWEEP_MS = 1e4;
+var SESSION_DB_RECLAIM_MAX_PAGES = 2e3;
+function sessionDbPath() {
+  return join4(homedir3(), ".local", "share", "opencode", "opencode.db");
+}
 async function runSweep(state, driver, config) {
   const mode = `age=${config.maxAgeMs ?? "\u2014"} count=${config.maxCount ?? "\u2014"}`;
   try {
@@ -6507,6 +7287,25 @@ async function runSweep(state, driver, config) {
       type: "info",
       message: `Session cleanup: inspected ${sessions.length}, deleted ${deleted}${failedNote}${skippedNote} (${mode})`
     });
+    const reclaimResult = await reclaimSessionDbSpace({
+      dbPath: sessionDbPath(),
+      maxPages: SESSION_DB_RECLAIM_MAX_PAGES,
+      allowFullVacuum: protectedNow.size === 0
+    });
+    if (reclaimResult.ok) {
+      const beforeMib = (reclaimResult.beforeBytes / 1024 / 1024).toFixed(1);
+      const afterMib = (reclaimResult.afterBytes / 1024 / 1024).toFixed(1);
+      const checkpointNote = reclaimResult.checkpoint.busy ? ` (on-disk file truncation deferred: checkpoint busy, ${reclaimResult.checkpoint.log} WAL frames pending)` : "";
+      logActivity(state, {
+        type: "info",
+        message: `Session cleanup: reclaimed session-db space (${reclaimResult.mode}): ${beforeMib} MiB -> ${afterMib} MiB${checkpointNote}`
+      });
+    } else {
+      logActivity(state, {
+        type: "info",
+        message: `Session cleanup: session-db space reclaim skipped (${reclaimResult.skipped})`
+      });
+    }
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     logActivity(state, {
@@ -6527,6 +7326,22 @@ function scheduleSessionCleanup(state, driver, options) {
   for (const warning2 of config.warnings) {
     logActivity(state, { type: "info", level: "warn", message: `Session cleanup: ${warning2}` });
   }
+  const dbBytes = statSessionDbBytes(homedir3());
+  void (async () => {
+    const reclaimSkipReason = dbBytes !== null && config.enabled ? await probeReclaimAvailability({ dbPath: sessionDbPath(), requiredBytes: dbBytes }) : null;
+    const sizeWarning = buildSessionStoreSizeWarning({
+      dbBytes,
+      cleanupEnabled: config.enabled,
+      reclaimSkipReason
+    });
+    if (sizeWarning !== null) {
+      logActivity(state, { type: "info", level: "warn", message: sizeWarning });
+    }
+  })().catch((err) => {
+    console.error(
+      `[scheduleSessionCleanup] size-warning preflight failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  });
   if (!config.enabled) return;
   logActivity(state, {
     type: "info",
@@ -6967,6 +7782,10 @@ async function run(options) {
     for (const warning2 of opencodeStartTimeoutWarnings) {
       logActivity(state, { type: "info", level: "warn", message: warning2 });
     }
+    const { value: maxActiveSessions, warnings: maxActiveSessionsWarnings } = resolveMaxActiveSessions(options, process.env);
+    for (const warning2 of maxActiveSessionsWarnings) {
+      logActivity(state, { type: "info", level: "warn", message: warning2 });
+    }
     const ocSpinner = interactive && !state.json ? ora3("Checking OpenCode...").start() : null;
     try {
       const oc = await ensureOpenCodeRunning({
@@ -7027,6 +7846,7 @@ async function run(options) {
       // REJECTED with `file_sync_disabled` on the ack, not silently ignored.
       fileSyncDirectories,
       homeDir: homedir3(),
+      maxActiveSessions,
       log: (entry) => (
         // Thread the driver's real level straight through so `debug`/`warn`
         // survive the sink filter (they no longer collapse to info). `type`
@@ -7103,6 +7923,13 @@ async function run(options) {
           logActivity(state, { type: "error", error: error2 });
           if (state.interactive) displayStatus(state);
         },
+        // `warn`, not `info`: `forwardRunnerActivity`'s FORWARDED_LEVELS floor is
+        // {'warn','error'}, so an `info` entry would never leave the machine and
+        // an operator couldn't correlate a reconnect storm with a relay deploy.
+        onWarning: (message) => {
+          logActivity(state, { type: "info", level: "warn", message });
+          if (state.interactive) displayStatus(state);
+        },
         // Web traffic is proxied transparently; note opencode is live and stamp
         // proxied activity so the idle loop treats interactive proxy use as work.
         // Fires per forwarded response head (incl. every SSE open) and excludes
@@ -7227,6 +8054,9 @@ program.command("run").description("Connect to Evident and process messages").op
 ).option(
   "--session-cleanup-max-count <n>",
   "Keep only the newest N OpenCode sessions. Enables cleanup. Env: EVIDENT_SESSION_CLEANUP_MAX_COUNT"
+).option(
+  "--max-active-sessions <n>",
+  "Cap how many sessions this runner works on at once (default: unlimited). Env: EVIDENT_MAX_ACTIVE_SESSIONS"
 ).option(
   "--session-cleanup-interval <duration>",
   "How often the cleanup sweep runs (default: 1h). Env: EVIDENT_SESSION_CLEANUP_INTERVAL"
@@ -7260,6 +8090,7 @@ 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,
+      maxActiveSessions: options.maxActiveSessions,
       sessionCleanupInterval: options.sessionCleanupInterval,
       // Raw string — the resolver in run.ts single-sources parsing
       // (resolveClaudeUsageReportingMode).