0sec-cli 0.22.4 → 0.24.0

package/chunks/chunk-TZRHWP7R.js

@@ -0,0 +1,736 @@
+#!/usr/bin/env node
+import { createRequire as __0CreateRequire } from "node:module";
+const require = __0CreateRequire(import.meta.url);
+import {
+  resolveOsecDbPath
+} from "./chunk-RCHAFSWS.js";
+import {
+  BACKEND_PROTOCOL_VERSION,
+  BackendDescriptorSchema,
+  BackendHandshakeSchema,
+  BackendRequestIdSchema,
+  backendCapabilitiesForApiPath,
+  homeStateDir,
+  parseBackendHandshake
+} from "./chunk-RZR2XXAK.js";
+import {
+  external_exports
+} from "./chunk-VIT5ALXF.js";
+
+// packages/cli/src/worker-deploy.ts
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+var REMOTE_DIR = "/tmp/zero-engine";
+var REMOTE_DEPS = {
+  "drizzle-orm": "^0.45.2",
+  "node-sqlite3-wasm": "^0.8.55",
+  "pdfkit": "^0.15.2",
+  "playwright": "1.60.0",
+  "react": "^19.2.4",
+  "react-dom": "^19.2.4",
+  "tree-sitter": `file:${REMOTE_DIR}/vendor/tree-sitter-0.21.1-node24.tgz`,
+  "tree-sitter-c": "0.21.4",
+  "@opentui/core": "0.5.4",
+  "@opentui/react": "0.5.4"
+};
+var SSH_HOST_PATTERN = /^[A-Za-z0-9._@-]+$/;
+var LIMA_NAME_PATTERN = /^[\w.-]+$/;
+var TARGET_GIT_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s'"]+$/;
+var sq = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+function resolveWorkerRepoRoot(moduleUrl = import.meta.url) {
+  let directory = dirname(fileURLToPath(moduleUrl));
+  while (true) {
+    if ((existsSync(join(directory, "dist/0.js")) || existsSync(join(directory, "0.js"))) && existsSync(join(directory, "vendor/tree-sitter-0.21.1-node24.tgz"))) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error("Worker deployment requires the built CLI dist/ and vendor/ assets. Run pnpm build first.");
+    directory = parent;
+  }
+}
+function validateWorkerOptions(options) {
+  if (options.enginePort !== void 0 && (!Number.isInteger(options.enginePort) || options.enginePort < 1 || options.enginePort > 65535)) throw new Error("enginePort must be 1-65535");
+  if (options.ssh && (!SSH_HOST_PATTERN.test(options.ssh) || options.ssh.startsWith("-"))) {
+    throw new Error("--ssh must be an OpenSSH host name or user@host (no options or shell characters)");
+  }
+  if (options.lima && !LIMA_NAME_PATTERN.test(options.lima)) throw new Error("--lima must be an instance name (letters, digits, ., _, -)");
+  if (options.targetGit && !TARGET_GIT_PATTERN.test(options.targetGit)) throw new Error("--target-git must be a URL without whitespace or quotes");
+}
+function createRunner(options) {
+  if (options.ssh) {
+    const host = options.ssh;
+    const configArgs = options.sshConfig ? ["-F", options.sshConfig] : [];
+    return {
+      label: host,
+      shell: (command, timeout = 3e5) => execFileSync("ssh", ["-o", "BatchMode=yes", "-o", "ConnectTimeout=15", ...configArgs, "--", host, "bash", "-s"], { input: command, encoding: "utf8", timeout }),
+      copy: (local, remote) => execFileSync("scp", ["-q", "-o", "BatchMode=yes", ...configArgs, "--", local, `${host}:${remote}`], { stdio: "inherit", timeout: 6e5 }),
+      tunnel: (port) => {
+        const child = spawn("ssh", ["-o", "BatchMode=yes", ...configArgs, "-N", "-L", `${port}:127.0.0.1:${port}`, "--", host], { stdio: "ignore", detached: true });
+        child.unref();
+        return child.pid;
+      }
+    };
+  }
+  const vm = options.lima ?? "zero-worker";
+  return {
+    label: vm,
+    shell: (command, timeout = 3e5) => execFileSync("limactl", ["shell", vm, "--", "bash", "-s"], { input: command, encoding: "utf8", timeout }),
+    copy: (local, remote) => execFileSync("limactl", ["copy", local, `${vm}:${remote}`], { stdio: "inherit", timeout: 6e5 }),
+    tunnel: (port) => {
+      const configPath = "/tmp/zero-worker-ssh.conf";
+      writeFileSync(configPath, execFileSync("limactl", ["show-ssh", "--format", "config", vm], { encoding: "utf8" }), { mode: 384 });
+      const child = spawn("ssh", ["-F", configPath, "-N", "-L", `${port}:127.0.0.1:${port}`, `lima-${vm}`], { stdio: "ignore", detached: true });
+      child.unref();
+      return child.pid;
+    }
+  };
+}
+async function deployWorker(options, runner = createRunner(options)) {
+  validateWorkerOptions(options);
+  const repoRoot = options.repoRoot ?? resolveWorkerRepoRoot();
+  const port = options.enginePort ?? 2e4 + Number.parseInt(createHash("sha256").update(runner.label).digest("hex").slice(0, 4), 16) % 2e4;
+  const token = createHash("sha256").update(randomBytes(32)).digest("hex");
+  const identity = createHash("sha256").update(`${options.ssh ? "ssh" : "lima"}:${runner.label}`).digest("hex").slice(0, 12);
+  const backendId = `${options.ssh ? "ssh" : "lima"}-worker-${identity}`;
+  const tokenEnv = `ZERO_WORKER_${identity.toUpperCase()}_TOKEN`;
+  const { shell } = runner;
+  if (!options.ssh) {
+    const status = execFileSync("limactl", ["list", "--format", "{{.Status}}", runner.label], { encoding: "utf8" }).trim();
+    if (status !== "Running") throw new Error(`VM ${runner.label} is ${status}; start it first`);
+  }
+  shell("uname -srm");
+  const nodeVersion = shell("command -v node >/dev/null && node --version || echo none").trim();
+  if (!(nodeVersion.startsWith("v2") && Number(nodeVersion.slice(1).split(".")[0]) >= 24)) {
+    const arch = shell("uname -m").trim() === "aarch64" ? "arm64" : "x64";
+    shell(`cd /tmp && curl -fsSL https://nodejs.org/dist/v24.14.0/node-v24.14.0-linux-${arch}.tar.xz -o node.tar.xz && sudo tar -xJf node.tar.xz -C /usr/local --strip-components=1 && node --version`, 6e5);
+  }
+  const clangVersion = shell("command -v clang >/dev/null && clang --version | head -1 || echo none").trim();
+  if (clangVersion === "none") {
+    shell("sudo apt-get update -qq && sudo apt-get install -y -qq clang build-essential python3 >/dev/null && clang --version | head -1", 9e5);
+  }
+  const staging = mkdtempSync(join(tmpdir(), "zero-worker-"));
+  try {
+    const bundleRoot = existsSync(join(repoRoot, "dist/0.js")) ? repoRoot : staging;
+    if (bundleRoot === staging) {
+      mkdirSync(join(staging, "dist"));
+      for (const asset of ["0.js", "cli-path-traversal-fixture.js", "chunks", "attacks", "dashboard", "worker-assets"]) {
+        if (existsSync(join(repoRoot, asset))) cpSync(join(repoRoot, asset), join(staging, "dist", asset), { recursive: true });
+      }
+    }
+    execFileSync("tar", ["-czf", join(staging, "bundle.tar.gz"), "-C", bundleRoot, "dist"], { stdio: "inherit", env: { ...process.env, COPYFILE_DISABLE: "1" } });
+    const demoRoot = existsSync(join(bundleRoot, "dist/worker-assets/demo-target")) ? join(bundleRoot, "dist/worker-assets") : join(repoRoot, "research/counterexample-decoder");
+    if (!options.targetGit) execFileSync("tar", ["-czf", join(staging, "demo-target.tar.gz"), "-C", demoRoot, "demo-target"], { stdio: "inherit", env: { ...process.env, COPYFILE_DISABLE: "1" } });
+    shell(`for entry in /proc/[0-9]*/cwd; do
+    test "$(readlink "$entry" 2>/dev/null)" = "${REMOTE_DIR}" || continue
+    pid=$(echo "$entry" | cut -d/ -f3)
+    command=$(tr '\\000' ' ' < /proc/$pid/cmdline 2>/dev/null) || continue
+    case "$command" in 'node dist/0.js dashboard '*|'node /tmp/zero-engine/dist/0.js dashboard '*) kill "$pid" || true;; esac
+  done`);
+    shell(`rm -rf ${REMOTE_DIR} && mkdir -p ${REMOTE_DIR}/vendor`);
+    runner.copy(join(staging, "bundle.tar.gz"), `${REMOTE_DIR}/bundle.tar.gz`);
+    if (!options.targetGit) runner.copy(join(staging, "demo-target.tar.gz"), `${REMOTE_DIR}/demo-target.tar.gz`);
+    runner.copy(join(repoRoot, "vendor/tree-sitter-0.21.1-node24.tgz"), `${REMOTE_DIR}/vendor/tree-sitter-0.21.1-node24.tgz`);
+    shell(`cd ${REMOTE_DIR} && tar -xzf bundle.tar.gz && ${options.targetGit ? "ls dist/0.js" : "tar -xzf demo-target.tar.gz && ls dist/0.js demo-target/src/decoder.c"}`);
+    writeFileSync(join(staging, "package.json"), JSON.stringify({ name: "zero-engine-remote", private: true, dependencies: REMOTE_DEPS }, null, 2));
+    runner.copy(join(staging, "package.json"), `${REMOTE_DIR}/package.json`);
+    shell(`cd ${REMOTE_DIR} && PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install --omit=dev --no-audit --no-fund > install.log 2>&1 || { tail -20 install.log; exit 1; }`, 9e5);
+    let targetPath;
+    if (options.targetGit) {
+      shell(`rm -rf ${REMOTE_DIR}/work && mkdir -p ${REMOTE_DIR}/work && git clone --depth 1 ${sq(options.targetGit)} ${REMOTE_DIR}/work/target`, 9e5);
+      targetPath = `${REMOTE_DIR}/work/target`;
+    } else {
+      shell(`rm -rf ${REMOTE_DIR}/work && mkdir -p ${REMOTE_DIR}/work && cp -R ${REMOTE_DIR}/demo-target ${REMOTE_DIR}/work/demo-target`);
+      targetPath = `${REMOTE_DIR}/work/demo-target`;
+    }
+    const providerEnv = options.forwardProviderKey && process.env.OPENAI_API_KEY ? `OPENAI_API_KEY=${sq(process.env.OPENAI_API_KEY)} ` : "";
+    try {
+      shell(`cd ${REMOTE_DIR} || exit 1; ${providerEnv}ZERO_WORKER_TOKEN=${token} setsid nohup node dist/0.js dashboard --host 127.0.0.1 --port ${port} --no-open --ready-json --engine-token-env ZERO_WORKER_TOKEN --engine-workspace ${REMOTE_DIR}/work > engine.log 2>&1 < /dev/null & echo $! > ${REMOTE_DIR}/engine.pid; echo started`, 3e4);
+    } catch {
+    }
+    const ready = shell(`for i in $(seq 1 30); do grep -q ZERO_DASHBOARD_READY ${REMOTE_DIR}/engine.log 2>/dev/null && echo ready && break; sleep 1; done; tail -2 ${REMOTE_DIR}/engine.log`, 6e4);
+    if (!ready.includes("ready")) throw new Error(`engine did not become ready: ${ready.trim()}`);
+    const tunnelPid = runner.tunnel(port);
+    const tunnelReady = Promise.withResolvers();
+    setTimeout(tunnelReady.resolve, 2e3);
+    await tunnelReady.promise;
+    execFileSync("curl", ["-sf", `http://127.0.0.1:${port}/`], { stdio: "ignore" });
+    const stateDir = join(homeStateDir(), "workers");
+    mkdirSync(stateDir, { recursive: true, mode: 448 });
+    const backendsConfig = options.backendsConfig ?? join(homeStateDir(), "backends.json");
+    let registry = { schemaVersion: 1, backends: [] };
+    try {
+      registry = JSON.parse(await (await import("node:fs/promises")).readFile(backendsConfig, "utf8"));
+    } catch {
+    }
+    registry.backends = [...registry.backends.filter((row) => row.id !== backendId), { id: backendId, name: `${runner.label} worker`, url: `http://127.0.0.1:${port}/`, bearerTokenEnv: tokenEnv }];
+    writeFileSync(backendsConfig, JSON.stringify(registry, null, 2) + "\n", { mode: 384 });
+    writeFileSync(join(stateDir, `${backendId}.env`), `${tokenEnv}=${token}
+`, { mode: 384 });
+    writeFileSync(join(stateDir, `${backendId}.json`), JSON.stringify({ schemaVersion: 1, backendId, ssh: options.ssh, lima: options.ssh ? void 0 : options.lima ?? "zero-worker", sshConfig: options.sshConfig, port, tunnelPid, remoteDir: REMOTE_DIR }, null, 2) + "\n", { mode: 384 });
+    process.env[tokenEnv] = token;
+    return { backendId, engine: `http://127.0.0.1:${port}/`, target: targetPath, backendsConfig, tokenEnv };
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+function loadManagedWorker(backendId) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(backendId)) throw new Error("Invalid worker ID.");
+  let worker;
+  try {
+    worker = JSON.parse(readFileSync(join(homeStateDir(), "workers", `${backendId}.json`), "utf8"));
+  } catch {
+    throw new Error("This connection has no managed deployment metadata. Stop its engine directly on the host.");
+  }
+  if (worker.schemaVersion !== 1 || worker.backendId !== backendId || worker.remoteDir !== REMOTE_DIR || !!worker.ssh === !!worker.lima) throw new Error("Invalid managed deployment metadata.");
+  validateWorkerOptions({ ...worker, enginePort: worker.port });
+  return worker;
+}
+function stopManagedTunnel(worker) {
+  if (!Number.isSafeInteger(worker.tunnelPid) || worker.tunnelPid <= 1) return false;
+  const result = spawnSync("ps", ["-p", String(worker.tunnelPid), "-o", "comm=", "-o", "args="], { encoding: "utf8" });
+  const command = result.stdout?.trim() ?? "";
+  const destination = worker.ssh ?? `lima-${worker.lima}`;
+  if (!/^\S*ssh\s/.test(command) || !command.includes(` ${worker.port}:127.0.0.1:${worker.port} `) || !command.endsWith(` ${destination}`)) return false;
+  try {
+    process.kill(worker.tunnelPid, "SIGTERM");
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function stopWorker(backendId, suppliedRunner) {
+  const worker = loadManagedWorker(backendId);
+  const runner = suppliedRunner ?? createRunner(worker);
+  runner.shell(`set -eu
+if test ! -f ${REMOTE_DIR}/engine.pid; then echo 'Managed engine PID is unavailable; engine was not stopped.' >&2; exit 1; fi
+pid=$(cat ${REMOTE_DIR}/engine.pid)
+case "$pid" in ''|*[!0-9]*) echo 'Invalid engine PID' >&2; exit 1;; esac
+if test "$pid" -le 1; then echo 'Invalid engine PID' >&2; exit 1; fi
+if test -e /proc/$pid/cmdline; then
+  if test "$(readlink /proc/$pid/cwd)" != "${REMOTE_DIR}"; then echo 'Engine working directory does not match managed Zero engine' >&2; exit 1; fi
+  command=$(tr '\\000' ' ' < /proc/$pid/cmdline)
+  case "$command" in 'node dist/0.js dashboard '*|'node /tmp/zero-engine/dist/0.js dashboard '*) kill "$pid";; *) echo 'Engine PID does not match managed Zero engine' >&2; exit 1;; esac
+fi
+rm -f ${REMOTE_DIR}/engine.pid`, 3e4);
+  return { stopped: true, tunnelStopped: stopManagedTunnel(worker), remoteFilesRemoved: false };
+}
+
+// packages/cli/src/web/backend-connections.ts
+import { randomUUID } from "node:crypto";
+import { constants, closeSync, fstatSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, readSync, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+var BackendConnectionError = class extends Error {
+  constructor(message, statusCode = 502) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "BackendConnectionError";
+  }
+  statusCode;
+};
+var idSchema = BackendDescriptorSchema.shape.id.refine((value) => value !== "local", "The local backend ID is reserved.");
+var connectionSchema = external_exports.object({
+  id: idSchema,
+  name: external_exports.string().trim().min(1).max(160),
+  url: external_exports.string().max(4096),
+  bearerTokenEnv: external_exports.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/).max(128),
+  expectedEngineId: BackendHandshakeSchema.shape.engineId.optional()
+}).strict();
+var configSchema = external_exports.object({ schemaVersion: external_exports.literal(1), backends: external_exports.array(connectionSchema).max(32) }).strict();
+var MAX_BODY = 1e6;
+var MAX_RESPONSE = 16e6;
+var MAX_CONFIG = 65536;
+function loopback(host) {
+  return host === "localhost" || host === "[::1]" || /^127\.(?:\d{1,3}\.){2}\d{1,3}$/.test(host);
+}
+function endpoint(value) {
+  const url = new URL(value);
+  if (url.username || url.password || url.search || url.hash || url.protocol !== "https:" && !(url.protocol === "http:" && loopback(url.hostname))) throw new BackendConnectionError("Backend URL must be credential-free HTTPS or loopback HTTP, without query or fragment.", 400);
+  if (url.pathname.split("/").some((part) => {
+    const decoded = decodeURIComponent(part);
+    return decoded === ".." || decoded === "." || /[\\\x00]/.test(decoded);
+  })) throw new BackendConnectionError("Invalid backend URL path.", 400);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/`;
+  return url;
+}
+function loadBackendConnectionConfig(configPath) {
+  const path = configPath ?? join2(homeStateDir(), "backends.json");
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  } catch (error) {
+    if (!configPath && error.code === "ENOENT") return [];
+    throw error;
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_CONFIG) throw new BackendConnectionError("Backend configuration must be a regular JSON file of at most 64 KiB.", 400);
+    const buffer = Buffer.alloc(MAX_CONFIG + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = readSync(fd, buffer, length, buffer.length - length, length);
+      if (!count) break;
+      length += count;
+    }
+    if (length > MAX_CONFIG) throw new BackendConnectionError("Backend configuration exceeds 64 KiB.", 400);
+    const config = configSchema.parse(JSON.parse(buffer.subarray(0, length).toString("utf8")));
+    if (new Set(config.backends.map((row) => row.id)).size !== config.backends.length) throw new BackendConnectionError("Backend connection IDs must be unique.", 400);
+    for (const row of config.backends) endpoint(row.url);
+    return config.backends;
+  } finally {
+    closeSync(fd);
+  }
+}
+function createBackendHandshake(dbPath, capabilities2 = []) {
+  const db = resolveOsecDbPath(dbPath);
+  let engineId = `engine-${randomUUID()}`;
+  if (db !== ":memory:") {
+    const path = `${resolve(db)}.engine-id`;
+    mkdirSync2(dirname2(path), { recursive: true, mode: 448 });
+    try {
+      writeFileSync2(path, `${engineId}
+`, { flag: "wx", mode: 384 });
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+      if (!fstatSync(fd).isFile() || fstatSync(fd).size > 256) throw new BackendConnectionError("Invalid persisted backend engine identity.", 500);
+      const buffer = Buffer.alloc(257);
+      const count = readSync(fd, buffer, 0, buffer.length, 0);
+      if (count > 256) throw new BackendConnectionError("Invalid persisted backend engine identity.", 500);
+      engineId = BackendHandshakeSchema.shape.engineId.parse(buffer.subarray(0, count).toString("utf8").trim());
+    } finally {
+      closeSync(fd);
+    }
+  }
+  return { protocolVersion: BACKEND_PROTOCOL_VERSION, engineId, capabilities: capabilities2, platform: { os: process.platform, pathStyle: process.platform === "win32" ? "windows" : "posix" }, serverInstanceId: randomUUID() };
+}
+function backendBearerFromEnv(name, env = process.env) {
+  if (!name) return void 0;
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new BackendConnectionError("Invalid engine token environment variable name.", 400);
+  const token = env[name];
+  if (!token || token.length < 32 || token.length > 4096 || /[\s\x00-\x1f\x7f]/.test(token)) throw new BackendConnectionError(`Configure a valid engine credential of 32\u20134096 characters.`, 400);
+  return token;
+}
+function apiPath(path) {
+  if (!path.startsWith("/api/") || path.length > 8192 || /[\x00-\x20\\]/.test(path)) throw new BackendConnectionError("Backend requests require an API path.", 400);
+  const url = new URL(path, "http://backend.invalid");
+  for (const segment of path.split("?")[0].split("/")) {
+    const decoded = decodeURIComponent(segment);
+    if (decoded === "." || decoded === ".." || /[\/\\\x00]/.test(decoded)) throw new BackendConnectionError("Invalid backend request path.", 400);
+  }
+  if (url.pathname.startsWith("/api/backends")) throw new BackendConnectionError("Backend connection registration is not a proxy operation.", 403);
+  return `${url.pathname}${url.search}`;
+}
+function capabilities(path) {
+  const pathname = path.split("?")[0];
+  const required = backendCapabilitiesForApiPath(pathname);
+  if (!required.length && pathname !== "/api/backend/handshake") throw new BackendConnectionError("API route is not admitted by the backend transport.", 403);
+  return required;
+}
+async function boundedResponse(response, maximum, signal) {
+  if (!response.body) return new Uint8Array();
+  const reader = response.body.getReader();
+  const chunks = [];
+  let length = 0;
+  const onAbort = () => {
+    void reader.cancel().catch(() => {
+    });
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    while (true) {
+      signal.throwIfAborted();
+      const next = await reader.read();
+      signal.throwIfAborted();
+      if (next.done) break;
+      length += next.value.length;
+      if (length > maximum) throw new BackendConnectionError("Backend response exceeds the transport limit.");
+      chunks.push(next.value);
+    }
+  } catch (error) {
+    await reader.cancel().catch(() => {
+    });
+    throw error;
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks, length);
+}
+var BackendConnectionRegistry = class {
+  #connections;
+  #descriptors = /* @__PURE__ */ new Map();
+  #pins = /* @__PURE__ */ new Map();
+  #handshakes = /* @__PURE__ */ new Map();
+  #pending = /* @__PURE__ */ new Map();
+  #env;
+  #fetch;
+  #local;
+  #timeoutMs;
+  #configPath;
+  #reloadFromDisk;
+  #abort = new AbortController();
+  #active = 0;
+  constructor(options = {}) {
+    this.#configPath = options.configPath;
+    this.#reloadFromDisk = options.connections === void 0;
+    const rows = options.connections ?? loadBackendConnectionConfig(options.configPath);
+    const parsed = configSchema.parse({ schemaVersion: 1, backends: rows }).backends;
+    if (new Set(parsed.map((row) => row.id)).size !== parsed.length) throw new BackendConnectionError("Backend IDs must be unique.", 400);
+    this.#connections = new Map(parsed.map((row) => [row.id, { ...row, url: endpoint(row.url).href }]));
+    this.#env = { ...options.env ?? process.env };
+    this.#fetch = options.fetch ?? fetch;
+    this.#timeoutMs = options.timeoutMs ?? 3e4;
+    this.#local = parseBackendHandshake(options.localHandshake ?? createBackendHandshake());
+    this.#descriptors.set("local", { id: "local", name: "Local engine", transport: "local", status: "connected", protocolVersion: this.#local.protocolVersion, capabilities: this.#local.capabilities, platform: this.#local.platform });
+    this.reload();
+    for (const row of parsed) if (!this.#descriptors.has(row.id)) this.#descriptors.set(row.id, { id: row.id, name: row.name, transport: "http", status: "disconnected", capabilities: [] });
+  }
+  reload() {
+    if (!this.#reloadFromDisk) return;
+    const rows = loadBackendConnectionConfig(this.#configPath);
+    for (const id of this.#connections.keys()) if (!rows.some((row) => row.id === id)) {
+      this.#connections.delete(id);
+      this.#descriptors.delete(id);
+      this.#handshakes.delete(id);
+      this.#pins.delete(id);
+    }
+    for (const row of rows) {
+      const normalized = { ...row, url: endpoint(row.url).href };
+      const previous = this.#connections.get(row.id);
+      if (JSON.stringify(previous) !== JSON.stringify(normalized)) {
+        this.#connections.set(row.id, normalized);
+        this.#handshakes.delete(row.id);
+        this.#pins.delete(row.id);
+        this.#descriptors.set(row.id, { id: row.id, name: row.name, transport: "http", status: "disconnected", capabilities: [] });
+      }
+      {
+        try {
+          const value = readFileSync2(join2(homeStateDir(), "workers", `${row.id}.env`), "utf8");
+          const token = value.split("\n").find((line) => line.startsWith(`${row.bearerTokenEnv}=`))?.slice(row.bearerTokenEnv.length + 1);
+          if (token) this.#env[row.bearerTokenEnv] = backendBearerFromEnv(row.bearerTokenEnv, { [row.bearerTokenEnv]: token });
+        } catch {
+        }
+      }
+    }
+  }
+  /** Remove this dashboard's trusted connection; remote engine files are untouched. */
+  remove(id) {
+    id = BackendDescriptorSchema.shape.id.parse(id);
+    if (id === "local") throw new BackendConnectionError("The local engine cannot be removed.", 400);
+    if (!this.#reloadFromDisk) throw new BackendConnectionError("This backend registry is not persisted.", 409);
+    const rows = loadBackendConnectionConfig(this.#configPath);
+    const row = rows.find((value) => value.id === id);
+    if (!row) throw new BackendConnectionError("Backend is not registered.", 404);
+    const path = this.#configPath ?? join2(homeStateDir(), "backends.json");
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync2(temporary, `${JSON.stringify({ schemaVersion: 1, backends: rows.filter((value) => value.id !== id) }, null, 2)}
+`, { mode: 384, flag: "wx" });
+      renameSync(temporary, path);
+    } finally {
+      rmSync2(temporary, { force: true });
+    }
+    try {
+      stopManagedTunnel(loadManagedWorker(id));
+    } catch {
+    }
+    rmSync2(join2(homeStateDir(), "workers", `${id}.json`), { force: true });
+    rmSync2(join2(homeStateDir(), "workers", `${id}.env`), { force: true });
+    if (!rows.some((value) => value.id !== id && value.bearerTokenEnv === row.bearerTokenEnv)) delete this.#env[row.bearerTokenEnv];
+    this.#connections.delete(id);
+    this.#descriptors.delete(id);
+    this.#handshakes.delete(id);
+    this.#pins.delete(id);
+  }
+  list() {
+    return structuredClone([...this.#descriptors.values()]);
+  }
+  async handshake(id) {
+    if (id === "local") return { backend: this.list()[0], handshake: structuredClone(this.#local) };
+    if (!this.#connections.has(id)) throw new BackendConnectionError("Backend is not registered.", 404);
+    const pending = this.#pending.get(id);
+    if (pending) return pending;
+    const run = this.#probe(id);
+    this.#pending.set(id, run);
+    try {
+      return await run;
+    } finally {
+      this.#pending.delete(id);
+    }
+  }
+  async #probe(id) {
+    const row = this.#connections.get(id);
+    const descriptor = this.#descriptors.get(id);
+    descriptor.status = "connecting";
+    delete descriptor.error;
+    try {
+      const response = await this.#send(row, "/api/backend/handshake", {});
+      if (!response.ok) throw new BackendConnectionError("Backend handshake was rejected.", response.status === 401 || response.status === 403 ? 403 : 502);
+      const raw = BackendHandshakeSchema.parse(await response.json());
+      descriptor.protocolVersion = raw.protocolVersion;
+      if (raw.protocolVersion !== BACKEND_PROTOCOL_VERSION) {
+        descriptor.status = "incompatible";
+        throw new BackendConnectionError("Backend protocol is incompatible.", 409);
+      }
+      const pin = row.expectedEngineId ?? this.#pins.get(id);
+      if (pin && pin !== raw.engineId) {
+        descriptor.status = "incompatible";
+        throw new BackendConnectionError("Backend engine identity changed; review the trusted connection configuration.", 409);
+      }
+      this.#pins.set(id, raw.engineId);
+      this.#handshakes.set(id, { value: raw, at: Date.now() });
+      Object.assign(descriptor, { status: "connected", capabilities: raw.capabilities, platform: raw.platform });
+      return { backend: structuredClone(descriptor), handshake: raw };
+    } catch (error) {
+      if (descriptor.status !== "incompatible") descriptor.status = "disconnected";
+      descriptor.error = error instanceof BackendConnectionError ? error.message : "Backend connection failed.";
+      this.#handshakes.delete(id);
+      return { backend: structuredClone(descriptor), error: descriptor.error };
+    }
+  }
+  async request(id, path, options = {}) {
+    if (id === "local") throw new BackendConnectionError("Local requests must use the local engine adapter.", 400);
+    const row = this.#connections.get(id);
+    if (!row) throw new BackendConnectionError("Backend is not registered.", 404);
+    const canonical = apiPath(path);
+    const cached = this.#handshakes.get(id);
+    const view = cached && Date.now() - cached.at < 5e3 ? { backend: this.#descriptors.get(id) } : await this.handshake(id);
+    if (view.backend.status !== "connected") throw new BackendConnectionError(view.backend.error ?? "Backend is disconnected.", view.backend.status === "incompatible" ? 409 : 503);
+    for (const required of capabilities(canonical)) if (!view.backend.capabilities.includes(required)) throw new BackendConnectionError(`Backend does not support ${required}.`, 409);
+    try {
+      return await this.#send(row, canonical, options);
+    } catch (error) {
+      if (!options.signal?.aborted && (!(error instanceof BackendConnectionError) || error.statusCode >= 500 || error.statusCode === 409)) {
+        this.#descriptors.get(id).status = error instanceof BackendConnectionError && error.statusCode === 409 ? "incompatible" : "disconnected";
+        this.#handshakes.delete(id);
+      }
+      throw error;
+    }
+  }
+  async #send(row, path, options) {
+    if (this.#active >= 32) throw new BackendConnectionError("Backend request capacity exceeded.", 429);
+    this.#abort.signal.throwIfAborted();
+    const method = (options.method ?? "GET").toUpperCase();
+    if (!["GET", "HEAD", "POST", "PATCH", "DELETE", "PUT"].includes(method)) throw new BackendConnectionError("Backend method is not allowed.", 405);
+    const body = options.body === void 0 ? void 0 : JSON.stringify(options.body);
+    if (body !== void 0 && Buffer.byteLength(body) > MAX_BODY) throw new BackendConnectionError("Backend request body exceeds 1 MB.", 413);
+    const token = backendBearerFromEnv(row.bearerTokenEnv, this.#env);
+    const requestId = BackendRequestIdSchema.safeParse(options.requestId).success ? options.requestId : randomUUID();
+    const expectedEngineId = this.#pins.get(row.id) ?? row.expectedEngineId;
+    if (options.lastEventId !== void 0 && (options.lastEventId.length > 4096 || /[\x00-\x20\x7f]/.test(options.lastEventId))) throw new BackendConnectionError("Invalid event replay cursor.", 400);
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(new BackendConnectionError("Backend request timed out.", 504)), this.#timeoutMs);
+    const signal = AbortSignal.any([this.#abort.signal, timeout.signal, ...options.signal ? [options.signal] : []]);
+    this.#active++;
+    let retained = false;
+    try {
+      const url = new URL(`.${path}`, row.url);
+      const response = await this.#fetch(url, { method, body, redirect: "error", signal, headers: { Authorization: `Bearer ${token}`, Accept: options.stream ? "text/event-stream" : "application/json", ...body !== void 0 ? { "Content-Type": "application/json" } : {}, "X-0-Request-ID": requestId, ...expectedEngineId ? { "X-0-Expected-Engine-ID": expectedEngineId } : {}, ...options.stream && options.lastEventId ? { "Last-Event-ID": options.lastEventId } : {} } });
+      if (path !== "/api/backend/handshake" && expectedEngineId && response.headers.get("x-0-engine-id") !== expectedEngineId) {
+        await response.body?.cancel();
+        throw new BackendConnectionError("Backend response identity does not match the registered engine.", 409);
+      }
+      const type = response.headers.get("content-type") ?? "application/json";
+      if (type.includes("text/event-stream")) {
+        if (!options.stream || method !== "GET") {
+          await response.body?.cancel();
+          throw new BackendConnectionError("Unexpected event stream response.");
+        }
+        clearTimeout(timer);
+        const reader = response.body?.getReader();
+        let released = false;
+        let onAbort;
+        const release = () => {
+          if (!released) {
+            released = true;
+            this.#active--;
+            if (onAbort) signal.removeEventListener("abort", onAbort);
+          }
+        };
+        let eventBytes = 0;
+        let lineBytes = 0;
+        const body2 = reader ? new ReadableStream({
+          start: (controller) => {
+            onAbort = () => {
+              release();
+              void reader.cancel().catch(() => {
+              });
+              controller.error(new BackendConnectionError("Backend event connection closed.", 499));
+            };
+            if (signal.aborted) onAbort();
+            else signal.addEventListener("abort", onAbort, { once: true });
+          },
+          pull: async (controller) => {
+            try {
+              signal.throwIfAborted();
+              const next = await reader.read();
+              if (next.done) {
+                release();
+                controller.close();
+                return;
+              }
+              for (const byte of next.value) {
+                eventBytes++;
+                if (byte === 10) {
+                  if (lineBytes === 0) eventBytes = 0;
+                  lineBytes = 0;
+                } else if (byte !== 13) lineBytes++;
+                if (eventBytes > MAX_BODY) throw new BackendConnectionError("Backend event exceeds 1 MB.");
+              }
+              controller.enqueue(next.value);
+            } catch (error) {
+              release();
+              await reader.cancel().catch(() => {
+              });
+              controller.error(error);
+            }
+          },
+          cancel: async () => {
+            release();
+            await reader.cancel().catch(() => {
+            });
+          }
+        }) : null;
+        if (body2) retained = true;
+        return new Response(body2, { status: response.status, headers: { "Content-Type": type, "X-0-Request-ID": requestId, ...response.headers.get("x-0-engine-id") ? { "X-0-Engine-ID": response.headers.get("x-0-engine-id") } : {} } });
+      }
+      const data = await boundedResponse(response, MAX_RESPONSE, signal);
+      return new Response([204, 205, 304].includes(response.status) || method === "HEAD" ? null : data, { status: response.status, headers: { "Content-Type": type, ...attachmentHeaders(response.headers), "X-0-Request-ID": requestId, ...response.headers.get("x-0-engine-id") ? { "X-0-Engine-ID": response.headers.get("x-0-engine-id") } : {} } });
+    } catch (error) {
+      if (error instanceof BackendConnectionError) throw error;
+      if (timeout.signal.aborted) throw new BackendConnectionError("Backend request timed out.", 504);
+      if (options.signal?.aborted) throw new BackendConnectionError("Backend request disconnected.", 499);
+      throw new BackendConnectionError("Backend transport failed.");
+    } finally {
+      clearTimeout(timer);
+      if (!retained) this.#active--;
+    }
+  }
+  dispose() {
+    this.#abort.abort();
+  }
+};
+async function requestJson(req) {
+  let length = 0;
+  const chunks = [];
+  for await (const chunk of req) {
+    const buffer = Buffer.from(chunk);
+    length += buffer.length;
+    if (length > MAX_BODY) {
+      req.resume();
+      throw new BackendConnectionError("Backend request exceeds 1 MB.", 413);
+    }
+    chunks.push(buffer);
+  }
+  if (!length) return void 0;
+  try {
+    return JSON.parse(Buffer.concat(chunks, length).toString("utf8"));
+  } catch {
+    throw new BackendConnectionError("Backend request must contain valid JSON.", 400);
+  }
+}
+function attachmentHeaders(headers) {
+  const value = headers.get("content-disposition");
+  const match = value?.match(/^attachment;\s*filename="([A-Za-z0-9][A-Za-z0-9_.-]{0,159})"$/i);
+  return match ? { "Content-Disposition": `attachment; filename="${match[1]}"` } : {};
+}
+function json(res, status, value) {
+  res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+  res.end(JSON.stringify(value));
+}
+async function handleBackendConnectionRequest(req, res, url, registry) {
+  if (url.pathname === "/api/backends") {
+    if (req.method !== "GET") throw new BackendConnectionError("Backend registry is read-only.", 405);
+    registry.reload();
+    json(res, 200, { backends: registry.list() });
+    return { handled: true };
+  }
+  if (url.pathname === "/api/backend/handshake") {
+    if (req.method !== "GET") throw new BackendConnectionError("Method not allowed.", 405);
+    json(res, 200, (await registry.handshake("local")).handshake);
+    return { handled: true };
+  }
+  const removal = url.pathname.match(/^\/api\/backends\/([^/]+)$/);
+  if (removal) {
+    if (req.method !== "DELETE") throw new BackendConnectionError("Use DELETE to remove a backend registration.", 405);
+    registry.remove(decodeURIComponent(removal[1]));
+    json(res, 200, { removed: true, remoteEngineRemoved: false });
+    return { handled: true };
+  }
+  const match = url.pathname.match(/^\/api\/backends\/([^/]+)\/(handshake|proxy(?:\/.*)?)$/);
+  if (!match) return { handled: false };
+  const id = decodeURIComponent(match[1]);
+  if (match[2] === "handshake") {
+    if (req.method !== "GET") throw new BackendConnectionError("Method not allowed.", 405);
+    json(res, 200, await registry.handshake(id));
+    return { handled: true };
+  }
+  const path = apiPath(`${url.pathname.slice(url.pathname.indexOf("/proxy/") + "/proxy".length)}${url.search}`);
+  if (id === "local") return { handled: false, localPath: path };
+  const abort = new AbortController();
+  const disconnect = () => abort.abort();
+  req.once("aborted", disconnect);
+  res.once("close", disconnect);
+  try {
+    const body = ["GET", "HEAD"].includes(req.method ?? "GET") ? void 0 : await requestJson(req);
+    const stream = req.headers.accept?.includes("text/event-stream") === true;
+    const response = await registry.request(id, path, { method: req.method, body, stream, signal: abort.signal, lastEventId: typeof req.headers["last-event-id"] === "string" ? req.headers["last-event-id"] : void 0, requestId: typeof req.headers["x-0-request-id"] === "string" ? req.headers["x-0-request-id"] : void 0 });
+    if (res.destroyed) return { handled: true };
+    res.writeHead(response.status, { "Content-Type": response.headers.get("content-type") ?? "application/json", ...attachmentHeaders(response.headers), "Cache-Control": "no-store", "X-0-Request-ID": response.headers.get("x-0-request-id") ?? randomUUID(), ...response.headers.get("x-0-engine-id") ? { "X-0-Engine-ID": response.headers.get("x-0-engine-id") } : {}, "X-Content-Type-Options": "nosniff", ...stream ? { "X-Accel-Buffering": "no" } : {} });
+    if (!response.body) {
+      res.end();
+      return { handled: true };
+    }
+    const reader = response.body.getReader();
+    const onAbort = () => {
+      void reader.cancel().catch(() => {
+      });
+    };
+    abort.signal.addEventListener("abort", onAbort, { once: true });
+    try {
+      while (!abort.signal.aborted) {
+        const next = await reader.read();
+        if (next.done) break;
+        if (next.value.length > MAX_RESPONSE) throw new BackendConnectionError("Backend stream chunk exceeds the transport limit.");
+        if (!res.write(next.value)) await new Promise((resolve2) => {
+          const done = () => {
+            res.removeListener("drain", done);
+            res.removeListener("close", done);
+            resolve2();
+          };
+          res.once("drain", done);
+          res.once("close", done);
+        });
+      }
+      res.end();
+    } catch {
+      res.destroy();
+    } finally {
+      abort.signal.removeEventListener("abort", onAbort);
+      await reader.cancel().catch(() => {
+      });
+      reader.releaseLock();
+    }
+    return { handled: true };
+  } finally {
+    req.removeListener("aborted", disconnect);
+    res.removeListener("close", disconnect);
+  }
+}
+
+export {
+  validateWorkerOptions,
+  deployWorker,
+  loadManagedWorker,
+  stopWorker,
+  BackendConnectionError,
+  loadBackendConnectionConfig,
+  createBackendHandshake,
+  backendBearerFromEnv,
+  BackendConnectionRegistry,
+  handleBackendConnectionRequest
+};