agent-log-viewer 1.0.1 → 1.0.2

package/README.md

@@ -95,22 +95,25 @@ bunx agent-log-viewer
 npx agent-log-viewer
 ```
 
-This starts the server on `127.0.0.1:8898` and opens your browser. Both launch
-paths require Bun to be installed because the authoritative state stores use
-Bun SQLite.
+This starts the server on `127.0.0.1:8898` and opens your browser. The CLI also
+starts and supervises the packaged structured runtime host, including restart
+backoff and Ctrl-C cleanup. Pipelines and the orchestrator work from this
+installation without Docker. Both launch paths require Bun because the runtime
+journal and authoritative state stores use Bun SQLite.
 
 ### From a local clone
 
 ```bash
 bun install
 bun run build
-bun run start -- --port 8898 --hostname 127.0.0.1
+bun bin/cli.mjs --no-open --port 8898 --hostname 127.0.0.1
 # open http://127.0.0.1:8898/
 ```
 
-`start` serves the output of the last `build`, so run `build` first. For
-development, `bun dev` runs the app with hot reload (it needs a high OS
-file-watch limit for large home directories).
+The CLI serves the output of the last `build`, so run `build` first. For
+development, `bun dev` runs the app with hot reload and expects a separately
+managed runtime host (it needs a high OS file-watch limit for large home
+directories).
 
 The Viewer server runs on Bun. The runtime journal and hot state collections
 use `bun:sqlite`, and macOS process ownership uses the kernel's microsecond
@@ -119,20 +122,15 @@ feature-flag configuration.
 
 ### Spawn transport
 
-Agents launch through a structured runtime host — no tmux pane between the
-Viewer and the agent — wherever a deployment can serve one. The transport is
-chosen by capability: a deployment that declares `LLV_RUNTIME_HOST_SOCKET`
-spawns structured, and one without a host still spawns through tmux instead of
-failing. Structured hosting itself is on by default; `LLV_STRUCTURED_HOSTS=0`,
-`LLV_RUNTIME_EVENTS=0`, and `NEXT_PUBLIC_RUNTIME_UI=0` are rollback switches.
-Each of the three sends the implicit choice back to tmux, so reaching for one
-during an incident never costs the ability to spawn. They accept the spellings
-an env file actually produces — `0`, `" 0 "`, `'0'`, `false`, `off`, `no` — and
-an unset variable means the default is on.
-
-`LLV_SPAWN_TRANSPORT=tmux|structured` overrides the choice. An explicit
-`structured` without a reachable host returns a gap naming what is missing
-rather than quietly downgrading the request.
+Agents launch through a structured runtime host. The installed CLI supervises
+that host with the same Bun executable as the Viewer and places its Unix socket
+and runtime journal under the Viewer state directory with installation-specific
+names. Ambient deployment runtime settings are ignored so separate bunx
+installations cannot attach to each other's host or claim each other's journal
+epoch. Startup fails clearly when Bun, the packaged host entry, the managed
+socket, or its directory permissions are unavailable.
+The CLI log carries the host failure and the pipeline card directs the operator
+to it. There is no tmux fallback.
 
 ### Connect an orchestrator through MCP
 

package/bin/cli.mjs

@@ -3,16 +3,18 @@
 import { spawn } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync } from "node:fs";
 import http from "node:http";
+import net from "node:net";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { detectTailscale, getToken, readStatus, serve as serveTailscale, TailscaleError } from "./tailscale.mjs";
 import {
+  cliRuntimeHostConfig,
+  cliRuntimeHostEnvironment,
   discardWakatimeEnvironmentCredential,
   viewerChildProcessOptions,
   viewerServerBunRuntime,
-  withoutWakatimeCredential,
 } from "./server-runtime.mjs";
 
 discardWakatimeEnvironmentCredential();
@@ -27,6 +29,11 @@ const READINESS_INTERVAL_MS = 200;
 // Reusing READINESS_INTERVAL_MS here made every probe abort before the healthy
 // server could answer, so startup always "timed out" and killed its own server.
 const READINESS_PROBE_TIMEOUT_MS = 5_000;
+const RUNTIME_HOST_READINESS_TIMEOUT_MS = 15_000;
+const RUNTIME_HOST_READINESS_INTERVAL_MS = 100;
+const RUNTIME_HOST_RESTART_BASE_MS = 500;
+const RUNTIME_HOST_RESTART_MAX_MS = 10_000;
+const RUNTIME_HOST_STABLE_UPTIME_MS = 30_000;
 
 const cliPath = fileURLToPath(import.meta.url);
 const cliDir = dirname(cliPath);
@@ -73,6 +80,13 @@ Options:
     tsCookie: () => "  After the first open the key is stored in a cookie for 30 days.",
     nonLocalWarn: () => "Warning: a non-local address exposes the viewer to the network, so access-key mode is forced on.",
     serverNotReady: () => "Server not ready.",
+    runtimeHostEntryMissing: () => "The runtime host is missing from this install. Reinstall agent-log-viewer and try again.",
+    runtimeHostStartFail: (detail) => `Couldn't start the structured runtime host: ${detail}`,
+    runtimeHostTimeout: (socketPath) => `the runtime host did not bind ${socketPath} within ${RUNTIME_HOST_READINESS_TIMEOUT_MS / 1_000} seconds; check the socket directory permissions`,
+    runtimeHostExited: (detail) => `the runtime host exited before its socket was ready${detail ? `: ${detail}` : ""}`,
+    runtimeHostOwnerMismatch: (ownerPid, childPid) => `the runtime host socket is owned by pid ${ownerPid}, while this CLI spawned pid ${childPid}; stop the other agent-log-viewer instance for this installation and try again`,
+    runtimeHostRestart: (delay, detail) => `[runtime host] ${detail}; restarting in ${delay}ms`,
+    runtimeHostRestartFail: (detail) => `[runtime host] restart failed: ${detail}`,
   },
   uk: {
     usage: () => `Використання: agent-log-viewer [опції]
@@ -104,6 +118,13 @@ Options:
     tsCookie: () => "  Після першого відкриття ключ зберігається у cookie на 30 днів.",
     nonLocalWarn: () => "Увага: нелокальна адреса відкриває viewer для мережі, тому режим ключа доступу увімкнено примусово.",
     serverNotReady: () => "Сервер не готовий.",
+    runtimeHostEntryMissing: () => "У цьому пакеті немає runtime host. Перевстановіть agent-log-viewer і повторіть спробу.",
+    runtimeHostStartFail: (detail) => `Не вдалося запустити structured runtime host: ${detail}`,
+    runtimeHostTimeout: (socketPath) => `runtime host не створив ${socketPath} за ${RUNTIME_HOST_READINESS_TIMEOUT_MS / 1_000} секунд; перевірте права каталогу сокета`,
+    runtimeHostExited: (detail) => `runtime host завершився до готовності сокета${detail ? `: ${detail}` : ""}`,
+    runtimeHostOwnerMismatch: (ownerPid, childPid) => `сокетом runtime host володіє процес ${ownerPid}, а цей CLI запустив процес ${childPid}; зупиніть інший agent-log-viewer для цієї інсталяції та повторіть спробу`,
+    runtimeHostRestart: (delay, detail) => `[runtime host] ${detail}; повторний запуск за ${delay} мс`,
+    runtimeHostRestartFail: (detail) => `[runtime host] помилка повторного запуску: ${detail}`,
   },
 };
 
@@ -255,9 +276,9 @@ function resolveServer(packageRoot) {
   };
 }
 
-function buildChildEnv(options, runtime, packageRoot) {
+function buildChildEnv(options, runtime, packageRoot, runtimeHostEnvironment) {
   const env = {
-    ...withoutWakatimeCredential(process.env),
+    ...runtimeHostEnvironment,
     PORT: String(options.port),
     // zsh exports HOSTNAME with the machine name on this user's machine; setting it here keeps standalone bound to the requested address.
     HOSTNAME: options.hostname,
@@ -306,10 +327,10 @@ function buildChildEnv(options, runtime, packageRoot) {
   return env;
 }
 
-function startServer(server, options, runtime, tailscaleProcessRef, packageRoot) {
+function startServer(server, options, runtime, tailscaleProcessRef, runtimeHostSupervisor, packageRoot, runtimeHostEnvironment) {
   const child = spawn(server.command, server.args, viewerChildProcessOptions({
     cwd: server.cwd,
-    env: buildChildEnv(options, runtime, packageRoot),
+    env: buildChildEnv(options, runtime, packageRoot, runtimeHostEnvironment),
     stdio: ["ignore", "inherit", "pipe"],
   }));
 
@@ -333,7 +354,11 @@ function startServer(server, options, runtime, tailscaleProcessRef, packageRoot)
   });
 
   child.on("error", (error) => {
-    fail(m.serverStartFail(error.message));
+    state.stopping = true;
+    void Promise.all([
+      tailscaleProcessRef?.current ? stopChild(tailscaleProcessRef.current) : Promise.resolve(),
+      runtimeHostSupervisor.stop(),
+    ]).finally(() => fail(m.serverStartFail(error.message)));
   });
 
   child.on("exit", async (code, signal) => {
@@ -348,6 +373,7 @@ function startServer(server, options, runtime, tailscaleProcessRef, packageRoot)
     if (tailscaleProcessRef?.current) {
       await stopChild(tailscaleProcessRef.current);
     }
+    await runtimeHostSupervisor.stop();
 
     if (state.sawAddressInUse) {
       process.exit(1);
@@ -369,6 +395,156 @@ function wait(ms) {
   });
 }
 
+function probeRuntimeHost(socketPath) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection(socketPath);
+    let settled = false;
+    const finish = (ready) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(ready);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.setTimeout(1_000, () => finish(false));
+  });
+}
+
+function runtimeHostFenceOwner(socketPath) {
+  try {
+    const owner = JSON.parse(readFileSync(`${socketPath}.lock`, "utf8"));
+    if (!Number.isSafeInteger(owner?.pid) || owner.pid <= 1) return null;
+    if (typeof owner.startIdentity !== "string" || !owner.startIdentity.startsWith(`${owner.pid}:`)) return null;
+    if (typeof owner.acquisitionId !== "string" || owner.acquisitionId.length < 16) return null;
+    return owner;
+  } catch {
+    return null;
+  }
+}
+
+function runtimeHostExitDetail(processHandle) {
+  const { child, state } = processHandle;
+  if (state.spawnError) {
+    return state.spawnError.code === "ENOENT"
+      ? `Bun executable ${state.command} is unavailable (${state.spawnError.message})`
+      : `Bun could not launch the host (${state.spawnError.message})`;
+  }
+  const outcome = child.signalCode ? `signal ${child.signalCode}` : `exit code ${child.exitCode ?? "unknown"}`;
+  const stderr = state.stderrTail
+    .split(/\r?\n/)
+    .map((line) => line.replace(/\s+/g, " ").trim())
+    .filter(Boolean)
+    .slice(-3)
+    .join(" | ");
+  return stderr ? `${outcome}: ${stderr}` : outcome;
+}
+
+async function waitForRuntimeHost(socketPath, processHandle = null) {
+  const deadline = Date.now() + RUNTIME_HOST_READINESS_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (processHandle?.state.spawnError) {
+      throw new Error(runtimeHostExitDetail(processHandle));
+    }
+    if (processHandle && (processHandle.child.exitCode !== null || processHandle.child.signalCode !== null)) {
+      throw new Error(m.runtimeHostExited(runtimeHostExitDetail(processHandle)));
+    }
+    if (await probeRuntimeHost(socketPath)) {
+      const owner = runtimeHostFenceOwner(socketPath);
+      if (!processHandle) return;
+      if (owner?.pid === processHandle.child.pid) return;
+      if (owner) throw new Error(m.runtimeHostOwnerMismatch(owner.pid, processHandle.child.pid));
+    }
+    await wait(RUNTIME_HOST_READINESS_INTERVAL_MS);
+  }
+  throw new Error(m.runtimeHostTimeout(socketPath));
+}
+
+function createRuntimeHostSupervisor(config, bunRuntime, environment, packageRoot) {
+  let current = null;
+  let restartTimer = null;
+  let restartFailures = 0;
+  let stopping = false;
+
+  const scheduleRestart = (detail, uptimeMs = 0) => {
+    if (stopping || restartTimer) return;
+    restartFailures = uptimeMs >= RUNTIME_HOST_STABLE_UPTIME_MS ? 1 : restartFailures + 1;
+    const delay = Math.min(
+      RUNTIME_HOST_RESTART_BASE_MS * (2 ** Math.max(0, restartFailures - 1)),
+      RUNTIME_HOST_RESTART_MAX_MS,
+    );
+    console.error(m.runtimeHostRestart(delay, detail));
+    restartTimer = setTimeout(() => {
+      restartTimer = null;
+      void launch(false).catch((error) => {
+        if (stopping) return;
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(m.runtimeHostRestartFail(message));
+        scheduleRestart(message);
+      });
+    }, delay);
+  };
+
+  const spawnHost = () => {
+    const child = spawn(bunRuntime, ["--bun", config.entrypoint], viewerChildProcessOptions({
+      cwd: packageRoot,
+      env: environment,
+      stdio: ["ignore", "inherit", "pipe"],
+    }));
+    const state = {
+      command: bunRuntime,
+      readyAt: null,
+      spawnError: null,
+      stderrTail: "",
+      stopping: false,
+    };
+    const processHandle = { child, state };
+    current = processHandle;
+    child.stderr.on("data", (chunk) => {
+      state.stderrTail = `${state.stderrTail}${chunk}`.slice(-8_192);
+      process.stderr.write(chunk);
+    });
+    child.once("error", (error) => {
+      state.spawnError = error;
+    });
+    child.once("exit", () => {
+      if (current !== processHandle || stopping || state.stopping || state.readyAt === null) return;
+      scheduleRestart(runtimeHostExitDetail(processHandle), Date.now() - state.readyAt);
+    });
+    return processHandle;
+  };
+
+  const launch = async (initial) => {
+    const processHandle = spawnHost();
+    try {
+      await waitForRuntimeHost(config.socketPath, processHandle);
+      processHandle.state.readyAt = Date.now();
+      if (processHandle.child.exitCode !== null || processHandle.child.signalCode !== null) {
+        throw new Error(m.runtimeHostExited(runtimeHostExitDetail(processHandle)));
+      }
+    } catch (error) {
+      await stopChild(processHandle);
+      if (initial) throw error;
+      throw error;
+    }
+  };
+
+  return {
+    async start() {
+      if (!existsSync(config.entrypoint)) throw new Error(m.runtimeHostEntryMissing());
+      await launch(true);
+    },
+    async stop() {
+      stopping = true;
+      if (restartTimer) {
+        clearTimeout(restartTimer);
+        restartTimer = null;
+      }
+      if (current) await stopChild(current);
+    },
+  };
+}
+
 function probe(url) {
   return new Promise((resolve) => {
     const request = http.get(url, (response) => {
@@ -477,16 +653,17 @@ async function stopChild(processHandle) {
   });
 }
 
-async function stopAll(serverProcess, tailscaleProcess) {
+async function stopAll(serverProcess, tailscaleProcess, runtimeHostSupervisor) {
   await Promise.all([
     serverProcess ? stopChild(serverProcess) : Promise.resolve(),
     tailscaleProcess ? stopChild(tailscaleProcess) : Promise.resolve(),
+    runtimeHostSupervisor ? runtimeHostSupervisor.stop() : Promise.resolve(),
   ]);
 }
 
-function installSignalHandlers(serverProcess, tailscaleProcessRef) {
+function installSignalHandlers(serverProcess, tailscaleProcessRef, runtimeHostSupervisor) {
   const shutdown = async () => {
-    await stopAll(serverProcess, tailscaleProcessRef.current);
+    await stopAll(serverProcess, tailscaleProcessRef.current, runtimeHostSupervisor);
     process.exit(0);
   };
 
@@ -626,9 +803,32 @@ async function main() {
   }
 
   const server = resolveServer(packageRoot);
+  const runtimeHostConfig = cliRuntimeHostConfig(packageRoot);
+  const runtimeHostEnvironment = cliRuntimeHostEnvironment(process.env, runtimeHostConfig);
+  const runtimeHostSupervisor = createRuntimeHostSupervisor(
+    runtimeHostConfig,
+    viewerServerBunRuntime(),
+    runtimeHostEnvironment,
+    packageRoot,
+  );
+  try {
+    await runtimeHostSupervisor.start();
+  } catch (error) {
+    await runtimeHostSupervisor.stop();
+    fail(m.runtimeHostStartFail(error instanceof Error ? error.message : String(error)));
+  }
+
   const tailscaleProcessRef = { current: null };
-  const serverProcess = startServer(server, options, runtime, tailscaleProcessRef, packageRoot);
-  installSignalHandlers(serverProcess, tailscaleProcessRef);
+  const serverProcess = startServer(
+    server,
+    options,
+    runtime,
+    tailscaleProcessRef,
+    runtimeHostSupervisor,
+    packageRoot,
+    runtimeHostEnvironment,
+  );
+  installSignalHandlers(serverProcess, tailscaleProcessRef, runtimeHostSupervisor);
 
   if (options.tailscale && runtime.tailscalePath) {
     tailscaleProcessRef.current = serveTailscale(runtime.tailscalePath, options.port);
@@ -637,7 +837,7 @@ async function main() {
   try {
     await waitForReadiness(options.port);
   } catch (error) {
-    await stopAll(serverProcess, tailscaleProcessRef.current);
+    await stopAll(serverProcess, tailscaleProcessRef.current, runtimeHostSupervisor);
     fail(error instanceof Error ? error.message : m.serverNotReady());
   }
 

package/bin/server-runtime.mjs

@@ -1,3 +1,8 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
 export const WAKATIME_CREDENTIAL_ENV = "WAKATIME_API_KEY";
 
 /** @param {Record<string, string | undefined>} environment */
@@ -51,3 +56,49 @@ export function viewerServerBunRuntime(options = {}) {
   const execPath = options.execPath ?? process.execPath;
   return versions.bun ? execPath : (env.LLV_BUN_EXECUTABLE || "bun");
 }
+
+/**
+ * Resolve the runtime host the public CLI will supervise. Ordinary package
+ * installs share the Viewer state directory while retaining distinct socket
+ * and journal ownership. Ambient deployment runtime configuration never
+ * crosses this CLI ownership boundary.
+ *
+ * @param {string} packageRoot
+ * @param {{ env?: Readonly<Record<string, string | undefined>>, home?: string }} [options]
+ */
+export function cliRuntimeHostConfig(packageRoot, options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? homedir();
+  const stateDirectory = env.LLV_STATE_DIR?.trim()
+    || join(env.XDG_CONFIG_HOME?.trim() || join(home, ".config"), "agent-log-viewer", "state");
+  const installId = createHash("sha256").update(resolve(packageRoot)).digest("hex").slice(0, 16);
+  const bundled = join(packageRoot, "dist", "runtime-host.mjs");
+  const source = join(packageRoot, "src", "runtime-host", "main.ts");
+  return {
+    socketPath: join(stateDirectory, `runtime-host-${installId}.sock`),
+    journalPath: join(stateDirectory, `runtime-events-${installId}.sqlite`),
+    entrypoint: existsSync(bundled) ? bundled : source,
+  };
+}
+
+/**
+ * Environment shared by the supervised runtime host and the Viewer server.
+ * The CLI is the structured-host activation boundary, including for callers
+ * whose shell still carries one of the former rollback values. Its journal
+ * follows the same installation boundary as its socket, so a CLI host cannot
+ * claim an ambient deployment's host epoch through the shared state directory.
+ *
+ * @param {Readonly<Record<string, string | undefined>>} base
+ * @param {{ socketPath: string, journalPath: string }} config
+ */
+export function cliRuntimeHostEnvironment(base, config) {
+  return {
+    ...withoutWakatimeCredential(base),
+    LLV_RUNTIME_HOST_SOCKET: config.socketPath,
+    LLV_RUNTIME_JOURNAL: config.journalPath,
+    LLV_STRUCTURED_HOSTS: "1",
+    LLV_RUNTIME_EVENTS: "1",
+    LLV_SPAWN_TRANSPORT: "structured",
+    NEXT_PUBLIC_RUNTIME_UI: "1",
+  };
+}

package/bin/server-runtime.test.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import fs from "node:fs";
+import net from "node:net";
 import os from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -10,8 +11,11 @@ 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 { RuntimeHostFence } from "@/runtime-host/runtimeHostFence";
 
 import {
+  cliRuntimeHostConfig,
+  cliRuntimeHostEnvironment,
   structuredHostsEnabled as structuredHostsEnabledInLauncher,
   viewerServerBunRuntime,
   viewerChildProcessOptions,
@@ -19,6 +23,192 @@ import {
   withoutWakatimeCredential,
 } from "./server-runtime.mjs";
 
+async function availablePort(): Promise<number> {
+  const server = net.createServer();
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("could not reserve a launcher test port");
+  await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  return address.port;
+}
+
+test("the CLI derives a distinct managed runtime host for each install", () => {
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), "llv-runtime-package-"));
+  const firstPackageRoot = path.join(sandbox, "first");
+  const secondPackageRoot = path.join(sandbox, "second");
+  const stateDirectory = path.join(sandbox, "state");
+  const ambientSocket = path.join(sandbox, "operator-runtime.sock");
+  const ambientJournal = path.join(sandbox, "operator-runtime.sqlite");
+  const firstBundle = path.join(firstPackageRoot, "dist", "runtime-host.mjs");
+  const secondBundle = path.join(secondPackageRoot, "dist", "runtime-host.mjs");
+  fs.mkdirSync(path.dirname(firstBundle), { recursive: true });
+  fs.mkdirSync(path.dirname(secondBundle), { recursive: true });
+  fs.writeFileSync(firstBundle, "export {};\n");
+  fs.writeFileSync(secondBundle, "export {};\n");
+  try {
+    const options = {
+      env: {
+        LLV_STATE_DIR: stateDirectory,
+        LLV_RUNTIME_HOST_SOCKET: ambientSocket,
+        LLV_RUNTIME_JOURNAL: ambientJournal,
+      },
+      home: path.join(sandbox, "home"),
+    };
+    const first = cliRuntimeHostConfig(firstPackageRoot, options);
+    const second = cliRuntimeHostConfig(secondPackageRoot, options);
+
+    expect(first.entrypoint).toBe(firstBundle);
+    expect(second.entrypoint).toBe(secondBundle);
+    expect(path.dirname(first.socketPath)).toBe(stateDirectory);
+    expect(path.dirname(second.socketPath)).toBe(stateDirectory);
+    expect(path.basename(first.socketPath)).toMatch(/^runtime-host-[a-f0-9]{16}\.sock$/);
+    expect(path.basename(second.socketPath)).toMatch(/^runtime-host-[a-f0-9]{16}\.sock$/);
+    expect(path.dirname(first.journalPath)).toBe(stateDirectory);
+    expect(path.dirname(second.journalPath)).toBe(stateDirectory);
+    expect(path.basename(first.journalPath)).toMatch(/^runtime-events-[a-f0-9]{16}\.sqlite$/);
+    expect(path.basename(second.journalPath)).toMatch(/^runtime-events-[a-f0-9]{16}\.sqlite$/);
+    expect(first.socketPath).not.toBe(second.socketPath);
+    expect(first.journalPath).not.toBe(second.journalPath);
+    expect(first.socketPath).not.toBe(ambientSocket);
+    expect(second.socketPath).not.toBe(ambientSocket);
+    expect(first.journalPath).not.toBe(ambientJournal);
+    expect(second.journalPath).not.toBe(ambientJournal);
+  } finally {
+    fs.rmSync(sandbox, { recursive: true, force: true });
+  }
+});
+
+test("the CLI uses the source runtime host in a checkout", () => {
+  const packageRoot = fs.mkdtempSync(path.join(os.tmpdir(), "llv-runtime-source-"));
+  const source = path.join(packageRoot, "src", "runtime-host", "main.ts");
+  const stateDirectory = path.join(packageRoot, "state");
+  fs.mkdirSync(path.dirname(source), { recursive: true });
+  fs.writeFileSync(source, "export {};\n");
+  try {
+    const config = cliRuntimeHostConfig(packageRoot, {
+      env: { LLV_STATE_DIR: stateDirectory },
+      home: path.join(packageRoot, "home"),
+    });
+    expect(config.entrypoint).toBe(source);
+    expect(path.dirname(config.socketPath)).toBe(stateDirectory);
+    expect(path.dirname(config.journalPath)).toBe(stateDirectory);
+  } finally {
+    fs.rmSync(packageRoot, { recursive: true, force: true });
+  }
+});
+
+test("the CLI runtime environment owns its socket and journal and strips ambient WakaTime credentials", () => {
+  const socketPath = "/runtime/viewer.sock";
+  const journalPath = "/runtime/viewer.sqlite";
+  const env: Record<string, string | undefined> = cliRuntimeHostEnvironment({
+    PATH: "/usr/bin",
+    LLV_RUNTIME_HOST_SOCKET: "/runtime/operator.sock",
+    LLV_RUNTIME_JOURNAL: "/runtime/operator.sqlite",
+    LLV_STRUCTURED_HOSTS: "off",
+    LLV_RUNTIME_EVENTS: "0",
+    LLV_SPAWN_TRANSPORT: "tmux",
+    NEXT_PUBLIC_RUNTIME_UI: "0",
+    [WAKATIME_CREDENTIAL_ENV]: "fixture-value",
+  }, { socketPath, journalPath });
+
+  expect(env).toMatchObject({
+    PATH: "/usr/bin",
+    LLV_RUNTIME_HOST_SOCKET: socketPath,
+    LLV_RUNTIME_JOURNAL: journalPath,
+    LLV_STRUCTURED_HOSTS: "1",
+    LLV_RUNTIME_EVENTS: "1",
+    LLV_SPAWN_TRANSPORT: "structured",
+    NEXT_PUBLIC_RUNTIME_UI: "1",
+  });
+  expect(env[WAKATIME_CREDENTIAL_ENV]).toBeUndefined();
+});
+
+test("the CLI rejects a ready runtime socket owned by another process", async () => {
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), "llv-runtime-incumbent-"));
+  const packageRoot = path.resolve(import.meta.dir, "..");
+  const stateDirectory = path.join(sandbox, "state");
+  const environment: Record<string, string | undefined> = {
+    ...process.env,
+    HOME: path.join(sandbox, "home"),
+    XDG_CONFIG_HOME: path.join(sandbox, "config"),
+    LLV_STATE_DIR: stateDirectory,
+    TMPDIR: path.join(sandbox, "tmp"),
+    LLV_LANG: "en",
+    LLV_RUNTIME_HOST_FENCE_WAIT_MS: "0",
+  };
+  const socketPath = cliRuntimeHostConfig(packageRoot, { env: environment, home: environment.HOME }).socketPath;
+  const fence = new RuntimeHostFence(`${socketPath}.lock`);
+  const listener = net.createServer((socket) => socket.end());
+  fs.mkdirSync(environment.HOME!, { recursive: true });
+  fs.mkdirSync(environment.XDG_CONFIG_HOME!, { recursive: true });
+  fs.mkdirSync(environment.TMPDIR!, { recursive: true });
+  fence.acquire();
+  await new Promise<void>((resolve, reject) => {
+    listener.once("error", reject);
+    listener.listen(socketPath, resolve);
+  });
+
+  const child = Bun.spawn([
+    process.execPath,
+    "--bun",
+    path.join(import.meta.dir, "cli.mjs"),
+    "--no-open",
+    "--port",
+    String(await availablePort()),
+  ], { cwd: packageRoot, env: environment, stdout: "pipe", stderr: "pipe" });
+  try {
+    const [exitCode, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Couldn't start the structured runtime host");
+    expect(stderr).toContain(`runtime host socket is owned by pid ${process.pid}`);
+    expect(stderr).toContain("stop the other agent-log-viewer instance");
+  } finally {
+    if (!child.killed) child.kill();
+    await new Promise<void>((resolve, reject) => listener.close((error) => error ? reject(error) : resolve()));
+    fence.release();
+    fs.rmSync(sandbox, { recursive: true, force: true });
+  }
+}, 10_000);
+
+test("the CLI names a missing Bun prerequisite before starting the Viewer", async () => {
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), "llv-runtime-missing-bun-"));
+  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 launcher prerequisite test requires Node");
+  const environment: Record<string, string | undefined> = {
+    ...process.env,
+    PATH: nodeSearchPath,
+    HOME: path.join(sandbox, "home"),
+    XDG_CONFIG_HOME: path.join(sandbox, "config"),
+    LLV_STATE_DIR: path.join(sandbox, "state"),
+    TMPDIR: path.join(sandbox, "tmp"),
+    LLV_BUN_EXECUTABLE: path.join(sandbox, "missing-bun"),
+  };
+  delete environment.LLV_RUNTIME_HOST_SOCKET;
+  const child = Bun.spawn([
+    nodeExecutable,
+    path.join(import.meta.dir, "cli.mjs"),
+    "--no-open",
+    "--port",
+    String(await availablePort()),
+  ], { cwd: path.resolve(import.meta.dir, ".."), env: environment, stdout: "pipe", stderr: "pipe" });
+  try {
+    const [exitCode, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Couldn't start the structured runtime host");
+    expect(stderr).toContain("Bun executable");
+    expect(stderr).toContain("is unavailable");
+  } finally {
+    fs.rmSync(sandbox, { recursive: true, force: true });
+  }
+}, 10_000);
+
 test("structured hosts select Bun for a CLI process launched by Node", () => {
   expect(viewerServerBunRuntime({
     env: { LLV_STRUCTURED_HOSTS: "1" },