agent-log-viewer 1.0.1 → 1.0.3

package/README.md

@@ -36,6 +36,22 @@ 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)
 
+### Hand a project to an orchestrator
+
+![The orchestrator dock beside its project board](docs/media/orchestrator-dock.png)
+
+Each project can designate one agent as its **orchestrator**. Press
+**Orchestrator** in the project header, tell it what you want shipped, and it
+opens a lane per issue, spawns the implementer, runs a fresh reviewer each
+round and merges on APPROVE. Its mandate and any handoff from a predecessor are
+written for you — there is no "you are an orchestrator" prompt to compose — and
+you come back to the board when an agent needs a decision.
+
+[docs/orchestrator.md](docs/orchestrator.md) walks the whole flow on a fresh
+install: the dock, the board, pipelines, tasks, the attention queue, the
+model/effort matrix the conveyor uses, and when three tasks a week does not
+need any of it.
+
 ### Spawn agents from the board
 
 Each project is a pannable, zoomable scheme — root conversations on top,
@@ -95,22 +111,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 +138,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
 
@@ -410,6 +424,8 @@ All optional. Transcription variables are documented in full in
 | `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_HOST_RETIREMENT_IDLE_HOURS` | How long a structured host's transcript must have been quiet before the automatic retirement sweep may end it (default `6`). `0` turns the sweep off. Staleness is transcript modification time, never process age, and the sweep still refuses any host with a turn in flight, a pending question, an undelivered handoff entry, an open spawn receipt, an unflushed event tail, a realtime binding, or an orchestrator seat. Every qualification is re-proved one step before the signal, and each retirement is written to `state/host-retirement-report.json` and appended to `state/host-retirement-journal.ndjson`. |
+| `LLV_HOST_RETIREMENT_GRACE_MS` | How long a retiring host may take to honour SIGTERM before its tree is force-killed (default `5000`, capped at `60000`). Raising it lowers how many hosts one sweep attempts, so a sweep's terminations still fit well inside the interval before the next one; whatever is skipped is reported as deferred and picked up by the following sweep. |
 | `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

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",
+  };
+}