Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
97.9 KB
Raw Blame
import { appSecretHeaders, rememberLocalServer } from "./app-request-secret.mjs";
import { randomUUID, X509Certificate } from "node:crypto";
import { spawnSync } from "node:child_process";
import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
import { chmod, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import net from "node:net";
import os from "node:os";
import path from "node:path";
import tls from "node:tls";
import { fileURLToPath } from "node:url";
import { isReleaseBuild, releaseEngineBinary } from "./build-variant.mjs";
import { pathToFileURL } from "node:url";
import {
  appendRuntimeRestartRecord,
  decideDeferredRestart,
  decideRuntimeRestart,
  readRuntimeRestartRecords,
} from "./runtime-restart-log.mjs";
import {
  desktopBootstrapPath,
  normalizeWorkspaceRootPath,
  omnirushEnvStorePath,
  omnirushServerConfigPath,
} from "@omnirush/paths";
import {
  dedupeCertificates,
  extendDefaultCaCertificates,
  resolveSystemCaBundle,
  summarizeSystemCaSources,
  systemPlatformCertificateLoader,
} from "./system-ca.mjs";

const __runtimeDir = path.dirname(fileURLToPath(import.meta.url));

const DIRECT_RUNTIME = "direct";
const OMNIRUSH_SERVER_PORT_RANGE_START = 48_000;
const OMNIRUSH_SERVER_PORT_RANGE_END = 51_000;
const MAX_BOOTSTRAP_BYTES = 256 * 1024;
const MAX_CHAIN_REPAIR_BODY_BYTES = 64 * 1024;
const MAX_CHAIN_REPAIR_ORIGINS = 3;
const CHAIN_REPAIR_TOTAL_TIMEOUT_MS = 20000;
const CHAIN_REPAIR_SOCKET_TIMEOUT_MS = 8000;
const CHAIN_REPAIR_FETCH_TIMEOUT_MS = 8000;
const CERTIFICATE_VERIFY_USE_CHROMIUM = -3;
const CERTIFICATE_VERIFY_OK = 0;
const ERR_CERT_AUTHORITY_INVALID = -202;
const MAX_CERTIFICATE_CHAIN_LENGTH = 10;
const PEM_CERTIFICATE_PATTERN = /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g;
/** @type {Map<string, X509Certificate | null>} */
const chainRepairRootCache = new Map();

/** @param {unknown} value */
function parsePemCertificates(value) {
  return String(value ?? "").match(PEM_CERTIFICATE_PATTERN) ?? [];
}

/** @param {string} value */
function parseCertificate(value) {
  try {
    return new X509Certificate(value);
  } catch {
    return null;
  }
}

/** @param {X509Certificate} certificate */
function certificateIsCurrent(certificate, now = Date.now()) {
  const validFrom = Date.parse(certificate.validFrom);
  const validTo = Date.parse(certificate.validTo);
  return Number.isFinite(validFrom) && Number.isFinite(validTo) && validFrom <= now && now <= validTo;
}

/** @param {X509Certificate} certificate @param {string | undefined} hostname */
function certificateMatchesHostname(certificate, hostname) {
  const value = String(hostname ?? "").trim();
  if (!value) return false;
  try {
    return net.isIP(value) ? certificate.checkIP(value) !== undefined : certificate.checkHost(value) !== undefined;
  } catch {
    return false;
  }
}

/** @param {X509Certificate} certificate */
function certificateAllowsTlsServerAuthentication(certificate) {
  return certificate.keyUsage?.some((usage) =>
    usage === "1.3.6.1.5.5.7.3.1" || /server ?auth/i.test(usage)
  ) === true;
}

/**
 * @typedef {Object} ElectronCertificate
 * @property {string} data
 * @property {ElectronCertificate} [issuerCert]
 */

/** @param {ElectronCertificate | undefined} certificate */
function presentedCertificateChain(certificate) {
  const chain = [];
  const seen = new Set();
  let current = certificate;
  while (current) {
    if (chain.length >= MAX_CERTIFICATE_CHAIN_LENGTH || typeof current.data !== "string") return null;
    const parsed = parseCertificate(current.data);
    if (!parsed) return null;
    const key = parsed.raw.toString("base64");
    if (seen.has(key)) return null;
    seen.add(key);
    chain.push(parsed);
    current = current.issuerCert;
  }
  return chain;
}

/** @param {ElectronCertificate | undefined} certificate @param {string | undefined} hostname @param {X509Certificate[]} trustedAnchors */
function chainEndsAtTrustedAnchor(certificate, hostname, trustedAnchors) {
  const chain = presentedCertificateChain(certificate);
  if (!chain || chain.length === 0 || chain.some((entry) => !certificateIsCurrent(entry))) return false;
  if (!certificateAllowsTlsServerAuthentication(chain[0])) return false;
  if (!certificateMatchesHostname(chain[0], hostname)) return false;
  for (let index = 0; index < chain.length - 1; index += 1) {
    if (chain[index + 1].ca !== true) return false;
    if (!chain[index].checkIssued(chain[index + 1]) || !chain[index].verify(chain[index + 1].publicKey)) return false;
  }
  const terminal = chain.at(-1);
  if (!terminal) return false;
  return trustedAnchors.some((anchor) =>
    anchor.ca === true && terminal.checkIssued(anchor) && terminal.verify(anchor.publicKey)
  );
}

/**
 * @param {string[]} trustedCertificates
 * @returns {(request: { verificationResult?: string, errorCode?: number, hostname?: string, certificate?: ElectronCertificate }, callback: (result: number) => void) => void}
 */
export function createSystemCaCertificateVerifyProc(trustedCertificates) {
  const trustedAnchors = trustedCertificates.map(parseCertificate).filter((certificate) => certificate !== null);
  return (request, callback) => {
    const authorityInvalid = request.verificationResult
      ? request.verificationResult === "net::ERR_CERT_AUTHORITY_INVALID"
        && (request.errorCode === undefined || request.errorCode === ERR_CERT_AUTHORITY_INVALID)
      : request.errorCode === ERR_CERT_AUTHORITY_INVALID;
    if (authorityInvalid && chainEndsAtTrustedAnchor(request.certificate, request.hostname, trustedAnchors)) {
      callback(CERTIFICATE_VERIFY_OK);
      return;
    }
    callback(CERTIFICATE_VERIFY_USE_CHROMIUM);
  };
}

function truncateOutput(value, limit = 8000) {
  const text = String(value ?? "");
  return text.length <= limit ? text : text.slice(text.length - limit);
}

function appendOutput(state, key, chunk) {
  const next = `${state[key] ?? ""}${String(chunk ?? "")}`;
  state[key] = truncateOutput(next);
}

function normalizeWorkspaceKey(value, platform = process.platform) {
  try {
    const normalized = normalizeWorkspaceRootPath(value, { platform });
    if (!normalized) return "";
    const paths = platform === "win32" ? path.win32 : path;
    return paths.resolve(normalized).replace(/\\/g, "/").toLowerCase();
  } catch {
    return "";
  }
}

function normalizeServerCredentials(value) {
  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
  const clientToken = typeof value.clientToken === "string" && value.clientToken.trim()
    ? value.clientToken
    : null;
  const hostToken = typeof value.hostToken === "string" && value.hostToken.trim()
    ? value.hostToken
    : null;
  if (!clientToken || !hostToken) return null;
  return {
    clientToken,
    hostToken,
    ownerToken: typeof value.ownerToken === "string" && value.ownerToken.trim()
      ? value.ownerToken
      : null,
    updatedAt: typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt)
      ? value.updatedAt
      : 0,
  };
}

export function migrateOmniRushServerTokenStore(value) {
  const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
  const sourceWorkspaces = source.workspaces && typeof source.workspaces === "object" && !Array.isArray(source.workspaces)
    ? source.workspaces
    : {};
  const workspaceEntries = Object.entries(sourceWorkspaces);
  const legacyCredentials = workspaceEntries
    .flatMap(([workspaceKey, entry]) => {
      const credentials = normalizeServerCredentials(entry);
      return credentials ? [{ workspaceKey, credentials }] : [];
    })
    .sort((left, right) => {
      const updatedAtDifference = right.credentials.updatedAt - left.credentials.updatedAt;
      if (updatedAtDifference !== 0) return updatedAtDifference;
      return left.workspaceKey < right.workspaceKey ? -1 : left.workspaceKey > right.workspaceKey ? 1 : 0;
    })[0]?.credentials;
  const credentials = normalizeServerCredentials(source.credentials) ?? legacyCredentials ?? {
    clientToken: randomUUID(),
    hostToken: randomUUID(),
    ownerToken: null,
    updatedAt: nowMs(),
  };
  return { version: 2, credentials };
}

export function prioritizeWorkspacePaths(preferredPath, workspacePaths = [], options = {}) {
  const platform = options.platform ?? process.platform;
  const paths = [];
  const seen = new Set();
  const add = (value) => {
    let workspacePath;
    try {
      workspacePath = normalizeWorkspaceRootPath(value, { platform });
    } catch {
      return;
    }
    const key = normalizeWorkspaceKey(workspacePath, platform);
    if (!workspacePath || !key || seen.has(key)) return;
    paths.push(workspacePath);
    seen.add(key);
  };
  add(preferredPath);
  for (const workspacePath of workspacePaths) add(workspacePath);
  return paths;
}

function workspaceInaccessibleError(workspacePath, cause) {
  if (cause && typeof cause === "object" && cause.code === "workspace_inaccessible") return cause;
  const error = new Error(`Workspace path is not accessible: ${workspacePath}`, { cause });
  Object.defineProperties(error, {
    code: { value: "workspace_inaccessible", enumerable: true },
    workspacePath: { value: workspacePath, enumerable: true },
  });
  return error;
}

export async function prepareRuntimeWorkspaceRoot(projectDir, options = {}) {
  const rawProjectDir = String(projectDir ?? "").trim();
  try {
    const workspaceRoot = normalizeWorkspaceRootPath(rawProjectDir, {
      platform: options.platform ?? process.platform,
    });
    if (!workspaceRoot) throw new Error("projectDir is required");
    await (options.mkdirImpl ?? mkdir)(workspaceRoot, { recursive: true });
    if (typeof options.ensureConfig === "function") {
      await options.ensureConfig(workspaceRoot);
    }
    return workspaceRoot;
  } catch (error) {
    throw workspaceInaccessibleError(rawProjectDir, error);
  }
}

export function resolveOmniRushServerConfigPath(env = process.env) {
  return omnirushServerConfigPath({ env });
}

export function seedWorkspacePathsForEmbeddedServer(workspacePaths, serverConfigExists) {
  return serverConfigExists ? [] : workspacePaths;
}

export function selectStickyOmniRushPortWorkspace(requestedWorkspacePaths = [], serverWorkspacePaths = []) {
  for (const value of [...requestedWorkspacePaths, ...serverWorkspacePaths]) {
    const workspacePath = String(value ?? "").trim();
    if (workspacePath) return workspacePath;
  }
  return "";
}

export function resolveEvalLocalServerDelayMs(env = process.env) {
  const delayMs = Number(env.OMNIRUSH_EVAL_LOCAL_SERVER_DELAY_MS);
  return Number.isFinite(delayMs) && delayMs > 0 ? delayMs : 0;
}

export function reconcileInjectedUserEnv({
  processEnv,
  inheritedEnv,
  userEnv,
  previouslyInjectedKeys = new Set(),
}) {
  for (const key of previouslyInjectedKeys) {
    if (Object.prototype.hasOwnProperty.call(userEnv, key)) continue;
    if (Object.prototype.hasOwnProperty.call(inheritedEnv, key)) {
      processEnv[key] = inheritedEnv[key];
    } else {
      delete processEnv[key];
    }
  }

  for (const [key, value] of Object.entries(userEnv)) {
    if (Object.prototype.hasOwnProperty.call(inheritedEnv, key)) continue;
    processEnv[key] = value;
  }

  return new Set(
    Object.keys(userEnv).filter(
      (key) => !Object.prototype.hasOwnProperty.call(inheritedEnv, key),
    ),
  );
}

export function commandMatchesPackagedSidecar(command, sidecarDirs = []) {
  const value = String(command ?? "");
  if (!sidecarDirs.some((dir) => String(dir ?? "").trim() && value.includes(dir))) {
    return false;
  }
  return /(?:^|[/\\])opencode[^/\\\s]*\s+serve\b/.test(value);
}

export function embeddedServerImportUrl(embeddedPath) {
  const url = pathToFileURL(embeddedPath);
  try {
    const stats = statSync(embeddedPath);
    url.searchParams.set("mtimeMs", String(stats.mtimeMs));
    url.searchParams.set("size", String(stats.size));
  } catch {
    // Fall back to the deterministic file URL if stat fails; startup can continue.
  }
  return url.href;
}

function nowMs() {
  return Date.now();
}

function createEngineState() {
  return {
    child: null,
    childExited: true,
    runtime: DIRECT_RUNTIME,
    projectDir: null,
    hostname: null,
    port: null,
    baseUrl: null,
    opencodeUsername: null,
    opencodePassword: null,
    opencodeBinPath: null,
    opencodeBinSource: null,
    managedByServer: false,
    managedPid: null,
    managedIsAlive: null,
    lastStdout: null,
    lastStderr: null,
    execution: null,
  };
}

export function snapshotEngineState(state) {
  const child = state.childExited ? null : state.child;
  let managedRunning = false;
  if (state.managedByServer && typeof state.managedIsAlive === "function") {
    try {
      managedRunning = state.managedIsAlive() === true;
    } catch {
      managedRunning = false;
    }
  }
  const childRunning = Boolean(child && child.exitCode === null && !child.killed);
  return {
    running: managedRunning || childRunning,
    runtime: state.runtime,
    managedByServer: state.managedByServer === true,
    baseUrl: state.baseUrl,
    projectDir: state.projectDir,
    hostname: state.hostname,
    port: state.port,
    opencodeUsername: state.opencodeUsername,
    opencodePassword: state.opencodePassword,
    opencodeBinPath: state.opencodeBinPath,
    opencodeBinSource: state.opencodeBinSource,
    pid: state.managedByServer ? state.managedPid ?? null : child?.pid ?? null,
    lastStdout: state.lastStdout,
    lastStderr: state.lastStderr,
    execution: state.execution,
  };
}

/**
 * Where the in-process omnirush-server persists its structured log. Packaged
 * apps have no visible stdout, so without this file every engine rollover
 * reason and reload trigger is lost. An explicit OMNIRUSH_SERVER_LOG_FILE wins.
 */
/**
 * Set by a user's sign-out, cleared once a server started with it: that
 * server stops sending what is queued and keeps it on disk for the account
 * that signed out (capture-host signOut). On disk, so a quit before the next
 * start still does it at the one after.
 */
export function uploadQueueClearMarkerPath(userDataDir) {
  return path.join(userDataDir, "omnirush-upload-queue-clear");
}

export function resolveOmniRushServerLogFile(userDataDir, env = process.env) {
  const explicit = String(env.OMNIRUSH_SERVER_LOG_FILE ?? "").trim();
  if (explicit) return explicit;
  return path.join(userDataDir, "logs", "omnirush-server.log");
}

function createOmniRushServerState() {
  return {
    child: null,
    childExited: true,
    inProcess: false,
    logFilePath: null,
    // Monotonic per-start identity assigned by startOmniRushServerInner.
    // Sticky ports and persisted tokens make the connection details identical
    // across restarts, so clients need this to observe a new server lifetime.
    generation: null,
    remoteAccessEnabled: false,
    host: null,
    port: null,
    baseUrl: null,
    connectUrl: null,
    mdnsUrl: null,
    lanUrl: null,
    clientToken: null,
    ownerToken: null,
    hostToken: null,
    managedOpencodeBinPath: null,
    managedOpencodeBinSource: null,
    lastStdout: null,
    lastStderr: null,
    managedOpencodeExecution: null,
  };
}

export function snapshotOmniRushServerState(state) {
  const child = state.childExited ? null : state.child;
  const running = state.inProcess || Boolean(child && child.exitCode === null && !child.killed);
  return {
    running,
    generation: typeof state.generation === "number" ? state.generation : null,
    remoteAccessEnabled: state.remoteAccessEnabled,
    host: state.host,
    port: state.port,
    baseUrl: state.baseUrl,
    connectUrl: state.connectUrl,
    mdnsUrl: state.mdnsUrl,
    lanUrl: state.lanUrl,
    clientToken: state.clientToken,
    ownerToken: state.ownerToken,
    hostToken: state.hostToken,
    managedOpencodeBinPath: state.managedOpencodeBinPath,
    managedOpencodeBinSource: state.managedOpencodeBinSource,
    logFilePath: state.logFilePath ?? null,
    pid: child?.pid ?? null,
    lastStdout: state.lastStdout,
    lastStderr: state.lastStderr,
    managedOpencodeExecution: state.managedOpencodeExecution,
  };
}

/**
 * Decide whether an engineStart request keeps the running embedded server.
 *
 * The engine is multi-instance: it boots a per-directory instance on demand,
 * so a request for a different workspace retargets the running runtime
 * instead of restarting it. A restart here would abort every in-flight run,
 * including sessions still working in the workspace being left. Only an
 * explicit forceRestart or a host rebind (remote access change) gives up the
 * running server.
 */
export function resolveOmniRushServerReuse({
  forceRestart,
  inProcess,
  lifecycleState,
  remoteAccessEnabled,
  requestedRemoteAccess,
  currentProjectDir,
  requestedProjectDir,
  platform,
}) {
  if (forceRestart === true) return { reuse: false, retarget: false };
  if (inProcess !== true || lifecycleState !== "healthy") return { reuse: false, retarget: false };
  if (remoteAccessEnabled !== (requestedRemoteAccess === true)) return { reuse: false, retarget: false };
  const retarget =
    normalizeWorkspaceKey(currentProjectDir, platform) !== normalizeWorkspaceKey(requestedProjectDir, platform);
  return { reuse: true, retarget };
}

/**
 * A failed server start must not leave the state objects describing the
 * runtime it already stopped: snapshotOmniRushServerState would report
 * running:true with a dead baseUrl and assertOmniRushServerReady would pass
 * against it. Keeps accumulated output for diagnostics and the project dir so
 * a retry via engineRestart still knows its workspace. The engine state only
 * resets when this start owned the engine (manageOpencode) — an external
 * engine keeps running regardless of the server's fate.
 */
export function resetRuntimeStatesAfterFailedServerStart(omnirushServerStateRef, engineStateRef, options = {}) {
  const serverStdout = omnirushServerStateRef.lastStdout;
  const serverStderr = omnirushServerStateRef.lastStderr;
  Object.assign(omnirushServerStateRef, createOmniRushServerState());
  omnirushServerStateRef.lastStdout = serverStdout;
  omnirushServerStateRef.lastStderr = serverStderr;
  if (options.manageOpencode === true) {
    const engineStdout = engineStateRef.lastStdout;
    const engineStderr = engineStateRef.lastStderr;
    const projectDir = engineStateRef.projectDir;
    Object.assign(engineStateRef, createEngineState());
    engineStateRef.lastStdout = engineStdout;
    engineStateRef.lastStderr = engineStderr;
    engineStateRef.projectDir = projectDir;
  }
}

function assertOmniRushServerReady(snapshot) {
  if (!snapshot?.running) {
    throw new Error("OmniRush.ai server did not stay running after startup.");
  }
  if (!snapshot.baseUrl) {
    throw new Error("OmniRush.ai server did not report a base URL after startup.");
  }
  if (!snapshot.ownerToken && !snapshot.clientToken) {
    throw new Error("OmniRush.ai server did not report an access token after startup.");
  }
  return snapshot;
}

async function readJsonFile(targetPath, fallback) {
  try {
    const raw = await readFile(targetPath, "utf8");
    return JSON.parse(raw);
  } catch {
    return fallback;
  }
}

function selectLanAddress() {
  const interfaces = os.networkInterfaces();
  for (const entries of Object.values(interfaces)) {
    for (const entry of entries ?? []) {
      if (entry && entry.family === "IPv4" && entry.internal === false) {
        return entry.address;
      }
    }
  }
  return null;
}

function buildConnectUrls(port) {
  const hostname = os.hostname().trim();
  const mdnsUrl = hostname ? `http://${hostname.replace(/\.local$/i, "")}.local:${port}` : null;
  const lan = selectLanAddress();
  const lanUrl = lan ? `http://${lan}:${port}` : null;
  return {
    connectUrl: lanUrl ?? mdnsUrl,
    mdnsUrl,
    lanUrl,
  };
}

function targetTriple() {
  if (process.platform === "darwin") {
    return process.arch === "arm64" ? "aarch64-apple-darwin" : "x86_64-apple-darwin";
  }
  if (process.platform === "linux") {
    return process.arch === "arm64" ? "aarch64-unknown-linux-gnu" : "x86_64-unknown-linux-gnu";
  }
  if (process.platform === "win32") {
    return process.arch === "arm64" ? "aarch64-pc-windows-msvc" : "x86_64-pc-windows-msvc";
  }
  return null;
}

function binaryFileNames(baseName) {
  const ext = process.platform === "win32" ? ".exe" : "";
  const triple = targetTriple();
  return [
    triple ? `${baseName}-${triple}${ext}` : null,
    `${baseName}${ext}`,
  ].filter(Boolean);
}

function isDirectory(targetPath) {
  try {
    return statSync(targetPath).isDirectory();
  } catch {
    return false;
  }
}

function nvmVersionBinPaths(home) {
  const base = path.join(home, ".nvm", "versions", "node");
  try {
    return readdirSync(base, { withFileTypes: true })
      .filter((entry) => entry.isDirectory())
      .map((entry) => path.join(base, entry.name, "bin"))
      .filter(isDirectory)
      .sort()
      .reverse();
  } catch {
    return [];
  }
}

// PATH resolution for the server and the sidecars it spawns. The engine-side
// twin lives in apps/server/src/engine-shell-path.ts and
// must list the same directories (a server test compares the two), so the
// engine's bash tool finds git and gh the way the packaged app does.
export function pathHelperEntries() {
  if (process.platform !== "darwin") return [];
  const result = spawnSync("/usr/libexec/path_helper", ["-s"], {
    encoding: "utf8",
    stdio: ["ignore", "pipe", "ignore"],
  });
  if (result.status !== 0) return [];
  const stdout = String(result.stdout ?? "");
  const match = stdout.match(/PATH="([^"]+)"/) ?? stdout.match(/PATH=([^;\n]+)/);
  return match?.[1]?.split(path.delimiter).filter(Boolean) ?? [];
}

export function extraPathEntries() {
  const home = os.homedir();
  const candidates = [];

  if (process.platform === "darwin") {
    candidates.push(
      ...pathHelperEntries(),
      "/opt/homebrew/bin",
      "/opt/homebrew/sbin",
      "/usr/local/bin",
      "/usr/local/sbin",
      path.join(home, ".nvm", "current", "bin"),
      ...nvmVersionBinPaths(home),
      path.join(home, ".fnm", "current", "bin"),
      path.join(home, ".volta", "bin"),
      path.join(home, "Library", "pnpm"),
      path.join(home, ".bun", "bin"),
      path.join(home, ".cargo", "bin"),
      path.join(home, ".pyenv", "shims"),
      path.join(home, ".local", "bin"),
    );
  }

  if (process.platform === "linux") {
    candidates.push(
      "/usr/local/bin",
      "/usr/local/sbin",
      path.join(home, ".nvm", "current", "bin"),
      ...nvmVersionBinPaths(home),
      path.join(home, ".fnm", "current", "bin"),
      path.join(home, ".volta", "bin"),
      path.join(home, ".local", "share", "pnpm"),
      path.join(home, ".bun", "bin"),
      path.join(home, ".cargo", "bin"),
      path.join(home, ".pyenv", "shims"),
      path.join(home, ".local", "bin"),
    );
  }

  if (process.platform === "win32") {
    candidates.push(
      path.join(home, ".volta", "bin"),
      path.join(home, ".bun", "bin"),
      path.join(home, ".cargo", "bin"),
      process.env.APPDATA ? path.join(process.env.APPDATA, "npm") : null,
      process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, "pnpm") : null,
    );
  }

  return candidates.filter((entry) => entry && isDirectory(entry));
}

// The PATH stock OpenCode would see: the launch PATH; for a Finder/Dock launch on macOS (launchd's
// default PATH) the login shell's, as path_helper gives it to every login shell.
const LAUNCHD_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
export function launchShellPath(launchPath, platform = process.platform, loginShellEntries = pathHelperEntries) {
  if (platform !== "darwin" || launchPath !== LAUNCHD_PATH) return launchPath;
  return loginShellEntries().join(path.delimiter) || launchPath;
}

export function enrichedPath(sidecarDirs, currentPath) {
  const entries = [
    ...sidecarDirs.filter(isDirectory),
    ...extraPathEntries(),
    ...String(currentPath ?? "").split(path.delimiter).filter(Boolean),
  ];
  const deduped = entries.filter((entry, index) => entries.indexOf(entry) === index);
  return deduped.length > 0 ? deduped.join(path.delimiter) : null;
}

async function portAvailable(host, port) {
  return new Promise((resolve) => {
    const server = net.createServer();
    server.unref();
    server.once("error", () => resolve(false));
    server.listen({ host, port }, () => {
      server.close(() => resolve(true));
    });
  });
}

async function findFreePort(host = "127.0.0.1") {
  return new Promise((resolve, reject) => {
    const server = net.createServer();
    server.unref();
    server.once("error", reject);
    server.listen({ host, port: 0 }, () => {
      const address = server.address();
      if (!address || typeof address === "string") {
        server.close(() => reject(new Error("Failed to allocate a free port.")));
        return;
      }
      const { port } = address;
      server.close(() => resolve(port));
    });
  });
}

async function fetchJson(url, options = {}, timeoutMs = 3000) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    // loopback-fetch: fetchJson callers pass runtime-managed 127.0.0.1 server URLs.
    const response = await fetch(url, {
      ...options,
      signal: controller.signal,
      headers: {
        Accept: "application/json",
        ...appSecretHeaders(url),
        ...(options.headers ?? {}),
      },
    });
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return await response.json();
  } finally {
    clearTimeout(timer);
  }
}

export function resolveUserEnvFilePath(env = process.env) {
  return omnirushEnvStorePath({ env });
}

const USER_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
const USER_ENV_RESERVED_PREFIXES = ["OMNIRUSH_", "OPENCODE_"];

// Synchronous, best-effort; absent or malformed returns {}. Reserved prefixes
// are stripped so a tampered file can never shadow OMNIRUSH_* / OPENCODE_*.
function loadUserEnvFile(env = process.env) {
  try {
    const raw = readFileSync(resolveUserEnvFilePath(env), "utf8");
    const parsed = JSON.parse(raw);
    if (!parsed || !Array.isArray(parsed.variables)) return {};
    const out = {};
    for (const entry of parsed.variables) {
      if (!entry || typeof entry !== "object") continue;
      const { key, value } = entry;
      if (typeof key !== "string" || typeof value !== "string") continue;
      if (!USER_ENV_KEY_PATTERN.test(key)) continue;
      if (USER_ENV_RESERVED_PREFIXES.some((p) => key.startsWith(p))) continue;
      out[key] = value;
    }
    return out;
  } catch {
    return {};
  }
}

/**
 * @param {unknown} value
 * @returns {value is Record<string, unknown>}
 */
function isPlainObject(value) {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/**
 * Reduces an administrator-provisioned Den control-plane URL to its exact
 * origin. Keep this in sync with apps/server/src/enterprise-den-origin.ts.
 *
 * @param {unknown} rawValue
 * @returns {string | null}
 */
function exactEnterpriseOrigin(rawValue) {
  if (typeof rawValue !== "string") return null;
  const raw = rawValue.trim();
  if (!raw || raw.length > 2 * 1024) return null;
  try {
    const url = new URL(raw);
    if (url.protocol !== "https:") return null;
    if (url.username || url.password || url.search || url.hash) return null;
    return url.origin;
  } catch {
    return null;
  }
}

/**
 * @param {string} filePath
 * @returns {Promise<string | null>}
 */
async function readActivatedEnterpriseOrigin(filePath) {
  if (typeof filePath !== "string" || !filePath.trim()) return null;
  try {
    const fileStat = await stat(filePath);
    if (!fileStat.isFile() || fileStat.size > MAX_BOOTSTRAP_BYTES) return null;
    const raw = await readFile(filePath, "utf8");
    if (Buffer.byteLength(raw, "utf8") > MAX_BOOTSTRAP_BYTES) return null;
    const data = JSON.parse(raw);
    if (!isPlainObject(data)) return null;
    const activation = isPlainObject(data.enterpriseActivation) ? data.enterpriseActivation : null;
    if (!activation) return null;
    if (typeof activation.activatedAt !== "string" || !activation.activatedAt.trim()) return null;
    return exactEnterpriseOrigin(activation.denBaseUrl);
  } catch {
    return null;
  }
}

/**
 * @param {Iterable<string>} values
 * @returns {string[]}
 */
function normalizeRepairOrigins(values) {
  const seen = new Set();
  const origins = [];
  for (const value of values) {
    const origin = exactEnterpriseOrigin(value);
    if (!origin || seen.has(origin)) continue;
    origins.push(origin);
    seen.add(origin);
    if (origins.length >= MAX_CHAIN_REPAIR_ORIGINS) break;
  }
  return origins;
}

/**
 * @param {string} origin
 * @returns {{ host: string, port: number }}
 */
function tlsTargetFromOrigin(origin) {
  const url = new URL(origin);
  return {
    host: url.hostname.replace(/^\[(.*)\]$/, "$1"),
    port: url.port ? Number(url.port) : 443,
  };
}

/**
 * @param {unknown} error
 * @returns {string}
 */
function errorCode(error) {
  return isPlainObject(error) && typeof error.code === "string" ? error.code : "unknown";
}

/**
 * @param {RuntimeChainRepairSocket} socket
 * @returns {void}
 */
function destroySocket(socket) {
  try {
    socket.destroy();
  } catch {
    // Best effort.
  }
}

/**
 * @typedef {Object} RuntimeSystemCaTlsModule
 * @property {(type?: string) => string[]} [getCACertificates]
 * @property {(certificates: string[]) => void} [setDefaultCACertificates]
 */

/**
 * @typedef {Object} RuntimeChainRepairFetchResponse
 * @property {boolean} [ok]
 * @property {number} [status]
 * @property {() => Promise<ArrayBuffer>} arrayBuffer
 */

/**
 * @typedef {Object} RuntimeChainRepairFetchOptions
 * @property {AbortSignal} [signal]
 */

/**
 * @typedef {(input: string, init?: RuntimeChainRepairFetchOptions) => Promise<RuntimeChainRepairFetchResponse>} RuntimeChainRepairFetch
 */

/**
 * @typedef {Object} RuntimeChainRepairTlsConnectOptions
 * @property {string} host
 * @property {number} port
 * @property {string} servername
 * @property {boolean} rejectUnauthorized
 * @property {number} timeout
 */

/**
 * @typedef {Object} RuntimeChainRepairPeerCertificate
 * @property {Buffer} [raw]
 * @property {RuntimeChainRepairPeerCertificate} [issuerCertificate]
 */

/**
 * @typedef {Object} RuntimeChainRepairSocket
 * @property {boolean} [authorized]
 * @property {unknown} [authorizationError]
 * @property {(eventName: string, listener: (...args: unknown[]) => void) => RuntimeChainRepairSocket} once
 * @property {(eventName: string, listener: (...args: unknown[]) => void) => RuntimeChainRepairSocket} off
 * @property {(timeout: number) => RuntimeChainRepairSocket} setTimeout
 * @property {() => void} destroy
 * @property {() => X509Certificate | undefined} [getPeerX509Certificate]
 * @property {(detailed?: boolean) => RuntimeChainRepairPeerCertificate | null} [getPeerCertificate]
 */

/**
 * @typedef {(options: RuntimeChainRepairTlsConnectOptions) => RuntimeChainRepairSocket} RuntimeChainRepairTlsConnect
 */

/**
 * @typedef {Object} RuntimeChainRepairOptions
 * @property {string[]} [origins]
 * @property {RuntimeChainRepairFetch} [fetchImpl]
 * @property {() => string[]} [rootsProvider]
 * @property {RuntimeChainRepairTlsConnect} [tlsConnectImpl]
 * @property {string} [bootstrapPath]
 * @property {boolean} [disabled]
 */

/**
 * @typedef {Object} ResolveSystemCaEnvOptions
 * @property {RuntimeSystemCaTlsModule} [tlsModule]
 * @property {string} userDataDir
 * @property {NodeJS.ProcessEnv} [parentEnv]
 * @property {(...args: unknown[]) => void} [logInfo]
 * @property {() => Promise<string[]>} [loadPlatformCertificates]
 * @property {string} [platformSourceName]
 * @property {NodeJS.Platform} [platform]
 * @property {RuntimeChainRepairOptions} [chainRepair]
 */

/**
 * @param {string} origin
 * @param {RuntimeChainRepairTlsConnect} tlsConnectImpl
 * @param {boolean} rejectUnauthorized
 * @returns {Promise<RuntimeChainRepairSocket>}
 */
function connectForChainRepair(origin, tlsConnectImpl, rejectUnauthorized) {
  const target = tlsTargetFromOrigin(origin);
  return new Promise((resolve, reject) => {
    let settled = false;
    let socket;
    const finish = (value, isError) => {
      if (settled) return;
      settled = true;
      if (socket) {
        socket.off("secureConnect", onSecureConnect);
        socket.off("error", onError);
        socket.off("timeout", onTimeout);
      }
      if (isError) reject(value);
      else resolve(value);
    };
    const onSecureConnect = () => finish(socket, false);
    const onError = (error) => {
      if (socket) destroySocket(socket);
      finish(error, true);
    };
    const onTimeout = () => {
      const error = new Error("TLS connection timed out");
      Object.defineProperty(error, "code", { value: "ETIMEDOUT" });
      if (socket) destroySocket(socket);
      finish(error, true);
    };

    try {
      socket = tlsConnectImpl({
        host: target.host,
        port: target.port,
        servername: target.host,
        rejectUnauthorized,
        timeout: CHAIN_REPAIR_SOCKET_TIMEOUT_MS,
      });
      socket.once("secureConnect", onSecureConnect);
      socket.once("error", onError);
      socket.once("timeout", onTimeout);
      socket.setTimeout(CHAIN_REPAIR_SOCKET_TIMEOUT_MS);
    } catch (error) {
      finish(error, true);
    }
  });
}

/**
 * @param {string} origin
 * @param {RuntimeChainRepairTlsConnect} tlsConnectImpl
 * @returns {Promise<string | null>}
 */
async function strictProbeChainRepair(origin, tlsConnectImpl) {
  let socket;
  try {
    socket = await connectForChainRepair(origin, tlsConnectImpl, true);
    return socket.authorized === true ? null : String(socket.authorizationError || "UNAUTHORIZED");
  } catch (error) {
    return errorCode(error);
  } finally {
    if (socket) destroySocket(socket);
  }
}

/**
 * @param {RuntimeChainRepairPeerCertificate | null} peer
 * @returns {boolean}
 */
function peerChainIsLeafOnly(peer) {
  if (!peer || typeof peer !== "object") return true;
  const issuer = peer.issuerCertificate;
  if (!issuer || issuer === peer) return true;
  if (peer.raw && issuer.raw && Buffer.compare(Buffer.from(peer.raw), Buffer.from(issuer.raw)) === 0) return true;
  return false;
}

/**
 * @param {string} origin
 * @param {RuntimeChainRepairTlsConnect} tlsConnectImpl
 * @returns {Promise<{ leaf: X509Certificate, leafOnly: boolean } | null>}
 */
async function introspectLeafCertificate(origin, tlsConnectImpl) {
  let socket;
  try {
    socket = await connectForChainRepair(origin, tlsConnectImpl, false);
    if (typeof socket.getPeerX509Certificate !== "function") return null;
    const leaf = socket.getPeerX509Certificate();
    if (!leaf) return null;
    const peer = typeof socket.getPeerCertificate === "function" ? socket.getPeerCertificate(true) : null;
    return { leaf, leafOnly: peerChainIsLeafOnly(peer) };
  } catch {
    return null;
  } finally {
    if (socket) destroySocket(socket);
  }
}

/**
 * @param {X509Certificate} certificate
 * @returns {string[]}
 */
function caIssuerUrls(certificate) {
  const urls = [];
  const infoAccess = typeof certificate.infoAccess === "string" ? certificate.infoAccess : "";
  for (const line of infoAccess.split(/\r?\n/)) {
    const match = /^\s*CA Issuers\s*-\s*URI:(.+?)\s*$/i.exec(line);
    if (!match) continue;
    try {
      const url = new URL(match[1].trim());
      if (url.protocol !== "http:" && url.protocol !== "https:") continue;
      urls.push(url.href);
      if (urls.length >= 2) break;
    } catch {
      // Ignore malformed AIA entries.
    }
  }
  return urls;
}

/**
 * @param {ArrayBuffer} bytes
 * @returns {X509Certificate}
 */
function certificateFromBody(bytes) {
  const buffer = Buffer.from(bytes);
  try {
    return new X509Certificate(buffer);
  } catch (bufferError) {
    const text = buffer.toString("utf8");
    if (/-----BEGIN CERTIFICATE-----/.test(text)) return new X509Certificate(text);
    throw bufferError;
  }
}

/**
 * @param {X509Certificate} certificate
 * @returns {string}
 */
function certificateCommonName(certificate) {
  for (const line of certificate.subject.split(/\r?\n/)) {
    const match = /^CN\s*=\s*(.+)$/.exec(line.trim());
    if (match) return match[1].trim();
  }
  return certificate.subject || "unknown subject";
}

/**
 * @param {string} pem
 * @returns {X509Certificate | null}
 */
function cachedRootCertificate(pem) {
  const key = String(pem ?? "").trim();
  if (!key) return null;
  if (chainRepairRootCache.has(key)) return chainRepairRootCache.get(key) ?? null;
  try {
    const certificate = new X509Certificate(key);
    chainRepairRootCache.set(key, certificate);
    return certificate;
  } catch {
    chainRepairRootCache.set(key, null);
    return null;
  }
}

/**
 * @param {X509Certificate} intermediate
 * @param {() => string[]} rootsProvider
 * @returns {boolean}
 */
function intermediateChainsToTrustedRoot(intermediate, rootsProvider) {
  let roots = [];
  try {
    roots = rootsProvider();
  } catch {
    roots = [];
  }
  for (const pem of roots) {
    const root = cachedRootCertificate(pem);
    if (root && intermediate.checkIssued(root) && intermediate.verify(root.publicKey)) return true;
  }
  return false;
}

/**
 * @param {X509Certificate} leaf
 * @param {X509Certificate} intermediate
 * @param {() => string[]} rootsProvider
 * @returns {string | null}
 */
function refusalReason(leaf, intermediate, rootsProvider) {
  if (intermediate.ca !== true) return "fetched certificate is not a CA";
  if (leaf.checkIssued(intermediate) !== true) return "fetched certificate did not issue leaf";
  if (leaf.verify(intermediate.publicKey) !== true) return "leaf signature verification failed";
  if (!intermediateChainsToTrustedRoot(intermediate, rootsProvider)) return "fetched certificate does not chain to a trusted public root";
  return null;
}

/**
 * @param {string} url
 * @param {RuntimeChainRepairFetch} fetchImpl
 * @returns {Promise<X509Certificate | null>}
 */
async function fetchIntermediateCertificate(url, fetchImpl) {
  const response = await fetchImpl(url, { signal: AbortSignal.timeout(CHAIN_REPAIR_FETCH_TIMEOUT_MS) });
  if (!response || typeof response.arrayBuffer !== "function") return null;
  if (response.ok === false) return null;
  const bytes = await response.arrayBuffer();
  if (bytes.byteLength > MAX_CHAIN_REPAIR_BODY_BYTES) return null;
  return certificateFromBody(bytes);
}

/**
 * @param {ResolveSystemCaEnvOptions} options
 * @returns {Promise<string[]>}
 */
async function resolveChainRepairOrigins(options) {
  const env = options.parentEnv ?? {};
  const chainRepair = options.chainRepair ?? {};
  if (chainRepair.origins) return normalizeRepairOrigins(chainRepair.origins);
  const envOrigins = typeof env.OMNIRUSH_CHAIN_REPAIR_ORIGINS === "string" ? env.OMNIRUSH_CHAIN_REPAIR_ORIGINS : "";
  if (envOrigins.trim()) return normalizeRepairOrigins(envOrigins.split(","));
  const bootstrapPath = chainRepair.bootstrapPath ?? desktopBootstrapPath({ env });
  const origin = await readActivatedEnterpriseOrigin(bootstrapPath);
  return origin ? [origin] : [];
}

/**
 * @param {ResolveSystemCaEnvOptions} options
 * @returns {Promise<{ pems: string[], timedOut: boolean }>}
 */
async function repairIncompleteChains(options) {
  const env = options.parentEnv ?? {};
  const chainRepair = options.chainRepair ?? {};
  const logInfo = options.logInfo;
  if (chainRepair.disabled === true || String(env.OMNIRUSH_DISABLE_CHAIN_REPAIR ?? "").trim() === "1") {
    if (typeof logInfo === "function") logInfo("OmniRush.ai runtime: chain repair disabled by OMNIRUSH_DISABLE_CHAIN_REPAIR.");
    return { pems: [], timedOut: false };
  }

  const origins = await resolveChainRepairOrigins(options);
  if (origins.length === 0) {
    if (!chainRepair.origins && !String(env.OMNIRUSH_CHAIN_REPAIR_ORIGINS ?? "").trim() && typeof logInfo === "function") {
      logInfo("OmniRush.ai runtime: chain repair skipped: no activation record.");
    }
    return { pems: [], timedOut: false };
  }

  const fetchImpl = chainRepair.fetchImpl ?? globalThis.fetch;
  const tlsModule = options.tlsModule ?? tls;
  const tlsConnectImpl = chainRepair.tlsConnectImpl ?? tls.connect;
  const totalTimeoutValue = Number(env.OMNIRUSH_CHAIN_REPAIR_TIMEOUT_MS);
  const totalTimeoutMs =
    Number.isFinite(totalTimeoutValue) && totalTimeoutValue >= 1000 && totalTimeoutValue <= 120000
      ? totalTimeoutValue
      : CHAIN_REPAIR_TOTAL_TIMEOUT_MS;
  const rootsProvider = chainRepair.rootsProvider ?? (() => {
    if (typeof tlsModule?.getCACertificates !== "function") return [];
    const roots = tlsModule.getCACertificates("default");
    return Array.isArray(roots) ? roots : [];
  });

  if (typeof fetchImpl !== "function") {
    if (typeof logInfo === "function") {
      for (const origin of origins) logInfo(`OmniRush.ai runtime: chain repair skipped for ${origin}: fetch unavailable`);
    }
    return { pems: [], timedOut: false };
  }

  const run = async () => {
    const pems = [];
    for (const origin of origins) {
      const strictError = await strictProbeChainRepair(origin, tlsConnectImpl);
      if (strictError === null) {
        if (typeof logInfo === "function") logInfo(`OmniRush.ai runtime: chain ok for ${origin}`);
        continue;
      }
      if (strictError !== "UNABLE_TO_VERIFY_LEAF_SIGNATURE") {
        if (typeof logInfo === "function") logInfo(`OmniRush.ai runtime: chain repair skipped for ${origin}: ${strictError}`);
        continue;
      }

      const leafState = await introspectLeafCertificate(origin, tlsConnectImpl);
      if (!leafState) {
        if (typeof logInfo === "function") logInfo(`OmniRush.ai runtime: chain repair skipped for ${origin}: certificate introspection failed`);
        continue;
      }
      if (!leafState.leafOnly) {
        if (typeof logInfo === "function") logInfo(`OmniRush.ai runtime: chain repair skipped for ${origin}: served chain includes an intermediate`);
        continue;
      }

      const issuerUrls = caIssuerUrls(leafState.leaf);
      if (issuerUrls.length === 0) {
        if (typeof logInfo === "function") logInfo(`OmniRush.ai runtime: chain repair skipped for ${origin}: no CA Issuers AIA URL`);
        continue;
      }

      let repaired = false;
      for (const url of issuerUrls) {
        let intermediate;
        try {
          intermediate = await fetchIntermediateCertificate(url, fetchImpl);
        } catch {
          intermediate = null;
        }
        if (!intermediate) continue;
        const reason = refusalReason(leafState.leaf, intermediate, rootsProvider);
        if (reason) {
          if (typeof logInfo === "function") logInfo(`OmniRush.ai runtime: chain repair refused for ${origin}: ${reason}`);
          continue;
        }
        pems.push(intermediate.toString());
        repaired = true;
        if (typeof logInfo === "function") {
          logInfo(`OmniRush.ai runtime: chain repaired for ${origin}: added "${certificateCommonName(intermediate)}"`);
        }
        break;
      }
      if (!repaired && typeof logInfo === "function") {
        logInfo(`OmniRush.ai runtime: chain repair skipped for ${origin}: no usable AIA issuer certificate`);
      }
    }
    return { pems, timedOut: false };
  };

  let timeoutId;
  const timeout = new Promise((resolve) => {
    timeoutId = setTimeout(() => resolve({ pems: [], timedOut: true }), totalTimeoutMs);
    timeoutId.unref?.();
  });
  try {
    return await Promise.race([run(), timeout]);
  } finally {
    clearTimeout(timeoutId);
  }
}

const CONFIGURED_EXTRA_CA_MESSAGE = "OmniRush.ai runtime: NODE_EXTRA_CA_CERTS is already set; child processes get it merged with the OS trust store.";
const UNREADABLE_EXTRA_CA_MESSAGE = "OmniRush.ai runtime: NODE_EXTRA_CA_CERTS is set but unreadable; child processes keep it as is.";

/**
 * @param {ResolveSystemCaEnvOptions} options
 * @returns {Promise<{ childEnv: NodeJS.ProcessEnv, trustedCertificates: string[], mergedFrom: string | null }>}
 */
async function resolveSystemCa({
  tlsModule = tls,
  userDataDir,
  parentEnv = process.env,
  logInfo = console.info,
  loadPlatformCertificates,
  platformSourceName,
  platform = process.platform,
  chainRepair,
}) {
  const env = parentEnv ?? {};
  const info = (message) => {
    if (typeof logInfo === "function") logInfo(message);
  };
  // A user-set NODE_EXTRA_CA_CERTS is kept: child processes get its
  // certificates merged with the OS trust store, and this process adds both.
  const configuredPath = Object.prototype.hasOwnProperty.call(env, "NODE_EXTRA_CA_CERTS")
    ? String(env.NODE_EXTRA_CA_CERTS)
    : null;
  /** @type {string[]} */
  let configuredCertificates = [];
  let configuredReadable = false;
  if (configuredPath !== null) {
    try {
      configuredCertificates = parsePemCertificates(await readFile(configuredPath, "utf8"));
      configuredReadable = true;
    } catch {
      configuredCertificates = [];
    }
  }
  const mergedFrom = configuredReadable ? configuredPath : null;

  try {
    const platformLoader = loadPlatformCertificates
      ? { name: platformSourceName || "platform-stores", load: loadPlatformCertificates }
      : systemPlatformCertificateLoader(platform);
    const bundle = await resolveSystemCaBundle({
      runtime: () => {
        if (typeof tlsModule?.getCACertificates !== "function") return [];
        const certs = tlsModule.getCACertificates("system");
        return Array.isArray(certs) ? certs : [];
      },
      platform: platformLoader,
    });
    info(`OmniRush.ai runtime: system CA bundle sources ${summarizeSystemCaSources(bundle.sources)}`);
    const trustedCertificates = dedupeCertificates([...configuredCertificates, ...bundle.certificates]);
    let repairedPems = [];
    try {
      // Chain repair stays off when the user manages NODE_EXTRA_CA_CERTS.
      const repaired = configuredPath !== null ? { pems: [], timedOut: false } : await repairIncompleteChains({
        tlsModule,
        userDataDir,
        parentEnv: env,
        logInfo,
        loadPlatformCertificates,
        platformSourceName,
        platform,
        chainRepair,
      });
      repairedPems = repaired.pems;
      if (repaired.timedOut) info("OmniRush.ai runtime: chain repair skipped: timed out");
    } catch {
      repairedPems = [];
    }
    const certificates = dedupeCertificates([...trustedCertificates, ...repairedPems]);
    if (certificates.length === 0) return { childEnv: {}, trustedCertificates, mergedFrom: null };

    const trust = extendDefaultCaCertificates(tlsModule, certificates);
    if (trust.applied) {
      info(`OmniRush.ai runtime: main-process TLS trusts ${trust.certificates.length} OS certificates${trust.rejected ? ` (skipped ${trust.rejected} the TLS library cannot parse)` : ""}`);
    } else if (typeof tlsModule?.setDefaultCACertificates === "function") {
      info(`OmniRush.ai runtime: main-process TLS trust unchanged: ${trust.error ?? "unknown error"}`);
    }
    if (configuredPath !== null && !configuredReadable) {
      info(UNREADABLE_EXTRA_CA_MESSAGE);
      return { childEnv: {}, trustedCertificates, mergedFrom: null };
    }
    if (configuredPath !== null) info(CONFIGURED_EXTRA_CA_MESSAGE);

    // Child processes (Node, and Bun, which honors NODE_EXTRA_CA_CERTS too)
    // get the certificates as a PEM file, including a user-set
    // NODE_EXTRA_CA_CERTS file's. Unparsable entries are left out: a single
    // bad certificate makes Node and Bun ignore the whole file.
    const pem = trust.certificates.join("\n");
    if (!pem) return { childEnv: {}, trustedCertificates, mergedFrom: null };
    const bundlePath = path.join(userDataDir, "system-ca-bundle.pem");
    await mkdir(path.dirname(bundlePath), { recursive: true });
    await writeFile(bundlePath, `${pem}\n`, "utf8");
    return {
      childEnv: { NODE_EXTRA_CA_CERTS: bundlePath },
      trustedCertificates,
      mergedFrom,
    };
  } catch {
    return { childEnv: {}, trustedCertificates: configuredCertificates, mergedFrom: null };
  }
}

export async function resolveSystemCaEnv(options) {
  return (await resolveSystemCa(options)).childEnv;
}

/**
 * @param {NodeJS.ProcessEnv} [baseEnv]
 * @param {NodeJS.ProcessEnv} [caEnv]
 * @param {NodeJS.ProcessEnv} [extra]
 * @param {string | null} [mergedFrom] the user-set NODE_EXTRA_CA_CERTS the generated bundle includes
 * @returns {NodeJS.ProcessEnv}
 */
export function mergeSystemCaChildEnv(baseEnv = {}, caEnv = {}, extra = {}, mergedFrom = null) {
  // The generated bundle replaces a user-set NODE_EXTRA_CA_CERTS only when it
  // was built from that same file (a superset of it). A value that changed
  // since startup, or one the bundle does not include, is kept.
  const userSet = Object.prototype.hasOwnProperty.call(baseEnv, "NODE_EXTRA_CA_CERTS");
  return {
    ...baseEnv,
    ...(!userSet || (mergedFrom !== null && String(baseEnv.NODE_EXTRA_CA_CERTS) === mergedFrom) ? caEnv : {}),
    ...extra,
  };
}

export function createRuntimeManager({
  app,
  desktopRoot,
  listLocalWorkspacePaths,
  localManagedMcpVaultKey,
  omnirushGatewayCredentials = null,
  appVersion = null,
  omnirushUiMcpLaunch = () => null,
  workspaceMkdir = mkdir,
  workspacePlatform = process.platform,
  // Chromium-backed fetch for requests off the machine (see external-fetch.mjs).
  externalFetch = null,
  captureFileUpload = null,
  // Hears the gateway's mandatory-update header and 426 refusals (update-gate.mjs).
  onUpdateSignal = null,
  // Hears when the agent starts and stops working (keep-awake.mjs).
  onTurnActivity = null,
}) {
  const inheritedProcessEnv = { ...process.env };
  let injectedUserEnvKeys = new Set();
  const engineState = createEngineState();
  const omnirushServerState = createOmniRushServerState();
  // Monotonic across this Electron process. Never reset with the server
  // state: each successful server start must be observable as a new
  // generation even when ports and tokens are reused.
  let omnirushServerGenerationCounter = 0;

  // Serialize engine lifecycle operations. Without this, concurrent renderer
  // invocations of engineStart/engineStop/engineRestart race: each call's
  // stopAllRuntimeChildren kills the previous call's freshly-started server,
  // and the prior call then times out its /health probe.
  /** @type {Promise<unknown>} */
  let runtimeLifecycleQueue = Promise.resolve();
  let lifecycleState = "idle";
  /**
   * Serialize engine lifecycle operations; preserves the wrapped function's
   * return type (untyped, this collapsed runtime-manager inference to
   * Promise<void> and blocked tightening the DesktopCommandMap results).
   * @template T
   * @param {() => Promise<T>} fn
   * @returns {Promise<T>}
   */
  function withRuntimeLifecycle(fn) {
    const next = runtimeLifecycleQueue.then(fn, fn);
    runtimeLifecycleQueue = next.catch(() => {});
    return next;
  }

  const userDataDir = app.getPath("userData");
  const sidecarDirs = [
    path.join(desktopRoot, "resources", "sidecars"),
    process.resourcesPath ? path.join(process.resourcesPath, "sidecars") : null,
    path.join(path.dirname(app.getPath("exe")), "sidecars"),
  ].filter(Boolean);
  let systemCaPromise = null;

  function systemCa() {
    systemCaPromise ??= resolveSystemCa({
      tlsModule: tls,
      userDataDir,
      parentEnv: { ...loadUserEnvFile(process.env), ...process.env },
      // AIA intermediate downloads for chain repair.
      chainRepair: typeof externalFetch === "function" ? { fetchImpl: externalFetch } : undefined,
    });
    return systemCaPromise;
  }

  function omnirushServerTokenStorePath() {
    const override = process.env.OMNIRUSH_SERVER_TOKEN_STORE_PATH?.trim();
    if (override) return path.resolve(override);
    return path.join(userDataDir, "omnirush-server-tokens.json");
  }

  function omnirushServerStatePath() {
    const override = process.env.OMNIRUSH_SERVER_STATE_PATH?.trim();
    if (override) return path.resolve(override);
    return path.join(userDataDir, "omnirush-server-state.json");
  }

  function managedOpencodeWorkdir() {
    return path.join(userDataDir, "managed-opencode-workdir");
  }

  async function loadTokenStore() {
    const stored = await readJsonFile(omnirushServerTokenStorePath(), { version: 1, workspaces: {} });
    const migrated = migrateOmniRushServerTokenStore(stored);
    if (JSON.stringify(stored) !== JSON.stringify(migrated)) {
      await saveTokenStore(migrated);
    }
    return migrated;
  }

  async function saveTokenStore(store) {
    const filePath = omnirushServerTokenStorePath();
    await mkdir(path.dirname(filePath), { recursive: true });
    // Server owner/client tokens: owner-only, including files older builds wrote 0644.
    await writeFile(filePath, `${JSON.stringify(store, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
    await chmod(filePath, 0o600);
  }

  async function loadPortState() {
    return readJsonFile(omnirushServerStatePath(), {
      version: 4,
      workspacePorts: {},
      preferredPort: null,
    });
  }

  async function savePortState(state) {
    const filePath = omnirushServerStatePath();
    await mkdir(path.dirname(filePath), { recursive: true });
    await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
  }

  async function loadServerCredentials() {
    const store = await loadTokenStore();
    return store.credentials;
  }

  async function persistServerOwnerToken(ownerToken) {
    const store = await loadTokenStore();
    store.credentials.ownerToken = ownerToken;
    store.credentials.updatedAt = nowMs();
    await saveTokenStore(store);
  }

  async function readPreferredOmniRushPort(workspaceKey) {
    const state = await loadPortState();
    const normalized = normalizeWorkspaceKey(workspaceKey, workspacePlatform);
    if (normalized && state.workspacePorts?.[normalized]) {
      return state.workspacePorts[normalized];
    }
    return state.preferredPort ?? null;
  }

  async function persistPreferredOmniRushPort(workspaceKey, port) {
    const state = await loadPortState();
    const normalized = normalizeWorkspaceKey(workspaceKey, workspacePlatform);
    state.version = 4;
    state.workspacePorts ??= {};
    if (normalized) {
      state.workspacePorts[normalized] = port;
      state.preferredPort = null;
    } else {
      state.preferredPort = port;
    }
    await savePortState(state);
  }

  async function waitForPortAvailable(host, port, timeoutMs = 2000) {
    const deadline = Date.now() + timeoutMs;
    while (Date.now() < deadline) {
      if (await portAvailable(host, port)) return true;
      await new Promise((resolve) => setTimeout(resolve, 100));
    }
    return portAvailable(host, port);
  }

  async function resolveOmniRushPort(host, workspaceKey, currentPort = null) {
    const preferredPort = await readPreferredOmniRushPort(workspaceKey);
    if (currentPort && (await waitForPortAvailable(host, currentPort))) {
      return { port: currentPort, preferredPort };
    }
    if (preferredPort && (await waitForPortAvailable(host, preferredPort))) {
      return { port: preferredPort, preferredPort };
    }
    return { port: await findFreePort(host), preferredPort };
  }

  async function ensureDevModePaths() {
    const root = path.join(userDataDir, "omnirush-dev-data");
    const paths = {
      homeDir: path.join(root, "home"),
      xdgConfigHome: path.join(root, "xdg", "config"),
      xdgDataHome: path.join(root, "xdg", "data"),
      xdgCacheHome: path.join(root, "xdg", "cache"),
      xdgStateHome: path.join(root, "xdg", "state"),
      opencodeConfigDir: path.join(root, "config", "opencode"),
    };

    for (const dir of Object.values(paths)) {
      await mkdir(dir, { recursive: true });
    }
    await mkdir(path.join(paths.xdgDataHome, "opencode"), { recursive: true });
    return paths;
  }

  async function buildChildEnv(extra = {}) {
    /** @type {NodeJS.ProcessEnv} */
    // User env is layered first so process.env + any caller overrides always
    // win. See apps/server/src/env-file.ts — all loaders must agree on path +
    // reserved-keys policy.
    const devPaths = process.env.OMNIRUSH_DEV_MODE === "1" && process.env.OMNIRUSH_DEV_SHARED_STATE !== "1"
      ? await ensureDevModePaths()
      : null;
    const userEnvPathEnv = devPaths
      ? {
          ...process.env,
          HOME: devPaths.homeDir,
          USERPROFILE: devPaths.homeDir,
          XDG_CONFIG_HOME: devPaths.xdgConfigHome,
        }
      : process.env;
    const userEnv = loadUserEnvFile(userEnvPathEnv);
    injectedUserEnvKeys = reconcileInjectedUserEnv({
      processEnv: process.env,
      inheritedEnv: inheritedProcessEnv,
      userEnv,
      previouslyInjectedKeys: injectedUserEnvKeys,
    });
    const baseEnv = {
      ...userEnv,
      ...process.env,
      BUN_CONFIG_DNS_RESULT_ORDER: "verbatim",
    };
    const { childEnv: caEnv, mergedFrom } = await systemCa();
    // Bun honors Node's NODE_EXTRA_CA_CERTS, so bundled Bun sidecars inherit
    // the exported OS trust store through the same child env variable.
    const env = mergeSystemCaChildEnv(baseEnv, caEnv, extra, mergedFrom);
    const pathKey =
      Object.prototype.hasOwnProperty.call(env, "PATH") ||
      !Object.prototype.hasOwnProperty.call(env, "Path")
        ? "PATH"
        : "Path";
    // Stock mode (OMNIRUSH_FARM): the agent's shell gets the launch PATH and CA file back (server stock-mode.mjs).
    env.OMNIRUSH_STOCK_SHELL_ENV = JSON.stringify({
      PATH: launchShellPath(inheritedProcessEnv[pathKey]),
      NODE_EXTRA_CA_CERTS: inheritedProcessEnv.NODE_EXTRA_CA_CERTS,
    });
    const pathEnv = enrichedPath(sidecarDirs, env[pathKey]);
    if (pathEnv) {
      env[pathKey] = pathEnv;
    }
    if (devPaths) {
      env.OMNIRUSH_DEV_MODE = "1";
      env.HOME = devPaths.homeDir;
      env.USERPROFILE = devPaths.homeDir;
      env.XDG_CONFIG_HOME = devPaths.xdgConfigHome;
      env.XDG_DATA_HOME = devPaths.xdgDataHome;
      env.XDG_CACHE_HOME = devPaths.xdgCacheHome;
      env.XDG_STATE_HOME = devPaths.xdgStateHome;
      env.OPENCODE_CONFIG_DIR = devPaths.opencodeConfigDir;
      env.OPENCODE_TEST_HOME = devPaths.homeDir;
    }
    return env;
  }

  function resolveBinaryInfo(baseName, extraPaths = []) {
    for (const directory of [...sidecarDirs, ...extraPaths]) {
      for (const fileName of binaryFileNames(baseName)) {
        const candidate = path.join(directory, fileName);
        if (existsSync(candidate)) {
          return { path: candidate, source: "bundled" };
        }
      }
    }

    const pathEntries = (enrichedPath([], process.env.PATH) ?? "")
      .split(path.delimiter)
      .filter(Boolean);
    for (const entry of pathEntries) {
      for (const fileName of binaryFileNames(baseName)) {
        const candidate = path.join(entry, fileName);
        if (existsSync(candidate)) {
          return { path: candidate, source: "path" };
        }
      }
    }

    if (baseName === "opencode") {
      for (const candidate of [
        path.join(app.getPath("home"), ".opencode", "bin", process.platform === "win32" ? "opencode.exe" : "opencode"),
        path.join("/opt/homebrew/bin", process.platform === "win32" ? "opencode.exe" : "opencode"),
        path.join("/usr/local/bin", process.platform === "win32" ? "opencode.exe" : "opencode"),
        path.join("/usr/bin", process.platform === "win32" ? "opencode.exe" : "opencode"),
      ]) {
        if (existsSync(candidate)) {
          return { path: candidate, source: "known-location" };
        }
      }
    }

    return null;
  }

  function resolveBinary(baseName, extraPaths = []) {
    return resolveBinaryInfo(baseName, extraPaths)?.path ?? null;
  }

  function resolveOpencodeBinary(opencodeBinPath) {
    // A release build runs only the engine it bundles, checked by its sha256: no
    // custom path, no PATH or known-location lookup (build-variant.mjs). Throws.
    if (isReleaseBuild()) return releaseEngineBinary({ fileNames: binaryFileNames("opencode") });
    const explicitPath = typeof opencodeBinPath === "string" ? opencodeBinPath.trim() : "";
    return explicitPath ? { path: explicitPath, source: "custom" } : resolveBinaryInfo("opencode");
  }

  function resolveDockerCandidates() {
    const candidates = [];
    const seen = new Set();

    for (const key of ["OMNIRUSH_DOCKER_BIN", "OPENWRK_DOCKER_BIN", "DOCKER_BIN"]) {
      const value = process.env[key]?.trim();
      if (value && !seen.has(value)) {
        seen.add(value);
        candidates.push(value);
      }
    }

    for (const entry of (process.env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
      const candidate = path.join(entry, process.platform === "win32" ? "docker.exe" : "docker");
      if (!seen.has(candidate)) {
        seen.add(candidate);
        candidates.push(candidate);
      }
    }

    for (const candidate of [
      "/opt/homebrew/bin/docker",
      "/usr/local/bin/docker",
      "/Applications/Docker.app/Contents/Resources/bin/docker",
    ]) {
      if (!seen.has(candidate)) {
        seen.add(candidate);
        candidates.push(candidate);
      }
    }

    return candidates.filter((candidate) => existsSync(candidate));
  }

  function runDockerCommandDetailed(args, timeoutMs = 8000) {
    const tried = [...resolveDockerCandidates(), process.platform === "win32" ? "docker.exe" : "docker"];
    const errors = [];

    for (const program of tried) {
      try {
        const result = spawnSync(program, args, {
          encoding: "utf8",
          timeout: timeoutMs,
          windowsHide: true,
        });
        return {
          program,
          status: typeof result.status === "number" ? result.status : -1,
          stdout: result.stdout ?? "",
          stderr: result.stderr ?? "",
        };
      } catch (error) {
        errors.push(error instanceof Error ? error.message : String(error));
      }
    }

    throw new Error(
      `Failed to run docker: ${errors.join("; ")} (Set OMNIRUSH_DOCKER_BIN to your docker binary if needed)`,
    );
  }

  const legacyOmniRushContainerPrefix = `${["omnirush", "orchestrator"].join("-")}-`;

  async function listOmniRushManagedContainers() {
    const result = runDockerCommandDetailed(["ps", "-a", "--format", "{{.Names}}"], 8000);
    if (result.status !== 0) {
      const combined = `${result.stdout.trim()}\n${result.stderr.trim()}`.trim();
      throw new Error(combined || `docker ps -a failed (status ${result.status})`);
    }
    return result.stdout
      .split(/\r?\n/)
      .map((line) => line.trim())
      .filter((name) => name && (name.startsWith(legacyOmniRushContainerPrefix) || name.startsWith("omnirush-dev-") || name.startsWith("openwrk-")))
      .sort();
  }

  async function runShellCommand(program, args, options = {}) {
    const result = spawnSync(program, args, {
      encoding: "utf8",
      cwd: options.cwd,
      env: options.env,
      shell: false,
      windowsHide: true,
      timeout: options.timeoutMs,
    });
    return {
      status: typeof result.status === "number" ? result.status : -1,
      stdout: result.stdout ?? "",
      stderr: result.stderr ?? "",
    };
  }

  function engineDoctor(options = {}) {
    let resolved = null;
    let refused = null;
    try {
      resolved = resolveOpencodeBinary(options?.opencodeBinPath);
    } catch (error) {
      refused = error instanceof Error ? error.message : String(error);
    }
    if (!resolved?.path) {
      return {
        found: false,
        inPath: false,
        resolvedPath: null,
        resolvedSource: null,
        version: null,
        supportsServe: false,
        notes: [refused ?? "OmniRush binary not found in bundled sidecars or PATH."],
        serveHelpStatus: null,
        serveHelpStdout: null,
        serveHelpStderr: null,
      };
    }

    const versionResult = spawnSync(resolved.path, ["--version"], { encoding: "utf8" });
    const helpResult = spawnSync(resolved.path, ["serve", "--help"], { encoding: "utf8" });
    const notes = [`Using ${resolved.source}: ${resolved.path}`];
    if (versionResult.status !== 0) {
      notes.push("OmniRush version probe failed.");
    }
    if (helpResult.status !== 0) {
      notes.push("OmniRush serve --help probe failed.");
    }

    return {
      found: true,
      inPath: resolved.source === "path",
      resolvedPath: resolved.path,
      resolvedSource: resolved.source,
      version: versionResult.stdout?.trim() || versionResult.stderr?.trim() || null,
      supportsServe: helpResult.status === 0,
      notes,
      serveHelpStatus: typeof helpResult.status === "number" ? helpResult.status : null,
      serveHelpStdout: helpResult.stdout?.trim() || null,
      serveHelpStderr: helpResult.stderr?.trim() || null,
    };
  }

  function processMatchesSidecar(command) {
    return commandMatchesPackagedSidecar(command, sidecarDirs);
  }

  function killProcessId(pid, signal = "SIGTERM") {
    if (!Number.isFinite(pid) || pid <= 0 || pid === process.pid) return;
    try {
      process.kill(pid, signal);
    } catch {
      // Process already exited or is not ours.
    }
  }

  async function cleanupPackagedSidecars() {
    if (!app.isPackaged) return;

    // Safety net: an unclean Electron quit can orphan sidecars. Packaged builds
    // should always own a fresh runtime per app launch, so remove any leftover
    // sidecars from this app bundle before choosing ports for the new runtime.
    const result = spawnSync("ps", ["-Ao", "pid=,command="], { encoding: "utf8" });
    const rows = String(result.stdout ?? "").split(/\r?\n/);
    const pids = [];
    for (const row of rows) {
      const match = row.match(/^\s*(\d+)\s+(.+)$/);
      if (!match) continue;
      const pid = Number(match[1]);
      const command = match[2] ?? "";
      if (processMatchesSidecar(command)) pids.push(pid);
    }
    for (const pid of pids) killProcessId(pid, "SIGTERM");
    if (pids.length > 0) {
      await new Promise((resolve) => setTimeout(resolve, 500));
      for (const pid of pids) killProcessId(pid, "SIGKILL");
    }
  }

  async function stopChild(state, options = {}) {
    const child = state.child;
    state.child = null;
    state.childExited = true;
    if (!child || child.exitCode != null || child.killed) return;

    if (options.requestShutdown) {
      try {
        const shutdownRequested = await options.requestShutdown();
        if (shutdownRequested) {
          await new Promise((resolve) => setTimeout(resolve, 750));
        }
      } catch {
        // ignore
      }
    }

    if (child.exitCode == null && !child.killed) {
      child.kill("SIGTERM");
      await new Promise((resolve) => setTimeout(resolve, 500));
      if (child.exitCode == null && !child.killed) {
        child.kill("SIGKILL");
      }
    }
  }

  async function issueOwnerToken(baseUrl, hostToken) {
    const payload = await fetchJson(
      `${baseUrl.replace(/\/+$/, "")}/tokens`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-OmniRush-Host-Token": hostToken,
        },
        body: JSON.stringify({ scope: "owner", label: "OmniRush.ai desktop owner token" }),
      },
      5000,
    );
    const token = typeof payload?.token === "string" ? payload.token.trim() : "";
    return token || null;
  }

  // In-process server handle. Kept alive across restarts so we can stop it.
  let inProcessServer = null;

  // ── Restart guard ───────────────────────────────────────────────────────
  // Stopping the running server ends every live run (the session uploader closes
  // each session and the engine is killed). Automatic triggers therefore never
  // stop a healthy server that still has running sessions: the request waits
  // until the engine is idle. Every stop is recorded with its reason.
  const DEFERRED_RESTART_POLL_MS = 15_000;
  let pendingRestart = null;
  let pendingRestartTimer = null;
  let pendingRestartChecking = false;
  let nextStartReason = null;

  function restartLogFile() {
    return omnirushServerState.logFilePath ?? resolveOmniRushServerLogFile(userDataDir);
  }

  function recordRestart(record) {
    appendRuntimeRestartRecord({
      serverLogFile: restartLogFile(),
      record: { kind: "server", generation: omnirushServerState.generation ?? null, ...record },
    });
  }

  function restartRequest(options, fallbackSource) {
    const reason = typeof options?.reason === "string" && options.reason.trim() ? options.reason.trim() : "unspecified";
    const source = typeof options?.source === "string" && options.source.trim() ? options.source.trim() : fallbackSource;
    return { reason, source, userInitiated: options?.userInitiated === true };
  }

  async function probeRunningServer() {
    const baseUrl = omnirushServerState.baseUrl;
    if (!inProcessServer || !baseUrl) return { running: false, healthy: false };
    for (let attempt = 0; attempt < 2; attempt += 1) {
      try {
        await fetchJson(`${baseUrl.replace(/\/+$/, "")}/health`, {}, 5000);
        return { running: true, healthy: true };
      } catch {
        // One retry: a single slow answer is not a dead server.
      }
    }
    return { running: true, healthy: false };
  }

  async function readBusySessions() {
    const server = inProcessServer;
    if (typeof server?.busySessions !== "function") return { sessions: 0, unknown: 1 };
    let timer = null;
    try {
      const result = await Promise.race([
        server.busySessions(),
        new Promise((_, reject) => {
          timer = setTimeout(() => reject(new Error("busy session probe timed out")), 8000);
        }),
      ]);
      return { sessions: result.sessions.length, unknown: result.unknown };
    } catch {
      return { sessions: 0, unknown: 1 };
    } finally {
      if (timer) clearTimeout(timer);
    }
  }

  /**
   * Returns { verdict, why, reason, source, userInitiated, busy }. Callers stop
   * the server only on "proceed"; "defer" queues the request until idle and
   * "skip" keeps the healthy server.
   */
  async function guardRestart(action, options, fallbackSource, extra = {}) {
    const request = restartRequest(options, fallbackSource);
    const probe = await probeRunningServer();
    const busy = probe.running && probe.healthy ? await readBusySessions() : { sessions: 0, unknown: 0 };
    const decision = decideRuntimeRestart({
      action,
      userInitiated: request.userInitiated,
      serverRunning: probe.running,
      serverHealthy: probe.healthy,
      busy,
      sameSettings: extra.sameSettings,
    });
    const result = { ...decision, ...request, busy };
    if (decision.verdict === "proceed") {
      if (probe.running) {
        recordRestart({
          action: "restarting",
          reason: request.reason,
          source: request.source,
          trigger: action,
          why: decision.why,
          busySessions: busy.sessions,
          busyUnknown: busy.unknown,
        });
      }
      if (request.userInitiated) clearPendingRestart();
      nextStartReason = request.reason;
    } else {
      recordRestart({
        action: decision.verdict === "defer" ? "deferred" : "skipped",
        reason: request.reason,
        source: request.source,
        trigger: action,
        why: decision.why,
        busySessions: busy.sessions,
        busyUnknown: busy.unknown,
      });
      if (decision.verdict === "defer") queuePendingRestart(action, options, request);
    }
    return result;
  }

  function clearPendingRestart() {
    pendingRestart = null;
    if (pendingRestartTimer) clearInterval(pendingRestartTimer);
    pendingRestartTimer = null;
  }

  function queuePendingRestart(action, options, request) {
    pendingRestart = {
      action,
      options: { ...(options ?? {}) },
      reason: request.reason,
      source: request.source,
      requestedAt: pendingRestart?.requestedAt ?? Date.now(),
    };
    if (pendingRestartTimer) return;
    pendingRestartTimer = setInterval(() => void runPendingRestartIfIdle(), DEFERRED_RESTART_POLL_MS);
    pendingRestartTimer.unref?.();
  }

  async function runPendingRestartIfIdle() {
    const pending = pendingRestart;
    if (!pending || pendingRestartChecking) return;
    pendingRestartChecking = true;
    try {
      const probe = await probeRunningServer();
      const busy = probe.running && probe.healthy ? await readBusySessions() : { sessions: 0, unknown: 0 };
      const verdict = decideDeferredRestart({
        serverRunning: probe.running,
        serverHealthy: probe.healthy,
        busy,
        deferredForMs: Date.now() - pending.requestedAt,
      });
      if (verdict === "wait" || pendingRestart !== pending) return;
      clearPendingRestart();
      if (verdict === "drop") {
        recordRestart({ action: "dropped", reason: pending.reason, source: pending.source, trigger: pending.action });
        return;
      }
      const options = {
        ...pending.options,
        reason: `${pending.reason} (deferred until idle)`,
        source: pending.source,
        deferredRun: true,
      };
      await (pending.action === "engine-restart"
        ? withRuntimeLifecycle(() => engineRestart(options))
        : withRuntimeLifecycle(() => omnirushServerRestart(options))
      ).catch((error) => {
        appendOutput(omnirushServerState, "lastStderr", `Deferred restart failed: ${error instanceof Error ? error.message : String(error)}\n`);
      });
    } finally {
      pendingRestartChecking = false;
    }
  }

  function pendingRestartSummary() {
    return pendingRestart
      ? {
          action: pendingRestart.action,
          reason: pendingRestart.reason,
          source: pendingRestart.source,
          requestedAt: new Date(pendingRestart.requestedAt).toISOString(),
        }
      : null;
  }

  /** Record a stop that is not a restart request (quit, stop, fresh runtime). */
  function recordStop(options, fallbackSource) {
    if (!inProcessServer) return;
    const request = restartRequest(options, fallbackSource);
    recordRestart({ action: "stopping", reason: request.reason, source: request.source });
  }

  async function startOmniRushServer(options) {
    // The inner start stops any previous runtime before mutating state, so a
    // throw below always happens with nothing left running.
    try {
      return await startOmniRushServerInner(options);
    } catch (error) {
      resetRuntimeStatesAfterFailedServerStart(omnirushServerState, engineState, options);
      throw error;
    }
  }

  async function startOmniRushServerInner(options) {
    const evalDelayMs = resolveEvalLocalServerDelayMs();
    if (evalDelayMs > 0) {
      await new Promise((resolve) => setTimeout(resolve, evalDelayMs));
    }
    const currentPort = omnirushServerState.port;
    // Stop any previously running in-process server
    if (inProcessServer) {
      try { await inProcessServer.stop(); } catch { /* ignore */ }
      inProcessServer = null;
    }
    await stopChild(omnirushServerState);

    const host = options.remoteAccessEnabled ? "0.0.0.0" : "127.0.0.1";

    // The 1.x engine runs only where it still ships (every chat runs on the 2.x engine below).
    const v1Bundled = Boolean(options.opencodeBinPath?.trim())
      || sidecarDirs.some((directory) => binaryFileNames("opencode").some((name) => existsSync(path.join(directory, name))));
    const managedOpencode = options.manageOpencode && v1Bundled ? resolveOpencodeBinary(options.opencodeBinPath) : null;
    // The 2.x engine every new chat runs on (engine-v2-preview.ts reads it): a release
    // runs only its bundled, hash-checked copy; a dev build may name another one.
    if (isReleaseBuild()) process.env.OMNIRUSH_OPENCODE2_BIN = releaseEngineBinary({ fileNames: binaryFileNames("opencode2") }).path;
    else if (!process.env.OMNIRUSH_OPENCODE2_BIN?.trim()) {
      const bundledV2 = resolveBinaryInfo("opencode2");
      if (bundledV2) process.env.OMNIRUSH_OPENCODE2_BIN = bundledV2.path;
    }
    omnirushServerState.managedOpencodeBinPath = managedOpencode?.path ?? null;
    omnirushServerState.managedOpencodeBinSource = managedOpencode?.source ?? null;
    if (options.manageOpencode) {
      engineState.opencodeBinPath = managedOpencode?.path ?? null;
      engineState.opencodeBinSource = managedOpencode?.source ?? null;
    }

    // Load the desktop account before creating the embedded broker. Account
    // tokens stay in the Electron main process and are never serialized into
    // OpenCode config or passed to the renderer.
    const gatewayCredentials = await omnirushGatewayCredentials?.load?.() ?? null;

    // Inject user env vars so the server and managed OpenCode inherit them.
    // The embedded server runs in this process and reads process.env, so an
    // OMNIRUSH_APPROVALS=full|guarded from the launching shell reaches it
    // here (the user env file cannot set OMNIRUSH_* keys, see
    // loadUserEnvFile) and forces the engine approval mode.
    const serverEnv = await buildChildEnv({});
    Object.assign(process.env, serverEnv);
    if (omnirushGatewayCredentials) {
      // The desktop account store is authoritative. Clear inherited or stale
      // account variables before every restart so sign-out cannot recreate a
      // broker from process-global credentials. Current credentials are passed
      // directly to the embedded server below and never reach OpenCode.
      delete process.env.OMNIRUSH_GATEWAY_URL;
      delete process.env.OMNIRUSH_ACCESS_TOKEN;
      delete process.env.OMNIRUSH_REFRESH_TOKEN;
    }

    // Once the embedded server has a persisted registry, it is the source of
    // truth. Do not pass Electron's legacy workspace list as CLI workspaces or
    // the server config loader will ignore server.json and lose server-created
    // workspaces after restart.
    const serverConfigPath = resolveOmniRushServerConfigPath(process.env);
    const requestedWorkspacePaths = prioritizeWorkspacePaths("", options.workspacePaths, {
      platform: workspacePlatform,
    });
    const workspacePaths = seedWorkspacePathsForEmbeddedServer(
      requestedWorkspacePaths,
      existsSync(serverConfigPath),
    );
    const activeWorkspace = selectStickyOmniRushPortWorkspace(requestedWorkspacePaths, workspacePaths);
    const portSelection = await resolveOmniRushPort(host, activeWorkspace, currentPort);
    const tokens = await loadServerCredentials();

    // One call: resolve config, spawn managed OpenCode, start HTTP server.
    // Dev must prefer apps/server/dist; build output also stages a packaged
    // copy under apps/desktop/server for electron-builder.
    const devPath = path.resolve(__runtimeDir, "..", "..", "server", "dist", "embedded.js");
    const packagedPaths = [
      path.resolve(__runtimeDir, "..", "server", "dist", "embedded.js"),
      ...(process.resourcesPath ? [path.resolve(process.resourcesPath, "server", "dist", "embedded.js")] : []),
    ];
    const candidates = process.env.OMNIRUSH_DEV_MODE === "1"
      ? [devPath, ...packagedPaths]
      : [...packagedPaths, devPath];
    const embeddedPath = candidates.find((candidate) => existsSync(candidate));
    if (!embeddedPath) {
      throw new Error(`Cannot find OmniRush.ai embedded server bundle. Checked: ${candidates.join(", ")}`);
    }
    // Must be set before the bundle loads: the server memoizes its file sink
    // from process.env the first time it creates a logger.
    const logFilePath = resolveOmniRushServerLogFile(userDataDir);
    process.env.OMNIRUSH_SERVER_LOG_FILE = logFilePath;
    // The project archive never archives this folder, or one inside or above it.
    process.env.OMNIRUSH_DESKTOP_USER_DATA_DIR = userDataDir;
    omnirushServerState.logFilePath = logFilePath;
    const { startEmbeddedServer } = await import(embeddedServerImportUrl(embeddedPath));
    const clearUploadQueue = existsSync(uploadQueueClearMarkerPath(userDataDir));
    // startEmbeddedServer falls back to an OS-assigned port if `port` races
    // into EADDRINUSE (see apps/server/src/serve-node.ts), so the bound port
    // below is authoritative.
    const handle = await startEmbeddedServer({
      host,
      port: portSelection.port,
      corsOrigins: ["*"],
      approvalMode: "auto",
      configPath: serverConfigPath,
      workspaces: workspacePaths,
      token: tokens.clientToken,
      hostToken: tokens.hostToken,
      opencodeBaseUrl: options.opencodeBaseUrl ?? undefined,
      opencodeDirectory: activeWorkspace || undefined,
      manageOpencode: options.manageOpencode === true && Boolean(managedOpencode),
      resumeInterruptedTasks: true,
      opencodeBin: managedOpencode?.path ?? undefined,
      opencodeCwd: managedOpencodeWorkdir(),
      localManagedMcpVaultKey,
      appVersion: typeof appVersion === "string" && appVersion.trim() ? appVersion.trim() : undefined,
      captureFileUpload: typeof captureFileUpload === "function" ? captureFileUpload : undefined,
      clearUploadQueue,
      ...(typeof onTurnActivity === "function" ? { onTurnActivity } : {}),
      // Bundled UI-control MCP launch for the startup migration of persisted
      // `npx -y omnirush-ui-mcp` entries; null removes those entries instead.
      omnirushUiMcp: omnirushUiMcpLaunch() ?? null,
      omnirushGatewayCredentials: gatewayCredentials
        ? {
            ...gatewayCredentials,
            // The account store is the one owner of the refresh token: the
            // broker asks it after a 401 and never refreshes on its own, so
            // no superseded refresh token is ever sent.
            refresh: (rejectedAccessToken) => omnirushGatewayCredentials.refresh(rejectedAccessToken),
            invalidate: () => omnirushGatewayCredentials.clear({ revokeRemote: false }),
            latest: () => omnirushGatewayCredentials.load(),
            ...(typeof onUpdateSignal === "function" ? { onUpdateSignal } : {}),
            // Name and email for the git commit identity default; the account
            // store owns the profile lookup and its token refresh.
            profile: async () => {
              const status = await omnirushGatewayCredentials.status?.();
              return status?.connected && status.email
                ? { email: status.email, displayName: status.displayName ?? null }
                : null;
            },
          }
        : undefined,
    });
    inProcessServer = handle;
    if (clearUploadQueue) await rm(uploadQueueClearMarkerPath(userDataDir), { force: true }).catch(() => undefined);
    omnirushServerState.managedOpencodeExecution = handle.managedOpencodeExecution ?? null;
    engineState.managedByServer = Boolean(handle.managedOpencode);
    engineState.managedPid = handle.managedOpencode?.pid ?? null;
    engineState.managedIsAlive = handle.managedOpencode?.isAlive ?? null;

    const boundPort = handle.port;
    const baseUrl = handle.url;

    omnirushServerState.inProcess = true;
    omnirushServerGenerationCounter += 1;
    omnirushServerState.generation = omnirushServerGenerationCounter;
    omnirushServerState.remoteAccessEnabled = options.remoteAccessEnabled;
    omnirushServerState.host = host;
    omnirushServerState.port = boundPort;
    omnirushServerState.baseUrl = baseUrl;
    rememberLocalServer(baseUrl);
    omnirushServerState.clientToken = tokens.clientToken;
    omnirushServerState.hostToken = tokens.hostToken;
    recordRestart({ action: "started", reason: nextStartReason ?? "startup", source: "runtime" });
    nextStartReason = null;
    clearPendingRestart();

    const connectUrls = options.remoteAccessEnabled ? buildConnectUrls(boundPort) : { connectUrl: null, mdnsUrl: null, lanUrl: null };
    omnirushServerState.connectUrl = connectUrls.connectUrl;
    omnirushServerState.mdnsUrl = connectUrls.mdnsUrl;
    omnirushServerState.lanUrl = connectUrls.lanUrl;

    // No health check needed -- startServer() resolves only after the listener is bound.
    let workspaceList = null;
    let ownerToken = tokens.ownerToken?.trim() || null;
    if (ownerToken) {
      try {
        workspaceList = await fetchJson(`${baseUrl}/workspaces`, {
          headers: { Authorization: `Bearer ${ownerToken}` },
        }, 5000);
      } catch {
        ownerToken = null;
      }
    }
    ownerToken ||= await issueOwnerToken(baseUrl, tokens.hostToken);
    omnirushServerState.ownerToken = ownerToken;
    if (ownerToken) {
      await persistServerOwnerToken(ownerToken);
    }
    if (ownerToken) {
      try {
        const list = workspaceList ?? await fetchJson(`${baseUrl}/workspaces`, {
          headers: { Authorization: `Bearer ${ownerToken}` },
        }, 5000);
        const first = Array.isArray(list?.items) ? list.items[0] : undefined;
        const opencode = first?.opencode;
        if (opencode?.baseUrl) {
          engineState.runtime = DIRECT_RUNTIME;
          engineState.projectDir = opencode.directory ?? activeWorkspace ?? null;
          engineState.hostname = new URL(opencode.baseUrl).hostname;
          engineState.port = Number(new URL(opencode.baseUrl).port) || null;
          engineState.baseUrl = opencode.baseUrl;
          engineState.opencodeUsername = opencode.username ?? null;
          engineState.opencodePassword = opencode.password ?? null;
          engineState.execution = handle.managedOpencodeExecution ?? null;
          engineState.child = null;
          engineState.childExited = false;
        }
      } catch (error) {
        appendOutput(omnirushServerState, "lastStderr", `OmniRush.ai server workspace probe: ${error instanceof Error ? error.message : String(error)}\n`);
      }
    }
    if (!portSelection.preferredPort || boundPort === portSelection.preferredPort) {
      await persistPreferredOmniRushPort(activeWorkspace, boundPort);
    }
    return snapshotOmniRushServerState(omnirushServerState);
  }

  async function stopAllRuntimeChildren() {
    // Stop the in-process server (and its managed OpenCode child) if running.
    clearPendingRestart();
    if (inProcessServer) {
      try { await inProcessServer.stop(); } catch { /* ignore */ }
      inProcessServer = null;
    }
    await stopChild(omnirushServerState);
    await stopChild(engineState);

    Object.assign(engineState, createEngineState());
    Object.assign(omnirushServerState, createOmniRushServerState());
  }

  async function prepareFreshRuntime(options = {}) {
    recordStop(options, "prepare-fresh-runtime");
    await resetRuntime();
  }

  async function resetRuntime() {
    lifecycleState = "cleaning";
    await stopAllRuntimeChildren();
    await cleanupPackagedSidecars();
    lifecycleState = "idle";
  }

  function settleAfterWorkspacePreparationFailure() {
    if (snapshotOmniRushServerState(omnirushServerState).running) {
      lifecycleState = "healthy";
      return;
    }
    Object.assign(engineState, createEngineState());
    Object.assign(omnirushServerState, createOmniRushServerState());
    lifecycleState = "idle";
  }

  async function ensureOmniRush(options) {
    let omnirushServer;
    try {
      omnirushServer = await startOmniRushServer({
        workspacePaths: options.workspacePaths,
        opencodeBaseUrl: engineState.baseUrl,
        opencodeUsername: engineState.opencodeUsername,
        opencodePassword: engineState.opencodePassword,
        remoteAccessEnabled: options.remoteAccessEnabled,
        manageOpencode: options.manageOpencode === true,
        opencodeBinPath: options.opencodeBinPath,
      });
    } catch (error) {
      appendOutput(engineState, "lastStderr", `OmniRush.ai server: ${error instanceof Error ? error.message : String(error)}\n`);
      throw error;
    }

    assertOmniRushServerReady(omnirushServer);
  }

  async function engineStart(projectDir, options = {}) {
    const rawProjectDir = String(projectDir ?? "").trim();
    if (!rawProjectDir) {
      throw new Error("projectDir is required");
    }
    let safeProjectDir;
    try {
      safeProjectDir = normalizeWorkspaceRootPath(rawProjectDir, { platform: workspacePlatform });
    } catch (error) {
      settleAfterWorkspacePreparationFailure();
      throw workspaceInaccessibleError(rawProjectDir, error);
    }

    // Reuse a healthy server instead of tearing it down. During boot the
    // main process kicks off bootRuntimeForSelectedWorkspace while renderer
    // routes independently call ensureDesktopLocalOmniRushConnection. Both go
    // through this serialized path; without this guard the second call runs
    // prepareFreshRuntime (killing the freshly bound server) and then rebinds
    // the sticky preferred port, racing the not-yet-released socket into
    // EADDRINUSE and leaving the runtime in error -> boot screen.
    // resolveOmniRushServerReuse also spans workspace switches: requesting a
    // different projectDir retargets the running runtime instead of killing
    // the process and every in-flight run with it.
    let reuseDecision = resolveOmniRushServerReuse({
      forceRestart: options.forceRestart,
      inProcess: omnirushServerState.inProcess,
      lifecycleState,
      remoteAccessEnabled: omnirushServerState.remoteAccessEnabled,
      requestedRemoteAccess: options.omnirushRemoteAccess,
      currentProjectDir: engineState.projectDir,
      requestedProjectDir: safeProjectDir,
      platform: workspacePlatform,
    });
    if (!reuseDecision.reuse && options.forceRestart !== true && inProcessServer) {
      // Not a restart request, yet it would replace the running server
      // (remote-access mismatch, or a lifecycle state left behind by an
      // earlier failure). Only a user action may do that to a healthy one.
      const guard = await guardRestart("engine-start", options, "engine-start");
      if (guard.verdict === "skip") {
        lifecycleState = "healthy";
        reuseDecision = {
          reuse: true,
          retarget: normalizeWorkspaceKey(engineState.projectDir, workspacePlatform)
            !== normalizeWorkspaceKey(safeProjectDir, workspacePlatform),
        };
      }
    }
    if (reuseDecision.reuse) {
      const existing = snapshotOmniRushServerState(omnirushServerState);
      if (existing.running && existing.baseUrl && (existing.ownerToken || existing.clientToken)) {
        if (reuseDecision.retarget) {
          try {
            safeProjectDir = await prepareRuntimeWorkspaceRoot(safeProjectDir, {
              platform: workspacePlatform,
              mkdirImpl: workspaceMkdir,
            });
          } catch (error) {
            settleAfterWorkspacePreparationFailure();
            throw error;
          }
          engineState.projectDir = safeProjectDir;
          await persistPreferredOmniRushPort(safeProjectDir, omnirushServerState.port);
        }
        return snapshotEngineState(engineState);
      }
    }

    lifecycleState = "starting";
    try {
      safeProjectDir = await prepareRuntimeWorkspaceRoot(safeProjectDir, {
        platform: workspacePlatform,
        mkdirImpl: workspaceMkdir,
      });
    } catch (error) {
      settleAfterWorkspacePreparationFailure();
      throw error;
    }
    await resetRuntime();

    const workspacePaths = prioritizeWorkspacePaths(safeProjectDir, options.workspacePaths, {
      platform: workspacePlatform,
    });
    const runtime = DIRECT_RUNTIME;

    try {
      lifecycleState = "starting";
      engineState.runtime = runtime;
      engineState.projectDir = safeProjectDir;
      engineState.child = null;
      engineState.childExited = true;

      await ensureOmniRush({
        projectDir: safeProjectDir,
        workspacePaths,
        remoteAccessEnabled: options.omnirushRemoteAccess === true,
        manageOpencode: true,
        opencodeBinPath: options.opencodeBinPath,
      });

      lifecycleState = "healthy";
      return snapshotEngineState(engineState);
    } catch (error) {
      lifecycleState = "error";
      throw error;
    }
  }

  async function engineStop(options = {}) {
    recordStop(options, "engine-stop");
    lifecycleState = "stopping";
    await stopAllRuntimeChildren();
    lifecycleState = "idle";
    return snapshotEngineState(engineState);
  }

  async function engineRestart(options = {}) {
    const projectDir = engineState.projectDir;
    if (!projectDir) {
      throw new Error("OmniRush is not configured for a local workspace");
    }
    if (options.deferredRun === true) {
      const request = restartRequest(options, "deferred");
      recordRestart({ action: "restarting", reason: request.reason, source: request.source, trigger: "engine-restart", why: "idle" });
      nextStartReason = request.reason;
    } else {
      const guard = await guardRestart("engine-restart", options, "engine-restart");
      if (guard.verdict !== "proceed") {
        return {
          ...snapshotEngineState(engineState),
          restartDeferred: guard.verdict === "defer",
          busySessions: guard.busy.sessions,
        };
      }
    }
    const omnirushRemoteAccess = typeof options.omnirushRemoteAccess === "boolean"
      ? options.omnirushRemoteAccess
      : omnirushServerState.remoteAccessEnabled;
    return engineStart(projectDir, {
      runtime: engineState.runtime,
      workspacePaths: [projectDir],
      omnirushRemoteAccess,
      forceRestart: true,
    });
  }

  async function engineInfo() {
    if (inProcessServer?.managedOpencode) {
      engineState.managedPid = inProcessServer.managedOpencode.pid ?? null;
    }
    return { ...snapshotEngineState(engineState), lifecycleState };
  }

  async function runtimeStatus() {
    return {
      lifecycleState,
      engine: await engineInfo(),
      enginePool: inProcessServer?.managedOpencodePool?.() ?? null,
      omnirushServer: snapshotOmniRushServerState(omnirushServerState),
    };
  }

  async function omnirushServerInfo() {
    return {
      ...snapshotOmniRushServerState(omnirushServerState),
      restarts: await readRuntimeRestartRecords(restartLogFile()),
      pendingRestart: pendingRestartSummary(),
    };
  }

  async function omnirushServerRestart(options = {}) {
    // Keep the running host binding unless the caller asks to change it: a
    // restart for another reason (account change) must not drop remote access.
    const remoteAccessEnabled = typeof options.remoteAccessEnabled === "boolean"
      ? options.remoteAccessEnabled
      : omnirushServerState.remoteAccessEnabled === true;
    if (options.deferredRun === true) {
      const request = restartRequest(options, "deferred");
      recordRestart({ action: "restarting", reason: request.reason, source: request.source, trigger: "server-restart", why: "idle" });
      nextStartReason = request.reason;
    } else {
      const guard = await guardRestart("server-restart", options, "server-restart", {
        sameSettings: omnirushServerState.remoteAccessEnabled === remoteAccessEnabled,
      });
      if (guard.verdict !== "proceed") {
        return {
          ...snapshotOmniRushServerState(omnirushServerState),
          restartDeferred: guard.verdict === "defer",
          restartSkipped: guard.verdict === "skip",
          busySessions: guard.busy.sessions,
        };
      }
    }
    const workspacePaths = prioritizeWorkspacePaths(engineState.projectDir, await listLocalWorkspacePaths(), {
      platform: workspacePlatform,
    });
    const shouldManageOpencode = Boolean(
      omnirushServerState.managedOpencodeBinPath || engineState.opencodeBinPath || !engineState.baseUrl,
    );
    return startOmniRushServer({
      workspacePaths,
      opencodeBaseUrl: shouldManageOpencode ? null : engineState.baseUrl,
      opencodeUsername: shouldManageOpencode ? null : engineState.opencodeUsername,
      opencodePassword: shouldManageOpencode ? null : engineState.opencodePassword,
      remoteAccessEnabled,
      manageOpencode: shouldManageOpencode,
      opencodeBinPath: engineState.opencodeBinPath ?? omnirushServerState.managedOpencodeBinPath,
    });
  }

  async function engineInstall() {
    // The engine is OmniRush.ai's own build of opencode 1.18.32 and ships
    // inside the app (resources/sidecars); there is no separate installer.
    // An upstream opencode install would keep its sessions apart from the
    // app's, so none is offered.
    return {
      ok: false,
      status: -1,
      stdout: "",
      stderr: "The OmniRush engine ships inside OmniRush.ai. Reinstall OmniRush.ai to restore it, then restart the app.",
    };
  }

  async function opencodeMcpAuth(projectDir, serverName) {
    const safeProjectDir = String(projectDir ?? "").trim();
    const safeServerName = String(serverName ?? "").trim();
    if (!safeProjectDir) {
      throw new Error("project_dir is required");
    }
    if (!safeServerName) {
      throw new Error("server_name is required");
    }

    const program = resolveOpencodeBinary()?.path ?? null;
    if (!program) {
      throw new Error("Failed to locate the local agent runtime.");
    }

    const result = await runShellCommand(program, ["mcp", "auth", safeServerName], {
      cwd: safeProjectDir,
      env: await buildChildEnv(),
      timeoutMs: 120_000,
    });
    return {
      ok: result.status === 0,
      status: result.status,
      stdout: result.stdout,
      stderr: result.stderr,
    };
  }

  async function sandboxCleanupOmniRushContainers() {
    const candidates = await listOmniRushManagedContainers().catch((error) => {
      throw error;
    });
    const removed = [];
    const errors = [];

    for (const name of candidates) {
      try {
        const result = runDockerCommandDetailed(["rm", "-f", name], 20_000);
        if (result.status === 0) {
          removed.push(name);
        } else {
          errors.push(`${name}: exit ${result.status}: ${(result.stdout + "\n" + result.stderr).trim()}`);
        }
      } catch (error) {
        errors.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
      }
    }

    return { candidates, removed, errors };
  }

  return {
    systemCaCertificates: async () => (await systemCa()).trustedCertificates,
    engineStart: (projectDir, options) => withRuntimeLifecycle(() => engineStart(projectDir, options)),
    engineStop: (options) => withRuntimeLifecycle(() => engineStop(options)),
    engineRestart: (options) => withRuntimeLifecycle(() => engineRestart(options)),
    prepareFreshRuntime: (options) => withRuntimeLifecycle(() => prepareFreshRuntime(options)),
    dispose: (options) => withRuntimeLifecycle(() => {
      recordStop(options ?? { reason: "app_quit" }, "dispose");
      return stopAllRuntimeChildren();
    }),
    runtimeStatus,
    engineInfo,
    engineDoctor,
    /** The engine binary a start would use and where the bundled copy belongs (start-report.mjs). */
    engineBinaryInfo: () => ({
      resolved: (() => {
        try {
          return resolveOpencodeBinary();
        } catch {
          return null;
        }
      })(),
      bundledCandidates: sidecarDirs.flatMap((directory) => binaryFileNames("opencode").map((name) => path.join(directory, name))),
      versionsFiles: sidecarDirs.map((directory) => path.join(directory, "versions.json")),
    }),
    engineInstall,
    omnirushServerInfo,
    omnirushServerRestart: (options) => withRuntimeLifecycle(() => omnirushServerRestart(options)),
    /** A user's sign-out: the next server start keeps the queued uploads and archives for that account only. */
    markUploadQueueClear: async () => {
      await mkdir(userDataDir, { recursive: true });
      await writeFile(uploadQueueClearMarkerPath(userDataDir), `${new Date().toISOString()}\n`, { mode: 0o600 });
    },
    opencodeMcpAuth,
    sandboxCleanupOmniRushContainers,
  };
}