@evident-ai/cli 3.4.1-dev.57ff127 → 3.4.1-dev.661a835

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { createRequire } from "module";
+import { createRequire as createRequire2 } from "module";
 import { Command } from "commander";
 
 // src/commands/login.ts
@@ -371,14 +371,14 @@ function blank() {
   console.log();
 }
 function waitForEnter(prompt = "Press Enter to continue...") {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     process.stdout.write(chalk.dim(prompt));
     const handler = () => {
       process.stdin.removeListener("data", handler);
       process.stdin.setRawMode?.(false);
       process.stdin.pause();
       console.log();
-      resolve3();
+      resolve4();
     };
     if (process.stdin.isTTY) {
       process.stdin.setRawMode?.(true);
@@ -388,7 +388,7 @@ function waitForEnter(prompt = "Press Enter to continue...") {
   });
 }
 function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 
 // src/commands/login.ts
@@ -466,19 +466,19 @@ async function tokenLogin() {
   );
   blank();
   process.stdout.write("Paste token: ");
-  const token = await new Promise((resolve3) => {
+  const token = await new Promise((resolve4) => {
     let data = "";
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
     process.stdin.on("end", () => {
-      resolve3(data.trim());
+      resolve4(data.trim());
     });
     if (process.stdin.isTTY) {
       process.stdin.once("data", (chunk) => {
         process.stdin.pause();
-        resolve3(chunk.toString().trim());
+        resolve4(chunk.toString().trim());
       });
       process.stdin.resume();
     }
@@ -722,6 +722,14 @@ function toReportedWindow(window) {
   if (!window) return null;
   return { utilization: window.utilization, resets_at: window.resetsAt };
 }
+function toReportedOwner(snapshot) {
+  if (!snapshot.owner) return null;
+  return {
+    email: snapshot.owner.email,
+    organization_name: snapshot.owner.organizationName,
+    rate_limit_tier: snapshot.owner.rateLimitTier
+  };
+}
 async function reportClaudeUsage(agentId, authHeader, snapshot) {
   try {
     const apiUrl = getApiUrlConfig();
@@ -730,7 +738,8 @@ async function reportClaudeUsage(agentId, authHeader, snapshot) {
       headers: { Authorization: authHeader, "Content-Type": "application/json" },
       body: JSON.stringify({
         five_hour: toReportedWindow(snapshot.fiveHour),
-        seven_day: toReportedWindow(snapshot.sevenDay)
+        seven_day: toReportedWindow(snapshot.sevenDay),
+        owner: toReportedOwner(snapshot)
       }),
       signal: AbortSignal.timeout(BEST_EFFORT_NOTIFY_TIMEOUT_MS)
     });
@@ -754,6 +763,13 @@ function toReportedOpenAiWindow(window) {
     resets_at: window.resetsAt
   };
 }
+function toReportedOpenAiSubscription(snapshot) {
+  if (!snapshot.subscription) return null;
+  return {
+    owner_email: snapshot.subscription.ownerEmail,
+    plan_type: snapshot.subscription.planType
+  };
+}
 async function reportOpenAiUsage(agentId, authHeader, snapshot) {
   try {
     const apiUrl = getApiUrlConfig();
@@ -764,7 +780,8 @@ async function reportOpenAiUsage(agentId, authHeader, snapshot) {
         primary: toReportedOpenAiWindow(snapshot.primary),
         secondary: toReportedOpenAiWindow(snapshot.secondary),
         has_credits: snapshot.hasCredits,
-        credits_unlimited: snapshot.creditsUnlimited
+        credits_unlimited: snapshot.creditsUnlimited,
+        subscription: toReportedOpenAiSubscription(snapshot)
       }),
       signal: AbortSignal.timeout(BEST_EFFORT_NOTIFY_TIMEOUT_MS)
     });
@@ -996,7 +1013,10 @@ import { readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 var CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+var CLAUDE_PROFILE_URL = "https://api.anthropic.com/api/oauth/profile";
+var CLAUDE_PROFILE_TIMEOUT_MS = 2e3;
 var KEYCHAIN_SERVICE = "Claude Code-credentials";
+var cachedOwner = null;
 var CLAUDE_CREDENTIALS_SEGMENTS = [".claude", ".credentials.json"];
 function parseClaudeCliCredentials(raw) {
   let parsed;
@@ -1070,6 +1090,47 @@ function toWindow(value) {
   }
   return { utilization: window.utilization, resetsAt };
 }
+function ownerLookupFailure(error2) {
+  const name = error2?.name;
+  return name === "TimeoutError" || name === "AbortError" ? "timed out" : "request failed";
+}
+async function getClaudeUsageOwner(accessToken) {
+  if (cachedOwner?.accessToken === accessToken) {
+    return { owner: cachedOwner.owner, ownerLookupError: null };
+  }
+  try {
+    const response = await fetch(CLAUDE_PROFILE_URL, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+        "anthropic-version": "2023-06-01"
+      },
+      signal: AbortSignal.timeout(CLAUDE_PROFILE_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      return { owner: null, ownerLookupError: `HTTP ${response.status}` };
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch (error2) {
+      return { owner: null, ownerLookupError: "malformed response" };
+    }
+    const profile = body;
+    if (typeof profile.account?.email !== "string" || !profile.account.email.trim()) {
+      return { owner: null, ownerLookupError: "malformed response" };
+    }
+    const owner = {
+      email: profile.account.email,
+      organizationName: typeof profile.organization?.name === "string" && profile.organization.name.trim() ? profile.organization.name.trim() : null,
+      rateLimitTier: typeof profile.organization?.rate_limit_tier === "string" && profile.organization.rate_limit_tier.trim() ? profile.organization.rate_limit_tier.trim() : null
+    };
+    cachedOwner = { accessToken, owner };
+    return { owner, ownerLookupError: null };
+  } catch (error2) {
+    return { owner: null, ownerLookupError: ownerLookupFailure(error2) };
+  }
+}
 async function getClaudeUsage() {
   const credentials2 = readClaudeCliCredentials();
   if (!credentials2) {
@@ -1089,15 +1150,19 @@ async function getClaudeUsage() {
       Authorization: `Bearer ${credentials2.accessToken}`,
       "Content-Type": "application/json",
       "anthropic-version": "2023-06-01"
-    }
+    },
+    signal: AbortSignal.timeout(CLAUDE_PROFILE_TIMEOUT_MS)
   });
   if (!res.ok) {
     throw new ClaudeUsageError(`Claude usage request failed: HTTP ${res.status}`, "request_failed");
   }
   const body = await res.json();
+  const { owner, ownerLookupError } = await getClaudeUsageOwner(credentials2.accessToken);
   return {
     fiveHour: toWindow(body.five_hour),
-    sevenDay: toWindow(body.seven_day)
+    sevenDay: toWindow(body.seven_day),
+    owner,
+    ownerLookupError
   };
 }
 
@@ -1126,8 +1191,9 @@ async function claudeUsage() {
 }
 
 // src/commands/run.ts
-import { homedir as homedir4 } from "os";
-import { isAbsolute as isAbsolute2, join as join7, parse, resolve as resolvePath } from "path";
+import { chmodSync as chmodSync3, existsSync as existsSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "fs";
+import { homedir as homedir5 } from "os";
+import { isAbsolute as isAbsolute3, join as join9, parse, resolve as resolvePath2 } from "path";
 import chalk6 from "chalk";
 
 // ../../packages/types/src/agents/index.ts
@@ -1467,7 +1533,14 @@ function drainSessionDbRecoveryReport({
         skippedLines++;
         return [];
       }
-      return [value];
+      return [
+        {
+          ...value,
+          provenance_reason: value.provenance_reason ?? null,
+          provenance_migration_delta: value.provenance_migration_delta ?? null,
+          replication_suspended: value.replication_suspended ?? false
+        }
+      ];
     } catch (error2) {
       skippedLines++;
       console.error(
@@ -1492,12 +1565,39 @@ function buildSessionDbRecoveryActivity(record) {
   const level = record.severity === "warning" ? "warn" : record.severity === "error" ? "error" : null;
   if (!level) return null;
   const noVerifiedPoint = record.verified_restore_point ? ` The verified restore point is ${record.verified_restore_point}.` : " No verified restore point is known.";
+  const replication = record.replication_suspended ? " This start is not backing up its new session history; restart after fixing the cause." : "";
+  const giveupMessage = (() => {
+    switch (record.reason) {
+      case "restore_deadline_exceeded":
+        return "The restore did not finish before this startup deadline. Earlier sessions are unavailable for this start; collect the SESSION-DB-RESTORE-TRUNCATED boot log before retrying.";
+      case "restore_tool_unusable":
+      case "classification_unrecognised":
+        return "The restore or classification tool produced an unsupported result. Inspect the named boot marker or log and repair the runner image or bundle before restarting.";
+      case "synchroniser_config_unevaluable":
+      case "synchroniser_config_incomplete":
+        return "The installed hook and synchroniser bundle could not agree on configuration. Inspect the named boot marker or log and repair the runner image or bundle before restarting.";
+      case "synchroniser_config_unresolved":
+        return "The synchroniser configuration could not be resolved. Inspect the preceding boot error and repair the identified runner image, bundle, or local environment before restarting.";
+      case "litestream_config_unavailable":
+        return "The local Litestream configuration could not be generated or written. Inspect the preceding boot error and repair the runner image, bundle, local environment, or write permissions before restarting.";
+      case "classification_fatal":
+        return "Session history could not be restored because backup setup could not be established. Inspect the named boot marker or log and repair the identified backup configuration or permissions.";
+      default:
+        return null;
+    }
+  })();
+  if (giveupMessage)
+    return {
+      level,
+      metadata: withoutContractFields(record),
+      message: `${giveupMessage}${replication}`
+    };
   switch (record.outcome) {
     case "fresh_session_db":
       return {
         level,
         metadata: withoutContractFields(record),
-        message: `This runner started with a fresh session database. Earlier sessions are unavailable, and queued conversation or session references from before this start may no longer resolve.${noVerifiedPoint} Review the runner's backup configuration before relying on restored session history.`
+        message: `This runner started with a fresh session database. Earlier sessions are unavailable, and queued conversation or session references from before this start may no longer resolve.${noVerifiedPoint} Review the runner's backup configuration before relying on restored session history.${replication}`
       };
     case "restore_retried":
       return {
@@ -1535,7 +1635,19 @@ function buildSessionDbRecoveryActivity(record) {
       return {
         level,
         metadata: withoutContractFields(record),
-        message: "This runner started with a fresh session database because it could not verify where its session history is backed up. Nothing in the backup was changed; check the runner backup configuration and permissions."
+        message: `This runner started without restoring session history because it could not verify where its session history is backed up. Nothing in the backup was changed; check the runner backup configuration and permissions.${replication}`
+      };
+    case "session_db_boot_refused":
+      return {
+        level,
+        metadata: withoutContractFields(record),
+        message: `This runner did not come online because its damaged session database could not be safely separated from its active backup or proven removed. Backed-up session history remains readable at ${record.quarantine_destination ?? "its original location or the quarantine destination named in the boot logs"}; any local session-database files that remain were left in place and nothing opened or wrote them. See the runner boot logs for SESSION-DB-LOCAL-DISCARD-FAILED details.`
+      };
+    case "schema_provenance_mismatch":
+      return {
+        level,
+        metadata: withoutContractFields(record),
+        message: `Session database schema provenance mismatch for ${record.dbPath ?? record.db_path ?? "unknown"}: recorded version=${record.recorded_version ?? "unknown"}, current version=${record.current_version ?? "unknown"}, reason=${record.provenance_reason ?? "unknown"}, migration delta=${record.provenance_migration_delta ?? "unknown"}. Inspect the session database and runner backup before continuing.`
       };
     default:
       return null;
@@ -1550,7 +1662,9 @@ var OUTCOMES = /* @__PURE__ */ new Set([
   "restore_retried",
   "fresh_session_db",
   "history_rolled_back",
-  "restore_misconfigured"
+  "restore_misconfigured",
+  "session_db_boot_refused",
+  "schema_provenance_mismatch"
 ]);
 var STAGES = /* @__PURE__ */ new Set(["restore", "verify"]);
 var SEVERITIES = /* @__PURE__ */ new Set(["warning", "error"]);
@@ -1568,7 +1682,7 @@ var STRING_OR_NULL_FIELDS = ["quarantine_destination", "verified_restore_point"]
 function isSessionDbRecoveryRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const record = value;
-  return record.v === 1 && record.event === "session_db_recovery" && typeof record.at === "string" && STAGES.has(record.stage) && OUTCOMES.has(record.outcome) && SEVERITIES.has(record.severity) && typeof record.reason === "string" && NUMBER_FIELDS.every((field) => record[field] === null || Number.isInteger(record[field])) && STRING_OR_NULL_FIELDS.every(
+  return record.v === 1 && record.event === "session_db_recovery" && typeof record.at === "string" && STAGES.has(record.stage) && OUTCOMES.has(record.outcome) && SEVERITIES.has(record.severity) && typeof record.reason === "string" && (record.replication_suspended === void 0 || typeof record.replication_suspended === "boolean") && (record.provenance_reason === void 0 || record.provenance_reason === null || typeof record.provenance_reason === "string") && (record.provenance_migration_delta === void 0 || record.provenance_migration_delta === null || Number.isInteger(record.provenance_migration_delta)) && NUMBER_FIELDS.every((field) => record[field] === null || Number.isInteger(record[field])) && STRING_OR_NULL_FIELDS.every(
     (field) => record[field] === null || typeof record[field] === "string"
   );
 }
@@ -1597,214 +1711,932 @@ async function waitForOpenCodeHealth(port, timeoutMs = 3e4) {
     if (health.healthy) {
       return health;
     }
-    await new Promise((resolve3) => setTimeout(resolve3, 1e3));
+    await new Promise((resolve4) => setTimeout(resolve4, 1e3));
   }
   return { healthy: false, error: "Timeout waiting for OpenCode to be healthy" };
 }
 
-// src/lib/opencode/opencode-version-gate.ts
-var QUEUE_VALIDATED_OPENCODE_VERSIONS = ["1.17.11", "1.18.3"];
-function isQueueValidatedVersion(version2) {
-  if (!version2) return false;
-  return QUEUE_VALIDATED_OPENCODE_VERSIONS.includes(version2);
-}
-function buildOpenCodeVersionWarning(version2) {
-  if (isQueueValidatedVersion(version2)) return null;
-  const detected = version2 ? `v${version2}` : "unknown";
-  const validated = QUEUE_VALIDATED_OPENCODE_VERSIONS.map((v) => `v${v}`).join(", ");
-  return `Warning: opencode ${detected} is not a queue-validated version (validated: ${validated}). Native message queuing \u2014 which channel (Slack) message handling relies on \u2014 is unverified on this version; queued/follow-up messages may behave unexpectedly. Continuing anyway. Bumping the validated set requires re-running the queue validation.`;
-}
+// src/lib/opencode/session-db-boot.ts
+import { spawn as spawn2 } from "child_process";
+import { mkdirSync, statSync as statSync2, unlinkSync as unlinkSync2, writeFileSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, resolve as resolvePath } from "path";
 
-// src/lib/opencode/process.ts
-import { execSync, spawn } from "child_process";
-var OPENCODE_PORT_RANGE = [4096, 4097, 4098, 4099, 4100];
-function getProcessCwd(pid) {
-  const platform = process.platform;
-  try {
-    if (platform === "darwin") {
-      const output = execSync(`lsof -a -p ${pid} -d cwd -Fn 2>/dev/null`, {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"]
-      }).trim();
-      const lines = output.split("\n");
-      for (const line of lines) {
-        if (line.startsWith("n") && !line.startsWith("n ")) {
-          return line.slice(1);
+// src/lib/runner-synchroniser.ts
+import { spawn } from "child_process";
+function appendError(stderr, error2) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return stderr === "" ? message : `${stderr}
+${message}`;
+}
+function runSynchroniser(args, opts) {
+  return new Promise((resolve4) => {
+    let child;
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timer = {};
+    let abortListener;
+    let spawnListener;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer.handle) clearTimeout(timer.handle);
+      if (abortListener) opts.signal?.removeEventListener("abort", abortListener);
+      if (spawnListener) child.removeListener("spawn", spawnListener);
+      resolve4(result);
+    };
+    try {
+      child = spawn("runner-synchroniser", args, {
+        env: opts.env ?? process.env,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (error2) {
+      finish({ code: null, stdout, stderr: appendError(stderr, error2), timedOut: false });
+      return;
+    }
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.once("error", (error2) => {
+      finish({ code: null, stdout, stderr: appendError(stderr, error2), timedOut: false });
+    });
+    child.once("close", (code) => {
+      finish({ code, stdout, stderr, timedOut: false });
+    });
+    if (opts.signal) {
+      const killChild = () => {
+        if (child.pid === void 0) {
+          if (!spawnListener) {
+            spawnListener = killChild;
+            child.once("spawn", spawnListener);
+          }
+          return;
         }
+        child.kill("SIGKILL");
+      };
+      abortListener = killChild;
+      if (opts.signal.aborted) {
+        abortListener();
+      } else {
+        opts.signal.addEventListener("abort", abortListener, { once: true });
+        if (opts.signal.aborted) abortListener();
       }
-    } else if (platform === "linux") {
-      const output = execSync(`readlink /proc/${pid}/cwd 2>/dev/null`, {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"]
-      }).trim();
-      if (output) return output;
     }
-  } catch {
-  }
-  return void 0;
+    timer.handle = setTimeout(
+      () => {
+        child.kill("SIGKILL");
+        finish({ code: null, stdout, stderr, timedOut: true });
+      },
+      Math.max(0, opts.timeoutMs)
+    );
+  });
 }
-function isPortInUse(port) {
-  const platform = process.platform;
+
+// src/lib/opencode/session-db-boot.ts
+var SESSION_DB_RESTORE_TIMEOUT_MS = 3e5;
+var SESSION_DB_VERIFY_TIMEOUT_MS = 12e4;
+var SESSION_DB_SYNCHRONISER_TIMEOUT_MS = 12e4;
+var SESSION_DB_VERIFY_WALKBACK_BUDGET_SECONDS = 120;
+function commandError(result) {
+  return result.stderr.trim() || `process exited with code ${result.code ?? "null"}`;
+}
+function reportRecord(stage, outcome, reason, litestreamExitCode, options) {
+  options.reportRecovery({
+    v: 1,
+    event: "session_db_recovery",
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    stage,
+    outcome,
+    severity: "error",
+    reason,
+    litestream_exit_code: litestreamExitCode,
+    attempt: null,
+    replica_objects: null,
+    replica_bytes: null,
+    quarantine_destination: null,
+    quarantined_objects: null,
+    quarantine_failed_objects: null,
+    quarantined_bytes: null,
+    verified_restore_point: null,
+    restore_points_tried: null,
+    provenance_reason: null,
+    provenance_migration_delta: null,
+    replication_suspended: stage === "restore"
+  });
+}
+function clearMarker(options) {
+  if (!options.noReplicateMarker) return;
   try {
-    if (platform === "darwin" || platform === "linux") {
-      execSync(`lsof -i :${port} -sTCP:LISTEN 2>/dev/null`, {
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"]
-      });
-      return true;
-    }
-  } catch {
+    unlinkSync2(options.noReplicateMarker);
+  } catch (error2) {
+    if (error2 instanceof Error && "code" in error2 && error2.code === "ENOENT") return;
+    options.log(
+      `Could not clear the previous session-DB no-replicate marker ${options.noReplicateMarker}: ${error2 instanceof Error ? error2.message : String(error2)}`,
+      "warn"
+    );
   }
-  return false;
 }
-function findAvailablePort(startPort, maxAttempts = 10) {
-  for (let i = 0; i < maxAttempts; i++) {
-    const port = startPort + i;
-    if (!isPortInUse(port)) {
-      return port;
+function markNoReplicate(options, message) {
+  if (options.noReplicateMarker) {
+    try {
+      mkdirSync(dirname2(options.noReplicateMarker), { recursive: true });
+      writeFileSync(options.noReplicateMarker, "");
+    } catch (error2) {
+      options.log(
+        `Could not write session-DB no-replicate marker ${options.noReplicateMarker}: ${error2 instanceof Error ? error2.message : String(error2)}`,
+        "error"
+      );
     }
   }
-  return null;
+  options.log(`SESSION-DB-NO-REPLICATE: ${message}`, "warn");
 }
-function findOpenCodeProcesses() {
-  const instances = [];
-  try {
-    const platform = process.platform;
-    if (platform === "darwin" || platform === "linux") {
-      let pids = [];
-      try {
-        const pgrepOutput = execSync('pgrep -f "opencode serve|opencode-serve"', {
-          encoding: "utf-8",
-          stdio: ["pipe", "pipe", "pipe"]
-        }).trim();
-        if (pgrepOutput) {
-          pids = pgrepOutput.split("\n").map((p) => parseInt(p.trim(), 10)).filter((p) => !isNaN(p));
-        }
-      } catch {
-        try {
-          const psOutput = execSync('ps aux | grep -E "opencode (serve|--port)" | grep -v grep', {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"]
-          }).trim();
-          if (psOutput) {
-            for (const line of psOutput.split("\n")) {
-              const parts = line.trim().split(/\s+/);
-              if (parts.length >= 2) {
-                const pid = parseInt(parts[1], 10);
-                if (!isNaN(pid)) pids.push(pid);
-              }
-            }
-          }
-        } catch (err) {
-          console.warn(
-            `findOpenCodeProcesses: ps fallback failed: ${err instanceof Error ? err.message : String(err)}`
-          );
-        }
-      }
-      for (const pid of pids) {
-        try {
-          const lsofOutput = execSync(`lsof -Pan -p ${pid} -i TCP -sTCP:LISTEN 2>/dev/null`, {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"]
-          }).trim();
-          for (const line of lsofOutput.split("\n")) {
-            const portMatch = line.match(/:(\d+)\s+\(LISTEN\)/);
-            if (portMatch) {
-              const port = parseInt(portMatch[1], 10);
-              if (!isNaN(port) && !instances.some((i) => i.port === port)) {
-                const cwd = getProcessCwd(pid);
-                instances.push({ pid, port, cwd });
-              }
-            }
-          }
-        } catch {
-        }
-      }
+function discardSessionDbDebris(options) {
+  for (const path of [options.dbPath, `${options.dbPath}-wal`, `${options.dbPath}-shm`]) {
+    try {
+      unlinkSync2(path);
+    } catch (error2) {
+      if (error2 instanceof Error && "code" in error2 && error2.code === "ENOENT") continue;
+      options.log(
+        `Could not remove session-DB debris ${path}: ${error2 instanceof Error ? error2.message : String(error2)}`,
+        "warn"
+      );
     }
-  } catch (err) {
-    console.warn(
-      `findOpenCodeProcesses: process detection failed: ${err instanceof Error ? err.message : String(err)}`
-    );
   }
-  return instances;
 }
-async function scanPortsForOpenCode() {
-  const instances = [];
-  const checks = OPENCODE_PORT_RANGE.map(async (port) => {
-    const health = await checkOpenCodeHealth(port);
-    if (health.healthy) {
-      let pid = 0;
-      try {
-        const lsofOutput = execSync(`lsof -ti :${port} -sTCP:LISTEN 2>/dev/null`, {
-          encoding: "utf-8",
-          stdio: ["pipe", "pipe", "pipe"]
-        }).trim();
-        if (lsofOutput) {
-          pid = parseInt(lsofOutput.split("\n")[0], 10) || 0;
-        }
-      } catch {
-      }
-      const cwd = pid ? getProcessCwd(pid) : void 0;
-      return { pid, port, cwd, version: health.version };
-    }
-    return null;
-  });
-  const results = await Promise.all(checks);
-  for (const result of results) {
-    if (result) {
-      instances.push(result);
-    }
-  }
-  return instances;
+function splitDiagnostics(text) {
+  return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
 }
-async function findHealthyOpenCodeInstances() {
-  const processes = findOpenCodeProcesses();
-  const healthy = [];
-  for (const proc of processes) {
-    const health = await checkOpenCodeHealth(proc.port);
-    if (health.healthy) {
-      healthy.push({ ...proc, version: health.version });
+function logSynchroniserDiagnostics(result, options) {
+  for (const line of splitDiagnostics(result.stderr)) options.log(line, "warn");
+}
+function parseSingleQuotedAssignment(line) {
+  const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line);
+  if (!match || !match[2].startsWith("'")) return null;
+  const valueSource = match[2];
+  let value = "";
+  for (let index = 1; index < valueSource.length; index++) {
+    const character = valueSource[index];
+    if (character !== "'") {
+      value += character;
+      continue;
     }
+    if (index === valueSource.length - 1) return [match[1], value];
+    if (valueSource.slice(index + 1, index + 4) !== "\\''") return null;
+    value += "'";
+    index += 3;
   }
-  if (healthy.length === 0) {
-    const scanned = await scanPortsForOpenCode();
-    return scanned;
-  }
-  return healthy;
+  return null;
 }
-async function startOpenCode(port) {
-  let command = "opencode";
-  let args = ["serve", "--port", port.toString(), "--hostname", "127.0.0.1"];
-  try {
-    execSync("which opencode", { stdio: "ignore" });
-  } catch {
-    command = "npx";
-    args = ["opencode", "serve", "--port", port.toString(), "--hostname", "127.0.0.1"];
-  }
-  const child = spawn(command, args, {
-    detached: true,
-    stdio: "ignore",
-    cwd: process.cwd()
+function parseSynchroniserEnv(stdout) {
+  const values = {};
+  for (const line of stdout.split("\n")) {
+    if (line.trim() === "") continue;
+    const assignment = parseSingleQuotedAssignment(line);
+    if (!assignment) return null;
+    values[assignment[0]] = assignment[1];
+  }
+  return values;
+}
+function runCommand(command, args, options) {
+  return new Promise((resolve4) => {
+    let child;
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve4(result);
+    };
+    try {
+      child = spawn2(command, args, {
+        env: options.env,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (error2) {
+      resolve4({
+        code: null,
+        stdout,
+        stderr: error2 instanceof Error ? error2.message : String(error2),
+        timedOut: false
+      });
+      return;
+    }
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.once("error", (error2) => {
+      finish({
+        code: null,
+        stdout,
+        stderr: stderr === "" ? error2.message : `${stderr}
+${error2.message}`,
+        timedOut: false
+      });
+    });
+    child.once("close", (code) => finish({ code, stdout, stderr, timedOut: false }));
+    const timer = setTimeout(
+      () => {
+        child.kill("SIGKILL");
+        finish({ code: null, stdout, stderr, timedOut: true });
+      },
+      Math.max(0, options.timeoutMs)
+    );
   });
-  return child;
 }
-function stopOpenCode(opencodeProcess) {
-  if (!opencodeProcess || !opencodeProcess.pid) {
-    return;
+async function ensureLitestreamConfig(options, env) {
+  const configPath = options.litestreamConfig;
+  if (!configPath) {
+    markNoReplicate(options, "no Litestream configuration path was provided");
+    reportRecord(
+      "restore",
+      "restore_misconfigured",
+      "litestream_config_unavailable",
+      null,
+      options
+    );
+    return null;
   }
   try {
-    if (process.platform === "win32") {
-      opencodeProcess.kill("SIGTERM");
-    } else {
-      process.kill(-opencodeProcess.pid, "SIGTERM");
-    }
-  } catch (err) {
-    if (err.code !== "ESRCH") {
+    if (statSync2(configPath).size > 0) return configPath;
+  } catch (error2) {
+    if (!(error2 instanceof Error && "code" in error2 && error2.code === "ENOENT")) {
+      options.log(
+        `Could not inspect ${configPath}: ${error2 instanceof Error ? error2.message : String(error2)}`,
+        "warn"
+      );
+    }
+  }
+  const rendered = await runSynchroniser(["litestream-config"], {
+    timeoutMs: SESSION_DB_SYNCHRONISER_TIMEOUT_MS,
+    env
+  });
+  logSynchroniserDiagnostics(rendered, options);
+  if (rendered.timedOut || rendered.code !== 0) {
+    options.log(
+      `Could not generate ${configPath}: runner-synchroniser litestream-config failed (${commandError(rendered)})`,
+      "error"
+    );
+    markNoReplicate(options, `could not generate ${configPath}`);
+    reportRecord(
+      "restore",
+      "restore_misconfigured",
+      "litestream_config_unavailable",
+      null,
+      options
+    );
+    return null;
+  }
+  try {
+    mkdirSync(dirname2(configPath), { recursive: true });
+    writeFileSync(configPath, rendered.stdout);
+  } catch (error2) {
+    options.log(
+      `Could not write ${configPath}: ${error2 instanceof Error ? error2.message : String(error2)}`,
+      "error"
+    );
+    markNoReplicate(options, `could not generate ${configPath}`);
+    reportRecord(
+      "restore",
+      "restore_misconfigured",
+      "litestream_config_unavailable",
+      null,
+      options
+    );
+    return null;
+  }
+  const version2 = await runCommand("litestream", ["version"], {
+    env,
+    timeoutMs: 1e4
+  });
+  const litestreamVersion = version2.code === 0 ? version2.stdout.trim() || "unknown" : "unknown";
+  const regionEmpty = !/^\s*region:\s*\S+/m.test(rendered.stdout);
+  options.log(
+    `litestream ${litestreamVersion}; AWS_REGION=${env.AWS_REGION ?? "<unset>"} AWS_DEFAULT_REGION=${env.AWS_DEFAULT_REGION ?? "<unset>"}; rendered litestream.yml region empty: ${regionEmpty ? "yes" : "no"}`
+  );
+  return configPath;
+}
+function restoreGiveUp(options, reason, message, litestreamExitCode, outcome = "fresh_session_db") {
+  discardSessionDbDebris(options);
+  markNoReplicate(options, message);
+  reportRecord("restore", outcome, reason, litestreamExitCode, options);
+}
+async function restoreSessionDb(options, configPath, env) {
+  const restored = await runCommand(
+    "litestream",
+    ["restore", "-config", configPath, "-if-db-not-exists", "-if-replica-exists", options.dbPath],
+    { env, timeoutMs: SESSION_DB_RESTORE_TIMEOUT_MS }
+  );
+  for (const line of splitDiagnostics(restored.stderr)) options.log(line, "warn");
+  if (restored.timedOut || restored.code === 124 || restored.code === 137) {
+    restoreGiveUp(
+      options,
+      "restore_deadline_exceeded",
+      `SESSION-DB-RESTORE-TRUNCATED: litestream restore did not finish within ${SESSION_DB_RESTORE_TIMEOUT_MS}ms; opencode starts with a fresh session DB and nothing is replicated this boot`,
+      restored.code ?? 124
+    );
+    return;
+  }
+  if (restored.code === null || restored.code === 125 || restored.code === 126 || restored.code === 127) {
+    options.log(`litestream restore could not run (${commandError(restored)})`, "error");
+    restoreGiveUp(
+      options,
+      "restore_tool_unusable",
+      `restore tool is broken (${commandError(restored)}); opencode starts with a fresh session DB and nothing is replicated this boot`,
+      restored.code
+    );
+    return;
+  }
+  const classified = await runSynchroniser(
+    [
+      "session-db-classify",
+      String(restored.code ?? 1),
+      "1",
+      "--on-unusable-replica=leave",
+      "--fresh-db-fallback"
+    ],
+    { timeoutMs: SESSION_DB_SYNCHRONISER_TIMEOUT_MS, env }
+  );
+  logSynchroniserDiagnostics(classified, options);
+  const classifyCode = classified.code;
+  switch (classifyCode) {
+    case 0:
+      return;
+    case 31:
+      acknowledgeSessionDbRecoveryReport(sessionDbRecoveryReportPath(homedir2(), env));
+      options.log(
+        "SESSION-DB-REPLICA-UNUSABLE: booting with a fresh opencode.db and replicating into the existing prefix this boot",
+        "warn"
+      );
+      return;
+    case 32:
+      acknowledgeSessionDbRecoveryReport(sessionDbRecoveryReportPath(homedir2(), env));
+      discardSessionDbDebris(options);
+      markNoReplicate(
+        options,
+        "session-db-classify asked for another restore attempt (32), but this boot has budget for only one; treating it as a give-up rather than retrying"
+      );
+      return;
+    case 30:
+      restoreGiveUp(
+        options,
+        "classification_fatal",
+        "session-db-classify returned fatal (30); see the FATAL message above",
+        restored.code,
+        "restore_misconfigured"
+      );
+      return;
+    default:
+      restoreGiveUp(
+        options,
+        "classification_unrecognised",
+        `session-db-classify exited ${classifyCode ?? "null"}, which is none of its documented answers`,
+        restored.code
+      );
+  }
+}
+async function verifySessionDb(options, configPath, env) {
+  if (!options.noReplicateMarker || !fileExists(options.noReplicateMarker)) {
+    const result = await runSynchroniser(["session-db-verify", configPath], {
+      timeoutMs: SESSION_DB_VERIFY_TIMEOUT_MS,
+      env: {
+        ...env,
+        // The synchroniser reads this value in SECONDS. Keep this at 120, not
+        // 120_000, so the walkback gives up before the outer process bound.
+        EVIDENT_SESSION_DB_WALKBACK_BUDGET_SECONDS: String(
+          SESSION_DB_VERIFY_WALKBACK_BUDGET_SECONDS
+        )
+      }
+    });
+    logSynchroniserDiagnostics(result, options);
+    if (result.timedOut || result.code === 124 || result.code === 137) {
+      options.log(
+        `SESSION-DB-VERIFY-TIMEOUT: verification did not finish within its ${SESSION_DB_VERIFY_TIMEOUT_MS}ms deadline; continuing with the restored opencode.db as-is, unverified`,
+        "warn"
+      );
+      return false;
+    }
+    if (result.code === 34) {
+      reportRecord(
+        "verify",
+        "session_db_boot_refused",
+        result.stderr.includes("SESSION-DB-LOCAL-DISCARD-FAILED") ? "local_discard_failed" : "replica_separation_unproven",
+        null,
+        options
+      );
+      return true;
+    }
+    if (result.code === 33) {
+      options.log(
+        "SESSION-DB-INTEGRITY-EXHAUSTED: booting continues and litestream still replicates, starting an empty backup chain after the corrupt replica was separated.",
+        "warn"
+      );
+      return false;
+    }
+    if (result.code !== 0) {
+      options.log(
+        `SESSION-DB-VERIFY-UNKNOWN: session-db-verify exited ${result.code ?? "null"}, which is none of its documented answers; continuing with the restored opencode.db as-is`,
+        "warn"
+      );
+    }
+    return false;
+  }
+  options.log(
+    "skipping session-DB verification: this boot's session DB was not proven safe to replicate",
+    "debug"
+  );
+  return false;
+}
+function fileExists(path) {
+  try {
+    statSync2(path);
+    return true;
+  } catch (error2) {
+    if (error2 instanceof Error && "code" in error2 && error2.code === "ENOENT") return false;
+    return true;
+  }
+}
+async function restoreAndVerifySessionDb(options) {
+  const env = options.env ?? process.env;
+  clearMarker(options);
+  acknowledgeSessionDbRecoveryReport(sessionDbRecoveryReportPath(homedir2(), env));
+  const synchroniserEnv = await runSynchroniser(["env"], {
+    timeoutMs: SESSION_DB_SYNCHRONISER_TIMEOUT_MS,
+    env
+  });
+  logSynchroniserDiagnostics(synchroniserEnv, options);
+  if (synchroniserEnv.timedOut || synchroniserEnv.code !== 0) {
+    options.log(
+      `runner-synchroniser env could not resolve the session-DB configuration (${commandError(synchroniserEnv)})`,
+      "error"
+    );
+    markNoReplicate(
+      options,
+      "could not resolve the runner-synchroniser configuration (see the ERROR above)"
+    );
+    reportRecord(
+      "restore",
+      "restore_misconfigured",
+      "synchroniser_config_unresolved",
+      null,
+      options
+    );
+    return { verifyFatal: false };
+  }
+  const values = parseSynchroniserEnv(synchroniserEnv.stdout);
+  if (!values) {
+    markNoReplicate(
+      options,
+      "the runner-synchroniser configuration could not be evaluated; the installed bundle likely does not match this hook"
+    );
+    reportRecord(
+      "restore",
+      "restore_misconfigured",
+      "synchroniser_config_unevaluable",
+      null,
+      options
+    );
+    return { verifyFatal: false };
+  }
+  const synchroniserDbPath = values.OPENCODE_DB_PATH;
+  if (!synchroniserDbPath) {
+    markNoReplicate(
+      options,
+      "run_synchroniser env did not define OPENCODE_DB_PATH; the installed runner-synchroniser build likely does not match this hook"
+    );
+    reportRecord(
+      "restore",
+      "restore_misconfigured",
+      "synchroniser_config_incomplete",
+      null,
+      options
+    );
+    return { verifyFatal: false };
+  }
+  if (resolvePath(synchroniserDbPath) !== resolvePath(options.dbPath)) {
+    options.log(
+      `runner-synchroniser reported OPENCODE_DB_PATH=${synchroniserDbPath}, but OpenCode uses ${options.dbPath}; continuing with OpenCode's session-DB path`,
+      "warn"
+    );
+  }
+  if (!values.PERSISTENCE_BUCKET) {
+    options.log(
+      "SESSION-DB-PERSISTENCE-DISABLED: LITESTREAM_BUCKET/LITESTREAM_PREFIX are not both set; opencode starts with a fresh session DB and nothing is replicated.",
+      "warn"
+    );
+    return { verifyFatal: false };
+  }
+  const configPath = await ensureLitestreamConfig(options, env);
+  if (!configPath) return { verifyFatal: false };
+  await restoreSessionDb(options, configPath, env);
+  if (options.noReplicateMarker && fileExists(options.noReplicateMarker)) {
+    return { verifyFatal: false };
+  }
+  return { verifyFatal: await verifySessionDb(options, configPath, env) };
+}
+
+// src/lib/opencode/session-db-provenance.ts
+import { createRequire } from "module";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, join as join3 } from "path";
+var require2 = createRequire(import.meta.url);
+function readSessionDbMigrationIds(dbPath) {
+  let db;
+  try {
+    const { DatabaseSync } = require2("node:sqlite");
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    const columns = db.prepare("PRAGMA table_info(migration)").all();
+    const hasExpectedShape = columns.length === 2 && columns.some(
+      (column) => column.name === "id" && typeof column.type === "string" && column.type.toUpperCase() === "TEXT" && column.pk === 1
+    ) && columns.some(
+      (column) => column.name === "time_completed" && typeof column.type === "string" && column.type.toUpperCase() === "INTEGER" && column.notnull === 1 && column.pk === 0
+    );
+    if (!hasExpectedShape) {
+      console.warn(`[readSessionDbMigrationIds] unsupported migration table shape in ${dbPath}`);
+      return null;
+    }
+    const rows = db.prepare("SELECT id FROM migration ORDER BY id").all();
+    if (rows.some((row) => typeof row.id !== "string")) return null;
+    return rows.map((row) => row.id);
+  } catch (error2) {
+    console.warn(
+      `[readSessionDbMigrationIds] could not read migration history from ${dbPath}: ${error2 instanceof Error ? error2.message : String(error2)}`
+    );
+    return null;
+  } finally {
+    try {
+      db?.close();
+    } catch (error2) {
       console.warn(
-        `stopOpenCode: kill failed: ${err instanceof Error ? err.message : String(err)}`
+        `[readSessionDbMigrationIds] could not close ${dbPath}: ${error2 instanceof Error ? error2.message : String(error2)}`
       );
     }
-  }
+  }
+}
+function sessionDbProvenanceStatePath(homeDir, env) {
+  const override = env.EVIDENT_SESSION_DB_PROVENANCE_STATE?.trim();
+  return override || join3(homeDir, ".local", "state", "evident", "session-db-provenance.json");
+}
+function loadSessionDbProvenanceState(path) {
+  let value;
+  try {
+    value = JSON.parse(readFileSync3(path, "utf8"));
+  } catch (error2) {
+    if (error2 instanceof Error && "code" in error2 && error2.code === "ENOENT") return {};
+    console.error(
+      `[session-db-provenance] could not read ${path}: ${error2 instanceof Error ? error2.message : String(error2)}`
+    );
+    return {};
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    console.error(`[session-db-provenance] ignored malformed state in ${path}`);
+    return {};
+  }
+  const state = {};
+  for (const [dbPath, record] of Object.entries(value)) {
+    if (!isSessionDbProvenanceRecord(record)) {
+      console.error(`[session-db-provenance] ignored malformed state in ${path}`);
+      return {};
+    }
+    state[dbPath] = record;
+  }
+  return state;
+}
+function saveSessionDbProvenanceState(path, state) {
+  try {
+    mkdirSync2(dirname3(path), { recursive: true });
+    writeFileSync2(path, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+  } catch (error2) {
+    console.error(
+      `[session-db-provenance] could not write ${path}: ${error2 instanceof Error ? error2.message : String(error2)}`
+    );
+  }
+}
+function evaluateSessionDbProvenance(input) {
+  const { currentVersion, currentIds, previous } = input;
+  if (!previous) return { anomaly: false, reason: null };
+  const current = new Set(currentIds);
+  const prior = new Set(previous.migrationIds);
+  for (const id of prior) {
+    if (!current.has(id)) return { anomaly: true, reason: "migration-history-regressed" };
+  }
+  if (current.size > prior.size && previous.opencodeVersion === currentVersion) {
+    return { anomaly: true, reason: "foreign-version-migrations" };
+  }
+  return { anomaly: false, reason: null };
+}
+function checkSessionDbProvenance(input) {
+  const { dbPath, currentVersion, homeDir, env } = input;
+  const path = sessionDbProvenanceStatePath(homeDir, env);
+  const state = loadSessionDbProvenanceState(path);
+  const previous = state[dbPath];
+  const currentIds = readSessionDbMigrationIds(dbPath);
+  if (currentIds === null) {
+    return {
+      anomaly: false,
+      reason: null,
+      recordedVersion: previous?.opencodeVersion ?? null,
+      migrationDelta: null
+    };
+  }
+  const decision = evaluateSessionDbProvenance({ currentVersion, currentIds, previous });
+  const migrationDelta = previous ? new Set(currentIds).size - new Set(previous.migrationIds).size : null;
+  state[dbPath] = {
+    opencodeVersion: currentVersion,
+    migrationIds: currentIds,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  saveSessionDbProvenanceState(path, state);
+  return {
+    ...decision,
+    recordedVersion: previous?.opencodeVersion ?? null,
+    migrationDelta
+  };
+}
+function isSessionDbProvenanceRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value;
+  return typeof record.opencodeVersion === "string" && Array.isArray(record.migrationIds) && record.migrationIds.every((id) => typeof id === "string") && typeof record.updatedAt === "string";
+}
+
+// src/lib/opencode/opencode-version-gate.ts
+var QUEUE_VALIDATED_OPENCODE_VERSIONS = ["1.17.11", "1.18.3"];
+function isQueueValidatedVersion(version2) {
+  if (!version2) return false;
+  return QUEUE_VALIDATED_OPENCODE_VERSIONS.includes(version2);
+}
+function buildOpenCodeVersionWarning(version2) {
+  if (isQueueValidatedVersion(version2)) return null;
+  const detected = version2 ? `v${version2}` : "unknown";
+  const validated = QUEUE_VALIDATED_OPENCODE_VERSIONS.map((v) => `v${v}`).join(", ");
+  return `Warning: opencode ${detected} is not a queue-validated version (validated: ${validated}). Native message queuing \u2014 which channel (Slack) message handling relies on \u2014 is unverified on this version; queued/follow-up messages may behave unexpectedly. Continuing anyway. Bumping the validated set requires re-running the queue validation.`;
+}
+
+// src/lib/opencode/process.ts
+import { execSync, spawn as spawn3 } from "child_process";
+
+// src/lib/process-stop.ts
+async function stopProcessAndWait(child, timeoutMs, sendTerm, sendKill) {
+  if (!child.pid) {
+    return { outcome: "not-running", code: child.exitCode, signal: child.signalCode };
+  }
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return { outcome: "exited", code: child.exitCode, signal: child.signalCode };
+  }
+  return new Promise((resolve4, reject) => {
+    let forced = false;
+    let settled = false;
+    const timer = setTimeout(() => {
+      forced = true;
+      try {
+        sendKill();
+      } catch (error2) {
+        if (error2.code === "ESRCH") {
+          finish({ outcome: "exited", code: child.exitCode, signal: child.signalCode });
+        } else {
+          fail(error2);
+        }
+      }
+    }, timeoutMs);
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.removeListener("exit", onExit);
+      resolve4(result);
+    };
+    const fail = (error2) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.removeListener("exit", onExit);
+      reject(error2);
+    };
+    const onExit = (code, signal) => {
+      finish({ outcome: forced ? "killed" : "exited", code, signal });
+    };
+    child.once("exit", onExit);
+    try {
+      sendTerm();
+    } catch (error2) {
+      if (error2.code === "ESRCH") {
+        finish({ outcome: "exited", code: child.exitCode, signal: child.signalCode });
+      } else {
+        fail(error2);
+      }
+      return;
+    }
+  });
+}
+
+// src/lib/opencode/process.ts
+var OPENCODE_PORT_RANGE = [4096, 4097, 4098, 4099, 4100];
+function getProcessCwd(pid) {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin") {
+      const output = execSync(`lsof -a -p ${pid} -d cwd -Fn 2>/dev/null`, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      const lines = output.split("\n");
+      for (const line of lines) {
+        if (line.startsWith("n") && !line.startsWith("n ")) {
+          return line.slice(1);
+        }
+      }
+    } else if (platform === "linux") {
+      const output = execSync(`readlink /proc/${pid}/cwd 2>/dev/null`, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      if (output) return output;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function isPortInUse(port) {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin" || platform === "linux") {
+      execSync(`lsof -i :${port} -sTCP:LISTEN 2>/dev/null`, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      return true;
+    }
+  } catch {
+  }
+  return false;
+}
+function findAvailablePort(startPort, maxAttempts = 10) {
+  for (let i = 0; i < maxAttempts; i++) {
+    const port = startPort + i;
+    if (!isPortInUse(port)) {
+      return port;
+    }
+  }
+  return null;
+}
+function findOpenCodeProcesses() {
+  const instances = [];
+  try {
+    const platform = process.platform;
+    if (platform === "darwin" || platform === "linux") {
+      let pids = [];
+      try {
+        const pgrepOutput = execSync('pgrep -f "opencode serve|opencode-serve"', {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"]
+        }).trim();
+        if (pgrepOutput) {
+          pids = pgrepOutput.split("\n").map((p) => parseInt(p.trim(), 10)).filter((p) => !isNaN(p));
+        }
+      } catch {
+        try {
+          const psOutput = execSync('ps aux | grep -E "opencode (serve|--port)" | grep -v grep', {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"]
+          }).trim();
+          if (psOutput) {
+            for (const line of psOutput.split("\n")) {
+              const parts = line.trim().split(/\s+/);
+              if (parts.length >= 2) {
+                const pid = parseInt(parts[1], 10);
+                if (!isNaN(pid)) pids.push(pid);
+              }
+            }
+          }
+        } catch (err) {
+          console.warn(
+            `findOpenCodeProcesses: ps fallback failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+      for (const pid of pids) {
+        try {
+          const lsofOutput = execSync(`lsof -Pan -p ${pid} -i TCP -sTCP:LISTEN 2>/dev/null`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"]
+          }).trim();
+          for (const line of lsofOutput.split("\n")) {
+            const portMatch = line.match(/:(\d+)\s+\(LISTEN\)/);
+            if (portMatch) {
+              const port = parseInt(portMatch[1], 10);
+              if (!isNaN(port) && !instances.some((i) => i.port === port)) {
+                const cwd = getProcessCwd(pid);
+                instances.push({ pid, port, cwd });
+              }
+            }
+          }
+        } catch {
+        }
+      }
+    }
+  } catch (err) {
+    console.warn(
+      `findOpenCodeProcesses: process detection failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return instances;
+}
+async function scanPortsForOpenCode() {
+  const instances = [];
+  const checks = OPENCODE_PORT_RANGE.map(async (port) => {
+    const health = await checkOpenCodeHealth(port);
+    if (health.healthy) {
+      let pid = 0;
+      try {
+        const lsofOutput = execSync(`lsof -ti :${port} -sTCP:LISTEN 2>/dev/null`, {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"]
+        }).trim();
+        if (lsofOutput) {
+          pid = parseInt(lsofOutput.split("\n")[0], 10) || 0;
+        }
+      } catch {
+      }
+      const cwd = pid ? getProcessCwd(pid) : void 0;
+      return { pid, port, cwd, version: health.version };
+    }
+    return null;
+  });
+  const results = await Promise.all(checks);
+  for (const result of results) {
+    if (result) {
+      instances.push(result);
+    }
+  }
+  return instances;
+}
+async function findHealthyOpenCodeInstances() {
+  const processes = findOpenCodeProcesses();
+  const healthy = [];
+  for (const proc of processes) {
+    const health = await checkOpenCodeHealth(proc.port);
+    if (health.healthy) {
+      healthy.push({ ...proc, version: health.version });
+    }
+  }
+  if (healthy.length === 0) {
+    const scanned = await scanPortsForOpenCode();
+    return scanned;
+  }
+  return healthy;
+}
+async function startOpenCode(port, options = {}) {
+  let command = "opencode";
+  const printLogs = options.inheritStdio ? ["--print-logs"] : [];
+  let args = ["serve", "--port", port.toString(), "--hostname", "127.0.0.1", ...printLogs];
+  try {
+    execSync("which opencode", { stdio: "ignore" });
+  } catch {
+    command = "npx";
+    args = [
+      "opencode",
+      "serve",
+      "--port",
+      port.toString(),
+      "--hostname",
+      "127.0.0.1",
+      ...printLogs
+    ];
+  }
+  const child = spawn3(command, args, {
+    detached: true,
+    stdio: options.inheritStdio ? "inherit" : "ignore",
+    cwd: process.cwd()
+  });
+  return child;
+}
+function stopOpenCodeAndWait(opencodeProcess, timeoutMs) {
+  const sendSignal = (signal) => {
+    if (process.platform === "win32") {
+      opencodeProcess.kill(signal);
+    } else {
+      process.kill(-opencodeProcess.pid, signal);
+    }
+  };
+  return stopProcessAndWait(
+    opencodeProcess,
+    timeoutMs,
+    () => sendSignal("SIGTERM"),
+    () => sendSignal("SIGKILL")
+  );
 }
 
 // src/lib/opencode/install.ts
@@ -2091,6 +2923,7 @@ async function createOpenCodeSession(port, directory) {
   return data.id;
 }
 async function getModelAttachmentCapability(port, model) {
+  const { model: baseModel } = splitModelVariant(model);
   try {
     const res = await timedFetch(`${opencodeBase(port)}/config/providers`);
     if (!res.ok) {
@@ -2107,9 +2940,9 @@ async function getModelAttachmentCapability(port, model) {
       );
       return null;
     }
-    const slash = model ? model.indexOf("/") : -1;
-    const providerId = slash > 0 ? model.slice(0, slash) : void 0;
-    let modelId = slash > 0 ? model.slice(slash + 1) : void 0;
+    const slash = baseModel ? baseModel.indexOf("/") : -1;
+    const providerId = slash > 0 ? baseModel.slice(0, slash) : void 0;
+    let modelId = slash > 0 ? baseModel.slice(slash + 1) : void 0;
     const defaults2 = body?.default && typeof body.default === "object" ? body.default : void 0;
     let provider = providerId ? providers.find((p) => p?.id === providerId) : void 0;
     if (!provider && !providerId) {
@@ -2189,6 +3022,29 @@ async function buildFileParts(attachments, capable) {
   }
   return { parts, outcomes, capabilityUnknown };
 }
+function splitModelVariant(raw) {
+  const value = raw?.trim();
+  if (!value) return {};
+  const hashIndex = value.indexOf("#");
+  if (hashIndex === -1) return { model: value };
+  const model = value.slice(0, hashIndex).trim() || void 0;
+  const variant = value.slice(hashIndex + 1).trim() || void 0;
+  return { model, variant };
+}
+function applyModelOptions(body, options) {
+  if (options?.agent) body.agent = options.agent;
+  const { model, variant } = splitModelVariant(options?.model);
+  if (model) {
+    const slashIndex = model.indexOf("/");
+    if (slashIndex !== -1) {
+      body.model = {
+        providerID: model.substring(0, slashIndex),
+        modelID: model.substring(slashIndex + 1)
+      };
+    }
+  }
+  if (variant) body.variant = variant;
+}
 function messageText(m) {
   if (!m || !Array.isArray(m.parts)) return "";
   return m.parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text).join("");
@@ -2213,18 +3069,7 @@ async function sendPromptAsync(port, sessionId, content, options, attachments) {
   const body = {
     parts
   };
-  if (options?.agent) {
-    body.agent = options.agent;
-  }
-  if (options?.model) {
-    const slashIndex = options.model.indexOf("/");
-    if (slashIndex !== -1) {
-      body.model = {
-        providerID: options.model.substring(0, slashIndex),
-        modelID: options.model.substring(slashIndex + 1)
-      };
-    }
-  }
+  applyModelOptions(body, options);
   const res = await timedFetch(`${opencodeBase(port)}/session/${sessionId}/prompt_async`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -2232,7 +3077,10 @@ async function sendPromptAsync(port, sessionId, content, options, attachments) {
   });
   if (res.status < 200 || res.status >= 300) {
     const text = await res.text().catch(() => "");
-    throw new Error(`OpenCode prompt_async failed: HTTP ${res.status}${text ? `: ${text}` : ""}`);
+    const { variant } = splitModelVariant(options?.model);
+    throw new Error(
+      `OpenCode prompt_async failed: HTTP ${res.status}${text ? `: ${text}` : ""}${variant ? ` (variant: ${variant})` : ""}`
+    );
   }
   const READ_BACK_ATTEMPTS = 5;
   const READ_BACK_DELAY_MS = 150;
@@ -2256,7 +3104,7 @@ async function sendPromptAsync(port, sessionId, content, options, attachments) {
       }
     }
     if (attempt < READ_BACK_ATTEMPTS - 1) {
-      await new Promise((resolve3) => setTimeout(resolve3, READ_BACK_DELAY_MS));
+      await new Promise((resolve4) => setTimeout(resolve4, READ_BACK_DELAY_MS));
     }
   }
   return null;
@@ -2387,7 +3235,7 @@ function isPreamblePinnedRunning(messages, userMessageId) {
   return completedOf(reply) != null && finishOf(reply) === "tool-calls";
 }
 function isB2AbandonmentConfirmed(params) {
-  return params.pinnedForMs >= params.minPinnedMs && params.descendantOngoing === false;
+  return params.pinnedForMs >= params.minPinnedMs && params.descendantOngoing === false && params.rootOngoing === false;
 }
 function isAmbiguousTerminalFinish(m) {
   if (completedOf(m) == null) return false;
@@ -2400,7 +3248,7 @@ function isAmbiguousFinishPinnedRunning(messages, userMessageId) {
   return isAmbiguousTerminalFinish(reply);
 }
 function isAmbiguousFinishResolved(params) {
-  return params.sessionOngoing === false || params.pinnedForMs >= params.maxPinnedMs;
+  return params.sessionOngoing === false || params.sessionOngoing !== true && params.pinnedForMs >= params.maxPinnedMs;
 }
 function messageError(messages, userMessageId) {
   const reply = findLastAssistantReplyFor(messages, userMessageId);
@@ -2609,13 +3457,13 @@ function resolveSessionCleanupConfig(flags, env = process.env) {
 }
 
 // src/lib/opencode/session-db-size.ts
-import { statSync as statSync2 } from "fs";
-import { join as join3 } from "path";
+import { statSync as statSync3 } from "fs";
+import { join as join4 } from "path";
 var LARGE_DB_THRESHOLD_BYTES = 268435456;
 function statSessionDbBytes(homeDir) {
-  const dbPath = join3(homeDir, ".local", "share", "opencode", "opencode.db");
+  const dbPath = join4(homeDir, ".local", "share", "opencode", "opencode.db");
   try {
-    return statSync2(dbPath).size;
+    return statSync3(dbPath).size;
   } catch (err) {
     const isMissingFile = err instanceof Error && "code" in err && err.code === "ENOENT";
     if (!isMissingFile) {
@@ -2641,11 +3489,11 @@ function buildSessionStoreSizeWarning(input) {
 }
 
 // src/lib/opencode/session-db-reclaim.ts
-import { statSync as statSync3, statfsSync } from "fs";
-import { dirname as dirname2 } from "path";
+import { statSync as statSync4, statfsSync } from "fs";
+import { dirname as dirname4 } from "path";
 function insufficientSpaceReason(dbPath, requiredBytes) {
   try {
-    const fsStats = statfsSync(dirname2(dbPath));
+    const fsStats = statfsSync(dirname4(dbPath));
     const availableBytes = fsStats.bavail * fsStats.bsize;
     if (availableBytes < requiredBytes) {
       return `only ${availableBytes} bytes free, need ${requiredBytes} for a second copy`;
@@ -2714,7 +3562,7 @@ async function reclaimSessionDbSpace(input) {
         );
         return { ok: false, skipped: "full-vacuum-blocked" };
       }
-      const fileBytesForGuard = statSync3(dbPath).size;
+      const fileBytesForGuard = statSync4(dbPath).size;
       const skipReason = insufficientSpaceReason(dbPath, fileBytesForGuard);
       if (skipReason !== null) {
         console.warn(
@@ -2842,12 +3690,12 @@ var StreamForwarder = class {
     let endBody;
     if (has_body) {
       const chunks = [];
-      bodyPromise = new Promise((resolve3) => {
+      bodyPromise = new Promise((resolve4) => {
         pushBody = (buf) => {
           chunks.push(buf);
         };
         endBody = () => {
-          resolve3(Buffer.concat(chunks));
+          resolve4(Buffer.concat(chunks));
         };
       });
     }
@@ -2976,7 +3824,7 @@ function connectTunnel(options) {
   } = options;
   const tunnelUrl = getTunnelUrlConfig();
   const url = `${tunnelUrl}/tunnel/${agentId}/connect`;
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const ws = new WebSocket2(url, {
       headers: {
         Authorization: authHeader
@@ -3027,8 +3875,8 @@ function connectTunnel(options) {
       try {
         message = JSON.parse(data.toString());
       } catch (error2) {
-        const errorMessage = error2 instanceof Error ? error2.message : "Unknown error";
-        onError?.(`Failed to handle message: ${errorMessage}`);
+        const errorMessage2 = error2 instanceof Error ? error2.message : "Unknown error";
+        onError?.(`Failed to handle message: ${errorMessage2}`);
         return;
       }
       if (isStreamFrame(message)) {
@@ -3040,7 +3888,7 @@ function connectTunnel(options) {
           clearTimeout(connectionTimeout);
           const connectedAgentId = message.agent_id ?? agentId;
           onConnected?.(connectedAgentId);
-          resolve3({
+          resolve4({
             ws,
             close: () => ws.close(1e3, "CLI shutdown")
           });
@@ -3171,10 +4019,10 @@ var RunnerConnection = class {
 };
 
 // src/lib/tunnel/ready-marker.ts
-import { writeFileSync } from "fs";
+import { writeFileSync as writeFileSync3 } from "fs";
 function writeTunnelReadyMarker(path, agentId) {
   try {
-    writeFileSync(path, `${agentId}
+    writeFileSync3(path, `${agentId}
 `);
     return { ok: true };
   } catch (error2) {
@@ -3182,10 +4030,52 @@ function writeTunnelReadyMarker(path, agentId) {
   }
 }
 
+// src/lib/replication.ts
+import { spawn as spawn4 } from "child_process";
+function startSessionDbReplication(configPath) {
+  return spawn4("litestream", ["replicate", "-config", configPath], {
+    stdio: "inherit"
+  });
+}
+async function stopSessionDbReplication(child, timeoutMs) {
+  return stopProcessAndWait(
+    child,
+    timeoutMs,
+    () => child.kill("SIGTERM"),
+    () => child.kill("SIGKILL")
+  );
+}
+
+// src/lib/process-liveness.ts
+import { readFileSync as readFileSync4 } from "fs";
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+  } catch (error2) {
+    const code = error2.code;
+    if (code === "ESRCH") return false;
+    if (code === "EPERM") return true;
+    console.error(
+      `[process-liveness] could not probe process ${pid}: ${error2 instanceof Error ? error2.message : String(error2)}`
+    );
+    return false;
+  }
+  if (process.platform !== "linux") return true;
+  try {
+    const status2 = readFileSync4(`/proc/${pid}/status`, "utf8");
+    return !/^State:\s+Z(?:\s|$)/m.test(status2);
+  } catch (error2) {
+    console.error(
+      `[process-liveness] could not inspect /proc/${pid}/status: ${error2 instanceof Error ? error2.message : String(error2)}`
+    );
+    return true;
+  }
+}
+
 // src/lib/openai-usage.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join4 } from "path";
+import { readFileSync as readFileSync5 } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join5 } from "path";
 var CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
 var OPENCODE_AUTH_SEGMENTS = [".local", "share", "opencode", "auth.json"];
 var OpenAiUsageError = class extends Error {
@@ -3199,7 +4089,7 @@ function isLocalCredentialProblem2(err) {
 }
 function readOpenCodeChatGptCredentials() {
   try {
-    const raw = readFileSync3(join4(homedir2(), ...OPENCODE_AUTH_SEGMENTS), "utf-8");
+    const raw = readFileSync5(join5(homedir3(), ...OPENCODE_AUTH_SEGMENTS), "utf-8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -3221,6 +4111,23 @@ function readOpenCodeChatGptCredentials() {
     return null;
   }
 }
+function parseChatGptIdentity(accessToken) {
+  const segments = accessToken.split(".");
+  if (segments.length !== 3) return null;
+  let payload;
+  try {
+    const parsed = JSON.parse(Buffer.from(segments[1], "base64url").toString("utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    payload = parsed;
+  } catch {
+    return null;
+  }
+  const profile = payload["https://api.openai.com/profile"];
+  const auth = payload["https://api.openai.com/auth"];
+  const ownerEmail = typeof profile?.email === "string" ? profile.email.trim() || null : null;
+  const planType = typeof auth?.chatgpt_plan_type === "string" ? auth.chatgpt_plan_type.trim() || null : null;
+  return ownerEmail === null && planType === null ? null : { ownerEmail, planType };
+}
 function toWindow2(headers, name) {
   const utilizationHeader = headers.get(`x-codex-${name}-used-percent`);
   const windowMinutesHeader = headers.get(`x-codex-${name}-window-minutes`);
@@ -3296,6 +4203,7 @@ async function getOpenAiUsage(port) {
       "credentials_expired"
     );
   }
+  const subscription = parseChatGptIdentity(credentials2.accessToken);
   const models = await resolveProbeModels(port);
   if (models.length === 0) {
     throw new OpenAiUsageError("No supported OpenAI probe model is available.", "no_probe_model");
@@ -3328,7 +4236,7 @@ async function getOpenAiUsage(port) {
             "no_usable_window"
           );
         }
-        return usage;
+        return { ...usage, subscription };
       }
       if (res.status === 401) {
         throw new OpenAiUsageError(
@@ -3572,15 +4480,15 @@ function createResourceUsageCollector(homeDir) {
 }
 
 // src/lib/channels/driver.ts
-import { homedir as homedir3 } from "os";
+import { homedir as homedir4 } from "os";
 
 // src/lib/runner-file-sync.ts
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // 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 dirname3, isAbsolute, join as join5, relative, resolve as resolve2, sep } from "path";
+import { basename, dirname as dirname5, isAbsolute, join as join6, relative, resolve as resolve2, sep } from "path";
 var FILE_MODE = 384;
 var DIRECTORY_MODE = 448;
 async function writePushedFile(request) {
@@ -3611,9 +4519,9 @@ async function writePushedFile(request) {
   }
   try {
     const { existingAncestor, missingSegments } = await resolveNearestExistingAncestor(
-      dirname3(candidate)
+      dirname5(candidate)
     );
-    const realTarget = join5(existingAncestor, ...missingSegments, basename(candidate));
+    const realTarget = join6(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.", {
@@ -3623,8 +4531,8 @@ async function writePushedFile(request) {
     }
     if (missingSegments.length > 0) {
       await createMissingDirectories(existingAncestor, missingSegments);
-      const realParent = await realpath(dirname3(realTarget));
-      if (realParent !== dirname3(realTarget) || !contains(allowedDirectory, realTarget)) {
+      const realParent = await realpath(dirname5(realTarget));
+      if (realParent !== dirname5(realTarget) || !contains(allowedDirectory, realTarget)) {
         return refuse("path_not_allowed", "The runner does not allow writing to that location.", {
           path: realTarget,
           bytes,
@@ -3649,7 +4557,7 @@ function expandAndValidate(requestedPath, homeDir) {
   if (requestedPath.trim() === "" || requestedPath.includes("\0")) {
     return null;
   }
-  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join5(homeDir, requestedPath.slice(2)) : requestedPath;
+  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join6(homeDir, requestedPath.slice(2)) : requestedPath;
   if (expanded.split(/[/\\]/).includes("..")) {
     return null;
   }
@@ -3667,7 +4575,7 @@ async function resolveNearestExistingAncestor(directory) {
     try {
       return { existingAncestor: await realpath(current), missingSegments };
     } catch (err) {
-      const parent = dirname3(current);
+      const parent = dirname5(current);
       if (err.code !== "ENOENT" || parent === current) {
         throw err;
       }
@@ -3722,13 +4630,13 @@ function contains(realDirectory, realTarget) {
 async function createMissingDirectories(existingAncestor, missingSegments) {
   let current = existingAncestor;
   for (const segment of missingSegments) {
-    current = join5(current, segment);
+    current = join6(current, segment);
     await mkdir(current, { recursive: true, mode: DIRECTORY_MODE });
     await chmod(current, DIRECTORY_MODE);
   }
 }
 async function writeAtomically(realTarget, content) {
-  const temporaryPath = join5(dirname3(realTarget), `.evident-push-${randomUUID()}.tmp`);
+  const temporaryPath = join6(dirname5(realTarget), `.evident-push-${randomUUID()}.tmp`);
   let handle;
   try {
     handle = await open2(temporaryPath, "wx", FILE_MODE);
@@ -3858,12 +4766,12 @@ var NOT_APPLIED = {
   opencodeAuthApplied: false
 };
 function isClaudeCredentialPath(requestedPath, homeDir) {
-  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join6(homeDir, requestedPath.slice(2)) : requestedPath;
-  return expanded === join6(homeDir, ...CLAUDE_CREDENTIALS_SEGMENTS);
+  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join7(homeDir, requestedPath.slice(2)) : requestedPath;
+  return expanded === join7(homeDir, ...CLAUDE_CREDENTIALS_SEGMENTS);
 }
 function isOpenCodeAuthPath(requestedPath, homeDir) {
-  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join6(homeDir, requestedPath.slice(2)) : requestedPath;
-  return expanded === join6(homeDir, ...OPENCODE_AUTH_SEGMENTS);
+  const expanded = requestedPath === "~" ? homeDir : requestedPath.startsWith("~/") ? join7(homeDir, requestedPath.slice(2)) : requestedPath;
+  return expanded === join7(homeDir, ...OPENCODE_AUTH_SEGMENTS);
 }
 async function applyOne(options, file) {
   const label = `${file.id.slice(0, 8)} (${file.path})`;
@@ -4390,6 +5298,7 @@ var ChannelDriver = class _ChannelDriver {
    * and stops opencode.
    */
   stopped = false;
+  recycleRequestedFlag = false;
   constructor(config) {
     this.agentId = config.agentId;
     this.port = config.port;
@@ -4409,7 +5318,7 @@ var ChannelDriver = class _ChannelDriver {
     this.stuckQueuedMs = config.stuckQueuedMs ?? DEFAULT_STUCK_QUEUED_MS;
     this.now = config.now ?? (() => Date.now());
     this.fileSyncDirectories = config.fileSyncDirectories ?? [];
-    this.homeDir = config.homeDir ?? homedir3();
+    this.homeDir = config.homeDir ?? homedir4();
     this.maxActiveSessions = config.maxActiveSessions;
     this.watcherStallMs = config.watcherStallMs ?? WATCHER_STALL_MS;
     this.wedgeWarningIntervalMs = config.wedgeWarningIntervalMs ?? WEDGE_WARNING_INTERVAL_MS;
@@ -4495,6 +5404,9 @@ var ChannelDriver = class _ChannelDriver {
     let dispatched = 0;
     try {
       const conversations = await this.getPendingConversations();
+      if (this.recycleRequestedFlag) {
+        this.stop();
+      }
       if (conversations.length > 0) {
         const total = conversations.reduce((sum, c) => sum + (c.pending_message_count ?? 0), 0);
         this.log({
@@ -4623,6 +5535,14 @@ var ChannelDriver = class _ChannelDriver {
   stop() {
     this.stopped = true;
   }
+  /**
+   * The server clears this request when a new MicroVM identity is recorded, so a
+   * same-VM tunnel reconnect does not consume it. This is a plain read rather
+   * than a consume; `run.ts` guards the action once-only.
+   */
+  get recycleRequested() {
+    return this.recycleRequestedFlag;
+  }
   /**
    * Wait (up to `timeoutMs`) for in-flight watcher work to settle during a
    * graceful shutdown, so a turn whose reply is ready — or completes within the
@@ -4760,7 +5680,7 @@ var ChannelDriver = class _ChannelDriver {
           this.signalDispatchNotStarted(conv, message, "session_existence_unknown");
           break;
         }
-        const errorMessage = err instanceof Error ? err.message : String(err);
+        const errorMessage2 = err instanceof Error ? err.message : String(err);
         this.sessions.delete(conv.id);
         this.supersede(conv.id, sessionId);
         this.log({
@@ -4769,7 +5689,7 @@ var ChannelDriver = class _ChannelDriver {
           conversation_id: conv.id,
           message_id: message.id
         });
-        await this.markFailed(conv.id, message.id, null, errorMessage).catch((markErr) => {
+        await this.markFailed(conv.id, message.id, null, errorMessage2).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)}`,
@@ -4780,7 +5700,7 @@ var ChannelDriver = class _ChannelDriver {
         });
         this.log({
           level: "error",
-          message: `Message ${message.id.slice(0, 8)} dispatch failed: ${errorMessage}`,
+          message: `Message ${message.id.slice(0, 8)} dispatch failed: ${errorMessage2}`,
           conversation_id: conv.id,
           message_id: message.id
         });
@@ -4801,14 +5721,14 @@ var ChannelDriver = class _ChannelDriver {
         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.`;
+        const errorMessage2 = `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: "error",
-          message: errorMessage,
+          message: errorMessage2,
           conversation_id: conv.id,
           message_id: message.id
         });
-        await this.markFailed(conv.id, message.id, null, errorMessage).catch((markErr) => {
+        await this.markFailed(conv.id, message.id, null, errorMessage2).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)}`,
@@ -5676,6 +6596,7 @@ var ChannelDriver = class _ChannelDriver {
       deliveryDeadlineAnchored: false,
       b2PinnedSinceMs: 0,
       b2LastDescendantCheckMs: 0,
+      b2RootOngoingHeldLogged: false,
       b2AbandonedSignalled: false,
       ambiguousPinnedSinceMs: 0,
       ambiguousResolved: false
@@ -5770,6 +6691,7 @@ var ChannelDriver = class _ChannelDriver {
       deliveryDeadlineAnchored: false,
       b2PinnedSinceMs: 0,
       b2LastDescendantCheckMs: 0,
+      b2RootOngoingHeldLogged: false,
       b2AbandonedSignalled: false,
       ambiguousPinnedSinceMs: 0,
       ambiguousResolved: false
@@ -6123,6 +7045,7 @@ var ChannelDriver = class _ChannelDriver {
       if (snapshotReadable) {
         inFlight.b2PinnedSinceMs = 0;
         inFlight.b2LastDescendantCheckMs = 0;
+        inFlight.b2RootOngoingHeldLogged = false;
         inFlight.b2AbandonedSignalled = false;
       }
     } else {
@@ -6134,11 +7057,15 @@ var ChannelDriver = class _ChannelDriver {
       const pinnedForMs = this.now() - inFlight.b2PinnedSinceMs;
       if (pinnedForMs >= B2_ABANDONMENT_MIN_PINNED_MS && this.now() - inFlight.b2LastDescendantCheckMs >= B2_ABANDONMENT_RECHECK_MS) {
         inFlight.b2LastDescendantCheckMs = this.now();
-        const descendantOngoing = await this.isAnyDescendantSessionOngoing(sessionId);
+        const [descendantOngoing, rootOngoing] = await Promise.all([
+          this.isAnyDescendantSessionOngoing(sessionId),
+          isSessionOngoing(this.port, sessionId)
+        ]);
         if (isB2AbandonmentConfirmed({
           pinnedForMs,
           minPinnedMs: B2_ABANDONMENT_MIN_PINNED_MS,
-          descendantOngoing
+          descendantOngoing,
+          rootOngoing
         })) {
           inFlight.b2AbandonedSignalled = true;
           this.log({
@@ -6147,12 +7074,26 @@ var ChannelDriver = class _ChannelDriver {
             conversation_id: conv.id,
             message_id: id
           });
+          const reply = findLastAssistantReplyFor(messages, inFlight.opencodeMessageId);
           void this.postSignal(conv.id, id, "b2_abandoned_resolved", {
-            watched_for_ms: pinnedForMs
+            watched_for_ms: pinnedForMs,
+            finish: reply?.info?.finish ?? reply?.finish,
+            ...rootOngoing != null ? { root_ongoing: rootOngoing } : {},
+            ...descendantOngoing != null ? { descendant_ongoing: descendantOngoing } : {},
+            opencode_message_id: inFlight.opencodeMessageId
           });
           await this.settleMessageDone(sessionId, watcher, inFlight, messages);
           return;
         }
+        if (rootOngoing === true && !inFlight.b2RootOngoingHeldLogged) {
+          inFlight.b2RootOngoingHeldLogged = true;
+          this.log({
+            level: "warn",
+            message: `Message ${id.slice(0, 8)} b2-pinned for ${Math.round(pinnedForMs / 1e3)}s with root_ongoing=${rootOngoing} and descendant_ongoing=${descendantOngoing} \u2014 holding until OpenCode confirms the root is idle`,
+            conversation_id: conv.id,
+            message_id: id
+          });
+        }
       }
     }
     const ambiguousPinnedNow = activelyRunning && isAmbiguousFinishPinnedRunning(messages, inFlight.opencodeMessageId);
@@ -6751,14 +7692,14 @@ var ChannelDriver = class _ChannelDriver {
         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.`;
+        const errorMessage2 = `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,
+          message: errorMessage2,
           conversation_id: row.conversation_id,
           message_id: row.id
         });
-        await this.markFailed(row.conversation_id, row.id, null, errorMessage).catch((markErr) => {
+        await this.markFailed(row.conversation_id, row.id, null, errorMessage2).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)}`,
@@ -7373,6 +8314,7 @@ var ChannelDriver = class _ChannelDriver {
       throw new Error(`Failed to get pending conversations: HTTP ${res.status}`);
     }
     const data = await res.json();
+    this.recycleRequestedFlag = data.recycle_requested === true;
     let conversations = data.conversations;
     if (this.conversationFilter) {
       conversations = conversations.filter((c) => c.id === this.conversationFilter);
@@ -7797,96 +8739,641 @@ async function ensureOpenCodeRunning(ctx) {
     blank();
     throw new Error(`OpenCode not running on port ${ctx.port}`);
   }
-  if (!isOpenCodeInstalled()) {
-    if (!ctx.interactive) {
-      throw new Error("OpenCode is not installed. Install it with: npm install -g opencode-ai");
-    }
-    const result = await promptOpenCodeInstall(true);
-    if (result === "exit") process.exit(0);
-    if (result !== "installed" && !isOpenCodeInstalled()) {
-      throw new Error("OpenCode is not installed");
+  if (!isOpenCodeInstalled()) {
+    if (!ctx.interactive) {
+      throw new Error("OpenCode is not installed. Install it with: npm install -g opencode-ai");
+    }
+    const result = await promptOpenCodeInstall(true);
+    if (result === "exit") process.exit(0);
+    if (result !== "installed" && !isOpenCodeInstalled()) {
+      throw new Error("OpenCode is not installed");
+    }
+  }
+  if (!ctx.interactive) {
+    ctx.log(`OpenCode is not running on port ${ctx.port}. Starting it automatically...`);
+    const proc = await startOpenCode(ctx.port, { inheritStdio: ctx.inheritStdio });
+    const health = await waitForOpenCodeHealth(ctx.port, ctx.startTimeoutMs);
+    if (!health.healthy) {
+      return {
+        port: ctx.port,
+        process: proc,
+        version: null,
+        notReadyReason: `it did not become healthy within ${Math.round(ctx.startTimeoutMs / 1e3)}s`
+      };
+    }
+    ctx.log(`OpenCode started on port ${ctx.port}${health.version ? ` (v${health.version})` : ""}`);
+    return {
+      port: ctx.port,
+      process: proc,
+      version: health.version ?? null,
+      notReadyReason: null
+    };
+  }
+  let port = ctx.port;
+  if (isPortInUse(port)) {
+    console.log(chalk5.yellow(`
+Port ${port} is already in use.`));
+    const alternativePort = findAvailablePort(port + 1);
+    if (alternativePort) {
+      const useAlternative = await select2({
+        message: `Use port ${alternativePort} instead?`,
+        choices: [
+          { name: `Yes, use port ${alternativePort}`, value: "yes" },
+          { name: "No, I will free the port manually", value: "no" }
+        ]
+      });
+      if (useAlternative === "yes") {
+        port = alternativePort;
+      } else {
+        throw new Error(`Port ${ctx.port} is in use`);
+      }
+    }
+  }
+  const action = await select2({
+    message: "OpenCode is not running. What would you like to do?",
+    choices: [
+      {
+        name: "Start OpenCode for me",
+        value: "start",
+        description: `Run 'opencode serve --port ${port}'`
+      },
+      {
+        name: "Show me the command",
+        value: "manual",
+        description: "Display the command to run manually"
+      },
+      {
+        name: "Continue without OpenCode",
+        value: "continue",
+        description: "Requests will fail until OpenCode starts"
+      }
+    ]
+  });
+  if (action === "manual") {
+    blank();
+    console.log(chalk5.bold("Run this command in another terminal:"));
+    blank();
+    console.log(`  ${chalk5.cyan(`opencode serve --port ${port}`)}`);
+    blank();
+    throw new Error("Please start OpenCode manually");
+  }
+  if (action === "start") {
+    const spinner = ora2("Starting OpenCode...").start();
+    const proc = await startOpenCode(port, { inheritStdio: ctx.inheritStdio });
+    const health = await waitForOpenCodeHealth(port, INTERACTIVE_START_TIMEOUT_MS);
+    if (!health.healthy) {
+      spinner.fail("Failed to start OpenCode");
+      throw new Error("OpenCode failed to start");
+    }
+    spinner.stop();
+    return { port, process: proc, version: health.version ?? null, notReadyReason: null };
+  }
+  return { port, process: null, version: null, notReadyReason: "you chose to continue without it" };
+}
+
+// src/lib/runner-credentials.ts
+import { chmodSync as chmodSync2, writeFileSync as writeFileSync4 } from "fs";
+import { spawn as spawn5 } from "child_process";
+var RUNNER_SECRET_FETCH_TIMEOUT_MS = 6e4;
+var CREDENTIAL_RESTORE_TIMEOUT_MS = 6e4;
+var GITHUB_PROBE_TIMEOUT_MS = 1e4;
+var GIT_CONFIG_GLOBAL = "/tmp/gitconfig";
+var GIT_CREDENTIAL_HELPER = "/tmp/git-credential-helper.sh";
+function commandError2(result) {
+  return result.stderr.trim() || `process exited with code ${result.code ?? "null"}`;
+}
+var runCommand2 = (command, args, opts) => {
+  return new Promise((resolve4) => {
+    let child;
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timer = {};
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer.handle) clearTimeout(timer.handle);
+      resolve4(result);
+    };
+    try {
+      child = spawn5(command, args, { env: opts.env, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error2) {
+      finish({
+        code: null,
+        stdout,
+        stderr: error2 instanceof Error ? error2.message : String(error2),
+        timedOut: false
+      });
+      return;
+    }
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.once("error", (error2) => {
+      finish({
+        code: null,
+        stdout,
+        stderr: stderr === "" ? error2.message : `${stderr}
+${error2.message}`,
+        timedOut: false
+      });
+    });
+    child.once("close", (code) => finish({ code, stdout, stderr, timedOut: false }));
+    timer.handle = setTimeout(
+      () => {
+        child.kill("SIGKILL");
+        finish({ code: null, stdout, stderr, timedOut: true });
+      },
+      Math.max(0, opts.timeoutMs)
+    );
+  });
+};
+function isEnvironmentObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function secretFailure(marker, detail, log3) {
+  const message = `${marker}: ${detail}`;
+  log3(message, "error");
+  return new Error(message);
+}
+async function installRunnerSecret({
+  env,
+  log: log3,
+  commandRunner
+}) {
+  const arn = env.RUNNER_SECRET_ARN?.trim();
+  if (!arn) {
+    log3("runner secret is not configured; continuing without GitHub and MCP credentials");
+    return false;
+  }
+  const result = await (commandRunner ?? runCommand2)(
+    "aws",
+    [
+      "secretsmanager",
+      "get-secret-value",
+      "--secret-id",
+      arn,
+      "--query",
+      "SecretString",
+      "--output",
+      "text"
+    ],
+    { env, timeoutMs: RUNNER_SECRET_FETCH_TIMEOUT_MS }
+  );
+  if (result.timedOut) {
+    throw secretFailure(
+      "CREDENTIAL-RESTORE-TIMEOUT",
+      `runner-secret did not finish within ${RUNNER_SECRET_FETCH_TIMEOUT_MS}ms`,
+      log3
+    );
+  }
+  if (result.code !== 0) {
+    throw secretFailure("RUNNER-SECRET-UNREADABLE", commandError2(result), log3);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch (error2) {
+    log3(
+      `RUNNER-SECRET-UNPARSEABLE: secret value is not a JSON object (${error2 instanceof Error ? error2.message : String(error2)})`,
+      "warn"
+    );
+    return false;
+  }
+  if (!isEnvironmentObject(payload)) {
+    log3("RUNNER-SECRET-UNPARSEABLE: secret value is not a JSON object", "warn");
+    return false;
+  }
+  let populated = 0;
+  let skipped = 0;
+  let githubTokenPopulated = false;
+  for (const [key, value] of Object.entries(payload)) {
+    if (typeof value !== "string" || value.length === 0) continue;
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+      log3(
+        `RUNNER-SECRET-KEY-SKIPPED: ${JSON.stringify(key)} is not a valid environment variable name`,
+        "warn"
+      );
+      skipped += 1;
+      continue;
+    }
+    env[key] = value;
+    populated += 1;
+    if (key === "GH_TOKEN") githubTokenPopulated = true;
+  }
+  if (populated === 0) {
+    log3(
+      "RUNNER-SECRET-UNPOPULATED: populate the runner secret as documented in infrastructure/evident-runner/MICROVM.md",
+      "warn"
+    );
+  } else {
+    log3(
+      `RUNNER-SECRET-OK: exported ${populated} secret values; skipped ${skipped} invalid environment variable names`
+    );
+  }
+  return githubTokenPopulated;
+}
+function restoreFailure(operation, result, log3) {
+  const message = `CREDENTIAL-RESTORE-FAILED: ${operation} failed: ${commandError2(result)}`;
+  log3(message, "error");
+  return new Error(message);
+}
+async function runCredentialRestore(args, operation, log3, synchroniserRunner) {
+  const result = await synchroniserRunner(args, { timeoutMs: CREDENTIAL_RESTORE_TIMEOUT_MS });
+  if (result.timedOut) {
+    log3(
+      `CREDENTIAL-RESTORE-TIMEOUT: ${operation} did not finish within ${CREDENTIAL_RESTORE_TIMEOUT_MS}ms; continuing without it`,
+      "warn"
+    );
+    return result;
+  }
+  if (result.code !== 0) throw restoreFailure(operation, result, log3);
+  return result;
+}
+async function restoreCredentialStores({
+  env,
+  log: log3,
+  synchroniserRunner = runSynchroniser
+}) {
+  await runCredentialRestore(["restore", "claude"], "restore-claude", log3, synchroniserRunner);
+  await runCredentialRestore(["restore", "opencode"], "restore-opencode", log3, synchroniserRunner);
+  const result = await synchroniserRunner(["model-auth-ready"], {
+    timeoutMs: CREDENTIAL_RESTORE_TIMEOUT_MS
+  });
+  if (result.timedOut) {
+    log3(
+      `CREDENTIAL-RESTORE-TIMEOUT: model-auth-ready did not finish within ${CREDENTIAL_RESTORE_TIMEOUT_MS}ms; continuing without it`,
+      "warn"
+    );
+    return;
+  }
+  switch (result.code) {
+    case 0:
+      return;
+    case 10:
+      log3(
+        `no model credentials under s3://${env.LITESTREAM_BUCKET ?? ""}/${env.LITESTREAM_PREFIX ?? ""}/ (neither claude/credentials.json nor opencode/auth.json yielded valid JSON) and neither ANTHROPIC_API_KEY nor OPENAI_API_KEY is set. This VM boots and connects; a turn that needs a model provider fails until one is connected. See 'Seeding a credential store' in infrastructure/evident-runner/MICROVM.md.`,
+        "warn"
+      );
+      return;
+    default:
+      log3("could not determine whether this VM has model credentials", "warn");
+  }
+}
+var GIT_CREDENTIAL_HELPER_CONTENT = [
+  "#!/usr/bin/env bash",
+  '[ "$1" = get ] || exit 0',
+  "echo username=x-access-token",
+  'echo "password=${GH_TOKEN}"',
+  ""
+].join("\n");
+async function probeGitHubAccess({ env, log: log3 }) {
+  const auth = await runCommand2("gh", ["api", "user", "--jq", ".login"], {
+    env,
+    timeoutMs: GITHUB_PROBE_TIMEOUT_MS
+  });
+  if (auth.timedOut) {
+    log3(`GITHUB-PROBE-TIMEOUT: auth probe exceeded ${GITHUB_PROBE_TIMEOUT_MS}ms`, "warn");
+    return;
+  }
+  if (auth.code !== 0) {
+    log3(`GITHUB-AUTH-REJECTED: ${commandError2(auth)}`, "warn");
+    return;
+  }
+  log3(`GITHUB-AUTH-OK: ${auth.stdout.trim()}`, "debug");
+  const remote = await runCommand2("git", ["-C", process.cwd(), "remote", "get-url", "origin"], {
+    env,
+    timeoutMs: GITHUB_PROBE_TIMEOUT_MS
+  });
+  if (remote.code !== 0 || remote.timedOut) return;
+  const repo = remote.stdout.trim().replace(/^(?:https:\/\/github\.com\/|git@github\.com:)/, "").replace(/\.git$/, "");
+  if (!repo) return;
+  const repository = await runCommand2("gh", ["api", `repos/${repo}`, "--jq", ".full_name"], {
+    env,
+    timeoutMs: GITHUB_PROBE_TIMEOUT_MS
+  });
+  if (repository.timedOut) {
+    log3(
+      `GITHUB-PROBE-TIMEOUT: repository probe for ${repo} exceeded ${GITHUB_PROBE_TIMEOUT_MS}ms`,
+      "warn"
+    );
+  } else if (repository.code !== 0) {
+    log3(`GITHUB-REPO-INACCESSIBLE: ${repo}: ${commandError2(repository)}`, "warn");
+  }
+}
+async function configureGitHubAccess({ env, log: log3 }) {
+  if (!env.GH_TOKEN) {
+    log3("GITHUB-CREDENTIALS-MISSING: GH_TOKEN is unavailable; see RUNNER-SECRET-* above", "warn");
+    return;
+  }
+  try {
+    env.GIT_CONFIG_GLOBAL = GIT_CONFIG_GLOBAL;
+    writeFileSync4(GIT_CONFIG_GLOBAL, "");
+    writeFileSync4(GIT_CREDENTIAL_HELPER, GIT_CREDENTIAL_HELPER_CONTENT, { mode: 448 });
+    chmodSync2(GIT_CREDENTIAL_HELPER, 448);
+    const config = [
+      ["user.name", env.GIT_USER_NAME ?? "evident-bot"],
+      ["user.email", env.GIT_USER_EMAIL ?? "evident-bot@users.noreply.github.com"],
+      ["init.defaultBranch", "main"],
+      ["credential.https://github.com.helper", GIT_CREDENTIAL_HELPER]
+    ];
+    for (const [key, value] of config) {
+      const result = await runCommand2("git", ["config", "--global", key, value], {
+        env,
+        timeoutMs: GITHUB_PROBE_TIMEOUT_MS
+      });
+      if (result.timedOut || result.code !== 0) throw new Error(commandError2(result));
+    }
+  } catch (error2) {
+    log3(
+      `GITHUB-SETUP-FAILED: could not configure local git credentials; continuing without GitHub access (${error2 instanceof Error ? error2.message : String(error2)})`,
+      "warn"
+    );
+    return;
+  }
+  void probeGitHubAccess({ env, log: log3 }).catch((error2) => {
+    log3(
+      `GITHUB-SETUP-FAILED: GitHub access probe failed: ${error2 instanceof Error ? error2.message : String(error2)}`,
+      "warn"
+    );
+  });
+}
+
+// src/lib/opencode/config-overlay.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { copyFileSync, existsSync as existsSync2, statSync as statSync5 } from "fs";
+import { isAbsolute as isAbsolute2, join as join8, resolve as resolve3 } from "path";
+function isFile(filePath) {
+  return existsSync2(filePath) && statSync5(filePath).isFile();
+}
+function applyRunnerOpenCodeConfig({
+  overlayPath,
+  cwd = process.cwd(),
+  log: log3
+}) {
+  if (!overlayPath) {
+    log3("runner OpenCode config is not configured; using the baked project config", "debug");
+    return;
+  }
+  const source = isAbsolute2(overlayPath) ? overlayPath : resolve3(cwd, overlayPath);
+  const target = isFile(join8(cwd, "opencode.jsonc")) ? "opencode.jsonc" : "opencode.json";
+  if (!isFile(source)) {
+    log3(
+      `RUNNER-OPENCODE-CONFIG-MISSING: ${source} is not a file; headless turns will wedge on the first external-directory permission prompt (#563)`,
+      "error"
+    );
+    return;
+  }
+  copyFileSync(source, join8(cwd, target));
+  try {
+    execFileSync2("git", ["-C", cwd, "update-index", "--skip-worktree", target], {
+      stdio: "ignore"
+    });
+  } catch (error2) {
+    const detail = error2 instanceof Error ? error2.message : String(error2);
+    log3(`could not mark ${target} skip-worktree: ${detail}; it may show as a local change`, "warn");
+  }
+  log3(`Applied runner OpenCode config ${source} to ${join8(cwd, target)}`);
+}
+
+// src/lib/credential-sync.ts
+import { renameSync, writeFileSync as writeFileSync5 } from "fs";
+var CREDENTIAL_SYNC_TICK_TIMEOUT_MS = 3e4;
+var CREDENTIAL_FLUSH_DEADLINE_MS = 8e3;
+var CREDENTIAL_FLUSH_ABORT_GRACE_MS = 500;
+var DEFAULT_CREDENTIAL_SYNC_INTERVAL_SECONDS = 60;
+var STORES = ["claude", "opencode"];
+var MAX_FLUSH_PASSES = 2;
+function outcomesWith(outcome) {
+  return { claude: outcome, opencode: outcome };
+}
+function errorMessage(error2) {
+  return error2 instanceof Error ? error2.message : String(error2);
+}
+function waitForSettlement(promise, timeoutMs) {
+  return new Promise((resolve4) => {
+    let settled = false;
+    const timer = setTimeout(() => finish(false), Math.max(0, timeoutMs));
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve4(value);
+    };
+    promise.then(
+      () => finish(true),
+      () => finish(true)
+    );
+  });
+}
+function writeMarker(markerPath, outcomes, log3) {
+  const body = `${STORES.map((store) => `${store}=${outcomes[store]}`).join("\n")}
+`;
+  const temporaryPath = `${markerPath}.tmp`;
+  try {
+    writeFileSync5(temporaryPath, body, { mode: 384 });
+    renameSync(temporaryPath, markerPath);
+  } catch (error2) {
+    log3(`CREDENTIAL-FLUSH-MARKER-UNWRITABLE: ${markerPath}: ${errorMessage(error2)}`, "warn");
+  }
+}
+function intervalSeconds(env, log3) {
+  const raw = env.CREDS_SYNC_INTERVAL;
+  if (raw === void 0 || /^[1-9][0-9]*$/.test(raw) && Number.isSafeInteger(Number(raw))) {
+    return raw === void 0 ? DEFAULT_CREDENTIAL_SYNC_INTERVAL_SECONDS : Number(raw);
+  }
+  log3(
+    `CREDENTIAL-SYNC-INTERVAL-INVALID: CREDS_SYNC_INTERVAL='${raw}' is not a positive integer; using ${DEFAULT_CREDENTIAL_SYNC_INTERVAL_SECONDS}s`,
+    "warn"
+  );
+  return DEFAULT_CREDENTIAL_SYNC_INTERVAL_SECONDS;
+}
+async function runFlushStore(store, env, synchroniserRunner, log3, deadlineAt) {
+  const remainingMs = deadlineAt - Date.now();
+  if (remainingMs <= 0) return { outcome: "timeout", orphaned: false };
+  const controller = new AbortController();
+  let result;
+  let failed = false;
+  const completion = Promise.resolve().then(
+    () => synchroniserRunner(["sync-once", store], {
+      timeoutMs: remainingMs,
+      env,
+      signal: controller.signal
+    })
+  ).then(
+    (value) => {
+      result = value;
+    },
+    (error2) => {
+      failed = true;
+      log3(`CREDENTIAL-FLUSH-ERROR: ${store}: ${errorMessage(error2)}`, "warn");
     }
-  }
-  if (!ctx.interactive) {
-    ctx.log(`OpenCode is not running on port ${ctx.port}. Starting it automatically...`);
-    const proc = await startOpenCode(ctx.port);
-    const health = await waitForOpenCodeHealth(ctx.port, ctx.startTimeoutMs);
-    if (!health.healthy) {
-      return {
-        port: ctx.port,
-        process: proc,
-        version: null,
-        notReadyReason: `it did not become healthy within ${Math.round(ctx.startTimeoutMs / 1e3)}s`
+  );
+  const abortTimer = setTimeout(() => controller.abort(), remainingMs);
+  const settledBeforeDeadline = await waitForSettlement(completion, remainingMs);
+  clearTimeout(abortTimer);
+  if (!settledBeforeDeadline) {
+    controller.abort();
+    const settledAfterAbort = await waitForSettlement(completion, CREDENTIAL_FLUSH_ABORT_GRACE_MS);
+    if (!settledAfterAbort) return { outcome: "timeout", orphaned: true };
+    return { outcome: "timeout", orphaned: false };
+  }
+  if (failed || !result) return { outcome: "failed", orphaned: false };
+  if (result.timedOut || Date.now() >= deadlineAt) {
+    return { outcome: "timeout", orphaned: false };
+  }
+  return { outcome: result.code === 0 ? "ok" : "failed", orphaned: false };
+}
+function createCredentialSync({
+  markerPath,
+  env,
+  log: log3,
+  synchroniserRunner = runSynchroniser
+}) {
+  const persistenceDisabled = !env.PERSISTENCE_BUCKET;
+  let disabled = persistenceDisabled;
+  let armed = false;
+  let stopped = false;
+  let timer;
+  let inFlight;
+  let activeTickAbort;
+  let lastTickFailed;
+  let flushPromise;
+  const scheduleTick = (intervalMs, startTick2) => {
+    if (stopped) return;
+    timer = setTimeout(() => {
+      timer = void 0;
+      startTick2();
+    }, intervalMs);
+  };
+  const startTick = (intervalMs) => {
+    if (stopped) return;
+    const controller = new AbortController();
+    activeTickAbort = controller;
+    const tick = (async () => {
+      const outcomes = {
+        claude: "failed",
+        opencode: "failed"
       };
+      for (const store of STORES) {
+        if (controller.signal.aborted) break;
+        try {
+          const result = await synchroniserRunner(["sync-once", store], {
+            timeoutMs: CREDENTIAL_SYNC_TICK_TIMEOUT_MS,
+            env,
+            signal: controller.signal
+          });
+          outcomes[store] = !result.timedOut && result.code === 0 ? "ok" : "failed";
+        } catch (error2) {
+          outcomes[store] = "failed";
+          log3(`CREDENTIAL-SYNC-TICK-ERROR: ${store}: ${errorMessage(error2)}`, "debug");
+        }
+      }
+      const failed = STORES.some((store) => outcomes[store] === "failed");
+      log3(
+        `CREDENTIAL-SYNC-TICK: claude=${outcomes.claude}, opencode=${outcomes.opencode}`,
+        "debug"
+      );
+      if (failed && lastTickFailed !== true) {
+        log3(
+          "CREDENTIAL-SYNC-FAILED: an interval credential sync failed; retrying on the next tick",
+          "warn"
+        );
+      } else if (!failed && lastTickFailed === true) {
+        log3("CREDENTIAL-SYNC-RECOVERED: interval credential sync succeeded again", "warn");
+      }
+      lastTickFailed = failed;
+    })().finally(() => {
+      if (activeTickAbort === controller) activeTickAbort = void 0;
+      if (inFlight === tick) inFlight = void 0;
+      scheduleTick(intervalMs, () => startTick(intervalMs));
+    });
+    inFlight = tick;
+  };
+  const performFlush = async () => {
+    stopped = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
+    }
+    const deadlineAt = Date.now() + CREDENTIAL_FLUSH_DEADLINE_MS;
+    if (inFlight) {
+      const settled = await waitForSettlement(inFlight, CREDENTIAL_FLUSH_DEADLINE_MS);
+      if (!settled) {
+        activeTickAbort?.abort();
+        const settledAfterAbort = await waitForSettlement(
+          inFlight,
+          CREDENTIAL_FLUSH_ABORT_GRACE_MS
+        );
+        if (!settledAfterAbort) {
+          log3(
+            "CREDENTIAL-FLUSH-ORPHANED-TICK: a sync-once child could not be proven settled; skipping the boundary flush rather than becoming a second writer",
+            "warn"
+          );
+          return { outcomes: outcomesWith("timeout"), orphaned: true };
+        }
+      }
     }
-    ctx.log(`OpenCode started on port ${ctx.port}${health.version ? ` (v${health.version})` : ""}`);
-    return {
-      port: ctx.port,
-      process: proc,
-      version: health.version ?? null,
-      notReadyReason: null
-    };
-  }
-  let port = ctx.port;
-  if (isPortInUse(port)) {
-    console.log(chalk5.yellow(`
-Port ${port} is already in use.`));
-    const alternativePort = findAvailablePort(port + 1);
-    if (alternativePort) {
-      const useAlternative = await select2({
-        message: `Use port ${alternativePort} instead?`,
-        choices: [
-          { name: `Yes, use port ${alternativePort}`, value: "yes" },
-          { name: "No, I will free the port manually", value: "no" }
-        ]
-      });
-      if (useAlternative === "yes") {
-        port = alternativePort;
-      } else {
-        throw new Error(`Port ${ctx.port} is in use`);
+    if (disabled) return { outcomes: outcomesWith("skipped"), orphaned: false };
+    const outcomes = outcomesWith("timeout");
+    for (const store of STORES) {
+      const result = await runFlushStore(store, env, synchroniserRunner, log3, deadlineAt);
+      if (result.orphaned) {
+        log3(
+          "CREDENTIAL-FLUSH-ORPHANED-CHILD: a flush sync-once child could not be proven settled; refusing another flush pass rather than becoming a second writer",
+          "warn"
+        );
+        return { outcomes: outcomesWith("timeout"), orphaned: true };
       }
+      outcomes[store] = result.outcome;
     }
-  }
-  const action = await select2({
-    message: "OpenCode is not running. What would you like to do?",
-    choices: [
-      {
-        name: "Start OpenCode for me",
-        value: "start",
-        description: `Run 'opencode serve --port ${port}'`
-      },
-      {
-        name: "Show me the command",
-        value: "manual",
-        description: "Display the command to run manually"
-      },
-      {
-        name: "Continue without OpenCode",
-        value: "continue",
-        description: "Requests will fail until OpenCode starts"
+    return { outcomes, orphaned: false };
+  };
+  let flushPasses = 0;
+  let lastFlush;
+  return {
+    arm() {
+      if (stopped || armed) return;
+      armed = true;
+      if (persistenceDisabled) {
+        disabled = true;
+        log3(
+          "CREDENTIAL-SYNC-DISABLED: LITESTREAM_BUCKET/LITESTREAM_PREFIX are not both set; no interval credential sync this boot",
+          "warn"
+        );
+        return;
       }
-    ]
-  });
-  if (action === "manual") {
-    blank();
-    console.log(chalk5.bold("Run this command in another terminal:"));
-    blank();
-    console.log(`  ${chalk5.cyan(`opencode serve --port ${port}`)}`);
-    blank();
-    throw new Error("Please start OpenCode manually");
-  }
-  if (action === "start") {
-    const spinner = ora2("Starting OpenCode...").start();
-    const proc = await startOpenCode(port);
-    const health = await waitForOpenCodeHealth(port, INTERACTIVE_START_TIMEOUT_MS);
-    if (!health.healthy) {
-      spinner.fail("Failed to start OpenCode");
-      throw new Error("OpenCode failed to start");
+      disabled = false;
+      const intervalMs = intervalSeconds(env, log3) * 1e3;
+      scheduleTick(intervalMs, () => startTick(intervalMs));
+    },
+    async stopAndFlush(publish) {
+      let result;
+      const runningFlush = flushPromise;
+      if (runningFlush) {
+        result = await runningFlush;
+      } else if (flushPasses >= MAX_FLUSH_PASSES || lastFlush?.orphaned) {
+        result = lastFlush ?? { outcomes: outcomesWith("timeout"), orphaned: true };
+      } else {
+        flushPasses++;
+        const currentFlush = performFlush();
+        flushPromise = currentFlush;
+        try {
+          result = await currentFlush;
+          lastFlush = result;
+        } finally {
+          if (flushPromise === currentFlush) flushPromise = void 0;
+        }
+      }
+      if (publish) writeMarker(markerPath, result.outcomes, log3);
+      return result.outcomes;
     }
-    spinner.stop();
-    return { port, process: proc, version: health.version ?? null, notReadyReason: null };
-  }
-  return { port, process: null, version: null, notReadyReason: "you chose to continue without it" };
+  };
 }
 
 // src/commands/run.ts
@@ -7895,6 +9382,7 @@ var CHANNEL_POLL_INTERVAL_MS = Number(process.env.EVIDENT_CHANNEL_POLL_INTERVAL_
 var CHANNEL_STUCK_QUEUED_MS = Number(process.env.EVIDENT_STUCK_QUEUED_MS) || void 0;
 var SHUTDOWN_DRAIN_TIMEOUT_MS = Number(process.env.EVIDENT_SHUTDOWN_DRAIN_MS) || 25e3;
 var TELEMETRY_SHUTDOWN_TIMEOUT_MS = 5e3;
+var CHILD_STOP_TIMEOUT_MS = 1e4;
 function resolveLogLevel(options) {
   const accepted = Object.keys(LOG_LEVELS);
   const validate = (value, source) => {
@@ -7925,11 +9413,11 @@ 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("~/") ? join7(homeDir, trimmed.slice(2)) : trimmed;
-    if (!isAbsolute2(expanded)) {
+    const expanded = trimmed === "~" ? homeDir : trimmed.startsWith("~/") ? join9(homeDir, trimmed.slice(2)) : trimmed;
+    if (!isAbsolute3(expanded)) {
       throw new Error(`--enable-file-sync-to requires an absolute directory path; got "${entry}"`);
     }
-    const normalized = resolvePath(expanded);
+    const normalized = resolvePath2(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)`
@@ -8045,7 +9533,7 @@ function logActivity(state, entry) {
 }
 function reportSessionDbRecovery(state) {
   try {
-    const report = drainSessionDbRecoveryReport({ homeDir: homedir4(), env: process.env });
+    const report = drainSessionDbRecoveryReport({ homeDir: homedir5(), env: process.env });
     for (const record of report.records) {
       const activity = buildSessionDbRecoveryActivity(record);
       if (!activity) throw new Error("could not map session-DB recovery record");
@@ -8063,6 +9551,16 @@ function reportSessionDbRecovery(state) {
     );
   }
 }
+function reportSessionDbRecoveryRecord(state, record) {
+  const activity = buildSessionDbRecoveryActivity(record);
+  if (!activity) throw new Error("could not map session-DB recovery record");
+  logActivity(state, {
+    type: activity.level === "error" ? "error" : "info",
+    level: activity.level,
+    ...activity.level === "error" ? { error: activity.message } : { message: activity.message },
+    metadata: activity.metadata
+  });
+}
 function displayStatus(state) {
   if (!state.interactive) return;
   const attempt = state.connection?.reconnectAttempt ?? 0;
@@ -8175,6 +9673,10 @@ async function driveChannels(state, driver) {
       consecutiveDrainFailures = 0;
       unreachableMs = 0;
       state.messageCount += processed;
+      if (driver.recycleRequested) {
+        await beginGracefulShutdown(state, "recycle");
+        return;
+      }
       const proxiedActivity = state.lastProxiedActivityAt !== lastSeenProxiedActivityAt;
       lastSeenProxiedActivityAt = state.lastProxiedActivityAt;
       const fileActivitySnapshot = driver.fileSyncActivity();
@@ -8217,8 +9719,8 @@ async function driveChannels(state, driver) {
         state.running = false;
         break;
       }
-      const errorMessage = error2 instanceof Error ? error2.message : String(error2);
-      logActivity(state, { type: "error", error: `Channel processing error: ${errorMessage}` });
+      const errorMessage2 = error2 instanceof Error ? error2.message : String(error2);
+      logActivity(state, { type: "error", error: `Channel processing error: ${errorMessage2}` });
       if (state.interactive) displayStatus(state);
       if (driver.hasInFlightWatchers()) {
         consecutiveDrainFailures = 0;
@@ -8235,7 +9737,7 @@ async function driveChannels(state, driver) {
         }
       }
     }
-    await new Promise((resolve3) => setTimeout(resolve3, CHANNEL_POLL_INTERVAL_MS));
+    await new Promise((resolve4) => setTimeout(resolve4, CHANNEL_POLL_INTERVAL_MS));
     const cycleMs = performance.now() - cycleStartedAtMs;
     if (idleThisCycle) idleMs += cycleMs;
     if (unreachableThisCycle) unreachableMs += cycleMs;
@@ -8258,7 +9760,43 @@ async function driveChannels(state, driver) {
 var SESSION_CLEANUP_FIRST_SWEEP_MS = 1e4;
 var SESSION_DB_RECLAIM_MAX_PAGES = 2e3;
 function sessionDbPath() {
-  return join7(homedir4(), ".local", "share", "opencode", "opencode.db");
+  return join9(homedir5(), ".local", "share", "opencode", "opencode.db");
+}
+function logSessionDbProvenanceMismatch(state, provenance, currentVersion, preBootMigrationCount) {
+  const record = {
+    v: 1,
+    event: "session_db_recovery",
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    stage: "verify",
+    outcome: "schema_provenance_mismatch",
+    severity: "error",
+    reason: provenance.reason ?? "schema-provenance-mismatch",
+    litestream_exit_code: null,
+    attempt: null,
+    replica_objects: null,
+    replica_bytes: null,
+    quarantine_destination: null,
+    quarantined_objects: null,
+    quarantine_failed_objects: null,
+    quarantined_bytes: null,
+    verified_restore_point: null,
+    restore_points_tried: null,
+    provenance_reason: provenance.reason,
+    provenance_migration_delta: provenance.migrationDelta,
+    replication_suspended: false,
+    dbPath: sessionDbPath(),
+    recorded_version: provenance.recordedVersion,
+    current_version: currentVersion,
+    provenance_pre_boot_migration_count: preBootMigrationCount
+  };
+  const activity = buildSessionDbRecoveryActivity(record);
+  if (!activity) throw new Error("could not map session-DB provenance activity");
+  logActivity(state, {
+    type: activity.level === "error" ? "error" : "info",
+    level: activity.level,
+    ...activity.level === "error" ? { error: activity.message } : { message: activity.message },
+    metadata: activity.metadata
+  });
 }
 async function runSweep(state, driver, config) {
   const mode = `age=${config.maxAgeMs ?? "\u2014"} count=${config.maxCount ?? "\u2014"}`;
@@ -8305,7 +9843,7 @@ async function runSweep(state, driver, config) {
     const reclaimResult = await reclaimSessionDbSpace({
       dbPath: sessionDbPath(),
       maxPages: SESSION_DB_RECLAIM_MAX_PAGES,
-      allowFullVacuum: protectedNow.size === 0
+      allowFullVacuum: protectedNow.size === 0 && !state.sessionDbProvenanceAnomaly
     });
     if (reclaimResult.ok) {
       const beforeMib = (reclaimResult.beforeBytes / 1024 / 1024).toFixed(1);
@@ -8341,7 +9879,7 @@ function scheduleSessionCleanup(state, driver, options) {
   for (const warning2 of config.warnings) {
     logActivity(state, { type: "info", level: "warn", message: `Session cleanup: ${warning2}` });
   }
-  const dbBytes = statSessionDbBytes(homedir4());
+  const dbBytes = statSessionDbBytes(homedir5());
   void (async () => {
     const reclaimSkipReason = dbBytes !== null && config.enabled ? await probeReclaimAvailability({ dbPath: sessionDbPath(), requiredBytes: dbBytes }) : null;
     const sizeWarning = buildSessionStoreSizeWarning({
@@ -8500,7 +10038,17 @@ function scheduleClaudeUsageReporting(state, options) {
     setTimer: (timer) => {
       state.claudeUsageTimer = timer;
     },
-    fetchUsage: getClaudeUsage,
+    fetchUsage: async () => {
+      const usage = await getClaudeUsage();
+      if (usage.ownerLookupError) {
+        logActivity(state, {
+          type: "info",
+          level: "debug",
+          message: `Claude usage owner lookup failed: ${usage.ownerLookupError}`
+        });
+      }
+      return usage;
+    },
     report: (usage) => reportClaudeUsage(state.agentId, state.authHeader, usage),
     isLocalCredentialProblem,
     forcedOnHint: "run `claude` to sign in",
@@ -8532,7 +10080,7 @@ function scheduleResourceUsageReporting(state, options) {
     });
     return;
   }
-  const collect = createResourceUsageCollector(homedir4());
+  const collect = createResourceUsageCollector(homedir5());
   let consecutiveFailures = 0;
   const tick = async () => {
     try {
@@ -8642,21 +10190,39 @@ async function cleanup(state, opts = {}) {
     clearTimeout(state.resourceUsageTimer);
     state.resourceUsageTimer = null;
   }
+  const credentialSync = state.credentialSync;
+  const flushCredentials = credentialSync ? async (phase, publish) => {
+    await timeShutdownPhase(state, durations, phase, async () => {
+      const outcomes = await credentialSync.stopAndFlush(publish);
+      const level = Object.values(outcomes).every((outcome) => outcome === "ok") ? "info" : "warn";
+      log2(
+        state,
+        `Credential flush: claude=${outcomes.claude}, opencode=${outcomes.opencode}`,
+        level
+      );
+    });
+  } : void 0;
+  let drainSettled = true;
   if (opts.graceful && state.channelDriver) {
     state.channelDriver.stop();
+  }
+  if (flushCredentials) {
+    await flushCredentials("credential_flush", !(opts.graceful && state.channelDriver));
+  }
+  if (opts.graceful && state.channelDriver) {
     log2(state, "Draining in-flight channel work before shutdown...");
     if (state.interactive) {
       logActivity(state, { type: "info", message: "Draining in-flight work before shutdown..." });
       displayStatus(state);
     }
     const driver = state.channelDriver;
-    const settled = await timeShutdownPhase(
+    drainSettled = await timeShutdownPhase(
       state,
       durations,
       "drain",
       () => driver.waitForInFlight(SHUTDOWN_DRAIN_TIMEOUT_MS)
     );
-    if (!settled) {
+    if (!drainSettled) {
       logActivity(state, {
         type: "info",
         message: "Shutdown drain timed out with work still in flight \u2014 leaving it for restart recovery"
@@ -8664,6 +10230,9 @@ async function cleanup(state, opts = {}) {
       if (state.interactive) displayStatus(state);
     }
   }
+  if (opts.graceful && state.channelDriver && flushCredentials && drainSettled) {
+    await flushCredentials("credential_flush_final", true);
+  }
   await timeShutdownPhase(state, durations, "offline_notify", () => notifyOffline(state));
   if (state.connection) {
     const connection = state.connection;
@@ -8672,24 +10241,83 @@ async function cleanup(state, opts = {}) {
   }
   if (state.opencodeProcess) {
     const opencodeProcess = state.opencodeProcess;
-    await timeShutdownPhase(state, durations, "opencode_stop", () => stopOpenCode(opencodeProcess));
+    const result = await timeShutdownPhase(
+      state,
+      durations,
+      "opencode_stop",
+      () => stopOpenCodeAndWait(opencodeProcess, CHILD_STOP_TIMEOUT_MS)
+    );
     if (state.interactive) {
-      logActivity(state, { type: "info", message: "Stopped OpenCode process" });
+      logActivity(state, { type: "info", message: `Stopped OpenCode process (${result.outcome})` });
       displayStatus(state);
     } else {
-      log2(state, "Stopped OpenCode process");
+      log2(state, `Stopped OpenCode process (${result.outcome})`);
     }
     state.opencodeProcess = null;
   }
+  if (state.litestreamProcess) {
+    const litestreamProcess = state.litestreamProcess;
+    const result = await timeShutdownPhase(
+      state,
+      durations,
+      "litestream_stop",
+      () => stopSessionDbReplication(litestreamProcess, CHILD_STOP_TIMEOUT_MS)
+    );
+    log2(state, `Stopped litestream replication (${result.outcome})`);
+    state.litestreamProcess = null;
+  }
   return durations;
 }
+async function beginGracefulShutdown(state, trigger) {
+  if (state.shuttingDown) return;
+  state.shuttingDown = true;
+  const shutdownStartedAt = Date.now();
+  const shutdownMessage = trigger === "recycle" ? "Recycle requested \u2014 finishing in-flight work, then exiting" : "Shutting down...";
+  if (state.interactive) {
+    logActivity(state, { type: "info", message: shutdownMessage });
+    displayStatus(state);
+  } else {
+    log2(state, shutdownMessage);
+  }
+  const durations = await cleanup(state, { graceful: true });
+  const telemetryBudgetMs = Number(process.env.EVIDENT_TELEMETRY_SHUTDOWN_MS) || TELEMETRY_SHUTDOWN_TIMEOUT_MS;
+  await timeShutdownPhase(state, durations, "telemetry_flush", async () => {
+    let timer;
+    const flushed = shutdownTelemetry().then(
+      () => true,
+      (error2) => {
+        log2(
+          state,
+          `Telemetry flush failed during shutdown: ${error2 instanceof Error ? error2.message : String(error2)}`,
+          "warn"
+        );
+        return true;
+      }
+    );
+    const timedOut = new Promise((resolve4) => {
+      timer = setTimeout(() => resolve4(false), telemetryBudgetMs);
+    });
+    if (!await Promise.race([flushed, timedOut])) {
+      log2(state, `Telemetry flush exceeded ${telemetryBudgetMs}ms \u2014 exiting anyway`, "warn");
+    }
+    clearTimeout(timer);
+  });
+  const breakdown = Object.entries(durations).map(([phase, ms]) => `${phase}=${ms}ms`).join(" ");
+  log2(state, `Shutdown complete in ${Date.now() - shutdownStartedAt}ms (${breakdown})`);
+  process.exit(0);
+}
 async function run(options) {
   const interactive = isInteractive(options.json);
   let logLevel;
   let fileSyncDirectories;
   try {
     logLevel = resolveLogLevel(options);
-    fileSyncDirectories = resolveFileSyncDirectories(options.enableFileSyncTo, homedir4());
+    fileSyncDirectories = resolveFileSyncDirectories(options.enableFileSyncTo, homedir5());
+    if (options.restoreSessionDb && !options.sessionDbNoReplicateMarker) {
+      throw new Error(
+        "--restore-session-db requires --session-db-no-replicate-marker <path>; restore failures must block Litestream replication"
+      );
+    }
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     if (options.json) {
@@ -8713,7 +10341,9 @@ async function run(options) {
     connected: false,
     opencodeConnected: false,
     opencodeVersion: null,
+    sessionDbProvenanceAnomaly: false,
     opencodeProcess: null,
+    litestreamProcess: null,
     connection: null,
     channelDriver: null,
     running: true,
@@ -8727,9 +10357,23 @@ async function run(options) {
     openaiUsageTimer: null,
     openaiUsageRearm: null,
     resourceUsageTimer: null,
+    credentialSync: null,
     authHeader: ""
   };
   setTelemetryAuthProvider(() => ({ authHeader: state.authHeader, agentId: state.agentId }));
+  if (options.credentialSyncMarker) {
+    state.credentialSync = createCredentialSync({
+      markerPath: options.credentialSyncMarker,
+      env: process.env,
+      log: (message, level = "info") => {
+        if (level === "error") {
+          logActivity(state, { type: "error", error: message });
+        } else {
+          logActivity(state, { type: "info", level, message });
+        }
+      }
+    });
+  }
   if (fileSyncDirectories.length > 0) {
     log2(state, `File sync enabled for: ${fileSyncDirectories.join(", ")}`);
   } else {
@@ -8755,43 +10399,7 @@ async function run(options) {
       "warn"
     );
   }
-  const handleSignal = async () => {
-    if (state.shuttingDown) return;
-    state.shuttingDown = true;
-    const shutdownStartedAt = Date.now();
-    if (state.interactive) {
-      logActivity(state, { type: "info", message: "Shutting down..." });
-      displayStatus(state);
-    } else {
-      log2(state, "Shutting down...");
-    }
-    const durations = await cleanup(state, { graceful: true });
-    const telemetryBudgetMs = Number(process.env.EVIDENT_TELEMETRY_SHUTDOWN_MS) || TELEMETRY_SHUTDOWN_TIMEOUT_MS;
-    await timeShutdownPhase(state, durations, "telemetry_flush", async () => {
-      let timer;
-      const flushed = shutdownTelemetry().then(
-        () => true,
-        (error2) => {
-          log2(
-            state,
-            `Telemetry flush failed during shutdown: ${error2 instanceof Error ? error2.message : String(error2)}`,
-            "warn"
-          );
-          return true;
-        }
-      );
-      const timedOut = new Promise((resolve3) => {
-        timer = setTimeout(() => resolve3(false), telemetryBudgetMs);
-      });
-      if (!await Promise.race([flushed, timedOut])) {
-        log2(state, `Telemetry flush exceeded ${telemetryBudgetMs}ms \u2014 exiting anyway`, "warn");
-      }
-      clearTimeout(timer);
-    });
-    const breakdown = Object.entries(durations).map(([phase, ms]) => `${phase}=${ms}ms`).join(" ");
-    log2(state, `Shutdown complete in ${Date.now() - shutdownStartedAt}ms (${breakdown})`);
-    process.exit(0);
-  };
+  const handleSignal = () => beginGracefulShutdown(state, "signal");
   process.on("SIGINT", handleSignal);
   process.on("SIGTERM", handleSignal);
   try {
@@ -8921,7 +10529,68 @@ async function run(options) {
     } else {
       log2(state, "Not running in a MicroVM (MICROVM_ID unset) \u2014 nothing to report", "debug");
     }
+    if (options.restoreRunnerCredentials) {
+      log2(state, "Restoring runner credentials before starting OpenCode");
+      const credentialContext = {
+        env: process.env,
+        log: (message, level = "info") => {
+          if (level === "error") {
+            logActivity(state, { type: "error", error: message });
+          } else {
+            logActivity(state, { type: "info", level, message });
+          }
+        }
+      };
+      const githubTokenPopulated = await installRunnerSecret(credentialContext);
+      await restoreCredentialStores(credentialContext);
+      if (githubTokenPopulated) await configureGitHubAccess(credentialContext);
+    }
+    state.credentialSync?.arm();
+    let sessionDbVerifyFatal = false;
+    if (!options.restoreSessionDb) {
+      log2(state, "Skipping session-DB restore: --restore-session-db was not passed", "debug");
+    } else {
+      const health = await checkOpenCodeHealth(state.port);
+      if (health.healthy) {
+        log2(
+          state,
+          "Skipping session-DB restore: OpenCode is already serving this database",
+          "debug"
+        );
+      } else {
+        const result = await restoreAndVerifySessionDb({
+          dbPath: sessionDbPath(),
+          litestreamConfig: options.litestreamConfig,
+          noReplicateMarker: options.sessionDbNoReplicateMarker,
+          env: process.env,
+          log: (message, level = "info") => {
+            if (level === "error") {
+              logActivity(state, { type: "error", error: message });
+            } else {
+              logActivity(state, { type: "info", level, message });
+            }
+          },
+          reportRecovery: (record) => reportSessionDbRecoveryRecord(state, record)
+        });
+        sessionDbVerifyFatal = result.verifyFatal;
+      }
+    }
     reportSessionDbRecovery(state);
+    if (sessionDbVerifyFatal) {
+      throw new Error(
+        "SESSION-DB-INTEGRITY-EXHAUSTED: the corrupt session DB could not be proven separated from the active backup prefix or removed from disk"
+      );
+    }
+    applyRunnerOpenCodeConfig({
+      overlayPath: options.opencodeConfigOverlay,
+      log: (message, level = "info") => {
+        if (level === "error") {
+          logActivity(state, { type: "error", error: message });
+        } else {
+          logActivity(state, { type: "info", level, message });
+        }
+      }
+    });
     const { timeoutMs: opencodeStartTimeoutMs, warnings: opencodeStartTimeoutWarnings } = resolveOpenCodeStartTimeoutMs(options, process.env);
     for (const warning2 of opencodeStartTimeoutWarnings) {
       logActivity(state, { type: "info", level: "warn", message: warning2 });
@@ -8930,6 +10599,7 @@ async function run(options) {
     for (const warning2 of maxActiveSessionsWarnings) {
       logActivity(state, { type: "info", level: "warn", message: warning2 });
     }
+    const preBootMigrationIds = readSessionDbMigrationIds(sessionDbPath());
     const ocSpinner = interactive && !state.json ? ora3("Checking OpenCode...").start() : null;
     try {
       const oc = await ensureOpenCodeRunning({
@@ -8937,11 +10607,41 @@ async function run(options) {
         interactive: state.interactive,
         agentId: state.agentId,
         log: (message) => log2(state, message),
-        startTimeoutMs: opencodeStartTimeoutMs
+        startTimeoutMs: opencodeStartTimeoutMs,
+        inheritStdio: Boolean(options.opencodePidFile)
       });
       state.port = oc.port;
-      state.opencodeProcess = oc.process;
+      state.opencodeProcess = options.opencodePidFile ? null : oc.process;
       state.opencodeVersion = oc.version;
+      if (options.opencodePidFile && oc.process?.pid !== void 0) {
+        try {
+          writeFileSync6(options.opencodePidFile, `${oc.process.pid}
+`, { mode: 384 });
+          chmodSync3(options.opencodePidFile, 384);
+        } catch (error2) {
+          logActivity(state, {
+            type: "error",
+            error: `Failed to write OpenCode pid file ${options.opencodePidFile}: ${error2 instanceof Error ? error2.message : String(error2)}`
+          });
+        }
+      }
+      if (state.opencodeVersion !== null) {
+        const provenance = checkSessionDbProvenance({
+          dbPath: sessionDbPath(),
+          currentVersion: state.opencodeVersion,
+          homeDir: homedir5(),
+          env: process.env
+        });
+        if (provenance.anomaly) {
+          state.sessionDbProvenanceAnomaly = true;
+          logSessionDbProvenanceMismatch(
+            state,
+            provenance,
+            state.opencodeVersion,
+            preBootMigrationIds?.length ?? null
+          );
+        }
+      }
       state.opencodeConnected = oc.notReadyReason === null;
       const version2 = state.opencodeVersion ? ` (v${state.opencodeVersion})` : "";
       ocSpinner?.succeed(`OpenCode running on port ${state.port}${version2}`);
@@ -8978,6 +10678,108 @@ async function run(options) {
       ocSpinner?.fail(error2.message);
       throw error2;
     }
+    if (options.litestreamPidFile) {
+      if (options.sessionDbNoReplicateMarker && existsSync3(options.sessionDbNoReplicateMarker)) {
+        log2(
+          state,
+          `Skipping Litestream replication because ${options.sessionDbNoReplicateMarker} marks this session database unsafe to replicate`
+        );
+      } else if (!options.litestreamConfig) {
+        logActivity(state, {
+          type: "info",
+          level: "warn",
+          message: "Skipping Litestream replication because no configuration file was provided"
+        });
+      } else {
+        let existingPid;
+        if (existsSync3(options.litestreamPidFile)) {
+          try {
+            const rawPid = readFileSync6(options.litestreamPidFile, "utf8").trim();
+            const parsedPid = Number(rawPid);
+            if (/^\d+$/.test(rawPid) && Number.isSafeInteger(parsedPid) && parsedPid > 0) {
+              existingPid = parsedPid;
+            }
+          } catch (error2) {
+            logActivity(state, {
+              type: "info",
+              level: "warn",
+              message: `Could not read Litestream pid file ${options.litestreamPidFile}; checking for a new process: ${error2 instanceof Error ? error2.message : String(error2)}`
+            });
+          }
+        }
+        if (existingPid !== void 0 && isProcessAlive(existingPid)) {
+          log2(state, `Litestream replication is already running with pid ${existingPid}`);
+        } else {
+          const litestreamProcess = startSessionDbReplication(options.litestreamConfig);
+          state.litestreamProcess = null;
+          let failureHandled = false;
+          const reportImageOwnedReplicationFailure = (message) => {
+            if (failureHandled || state.shuttingDown || !state.running) return;
+            failureHandled = true;
+            logActivity(state, { type: "error", error: message });
+            if (state.interactive) displayStatus(state);
+          };
+          litestreamProcess.on("exit", (code, signal) => {
+            reportImageOwnedReplicationFailure(
+              `Litestream replication stopped unexpectedly (code: ${code ?? "null"}, signal: ${signal ?? "none"})`
+            );
+          });
+          litestreamProcess.on("error", (error2) => {
+            reportImageOwnedReplicationFailure(
+              `Litestream replication failed: ${error2 instanceof Error ? error2.message : String(error2)}`
+            );
+          });
+          try {
+            if (litestreamProcess.pid !== void 0) {
+              writeFileSync6(options.litestreamPidFile, `${litestreamProcess.pid}
+`, {
+                mode: 384
+              });
+              chmodSync3(options.litestreamPidFile, 384);
+            }
+          } catch (error2) {
+            logActivity(state, {
+              type: "error",
+              error: `Failed to write Litestream pid file ${options.litestreamPidFile}: ${error2 instanceof Error ? error2.message : String(error2)}`
+            });
+          }
+          log2(state, `Started litestream replication with config ${options.litestreamConfig}`);
+        }
+      }
+    } else if (options.litestreamConfig) {
+      const litestreamProcess = startSessionDbReplication(options.litestreamConfig);
+      state.litestreamProcess = litestreamProcess;
+      let failureHandled = false;
+      const failRunForReplication = (message) => {
+        if (failureHandled || state.shuttingDown || !state.running) return;
+        failureHandled = true;
+        state.shuttingDown = true;
+        logActivity(state, { type: "error", error: message });
+        if (state.interactive) displayStatus(state);
+        void (async () => {
+          try {
+            await cleanup(state);
+            await shutdownTelemetry();
+          } catch (error2) {
+            console.error(
+              `[run] replication failure cleanup failed: ${error2 instanceof Error ? error2.message : String(error2)}`
+            );
+          }
+          process.exit(1);
+        })();
+      };
+      litestreamProcess.on("exit", (code, signal) => {
+        failRunForReplication(
+          `Litestream replication stopped unexpectedly (code: ${code ?? "null"}, signal: ${signal ?? "none"})`
+        );
+      });
+      litestreamProcess.on("error", (error2) => {
+        failRunForReplication(
+          `Litestream replication failed: ${error2 instanceof Error ? error2.message : String(error2)}`
+        );
+      });
+      log2(state, `Started litestream replication with config ${options.litestreamConfig}`);
+    }
     const tunnelSpinner = interactive && !state.json ? ora3("Connecting tunnel...").start() : null;
     const channelDriver = new ChannelDriver({
       agentId: state.agentId,
@@ -8989,7 +10791,7 @@ async function run(options) {
       // #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: homedir4(),
+      homeDir: homedir5(),
       maxActiveSessions,
       log: (entry) => (
         // Thread the driver's real level straight through so `debug`/`warn`
@@ -9135,7 +10937,17 @@ async function run(options) {
       setTimer: (timer) => {
         state.openaiUsageTimer = timer;
       },
-      fetchUsage: () => getOpenAiUsage(state.port),
+      fetchUsage: async () => {
+        const usage = await getOpenAiUsage(state.port);
+        if (usage.subscription === null) {
+          logActivity(state, {
+            type: "info",
+            level: "debug",
+            message: "OpenAI usage subscription could not be identified from the local credential"
+          });
+        }
+        return usage;
+      },
       report: (usage) => reportOpenAiUsage(state.agentId, state.authHeader, usage),
       isLocalCredentialProblem: isLocalCredentialProblem2,
       forcedOnHint: "connect a ChatGPT account to this runner, or run `opencode auth login`",
@@ -9181,7 +10993,7 @@ async function run(options) {
 }
 
 // src/index.ts
-var { version } = createRequire(import.meta.url)("../package.json");
+var { version } = createRequire2(import.meta.url)("../package.json");
 var program = new Command();
 program.name("evident").description("Run OpenCode locally and connect it to Evident").version(version).option(
   "--endpoint <url>",
@@ -9238,6 +11050,30 @@ program.command("run").description("Connect to Evident and process messages").op
 ).option(
   "--tunnel-ready-file <path>",
   "Path to write once the tunnel is connected (opt-in; unused unless an operator/image sets it)"
+).option(
+  "--litestream-config <path>",
+  "Replicate the OpenCode session database with `litestream replicate` using this config file (written by the runner image). Omit to disable replication."
+).option(
+  "--opencode-pid-file <path>",
+  "Record the OpenCode pid here and leave the process running at shutdown for the runner image's lifecycle hooks to stop."
+).option(
+  "--litestream-pid-file <path>",
+  "Record the Litestream pid here and leave the process running at shutdown for the runner image's lifecycle hooks to stop."
+).option(
+  "--session-db-no-replicate-marker <path>",
+  "Read this marker as a gate before starting Litestream; the session-DB restore writes it when this boot's database is not safe to replicate."
+).option(
+  "--restore-session-db",
+  "Restore and verify the OpenCode session database before starting OpenCode; requires --litestream-config for the replica and --session-db-no-replicate-marker for give-up records."
+).option(
+  "--restore-runner-credentials",
+  "Restore the hosted runner secret and persisted credential stores before starting OpenCode."
+).option(
+  "--opencode-config-overlay <path>",
+  "Apply this runner-provided OpenCode config before starting OpenCode."
+).option(
+  "--credential-sync-marker <path>",
+  "Own the interval credential sync and write this marker once the shutdown flush has finished, so the runner image's lifecycle hooks can wait on it."
 ).action(
   (options) => {
     run({
@@ -9269,7 +11105,15 @@ program.command("run").description("Connect to Evident and process messages").op
       // Raw values — expansion/validation is single-sourced in run.ts's
       // resolveFileSyncDirectories.
       enableFileSyncTo: options.enableFileSyncTo,
-      tunnelReadyFile: options.tunnelReadyFile
+      tunnelReadyFile: options.tunnelReadyFile,
+      litestreamConfig: options.litestreamConfig,
+      opencodePidFile: options.opencodePidFile,
+      litestreamPidFile: options.litestreamPidFile,
+      sessionDbNoReplicateMarker: options.sessionDbNoReplicateMarker,
+      restoreSessionDb: options.restoreSessionDb,
+      restoreRunnerCredentials: options.restoreRunnerCredentials,
+      opencodeConfigOverlay: options.opencodeConfigOverlay,
+      credentialSyncMarker: options.credentialSyncMarker
     });
   }
 );