agent-log-viewer 0.11.7 → 1.0.1

package/bin/mcp-server.test.ts

@@ -0,0 +1,266 @@
+import { afterEach, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const sandboxes: string[] = [];
+
+afterEach(() => {
+  for (const sandbox of sandboxes.splice(0)) fs.rmSync(sandbox, { recursive: true, force: true });
+});
+
+function installedPackage(serverSource = `
+  process.stdout.write(JSON.stringify({ bun: process.versions.bun ?? null }) + "\\n");
+  process.stdin.pipe(process.stdout);
+`): { root: string; launcher: string } {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "llv-installed-mcp-"));
+  sandboxes.push(root);
+  fs.mkdirSync(path.join(root, "bin"), { recursive: true });
+  fs.mkdirSync(path.join(root, "dist"), { recursive: true });
+  fs.copyFileSync(path.join(import.meta.dir, "mcp-server.mjs"), path.join(root, "bin", "mcp-server.mjs"));
+  fs.copyFileSync(path.join(import.meta.dir, "server-runtime.mjs"), path.join(root, "bin", "server-runtime.mjs"));
+  fs.writeFileSync(path.join(root, "dist", "mcp-server.mjs"), serverSource, "utf8");
+  return { root, launcher: path.join(root, "bin", "mcp-server.mjs") };
+}
+
+async function launchInstalled(env: Record<string, string>): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const { root, launcher } = installedPackage();
+  return launchFrom(root, launcher, env, "initialize-handshake\n");
+}
+
+async function launchFrom(
+  root: string,
+  launcher: string,
+  env: Record<string, string>,
+  input: string,
+  runtime: "node" | "bun" = "node",
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const node = Bun.which("node");
+  const bun = Bun.which("bun");
+  if (!node || !bun) throw new Error("Node and Bun are required for the launcher test");
+  const child = Bun.spawn({
+    cmd: [runtime === "bun" ? bun : node, launcher],
+    cwd: root,
+    env: { ...process.env, ...env, LLV_BUN_EXECUTABLE: bun },
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  child.stdin.write(input);
+  child.stdin.end();
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ]);
+  return { exitCode, stdout, stderr };
+}
+
+test("fresh Claude and Codex hosts load the exact MCP runtime named by the promoted release", async () => {
+  const previousRevision = "8".repeat(40);
+  const candidateRevision = "7".repeat(40);
+  const { root, launcher } = installedPackage(`
+    process.stdout.write(JSON.stringify({
+      revision: "${previousRevision}",
+      tools: ["deploy_exact_sha", "get_pipeline"],
+      host: process.env.LLV_TEST_HOST,
+    }) + "\\n");
+    process.stdin.pipe(process.stdout);
+  `);
+  const stateDir = path.join(root, "state");
+  const releaseId = `deploy-${candidateRevision}`;
+  const releaseRoot = path.join(stateDir, "mcp-runtime", "releases", releaseId);
+  const candidateBundle = `
+    process.stdout.write(JSON.stringify({
+      revision: "${candidateRevision}",
+      tools: ["deployment_status", "board_snapshot"],
+      host: process.env.LLV_TEST_HOST,
+      hotStateRevision: process.env.LLV_HOT_STATE_RELEASE_REVISION,
+    }) + "\\n");
+    process.stdin.pipe(process.stdout);
+  `;
+  fs.mkdirSync(path.join(releaseRoot, "dist"), { recursive: true });
+  fs.writeFileSync(path.join(releaseRoot, "dist", "mcp-server.mjs"), candidateBundle, "utf8");
+  const targetFile = path.join(root, "targets", "viewer-release.json");
+  fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+  fs.writeFileSync(targetFile, JSON.stringify({
+    revision: candidateRevision,
+    image: `viewer:${candidateRevision}`,
+    container: "viewer-candidate",
+    endpoint: "http://127.0.0.1:18001",
+    mcpRuntime: {
+      source: "managed",
+      revision: candidateRevision,
+      releaseId,
+      artifactDigest: createHash("sha256").update(candidateBundle).digest("hex"),
+      stagedAt: "2026-07-23T08:00:00.000Z",
+    },
+  }), "utf8");
+
+  for (const host of ["claude", "codex"]) {
+    const result = await launchFrom(root, launcher, {
+      LLV_TEST_HOST: host,
+      LLV_STATE_DIR: stateDir,
+      LLV_VIEWER_DEPLOY_TARGET: targetFile,
+    }, `${host}-initialize\n`, "bun");
+    expect(result).toMatchObject({ exitCode: 0, stderr: "" });
+    const [runtime, handshake] = result.stdout.trim().split("\n");
+    expect(JSON.parse(runtime!)).toEqual({
+      revision: candidateRevision,
+      tools: ["deployment_status", "board_snapshot"],
+      host,
+      hotStateRevision: candidateRevision,
+    });
+    expect(handshake).toBe(`${host}-initialize`);
+  }
+}, 15_000);
+
+test("a fresh host rejects a managed MCP runtime whose bundle differs from the published digest", async () => {
+  const revision = "7".repeat(40);
+  const { root, launcher } = installedPackage();
+  const stateDir = path.join(root, "state");
+  const releaseId = `deploy-${revision}`;
+  const releaseRoot = path.join(stateDir, "mcp-runtime", "releases", releaseId);
+  fs.mkdirSync(path.join(releaseRoot, "dist"), { recursive: true });
+  fs.writeFileSync(path.join(releaseRoot, "dist", "mcp-server.mjs"), "process.stdout.write('tampered\\n');", "utf8");
+  const targetFile = path.join(stateDir, "viewer-release.json");
+  fs.writeFileSync(targetFile, JSON.stringify({
+    revision,
+    image: `viewer:${revision}`,
+    container: "viewer-candidate",
+    endpoint: "http://127.0.0.1:18001",
+    mcpRuntime: {
+      source: "managed",
+      revision,
+      releaseId,
+      artifactDigest: "a".repeat(64),
+      stagedAt: "2026-07-23T08:00:00.000Z",
+    },
+  }), "utf8");
+
+  const result = await launchFrom(root, launcher, {
+    LLV_STATE_DIR: stateDir,
+    LLV_VIEWER_DEPLOY_TARGET: targetFile,
+  }, "", "bun");
+  expect(result.exitCode).toBe(1);
+  expect(result.stdout).toBe("");
+  expect(result.stderr).toContain("MCP runtime bundle digest does not match the active release");
+});
+
+test("an existing malformed release target fails closed instead of loading the legacy runtime", async () => {
+  const { root, launcher } = installedPackage("process.stdout.write('legacy\\n');");
+  const stateDir = path.join(root, "state");
+  const targetFile = path.join(stateDir, "viewer-release.json");
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(targetFile, "{}\n", "utf8");
+
+  const result = await launchFrom(root, launcher, {
+    LLV_STATE_DIR: stateDir,
+    LLV_VIEWER_DEPLOY_TARGET: targetFile,
+  }, "", "bun");
+  expect(result.exitCode).toBe(1);
+  expect(result.stdout).toBe("");
+  expect(result.stderr).toContain("active Viewer release target is invalid");
+});
+
+test("the installed MCP launcher selects Bun for Bun-only Viewer configuration and preserves stdio", async () => {
+  const configurations: Record<string, string>[] = [
+    { LLV_AGENT_REGISTRY_SQLITE: "read" },
+    { LLV_STRUCTURED_HOSTS: "1" },
+  ];
+  for (const env of configurations) {
+    const result = await launchInstalled(env);
+    expect(result).toMatchObject({ exitCode: 0, stderr: "" });
+    const [runtime, handshake] = result.stdout.trim().split("\n");
+    expect(JSON.parse(runtime!)).toMatchObject({ bun: expect.any(String) });
+    expect(handshake).toBe("initialize-handshake");
+  }
+}, 15_000);
+
+test("the installed MCP launcher forwards termination to its Bun child", async () => {
+  const readyPath = path.join(os.tmpdir(), `llv-mcp-ready-${crypto.randomUUID()}`);
+  const signalPath = path.join(os.tmpdir(), `llv-mcp-signal-${crypto.randomUUID()}`);
+  sandboxes.push(readyPath, signalPath);
+  const { root, launcher } = installedPackage(`
+    const fs = await import("node:fs");
+    fs.writeFileSync(process.env.LLV_TEST_READY, "ready\\n", "utf8");
+    process.once("SIGTERM", () => {
+      fs.writeFileSync(process.env.LLV_TEST_SIGNAL, "SIGTERM\\n", "utf8");
+      process.exit(0);
+    });
+    setInterval(() => {}, 1_000);
+  `);
+  const node = Bun.which("node");
+  const bun = Bun.which("bun");
+  if (!node || !bun) throw new Error("Node and Bun are required for the launcher test");
+  const child = Bun.spawn({
+    cmd: [node, launcher],
+    cwd: root,
+    env: {
+      ...process.env,
+      LLV_STRUCTURED_HOSTS: "1",
+      LLV_BUN_EXECUTABLE: bun,
+      LLV_TEST_READY: readyPath,
+      LLV_TEST_SIGNAL: signalPath,
+    },
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const deadline = Date.now() + 5_000;
+  while (!fs.existsSync(readyPath)) {
+    if (Date.now() >= deadline) throw new Error("timed out waiting for the Bun MCP child");
+    await Bun.sleep(5);
+  }
+  child.kill("SIGTERM");
+  await child.exited;
+  expect(fs.readFileSync(signalPath, "utf8")).toBe("SIGTERM\n");
+}, 15_000);
+
+test("the installed MCP launcher forwards escalating signals until its Bun child exits", async () => {
+  const readyPath = path.join(os.tmpdir(), `llv-mcp-ready-${crypto.randomUUID()}`);
+  const signalPath = path.join(os.tmpdir(), `llv-mcp-signals-${crypto.randomUUID()}`);
+  sandboxes.push(readyPath, signalPath);
+  const { root, launcher } = installedPackage(`
+    const fs = await import("node:fs");
+    fs.writeFileSync(process.env.LLV_TEST_READY, "ready\\n", "utf8");
+    process.on("SIGINT", () => fs.appendFileSync(process.env.LLV_TEST_SIGNAL, "SIGINT\\n", "utf8"));
+    process.on("SIGTERM", () => {
+      fs.appendFileSync(process.env.LLV_TEST_SIGNAL, "SIGTERM\\n", "utf8");
+      process.exit(0);
+    });
+    setTimeout(() => process.exit(7), 1_500);
+    setInterval(() => {}, 1_000);
+  `);
+  const node = Bun.which("node");
+  const bun = Bun.which("bun");
+  if (!node || !bun) throw new Error("Node and Bun are required for the launcher test");
+  const child = Bun.spawn({
+    cmd: [node, launcher],
+    cwd: root,
+    env: {
+      ...process.env,
+      LLV_STRUCTURED_HOSTS: "1",
+      LLV_BUN_EXECUTABLE: bun,
+      LLV_TEST_READY: readyPath,
+      LLV_TEST_SIGNAL: signalPath,
+    },
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const deadline = Date.now() + 5_000;
+  while (!fs.existsSync(readyPath)) {
+    if (Date.now() >= deadline) throw new Error("timed out waiting for the Bun MCP child");
+    await Bun.sleep(5);
+  }
+  child.kill("SIGINT");
+  while (!fs.existsSync(signalPath) || !fs.readFileSync(signalPath, "utf8").includes("SIGINT\n")) {
+    if (Date.now() >= deadline) throw new Error("timed out waiting for SIGINT forwarding");
+    await Bun.sleep(5);
+  }
+  child.kill("SIGTERM");
+  const exitCode = await child.exited;
+  const stderr = await new Response(child.stderr).text();
+  expect({ exitCode, stderr }).toEqual({ exitCode: 0, stderr: "" });
+  expect(fs.readFileSync(signalPath, "utf8")).toBe("SIGINT\nSIGTERM\n");
+}, 15_000);

package/bin/provision-telegram-connector.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * Provisions the packaged Telegram connector environment (issue #1059).
+ *
+ * Builds the Viewer-owned Python venv from the vendored pinned source
+ * (`vendor/telegram-mcp`, see its PROVENANCE.md) with `uv sync --frozen`, so a
+ * clean installation can start the connector without a manual clone and
+ * without ever resolving the poisoned `telegram-mcp` PyPI name.
+ *
+ * Ships in `bin/` with the published package (npm `files`), dependency-free,
+ * so an installed `agent-log-viewer` can run it directly:
+ *
+ *   node bin/provision-telegram-connector.mjs      # or: bun run telegram:provision
+ *
+ * Environment (same contract as src/lib/telegram/packaging.ts):
+ *   LLV_TELEGRAM_VENDOR_DIR  vendored tree (default: <package>/vendor/telegram-mcp)
+ *   LLV_STATE_DIR            viewer state root (default: $XDG_CONFIG_HOME/agent-log-viewer/state)
+ *   LLV_TELEGRAM_PYTHON      expected venv python (default: <state>/telegram/venv/bin/python)
+ */
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const UV_BOOTSTRAP_VERSION = "0.7.13";
+const MAX_UV_ARCHIVE_BYTES = 64 * 1024 * 1024;
+const UV_DOWNLOAD_TIMEOUT_MS = 120_000;
+const UV_SELF_CHECK_TIMEOUT_MS = 10_000;
+const CONNECTOR_PROVISION_TIMEOUT_MS = 10 * 60_000;
+const UV_RELEASES = Object.freeze({
+  "darwin-arm64": { triple: "aarch64-apple-darwin", sha256: "721f532b73171586574298d4311a91d5ea2c802ef4db3ebafc434239330090c6" },
+  "darwin-x64": { triple: "x86_64-apple-darwin", sha256: "d785753ac092e25316180626aa691c5dfe1fb075290457ba4fdb72c7c5661321" },
+  "linux-arm64-gnu": { triple: "aarch64-unknown-linux-gnu", sha256: "0b2ad9fe4295881615295add8cc5daa02549d29cc9a61f0578e397efcf12f08f" },
+  "linux-arm64-musl": { triple: "aarch64-unknown-linux-musl", sha256: "52baba71881c978d32b7c32216ad0cde4546a4dc62e606c9834ec4616c1610eb" },
+  "linux-x64-gnu": { triple: "x86_64-unknown-linux-gnu", sha256: "909278eb197c5ed0e9b5f16317d1255270d1f9ea4196e7179ce934d48c4c2545" },
+  "linux-x64-musl": { triple: "x86_64-unknown-linux-musl", sha256: "560bb64e060354e45138d7dd47c8dd48a4f7a349af5520d29cd3c704e79f286c" },
+});
+
+function usesGlibc() {
+  return Boolean(process.report?.getReport?.().header?.glibcVersionRuntime);
+}
+
+export function uvReleaseFor(platform = process.platform, arch = process.arch, glibc = usesGlibc()) {
+  const libc = platform === "linux" ? (glibc ? "-gnu" : "-musl") : "";
+  const release = UV_RELEASES[`${platform}-${arch}${libc}`];
+  if (!release) throw new Error(`unsupported uv bootstrap target ${platform}-${arch}${libc}`);
+  const asset = `uv-${release.triple}.tar.gz`;
+  return {
+    ...release,
+    asset,
+    url: `https://github.com/astral-sh/uv/releases/download/${UV_BOOTSTRAP_VERSION}/${asset}`,
+  };
+}
+
+function ownerOnlyDirectory(pathname) {
+  if (!existsSync(pathname)) mkdirSync(pathname, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(pathname);
+  if (stat.isSymbolicLink() || !stat.isDirectory() || (stat.mode & 0o077) !== 0
+    || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+    throw new Error("telegram state directory is not owner-only");
+  }
+}
+
+function commandRuns(command) {
+  const result = spawnSync(command, ["--version"], { stdio: "ignore", timeout: UV_SELF_CHECK_TIMEOUT_MS });
+  return !result.error && result.status === 0;
+}
+
+export async function installPinnedUv(toolsDir, options = {}) {
+  const release = options.release || uvReleaseFor();
+  const fetcher = options.fetcher || fetch;
+  ownerOnlyDirectory(toolsDir);
+  const destination = join(toolsDir, "uv");
+  if (existsSync(destination)) {
+    const existing = lstatSync(destination);
+    if (existing.isSymbolicLink() || !existing.isFile() || (existing.mode & 0o077) !== 0
+      || (typeof process.getuid === "function" && existing.uid !== process.getuid())) {
+      throw new Error("installed uv executable is unsafe");
+    }
+    if (commandRuns(destination)) return destination;
+    throw new Error("installed uv executable failed its self-check");
+  }
+
+  const installDir = join(toolsDir, `.uv-install-${process.pid}-${randomUUID()}`);
+  const archive = join(installDir, release.asset);
+  mkdirSync(installDir, { mode: 0o700 });
+  try {
+    const response = await fetcher(release.url, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(UV_DOWNLOAD_TIMEOUT_MS),
+    });
+    if (!response.ok) throw new Error(`uv download failed with HTTP ${response.status}`);
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_UV_ARCHIVE_BYTES) throw new Error("uv archive is oversized");
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length === 0 || bytes.length > MAX_UV_ARCHIVE_BYTES) throw new Error("uv archive has an invalid size");
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== release.sha256) throw new Error("uv archive checksum mismatch");
+    writeFileSync(archive, bytes, { mode: 0o600 });
+    const extracted = spawnSync("tar", ["-xzf", archive, "-C", installDir], { stdio: "ignore" });
+    if (extracted.error || extracted.status !== 0) throw new Error("uv archive extraction failed");
+    const source = join(installDir, `uv-${release.triple}`, "uv");
+    if (!existsSync(source)) throw new Error("uv archive did not contain the expected executable");
+    chmodSync(source, 0o700);
+    renameSync(source, destination);
+    chmodSync(destination, 0o700);
+    if (!commandRuns(destination)) throw new Error("installed uv executable failed its self-check");
+    return destination;
+  } finally {
+    rmSync(installDir, { recursive: true, force: true });
+  }
+}
+
+export async function provisionTelegramConnector(env = process.env) {
+  const vendorDir = env.LLV_TELEGRAM_VENDOR_DIR || join(packageRoot, "vendor", "telegram-mcp");
+  const stateDir = env.LLV_STATE_DIR
+    || join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "agent-log-viewer", "state");
+  const venvDir = join(stateDir, "telegram", "venv");
+  const venvPython = env.LLV_TELEGRAM_PYTHON || join(venvDir, "bin", "python");
+  const telegramStateDir = dirname(venvDir);
+  if (!existsSync(join(vendorDir, "pyproject.toml"))) throw new Error("vendored connector is unavailable");
+  ownerOnlyDirectory(telegramStateDir);
+
+  const uvCommand = await installPinnedUv(join(telegramStateDir, "tools"));
+  /* The packaged tree can sit on a read-only filesystem (#1081), while the
+     vendored runtime's supply-chain guard requires running from a source
+     checkout and setuptools writes build metadata into the project dir. So:
+     stage a writable owner-only copy at a STABLE path, editable-install from
+     it, and keep it — the connector runs from this copy (#1084). */
+  const sourceDir = join(telegramStateDir, "vendor-src");
+  const incoming = join(telegramStateDir, `.vendor-src-${process.pid}-${randomUUID()}`);
+  try {
+    cpSync(vendorDir, incoming, { recursive: true });
+    chmodSync(incoming, 0o700);
+    rmSync(sourceDir, { recursive: true, force: true });
+    renameSync(incoming, sourceDir);
+  } finally {
+    rmSync(incoming, { recursive: true, force: true });
+  }
+
+  const result = spawnSync(uvCommand, ["sync", "--frozen", "--no-dev", "--project", sourceDir], {
+    cwd: sourceDir,
+    env: { ...env, UV_PROJECT_ENVIRONMENT: venvDir },
+    stdio: "inherit",
+    timeout: CONNECTOR_PROVISION_TIMEOUT_MS,
+    killSignal: "SIGKILL",
+  });
+  const failed = () => {
+    /* A partial venv must never pass a later provisioned check (#1084). */
+    rmSync(venvDir, { recursive: true, force: true });
+    rmSync(sourceDir, { recursive: true, force: true });
+  };
+  if (result.error || result.status !== 0) {
+    failed();
+    throw new Error("connector dependency provisioning failed");
+  }
+  if (!existsSync(venvPython)) {
+    failed();
+    throw new Error("provisioning completed without a Python executable");
+  }
+  /* Success is a verified import, recorded durably — bare venv existence has
+     already lied once (#1084). */
+  const probe = spawnSync(venvPython, ["-c", "import telethon, telegram_mcp"], {
+    stdio: "ignore",
+    timeout: UV_SELF_CHECK_TIMEOUT_MS * 6,
+  });
+  if (probe.error || probe.status !== 0) {
+    failed();
+    throw new Error("provisioned environment failed its import probe");
+  }
+  writeFileSync(join(venvDir, ".llv-provisioned"), "ok\n", { mode: 0o600 });
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  provisionTelegramConnector().catch((error) => {
+    console.error("telegram connector provisioning failed:", error instanceof Error ? error.message : "unknown error");
+    process.exitCode = 1;
+  });
+}

package/bin/server-runtime.mjs

@@ -0,0 +1,53 @@
+export const WAKATIME_CREDENTIAL_ENV = "WAKATIME_API_KEY";
+
+/** @param {Record<string, string | undefined>} environment */
+export function discardWakatimeEnvironmentCredential(environment = process.env) {
+  delete environment[WAKATIME_CREDENTIAL_ENV];
+}
+
+/**
+ * @param {Readonly<Record<string, string | undefined>>} base
+ * @returns {Record<string, string | undefined>}
+ */
+export function withoutWakatimeCredential(base) {
+  const env = { NODE_ENV: base.NODE_ENV };
+  for (const key of Object.keys(base)) {
+    if (key === WAKATIME_CREDENTIAL_ENV) continue;
+    env[key] = base[key];
+  }
+  return env;
+}
+
+/**
+ * @param {Record<string, unknown> & { env?: Readonly<Record<string, string | undefined>> }} options
+ */
+export function viewerChildProcessOptions(options = {}) {
+  return {
+    ...options,
+    env: withoutWakatimeCredential(options.env ?? process.env),
+  };
+}
+
+/**
+ * Mirror of `structuredHostsEnabled` (and its rollback normalisation) from
+ * `src/lib/runtime/flags.ts`. `bin/` is plain JS outside the TS build and
+ * cannot import that module, so `bin/server-runtime.test.ts` pins both readers
+ * to one truth table. Structured hosting and the authoritative hot-state
+ * collections use Bun SQLite. The hot-state requirement applies in every
+ * feature-flag configuration, so the packaged launcher always selects Bun.
+ *
+ * @param {Readonly<Record<string, string | undefined>>} [env]
+ */
+export function structuredHostsEnabled(env = process.env) {
+  const raw = env.LLV_STRUCTURED_HOSTS;
+  if (raw === undefined) return true;
+  const normalized = raw.trim().replace(/^(["'])([\s\S]*)\1$/, "$2").trim().toLowerCase();
+  return !(normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no");
+}
+
+export function viewerServerBunRuntime(options = {}) {
+  const env = options.env ?? process.env;
+  const versions = options.versions ?? process.versions;
+  const execPath = options.execPath ?? process.execPath;
+  return versions.bun ? execPath : (env.LLV_BUN_EXECUTABLE || "bun");
+}

package/bin/server-runtime.test.ts

@@ -0,0 +1,161 @@
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { Database } from "bun:sqlite";
+import { expect, test } from "bun:test";
+
+import { loadFlows } from "@/lib/flows/store";
+import { loadArchivedPipelines, loadPipelines } from "@/lib/pipelines/store";
+import { structuredHostsEnabled as structuredHostsEnabledInApp } from "@/lib/runtime/flags";
+import { loadWorkflows } from "@/lib/workflows/store";
+
+import {
+  structuredHostsEnabled as structuredHostsEnabledInLauncher,
+  viewerServerBunRuntime,
+  viewerChildProcessOptions,
+  WAKATIME_CREDENTIAL_ENV,
+  withoutWakatimeCredential,
+} from "./server-runtime.mjs";
+
+test("structured hosts select Bun for a CLI process launched by Node", () => {
+  expect(viewerServerBunRuntime({
+    env: { LLV_STRUCTURED_HOSTS: "1" },
+    versions: { node: "20.9.0" },
+    execPath: "/usr/bin/node",
+  })).toBe("bun");
+  expect(viewerServerBunRuntime({
+    env: { LLV_STRUCTURED_HOSTS: "1", LLV_BUN_EXECUTABLE: "/opt/bun/bin/bun" },
+    versions: { node: "20.9.0" },
+    execPath: "/usr/bin/node",
+  })).toBe("/opt/bun/bin/bun");
+});
+
+test("the packaged helper makes the same structured-runtime choice under Node", () => {
+  const helper = path.join(path.dirname(fileURLToPath(import.meta.url)), "server-runtime.mjs");
+  const nodeSearchPath = (process.env.PATH ?? "")
+    .split(path.delimiter)
+    .filter((directory) => !path.basename(directory).startsWith("bun-node-"))
+    .join(path.delimiter);
+  const nodeExecutable = Bun.which("node", { PATH: nodeSearchPath });
+  if (!nodeExecutable) throw new Error("the packaged runtime test requires Node");
+  const probe = Bun.spawnSync([
+    nodeExecutable,
+    "--input-type=module",
+    "--eval",
+    `import { viewerServerBunRuntime } from ${JSON.stringify(pathToFileURL(helper).href)}; process.stdout.write(String(viewerServerBunRuntime()));`,
+  ], {
+    env: { ...process.env, PATH: nodeSearchPath, LLV_STRUCTURED_HOSTS: "1", LLV_BUN_EXECUTABLE: "/verified/bun" },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  expect(probe.exitCode).toBe(0);
+  expect(probe.stdout.toString()).toBe("/verified/bun");
+});
+
+/* Structured hosting is on by default, and it genuinely needs Bun (`bun:sqlite`
+   journal, kernel start tokens on macOS). A launcher that still keyed on a
+   literal "1" would run the default configuration under Node — where startup
+   adoption throws the Darwin runtime requirement and the release controllers
+   never start. */
+test("an unset structured-hosts variable still selects Bun for the launcher", () => {
+  expect(viewerServerBunRuntime({
+    env: {},
+    versions: { node: "20.9.0" },
+    execPath: "/usr/bin/node",
+  })).toBe("bun");
+});
+
+/* `bin/` is plain JS outside the TS build, so its predicate is a copy. This
+   pins the copy to the original: one truth table, both readers. */
+test.each([
+  [undefined],
+  [""],
+  ["1"],
+  ["0"],
+  [" 0 "],
+  ["\"0\""],
+  ["'0'"],
+  ["false"],
+  ["OFF"],
+  ["no"],
+  ["yes"],
+] as const)("the launcher mirror and the app definition agree on %p", (value) => {
+  const env = value === undefined ? {} : { LLV_STRUCTURED_HOSTS: value };
+  expect(structuredHostsEnabledInLauncher(env)).toBe(structuredHostsEnabledInApp(env));
+  expect(viewerServerBunRuntime({ env, versions: { node: "20.9.0" }, execPath: "/usr/bin/node" }))
+    .toBe("bun");
+});
+
+test("hot SQLite stores select Bun when optional Bun features are disabled", () => {
+  expect(viewerServerBunRuntime({
+    env: { LLV_AGENT_REGISTRY_SQLITE: "off", LLV_STRUCTURED_HOSTS: "0" },
+    versions: { node: "20.9.0" },
+    execPath: "/usr/bin/node",
+  })).toBe("bun");
+});
+
+test("documented development and production scripts pin Bun and open every hot collection", () => {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8")) as {
+    engines: Record<string, string>;
+    scripts: Record<string, string>;
+  };
+  expect(packageJson.engines.bun).toBeTruthy();
+  expect(packageJson.scripts.dev).toContain("bun --bun");
+  expect(packageJson.scripts.start).toContain("bun --bun");
+
+  const previous = process.env.LLV_STATE_DIR;
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), "llv-bun-startup-"));
+  process.env.LLV_STATE_DIR = sandbox;
+  try {
+    expect(loadFlows()).toEqual([]);
+    expect(loadPipelines()).toEqual([]);
+    expect(loadArchivedPipelines()).toEqual([]);
+    expect(loadWorkflows()).toEqual([]);
+    const db = new Database(path.join(sandbox, "state.sqlite"), { readonly: true, strict: true });
+    const collections = db.query<{ collection: string }, []>("SELECT collection FROM state_collections ORDER BY collection").all();
+    db.close();
+    expect(collections.map((row) => row.collection)).toEqual(["flows", "pipelines", "pipelines_archive", "workflows"]);
+  } finally {
+    if (previous === undefined) delete process.env.LLV_STATE_DIR;
+    else process.env.LLV_STATE_DIR = previous;
+    fs.rmSync(sandbox, { recursive: true, force: true });
+  }
+});
+
+test("Viewer child processes receive no ambient WakaTime key material", () => {
+  const placeholder = ["child", "fixture", "value"].join("-");
+  const env = withoutWakatimeCredential({
+    PATH: process.env.PATH,
+    KEEP_ME: "kept",
+    [WAKATIME_CREDENTIAL_ENV]: placeholder,
+  });
+  const probe = Bun.spawnSync([
+    process.execPath,
+    "--eval",
+    "process.stdout.write(JSON.stringify({ keep: process.env.KEEP_ME, key: process.env.WAKATIME_API_KEY ?? null }))",
+  ], { env, stdout: "pipe", stderr: "pipe" });
+
+  expect(probe.exitCode).toBe(0);
+  expect(JSON.parse(probe.stdout.toString())).toEqual({ keep: "kept", key: null });
+  expect(JSON.stringify(env)).not.toContain(placeholder);
+});
+
+test("published launcher child options capture no ambient WakaTime key material", () => {
+  const placeholder = ["launcher", "fixture", "value"].join("-");
+  const options = viewerChildProcessOptions({
+    cwd: "/viewer",
+    env: {
+      PATH: process.env.PATH,
+      KEEP_ME: "kept",
+      [WAKATIME_CREDENTIAL_ENV]: placeholder,
+    },
+    stdio: "ignore",
+  });
+
+  expect(options.env.KEEP_ME).toBe("kept");
+  expect(options.env[WAKATIME_CREDENTIAL_ENV]).toBeUndefined();
+  expect(JSON.stringify(options)).not.toContain(placeholder);
+});