agent-log-viewer 0.11.7 → 1.0.1

package/README.md

@@ -1,30 +1,67 @@
-# Live Log Viewer
+# Agent Log Viewer
 
 `agent-log-viewer` is a local web UI that turns raw Codex / Claude Code agent
 logs into a readable, live-updating chat feed. It discovers every session,
 subagent and background shell task on your machine, links them into a
 parent→child tree, and tails the selected one in real time.
 
-Everything runs locally against files already on disk. There is no database and
-no external service — the app reads `~/.claude` and `~/.codex` and renders what
-it finds.
+![From the overview board into a session and its live tail](docs/media/board-to-live-tail.gif)
+
+The default setup runs locally against transcripts already on disk. It reads
+`~/.claude` and `~/.codex` directly, while operational Viewer state is kept in
+a local SQLite database under its private configuration directory.
+Optional outbound integrations stay disabled until you configure them:
+
+```bash
+bunx agent-log-viewer   # or: npx agent-log-viewer
+```
+
+See [WakaTime activity integration](docs/wakatime.md) for opt-in activity
+export, its disclosure boundary, and disablement steps.
+
+Prefer video? A 45-second cut of the full flow lives at
+[docs/media/demo.mp4](docs/media/demo.mp4).
+
+## The tour
+
+### Read any session as a chat
+
+User bubbles, assistant prose, tool-call cards with ✓/✗ statuses, expandable
+command output and diffs — for **Claude Code** sessions and their subagents
+(`~/.claude/projects/**/*.jsonl`), **Codex CLI** rollouts
+(`~/.codex/sessions/**/rollout-*.jsonl`) with command cards, patches and
+service events, and **background shell tasks** (recovered from the transcript
+and shown above the terminal output).
 
 ![The chat feed: user bubbles, assistant prose, and tool-call cards with
 statuses and expandable output](docs/media/chat-feed.png)
 
-## What it shows
+### Spawn agents from the board
+
+Each project is a pannable, zoomable scheme — root conversations on top,
+spawned agents one generation below, arrows colored by engine. Draft a new
+agent right on the board: pick Claude or Codex, a model and reasoning effort,
+type the first prompt, and it launches into tmux.
+
+![Drafting and configuring a new agent on the project board](docs/media/spawn-agent.gif)
 
-- **Claude Code sessions** (`~/.claude/projects/**/*.jsonl`) and their
-  subagents, rendered as a chat: user bubbles, assistant prose, tool-call
-  cards with ✓/✗ statuses and expandable output.
-- **Codex CLI sessions** (`~/.codex/sessions/**/rollout-*.jsonl`) with command
-  cards, patches and service events.
-- **Background shell tasks** (`claude-<uid>/**/tasks/*.output` under the OS
-  temp dir — `/tmp` on Linux, `$TMPDIR` on macOS) — the originating Bash
-  command is recovered from the session transcript and shown above the
-  terminal output.
+### Run implement → review loops
 
-## Highlights
+The viewer orchestrates review cycles: a long-lived implementer in tmux, a
+fresh read-only reviewer each round over the full diff, findings relayed
+automatically, and a verdict deck in the scheme view.
+
+![A review loop: round 1 requested changes, round 2 re-checks live](docs/media/review-loop.gif)
+
+### Answer a blocked agent from the browser
+
+When an agent stops on an `AskUserQuestion`, the question surfaces as a card
+with clickable options. The answer is delivered into the agent's tmux pane and
+confirmed against the transcript — the agent just keeps going.
+
+![Answering a pending AskUserQuestion from the feed](docs/media/pending-question.gif)
+
+### And everything around it
 
 - **Parentage tree**: session → subagents → rollouts → background tasks, built
   server-side by scanning transcripts (append-only incremental,
@@ -33,15 +70,10 @@ statuses and expandable output](docs/media/chat-feed.png)
   it is mid-turn and *done* once the final assistant message lands.
 - **Deep links**: every selection is reflected in the URL (`#f=<path>`), so a
   link opens that exact log.
-- **Project scheme**: each project is a pannable, zoomable diagram — the root
-  conversation on top, spawned agents one generation below, arrows colored by
-  engine. Quiet branches and tasks collapse under their nearest ancestor.
-- **English or Ukrainian UI**, model chips (`fable-5`, `gpt-5.5`, `sonnet`…),
+- **English or Ukrainian UI**, model chips (`opus`, `gpt-5.6-sol`, `sonnet`…),
   collapsible tree with persisted state, follow-mode autoscroll, service-event
   toggle, and a line filter.
 
-## Screenshots
-
 The session parentage tree, wiring root conversations to their spawned agents:
 
 ![Session parentage tree](docs/media/session-tree.png)
@@ -50,9 +82,12 @@ The session parentage tree, wiring root conversations to their spawned agents:
 | --- | --- |
 | ![Codex session with command cards and patches](docs/media/codex-session.png) | ![Overview board across projects](docs/media/overview-board.png) |
 
+All media above is regenerated deterministically from a synthetic fixture —
+see [docs/media/README.md](docs/media/README.md).
+
 ## Run
 
-The package is published to npm, so the quickstart needs no clone:
+The package is published to npm, so the quickstart above needs no clone:
 
 ```bash
 bunx agent-log-viewer
@@ -60,30 +95,153 @@ bunx agent-log-viewer
 npx agent-log-viewer
 ```
 
-This starts the server on `127.0.0.1:8898` and opens your browser.
+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.
 
 ### From a local clone
 
-With bun:
-
 ```bash
 bun install
 bun run build
-bun start --port 8898 --hostname 127.0.0.1
+bun run start -- --port 8898 --hostname 127.0.0.1
 # open http://127.0.0.1:8898/
 ```
 
-With npm (note the `--` that forwards flags to the start script):
+`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 Viewer server runs on Bun. The runtime journal and hot state collections
+use `bun:sqlite`, and macOS process ownership uses the kernel's microsecond
+start token. The Docker runtime and `agent-log-viewer` CLI select Bun for every
+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.
+
+### Connect an orchestrator through MCP
+
+The package includes `agent-log-viewer-mcp`, a local stdio MCP server. It
+invokes Viewer services in-process and shares their durable stores, locks, and
+idempotency rules. Keep the Viewer package and the MCP process under the same
+OS user so they resolve the same state directory.
+
+For an installed package, add this server to the orchestrator's standard MCP
+configuration:
+
+```json
+{
+  "mcpServers": {
+    "viewer": {
+      "command": "agent-log-viewer-mcp"
+    }
+  }
+}
+```
+
+For a local clone, point the client at the launcher:
+
+```json
+{
+  "mcpServers": {
+    "viewer": {
+      "command": "bun",
+      "args": ["/absolute/path/to/live-log-viewer-next/bin/mcp-server.mjs"]
+    }
+  }
+}
+```
+
+Quick install from the CLI:
 
 ```bash
-npm install
-npm run build
-npm start -- --port 8898 --hostname 127.0.0.1
+# Claude Code (user scope)
+claude mcp add viewer -s user -- bun /absolute/path/to/live-log-viewer-next/bin/mcp-server.mjs
+
+# Codex — append to ~/.codex/config.toml
+[mcp_servers.viewer]
+command = "bun"
+args = ["/absolute/path/to/live-log-viewer-next/bin/mcp-server.mjs"]
 ```
 
-`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).
+To register the server everywhere at once — the operator's Claude Code and
+Codex configs plus every Viewer-managed account under
+`~/.config/agent-log-viewer/accounts` (their spawned agents each run with
+their own `CLAUDE_CONFIG_DIR`/`CODEX_HOME`, so each account needs its own
+registration) — run the idempotent installer and re-run it after adding
+accounts:
+
+```bash
+scripts/install-mcp.sh                     # uses the managed stable launcher when present
+LLV_MCP_BIN=/path/to/mcp-server.mjs \
+  scripts/install-mcp.sh                   # select an explicit launcher
+```
+
+Exact deployments keep the managed executable at
+`~/.agents/tools/llv-mcp-runtime/bin/mcp-server.mjs`. Existing Claude and
+Codex registrations retain that path. Each fresh MCP process reads the atomic
+Viewer release target and starts the runtime bundle staged from the same
+revision. Deployment receipts expose the staged runtime digest plus durable
+activation or restore evidence.
+
+The server name must stay `viewer` (or another `isViewerMcpServer()` match:
+`viewer-*`, `agent-log-viewer*`) — transcript calls attributed to other names
+do not render as Viewer cards.
+
+The MCP surface includes:
+
+- conversations and the board: `board_snapshot`, `list_conversations`,
+  `get_conversation`, `send_message`, and `conversation_action` for
+  `interrupt`, `kill`, `resume`, `compact`, and `dialog-key`;
+- review flows: `list_flows`, `get_flow`, and `flow_action`;
+- pipelines: `create_pipeline`, `list_pipelines`, `get_pipeline`,
+  `pipeline_action`, and `link_task_to_pipeline`;
+- tasks: `create_task`, `list_tasks`, `get_task`, and `update_task`;
+- operator/runtime reads: `operator_snapshot`, `deployment_status`, and
+  `resources`;
+- agent liveness and lifecycle: `agent_activity` for the per-conversation
+  `{lastRecordAt, turnState, host alive/gone, stalledForMs}` stall snapshot, and
+  `lifecycle_events` for the durable lifecycle journal (`mode: "query"`, by
+  project/pipeline/conversation and cursor) and its bounded relay digest
+  (`mode: "digest"`, terminal events immediately, routine progress coalesced and
+  rate-limited to one per five minutes per subscriber);
+- agent/runtime mutations: `spawn_agent`, `conversation_migration`, and
+  `deploy_exact_sha`;
+- the operator's attention: `request_attention`, which offers to move their
+  Viewer to a target and waits for their answer. It only asks — nothing moves
+  until they agree on a device, and the request names the root agent by an
+  identity the server resolves, never one the caller supplies.
+
+Every call requires a stable `clientRequestId`. Reusing that id with the same
+arguments returns the durable result as a replay. Reusing it with different
+arguments returns an idempotency conflict. Read tools are inert, bounded, and
+secret-redacted. Mutating tools return stable operation receipts, and their
+durable MCP receipt prevents a replay from applying the action twice.
+`deploy_exact_sha` accepts a full 40-character commit SHA and requires
+`confirm: "deploy"`.
+
+The package exposes the MCP launcher as `agent-log-viewer/mcp-server` in
+addition to the `agent-log-viewer-mcp` executable.
+
+Tool results contain the durable entity identifiers available for that action,
+including conversation ids, transcript paths, pipeline ids, task ids, and
+runtime operation ids. Viewer transcripts render calls attributed to the `viewer` MCP
+server as live cards and turn those identifiers into navigation chips.
 
 **Prerequisites:** Node ≥ 20.9, and bun or npm/pnpm. `tmux` is optional — see
 [Platform support](#platform-support).
@@ -91,18 +249,33 @@ file-watch limit for large home directories).
 ### Docker (reproducible runtime)
 
 For a pinned, reproducible deployment the repo ships a `Dockerfile` and
-`docker-compose.yml` that build `.next` inside the image and run the viewer
-with host parity (the container reuses your real `tmux`, `claude`, `codex` and
-home directory). This is how the maintainer's own prod instance runs.
+`docker-compose.yml` that build `.next` inside the image and run the Viewer
+with host parity. The container reuses your real `tmux`, `claude`, `codex`, and
+home directory. Runtime-host owns production releases and the listener.
+Complete the [bootstrap listener migration](docs/docker.md#bootstrap-listener-ownership)
+before the first runtime-host activation.
 
 ```bash
-docker compose up -d viewer          # prod on 127.0.0.1:8898, restarts on reboot
+export LLV_DOCKER_GID="$(stat -c %g /var/run/docker.sock)"
+LLV_RUNTIME_EVENTS=1 LLV_VIEWER_DEPLOYMENTS=1 docker compose --profile runtime-host up -d runtime-host
+scripts/rebuild.sh
 LLV_TEST_PORT=8901 docker compose --profile test up -d viewer-test
 ```
 
 See [docs/docker.md](docs/docker.md) for the parity model, the nsenter shims,
 and volume/port details.
 
+### Attach to a live tmux pane
+
+The Viewer resolves and copies a complete command for each live pane. Paste that command into a normal shell; it selects the supervisor endpoint and the current pane coordinate. The read-only variant adds `-r`.
+
+```bash
+TMUX_TMPDIR='/run/user/1000/agent-log-viewer' tmux attach-session -t 'agents:2.0'
+TMUX_TMPDIR='/run/user/1000/agent-log-viewer' tmux attach-session -r -t 'agents:2.0'
+```
+
+Detach with `Ctrl-b d` and the agent keeps running. An unqualified tmux command may use a different server. Refresh and copy again after a stale-pane or restarted-server message; the fresh command accounts for window renumbering. See [the Docker guide](docs/docker.md#attach-to-a-viewer-pane) for the supervisor migration context.
+
 ### CLI options
 
 ```
@@ -232,6 +405,11 @@ All optional. Transcription variables are documented in full in
 | `LLV_WHISPER_VENV` | Path to the whisper virtualenv (default `~/.cache/agent-log-viewer/whisper-venv`). |
 | `LLV_ELEVENLABS_STT_MODEL` | ElevenLabs batch model override. |
 | `ELEVENLABS_API_KEY` | ElevenLabs API key for the ElevenLabs backend. |
+| `LLV_REAPER_ENABLED` | `1` enables verified pane and detached-reviewer process cleanup by the deterministic agent reaper. Unset keeps dry-run mode and exposes its latest report at `GET /api/lifecycle/reaper`. |
+| `LLV_SCHEME_PROJECT_CAP` | Number of most-recent projects rendered by the scheme feed (default `10`). List and search remain complete. |
+| `LLV_SCHEME_CARDS_PER_PROJECT` | Maximum scanner entries rendered per scheme project (default `80`). List and search remain complete. |
+| `NEXT_PUBLIC_LLV_SCHEME_AGE_HORIZON_HOURS` | Age horizon in hours for automatic card placement on the project scheme (default `48`). A root conversation with activity inside the horizon keeps an automatic card even while idle; older roots leave the canvas for quiet history and «All conversations». Live or running conversations and manually placed cards are never removed by the horizon. Inlined at build time (`NEXT_PUBLIC_*`). |
+| `LLV_HEADLESS_REAPER_THRESHOLD_MS` | Minimum age in milliseconds for the always-active leaked Codex/MCP safety reaper (default `7200000`, two hours; minimum accepted value `60000`). |
 | `LLV_DOCKER_NSENTER_SHIMS` | `1` makes the agent CLI resolver prefer the container's `/usr/local/bin` nsenter shims for host CLIs. Set automatically by the Docker image; leave unset on a host runtime. See [docs/docker.md](docs/docker.md). |
 
 ## Config paths
@@ -244,8 +422,9 @@ package:
 - `~/.cache/agent-log-viewer/whisper-venv` — the local transcription
   virtualenv.
 
-Legacy `live-log-viewer` paths are still honored as read-only fallbacks, so
-existing setups keep working without changes.
+Legacy `live-log-viewer` paths remain valid fallbacks. When a legacy config or
+cache file is the resolved existing file, subsequent updates keep using that
+same path so existing setups continue without a forced move.
 
 ## Architecture
 

package/bin/cli.mjs

@@ -8,6 +8,14 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { detectTailscale, getToken, readStatus, serve as serveTailscale, TailscaleError } from "./tailscale.mjs";
+import {
+  discardWakatimeEnvironmentCredential,
+  viewerChildProcessOptions,
+  viewerServerBunRuntime,
+  withoutWakatimeCredential,
+} from "./server-runtime.mjs";
+
+discardWakatimeEnvironmentCredential();
 
 const DEFAULT_PORT = 8898;
 const DEFAULT_HOSTNAME = "127.0.0.1";
@@ -44,6 +52,7 @@ Options:
       --tailscale      Access over Tailscale
       --no-open        Don't open the browser
       --new-token      Create a new access key
+      --new-operator-token  Rotate the operator spawn capability
   -v, --version        Show the version
   -h, --help           Show this help`,
     badPort: (value) => `Invalid port: ${value}`,
@@ -74,6 +83,7 @@ Options:
       --tailscale      Доступ через Tailscale
       --no-open        Не відкривати браузер
       --new-token      Створити новий ключ доступу
+      --new-operator-token  Оновити операторський ключ запуску агентів
   -v, --version        Показати версію
   -h, --help           Показати довідку`,
     badPort: (value) => `Некоректний порт: ${value}`,
@@ -131,6 +141,7 @@ function parseArgs(args) {
     tailscale: false,
     noOpen: false,
     newToken: false,
+    newOperatorToken: false,
     help: false,
     version: false,
   };
@@ -159,6 +170,8 @@ function parseArgs(args) {
       options.noOpen = true;
     } else if (arg === "--new-token") {
       options.newToken = true;
+    } else if (arg === "--new-operator-token") {
+      options.newOperatorToken = true;
     } else if (arg === "-v" || arg === "--version") {
       options.version = true;
     } else if (arg === "-h" || arg === "--help") {
@@ -206,11 +219,15 @@ function readPackageJson(packageRoot) {
 }
 
 function resolveServer(packageRoot) {
+  const bunRuntime = viewerServerBunRuntime();
+  const commandFor = (command, args, bunEntry = command, bunArgs = args) => bunRuntime
+    ? { command: bunRuntime, args: ["--bun", bunEntry, ...bunArgs] }
+    : { command, args };
   const publishedStandalone = join(packageRoot, "dist", "standalone", "server.js");
   if (existsSync(publishedStandalone)) {
+    const launch = commandFor(process.execPath, [publishedStandalone], publishedStandalone, []);
     return {
-      command: process.execPath,
-      args: [publishedStandalone],
+      ...launch,
       cwd: join(packageRoot, "dist", "standalone"),
       label: "server.js",
     };
@@ -218,9 +235,9 @@ function resolveServer(packageRoot) {
 
   const repoStandalone = join(packageRoot, ".next", "standalone", "server.js");
   if (existsSync(repoStandalone)) {
+    const launch = commandFor(process.execPath, [repoStandalone], repoStandalone, []);
     return {
-      command: process.execPath,
-      args: [repoStandalone],
+      ...launch,
       cwd: join(packageRoot, ".next", "standalone"),
       label: "server.js",
     };
@@ -232,21 +249,44 @@ function resolveServer(packageRoot) {
   }
 
   return {
-    command: nextBin,
-    args: ["start"],
+    ...commandFor(nextBin, ["start"]),
     cwd: packageRoot,
     label: "next start",
   };
 }
 
-function buildChildEnv(options, runtime) {
+function buildChildEnv(options, runtime, packageRoot) {
   const env = {
-    ...process.env,
+    ...withoutWakatimeCredential(process.env),
     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,
   };
 
+  // The standalone server runs with cwd inside dist/standalone, so the
+  // Telegram connector assets (issue #1059) are pinned to the package root
+  // explicitly; a pre-set override always wins.
+  const telegramVendor = join(packageRoot, "vendor", "telegram-mcp");
+  if (!env.LLV_TELEGRAM_VENDOR_DIR && existsSync(telegramVendor)) {
+    env.LLV_TELEGRAM_VENDOR_DIR = telegramVendor;
+  }
+  const telegramBridge = join(packageRoot, "bin", "telegram-login-bridge.py");
+  if (!env.LLV_TELEGRAM_BRIDGE && existsSync(telegramBridge)) {
+    env.LLV_TELEGRAM_BRIDGE = telegramBridge;
+  }
+  const telegramServerBridge = join(packageRoot, "bin", "telegram-mcp-server.py");
+  if (!env.LLV_TELEGRAM_SERVER_BRIDGE && existsSync(telegramServerBridge)) {
+    env.LLV_TELEGRAM_SERVER_BRIDGE = telegramServerBridge;
+  }
+  const telegramSessionReader = join(packageRoot, "bin", "telegram-session-reader.mjs");
+  if (!env.LLV_TELEGRAM_SESSION_READER && existsSync(telegramSessionReader)) {
+    env.LLV_TELEGRAM_SESSION_READER = telegramSessionReader;
+  }
+  const telegramProvisioner = join(packageRoot, "bin", "provision-telegram-connector.mjs");
+  if (!env.LLV_TELEGRAM_PROVISIONER && existsSync(telegramProvisioner)) {
+    env.LLV_TELEGRAM_PROVISIONER = telegramProvisioner;
+  }
+
   if (runtime.llvToken) {
     env.LLV_TOKEN = runtime.llvToken;
   }
@@ -259,15 +299,19 @@ function buildChildEnv(options, runtime) {
     env.LLV_TS_URL = runtime.tailnetUrl;
   }
 
+  if (options.newOperatorToken) {
+    env.LLV_ROTATE_OPERATOR_SPAWN_CAPABILITY = "1";
+  }
+
   return env;
 }
 
-function startServer(server, options, runtime, tailscaleProcessRef) {
-  const child = spawn(server.command, server.args, {
+function startServer(server, options, runtime, tailscaleProcessRef, packageRoot) {
+  const child = spawn(server.command, server.args, viewerChildProcessOptions({
     cwd: server.cwd,
-    env: buildChildEnv(options, runtime),
+    env: buildChildEnv(options, runtime, packageRoot),
     stdio: ["ignore", "inherit", "pipe"],
-  });
+  }));
 
   const state = {
     sawAddressInUse: false,
@@ -368,7 +412,7 @@ function localUrl(options) {
 }
 
 function printBanner(version, options) {
-  console.log(`  ✳ Live Log Viewer v${version}`);
+  console.log(`  ✳ Agent Log Viewer v${version}`);
   console.log(m.bannerOpened(localUrl(options)));
   console.log(m.bannerReads());
   console.log(m.bannerStop());
@@ -400,10 +444,10 @@ function openBrowser(url) {
     return;
   }
 
-  const child = spawn(opener, [url], {
+  const child = spawn(opener, [url], viewerChildProcessOptions({
     stdio: "ignore",
     detached: true,
-  });
+  }));
   child.unref();
 }
 
@@ -583,7 +627,7 @@ async function main() {
 
   const server = resolveServer(packageRoot);
   const tailscaleProcessRef = { current: null };
-  const serverProcess = startServer(server, options, runtime, tailscaleProcessRef);
+  const serverProcess = startServer(server, options, runtime, tailscaleProcessRef, packageRoot);
   installSignalHandlers(serverProcess, tailscaleProcessRef);
 
   if (options.tailscale && runtime.tailscalePath) {

package/bin/mcp-server.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, fstatSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  discardWakatimeEnvironmentCredential,
+  viewerChildProcessOptions,
+  viewerServerBunRuntime,
+} from "./server-runtime.mjs";
+
+discardWakatimeEnvironmentCredential();
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+let selectedReleaseRevision = null;
+
+function deployedPackageRoot() {
+  const configRoot = process.env.XDG_CONFIG_HOME || join(process.env.HOME || "/home/user", ".config");
+  const stateDir = process.env.LLV_STATE_DIR || join(configRoot, "agent-log-viewer", "state");
+  const targetFile = process.env.LLV_VIEWER_DEPLOY_TARGET || join(stateDir, "viewer-release.json");
+  let target;
+  try {
+    target = JSON.parse(readFileSync(targetFile, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return packageRoot;
+    throw new Error(`Could not read the Viewer release target: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!target
+    || typeof target !== "object"
+    || Array.isArray(target)
+    || typeof target.image !== "string"
+    || typeof target.container !== "string"
+    || typeof target.endpoint !== "string"
+    || typeof target.revision !== "string"
+    || !/^[0-9a-f]{40}$/.test(target.revision)) {
+    throw new Error("The active Viewer release target is invalid.");
+  }
+  selectedReleaseRevision = target.revision;
+  const runtime = target.mcpRuntime;
+  if (runtime === undefined) return packageRoot;
+  if (!runtime
+    || typeof runtime !== "object"
+    || runtime.source !== "managed"
+    || typeof runtime.releaseId !== "string"
+    || !/^[a-z0-9-]+$/.test(runtime.releaseId)
+    || typeof runtime.revision !== "string"
+    || runtime.revision !== target.revision
+    || !/^[0-9a-f]{40}$/.test(runtime.revision)
+    || typeof runtime.artifactDigest !== "string"
+    || !/^[0-9a-f]{64}$/.test(runtime.artifactDigest)
+    || typeof runtime.stagedAt !== "string") {
+    throw new Error("The active Viewer release has an invalid MCP runtime identity.");
+  }
+  const releasesRoot = join(stateDir, "mcp-runtime", "releases");
+  const releaseRoot = join(releasesRoot, runtime.releaseId);
+  const bundle = join(releaseRoot, "dist", "mcp-server.mjs");
+  let bundled;
+  try {
+    bundled = readFileSync(bundle);
+  } catch (error) {
+    /* Same policy as an absent release target: a runtime the deployment never
+       published (or already retired) falls back to this image's own bundle
+       instead of leaving the operator with no MCP server at all. */
+    if (error?.code === "ENOENT") return packageRoot;
+    throw new Error(`Could not read the published MCP runtime bundle: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const artifactDigest = createHash("sha256").update(bundled).digest("hex");
+  if (artifactDigest !== runtime.artifactDigest) {
+    throw new Error("MCP runtime bundle digest does not match the active release.");
+  }
+  return releaseRoot;
+}
+
+const selectedPackageRoot = deployedPackageRoot();
+if (selectedReleaseRevision) process.env.LLV_HOT_STATE_RELEASE_REVISION = selectedReleaseRevision;
+const bundled = join(selectedPackageRoot, "dist", "mcp-server.mjs");
+const source = join(selectedPackageRoot, "src", "lib", "mcp", "entry.ts");
+
+async function runChild(runtime, entry) {
+  let admissionChannel = false;
+  try {
+    admissionChannel = fstatSync(3).isSocket();
+  } catch {
+    admissionChannel = false;
+  }
+  const child = spawn(runtime, [entry], viewerChildProcessOptions({
+    cwd: selectedPackageRoot,
+    env: {
+      ...process.env,
+      ...(selectedReleaseRevision ? { LLV_HOT_STATE_RELEASE_REVISION: selectedReleaseRevision } : {}),
+    },
+    stdio: admissionChannel ? [0, 1, 2, 3] : [0, 1, 2, "ignore"],
+  }));
+  let childExited = false;
+  const forwardInterrupt = () => {
+    if (!childExited) child.kill("SIGINT");
+  };
+  const forwardTermination = () => {
+    if (!childExited) child.kill("SIGTERM");
+  };
+  process.on("SIGINT", forwardInterrupt);
+  process.on("SIGTERM", forwardTermination);
+  await new Promise((resolve) => {
+    let settled = false;
+    const finish = (exitCode) => {
+      if (settled) return;
+      settled = true;
+      childExited = true;
+      process.removeListener("SIGINT", forwardInterrupt);
+      process.removeListener("SIGTERM", forwardTermination);
+      process.exitCode = exitCode;
+      resolve();
+    };
+    child.once("error", (error) => {
+      console.error(`Could not start the Viewer MCP server: ${error.message}`);
+      finish(1);
+    });
+    child.once("exit", (code, signal) => {
+      finish(code ?? (signal ? 1 : 0));
+    });
+  });
+}
+
+if (existsSync(bundled)) {
+  const bunRuntime = viewerServerBunRuntime();
+  if (bunRuntime && !process.versions.bun) await runChild(bunRuntime, bundled);
+  else await import(pathToFileURL(bundled).href);
+} else if (process.versions.bun) {
+  await import(pathToFileURL(source).href);
+} else {
+  const bun = process.env.LLV_BUN_EXECUTABLE || "bun";
+  await runChild(bun, source);
+}