agent-log-viewer 1.0.0 → 1.0.1

package/README.md

@@ -7,8 +7,9 @@ parent→child tree, and tails the selected one in real time.
 
 ![From the overview board into a session and its live tail](docs/media/board-to-live-tail.gif)
 
-The default setup runs locally against files already on disk. The app uses no
-database; it reads `~/.claude` and `~/.codex` and renders what it finds.
+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
@@ -94,38 +95,27 @@ 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 --bun node_modules/.bin/next 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):
-
-```bash
-npm install
-npm run build
-npm start -- --port 8898 --hostname 127.0.0.1
-```
-
 `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 gated SQLite registry modes require the Viewer server to run on Bun.
-Structured host mode requires Bun too — the runtime journal runs on `bun:sqlite`,
-and on macOS process ownership uses the kernel's microsecond start token. Since
-structured hosting is on by default, the Docker runtime and `agent-log-viewer`
-CLI select Bun unless `LLV_STRUCTURED_HOSTS=0` rolls it back and
-`LLV_AGENT_REGISTRY_SQLITE` is off. Local source checkouts should use the
-explicit `bun --bun` command above.
+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
 
@@ -418,6 +408,7 @@ All optional. Transcription variables are documented in full in
 | `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). |
 

package/bin/cli.mjs

@@ -255,7 +255,7 @@ function resolveServer(packageRoot) {
   };
 }
 
-function buildChildEnv(options, runtime) {
+function buildChildEnv(options, runtime, packageRoot) {
   const env = {
     ...withoutWakatimeCredential(process.env),
     PORT: String(options.port),
@@ -263,6 +263,30 @@ function buildChildEnv(options, runtime) {
     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;
   }
@@ -282,10 +306,10 @@ function buildChildEnv(options, runtime) {
   return env;
 }
 
-function startServer(server, options, runtime, tailscaleProcessRef) {
+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"],
   }));
 
@@ -603,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

@@ -15,6 +15,7 @@ import {
 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");
@@ -37,6 +38,7 @@ function deployedPackageRoot() {
     || !/^[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
@@ -73,6 +75,7 @@ function deployedPackageRoot() {
 }
 
 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");
 
@@ -85,6 +88,10 @@ async function runChild(runtime, entry) {
   }
   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;

package/bin/mcp-server.test.ts

@@ -76,6 +76,7 @@ test("fresh Claude and Codex hosts load the exact MCP runtime named by the promo
       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);
   `;
@@ -109,6 +110,7 @@ test("fresh Claude and Codex hosts load the exact MCP runtime named by the promo
       revision: candidateRevision,
       tools: ["deployment_status", "board_snapshot"],
       host,
+      hotStateRevision: candidateRevision,
     });
     expect(handshake).toBe(`${host}-initialize`);
   }

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

@@ -31,11 +31,10 @@ export function viewerChildProcessOptions(options = {}) {
 /**
  * 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 the predicate is duplicated — never diverged:
- * `bin/server-runtime.test.ts` pins the two to one truth table. Structured
- * hosting is on unless explicitly rolled back, and it genuinely requires Bun
- * (the journal runs on `bun:sqlite`; macOS process ownership needs the kernel
- * start token), so the launcher must select Bun on the same answer.
+ * 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]
  */
@@ -50,8 +49,5 @@ export function viewerServerBunRuntime(options = {}) {
   const env = options.env ?? process.env;
   const versions = options.versions ?? process.versions;
   const execPath = options.execPath ?? process.execPath;
-  const sqliteMode = env.LLV_AGENT_REGISTRY_SQLITE ?? "off";
-  const requiresBun = sqliteMode !== "off" || structuredHostsEnabled(env);
-  if (!requiresBun) return null;
   return versions.bun ? execPath : (env.LLV_BUN_EXECUTABLE || "bun");
 }

package/bin/server-runtime.test.ts

@@ -1,9 +1,15 @@
 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,
@@ -28,13 +34,19 @@ test("structured hosts select Bun for a CLI process launched by Node", () => {
 
 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([
-    "node",
+    nodeExecutable,
     "--input-type=module",
     "--eval",
     `import { viewerServerBunRuntime } from ${JSON.stringify(pathToFileURL(helper).href)}; process.stdout.write(String(viewerServerBunRuntime()));`,
   ], {
-    env: { ...process.env, LLV_STRUCTURED_HOSTS: "1", LLV_BUN_EXECUTABLE: "/verified/bun" },
+    env: { ...process.env, PATH: nodeSearchPath, LLV_STRUCTURED_HOSTS: "1", LLV_BUN_EXECUTABLE: "/verified/bun" },
     stdout: "pipe",
     stderr: "pipe",
   });
@@ -73,17 +85,44 @@ test.each([
 ] 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));
-  // …and the launcher's Bun selection follows that one answer.
-  expect(viewerServerBunRuntime({ env, versions: { node: "20.9.0" }, execPath: "/usr/bin/node" }) !== null)
-    .toBe(structuredHostsEnabledInApp(env));
+  expect(viewerServerBunRuntime({ env, versions: { node: "20.9.0" }, execPath: "/usr/bin/node" }))
+    .toBe("bun");
 });
 
-test("legacy Node mode stays available when Bun-only features are disabled", () => {
+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",
-  })).toBeNull();
+  })).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", () => {