faberun 0.3.0

package/src/seat/tmux.mjs

@@ -0,0 +1,208 @@
+/**
+ * The tmux half of the operator seat: one session (`faberun-seat`) with
+ * one window per open campaign.
+ *
+ * tmux is optional by design (ADR-0033): the run engine never binds to it, so
+ * every function here returns an explicit result and an absent binary becomes
+ * `{available: false}` instead of a throw. That is what keeps every campaign
+ * command working on a host without tmux, where only reattaching is lost.
+ */
+import { execFileSync } from "node:child_process";
+import { errorCode, exitStatus } from "../util.mjs";
+
+/** The single seat session every campaign window lives in. */
+export const SEAT_SESSION = "faberun-seat";
+
+/** Window option recording which harness launched the window. */
+const HARNESS_OPTION = "@faberun-harness";
+
+/** `list-windows` format: name, index, harness option, pane command, tab-separated. */
+const WINDOW_FORMAT = "#{window_name}\t#{window_index}\t#{@faberun-harness}\t#{pane_current_command}";
+
+/** Measured 2026-09-12: every seat tmux call here returns in well under a second. */
+const TMUX_TIMEOUT_MS = 10_000;
+
+/**
+ * @typedef {{available: boolean, ok: boolean, status: number|null, stdout: string, stderr: string, reason: string|null}} TmuxResult
+ * @typedef {{window: string, index: number|null, harness: string|null, command: string|null}} SeatWindow
+ */
+
+/**
+ * @param {string[]} args
+ * @param {{cwd?: string}} [options]
+ * @returns {TmuxResult}
+ */
+function runTmux(args, options = {}) {
+  try {
+    const stdout = execFileSync("tmux", args, {
+      cwd: options.cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: TMUX_TIMEOUT_MS,
+    });
+    return { available: true, ok: true, status: 0, stdout: String(stdout), stderr: "", reason: null };
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      return { available: false, ok: false, status: null, stdout: "", stderr: "", reason: "tmux_unavailable" };
+    }
+    const failure = spawnFailure(error);
+    return {
+      available: true,
+      ok: false,
+      status: exitStatus(error) ?? null,
+      stdout: failure.stdout,
+      stderr: failure.stderr,
+      reason: "tmux_command_failed",
+    };
+  }
+}
+
+/** @param {unknown} error @returns {{stdout: string, stderr: string}} */
+function spawnFailure(error) {
+  const record = /** @type {{stdout?: string|Buffer, stderr?: string|Buffer}} */ (error);
+  return { stdout: textOf(record.stdout), stderr: textOf(record.stderr) };
+}
+
+/** @param {unknown} value @returns {string} */
+function textOf(value) {
+  if (value === undefined || value === null) return "";
+  return Buffer.isBuffer(value) ? value.toString("utf8") : String(value);
+}
+
+/**
+ * @param {string} session
+ * @returns {{available: boolean, exists: boolean}}
+ */
+function sessionExists(session) {
+  const result = runTmux(["has-session", "-t", session]);
+  if (!result.available) return { available: false, exists: false };
+  return { available: true, exists: result.ok };
+}
+
+/**
+ * Create the seat window for one campaign, creating the session on the first
+ * window. The harness argv is quoted into the single shell-command tmux takes;
+ * the harness name is recorded as a window option so status can name it even
+ * after the pane's foreground command changes.
+ *
+ * @param {{session: string, window: string, argv: readonly string[], harness: string, cwd: string}} options
+ * @returns {{available: boolean, ok: boolean, created: boolean, session: string, window: string, command: string|null, reason: string|null, stderr: string}}
+ */
+export function createSeatWindow(options) {
+  const existing = sessionExists(options.session);
+  if (!existing.available) {
+    return { available: false, ok: false, created: false, session: options.session, window: options.window, command: null, reason: "tmux_unavailable", stderr: "" };
+  }
+  const command = shellCommand(options.argv);
+  const args = existing.exists
+    ? ["new-window", "-t", options.session, "-n", options.window, "-c", options.cwd, command]
+    : ["new-session", "-d", "-s", options.session, "-n", options.window, "-c", options.cwd, command];
+  const result = runTmux(args);
+  if (!result.ok) {
+    return { available: result.available, ok: false, created: false, session: options.session, window: options.window, command, reason: result.reason, stderr: result.stderr };
+  }
+  runTmux(["set-option", "-w", "-t", `${options.session}:${options.window}`, HARNESS_OPTION, options.harness]);
+  return { available: true, ok: true, created: true, session: options.session, window: options.window, command, reason: null, stderr: "" };
+}
+
+/** @param {readonly string[]} argv @returns {string} */
+function shellCommand(argv) {
+  return argv
+    .map((argument) => (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(argument) ? argument : `'${argument.replace(/'/gu, "'\\''")}'`))
+    .join(" ");
+}
+
+/**
+ * Replace the process in an existing seat window with a new harness, keeping
+ * the window, its name and its index. `respawn-window -k` is the kill and the
+ * launch in one tmux verb; the caller materializes the brief before calling,
+ * so a failed brief never tears down a working pane.
+ *
+ * @param {{session: string, window: string, argv: readonly string[], harness: string, cwd: string}} options
+ * @returns {{available: boolean, ok: boolean, respawned: boolean, session: string, window: string, command: string|null, reason: string|null, stderr: string}}
+ */
+export function respawnSeatWindow(options) {
+  const command = shellCommand(options.argv);
+  const result = runTmux(["respawn-window", "-k", "-t", `${options.session}:${options.window}`, "-c", options.cwd, command]);
+  if (!result.ok) {
+    return { available: result.available, ok: false, respawned: false, session: options.session, window: options.window, command, reason: result.reason, stderr: result.stderr };
+  }
+  runTmux(["set-option", "-w", "-t", `${options.session}:${options.window}`, HARNESS_OPTION, options.harness]);
+  return { available: true, ok: true, respawned: true, session: options.session, window: options.window, command, reason: null, stderr: "" };
+}
+
+/**
+ * @param {string} session
+ * @returns {{available: boolean, windows: SeatWindow[], reason: string|null, stderr: string}}
+ */
+export function listSeatWindows(session) {
+  const result = runTmux(["list-windows", "-t", session, "-F", WINDOW_FORMAT]);
+  if (!result.available) return { available: false, windows: [], reason: "tmux_unavailable", stderr: "" };
+  if (!result.ok) {
+    return { available: true, windows: [], reason: result.status === 1 ? "no_session" : "tmux_command_failed", stderr: result.stderr };
+  }
+  const windows = result.stdout.split("\n").map(parseWindowLine).filter((window) => window !== null);
+  return { available: true, windows, reason: null, stderr: "" };
+}
+
+/**
+ * @param {string} line
+ * @returns {SeatWindow|null}
+ */
+function parseWindowLine(line) {
+  if (!line.trim()) return null;
+  const [name, index, harness, command] = line.split("\t");
+  if (!name) return null;
+  const parsed = Number.parseInt(index ?? "", 10);
+  return {
+    window: name,
+    index: Number.isFinite(parsed) ? parsed : null,
+    harness: harness ? harness : null,
+    command: command ? command : null,
+  };
+}
+
+/**
+ * @returns {{available: boolean, version: string|null, reason: string|null}}
+ */
+export function tmuxAvailability() {
+  const result = runTmux(["-V"]);
+  return {
+    available: result.available,
+    version: result.ok && result.stdout.trim() ? result.stdout.trim() : null,
+    reason: result.reason,
+  };
+}
+
+/**
+ * @param {string} session
+ * @param {string} window
+ * @returns {{available: boolean, ok: boolean, reason: string|null, stderr: string}}
+ */
+export function stopSeatWindow(session, window) {
+  return stopTmux(["kill-window", "-t", `${session}:${window}`], "window");
+}
+
+/**
+ * @param {string} session
+ * @returns {{available: boolean, ok: boolean, reason: string|null, stderr: string}}
+ */
+export function stopSeatSession(session) {
+  return stopTmux(["kill-session", "-t", session], "session");
+}
+
+/**
+ * tmux exits 1 when the target is already gone. That is idempotent success for
+ * a stop, not a failure: stopping the last window takes the session with it.
+ *
+ * @param {string[]} args
+ * @param {"window"|"session"} label
+ * @returns {{available: boolean, ok: boolean, reason: string|null, stderr: string}}
+ */
+function stopTmux(args, label) {
+  const result = runTmux(args);
+  if (result.available && !result.ok && result.status === 1) {
+    return { available: true, ok: true, reason: `no_${label}`, stderr: result.stderr };
+  }
+  return { available: result.available, ok: result.ok, reason: result.reason, stderr: result.stderr };
+}

package/src/web/api.mjs

@@ -0,0 +1,371 @@
+/**
+ * The operator's remote API: the phone-shaped surface behind the dashboard
+ * server. Reads go straight to the campaign/seat aggregators that already
+ * exist; every write shells out to the runner CLI and touches no state file of
+ * its own (ADR-0034: a daemon that wrote state would be a second state machine
+ * with its own rules, and the CLI is the only writer). That is also why there
+ * is no replan, contract, routing or gate route: the contract is frozen with a
+ * digest, and the sanctioned middle ground from a phone is `campaign note`.
+ * Pause/resume ride the run-level `cancel`/`resume` verbs — the reversible
+ * pair this repo already owns (a canceled run is a resumable state) — fired
+ * once per linked run that still has work in flight.
+ */
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import { discoverCampaigns } from "../campaign/index.mjs";
+import { BRIEF_FILE, JOURNAL_FILE } from "../campaign/layout.mjs";
+import { seatStatus } from "../seat/index.mjs";
+import { errorMessage, errorCode, fail, readJsonTolerant, truncateChars } from "../util.mjs";
+
+const DEFAULT_CLI_ENTRY = fileURLToPath(new URL("../cli.mjs", import.meta.url));
+/** One events page is bounded twice: by the bytes read from the journal and by the entry count returned. */
+const EVENTS_WINDOW_BYTES = 32 * 1024;
+const EVENTS_WINDOW_ENTRIES = 100;
+const REQUEST_BODY_MAX_BYTES = 16 * 1024;
+const OUTPUT_TAIL_CHARS = 4 * 1024;
+const LIST_GOAL_CHARS = 200;
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const RUN_DONE_STATUSES = new Set(["done", "no-op"]);
+const RUN_TERMINAL_STATUSES = new Set(["done", "no-op", "failed", "blocked", "exhausted", "stalled", "canceled", "cancelled"]);
+const RUN_ATTENTION_STATUSES = new Set(["blocked", "failed", "exhausted", "stalled", "canceled", "cancelled"]);
+/** The journal's `sessionId` records who spoke; the web daemon is a speaker of its own. */
+const WEB_SESSION_ID = "web";
+
+/** @typedef {import("node:http").IncomingMessage} IncomingMessage */
+/** @typedef {import("node:http").ServerResponse} ServerResponse */
+/** @typedef {{runsDir: string, repoRoot: string, cliEntry: string, url: URL, request: IncomingMessage}} ApiContext */
+/** @typedef {{type: string, eventId: string, at: string, [key: string]: unknown}} JournalRecord */
+/** @typedef {(context: ApiContext, response: ServerResponse, params: string[]) => Promise<void>} ApiHandler */
+
+/** @type {[RegExp, ApiHandler][]} */
+const GET_ROUTES = [
+  [/^\/api\/campaigns$/u, listCampaigns],
+  [/^\/api\/campaigns\/([^/]+)$/u, showCampaign],
+  [/^\/api\/campaigns\/([^/]+)\/events$/u, campaignEvents],
+  [/^\/api\/campaigns\/([^/]+)\/brief$/u, campaignBrief],
+  [/^\/api\/seats$/u, listSeats],
+];
+
+/** @type {[RegExp, ApiHandler][]} */
+const POST_ROUTES = [
+  [/^\/api\/campaigns\/([^/]+)\/note$/u, postNote],
+  [/^\/api\/campaigns\/([^/]+)\/decisions\/([^/]+)$/u, postDecision],
+  [/^\/api\/campaigns\/([^/]+)\/pause$/u, postPause],
+  [/^\/api\/campaigns\/([^/]+)\/resume$/u, postResume],
+  [/^\/api\/seats\/([^/]+)\/switch$/u, postSeatSwitch],
+];
+
+/**
+ * Route one `/api/*` request. Unknown paths answer 404 — deliberately,
+ * including the replan-shaped ones — and a path matched with the wrong method
+ * answers 405. Never throws: the failure envelope is JSON like the payloads.
+ *
+ * @param {IncomingMessage} request
+ * @param {ServerResponse} response
+ * @param {{runsDir: string, cliEntry?: string}} options
+ */
+export async function handleApiRequest(request, response, options) {
+  const url = new URL(request.url ?? "/", "http://localhost");
+  /** @type {ApiContext} */
+  const context = {
+    runsDir: options.runsDir,
+    repoRoot: dirname(options.runsDir),
+    cliEntry: options.cliEntry ?? DEFAULT_CLI_ENTRY,
+    url,
+    request,
+  };
+  try {
+    const table = request.method === "GET" ? GET_ROUTES : request.method === "POST" ? POST_ROUTES : [];
+    for (const [pattern, handler] of table) {
+      const params = pattern.exec(url.pathname)?.slice(1);
+      if (params) return await handler(context, response, params.map(safeSegment));
+    }
+    if ([...GET_ROUTES, ...POST_ROUTES].some(([pattern]) => pattern.test(url.pathname))) {
+      throw fail("method_not_allowed", `use ${request.method === "GET" ? "POST" : "GET"} for ${url.pathname}`);
+    }
+    throw notFound("no such path");
+  } catch (error) {
+    const code = errorCode(error);
+    const status = code === "bad_request" ? 400 : code === "not_found" ? 404 : code === "method_not_allowed" ? 405 : 500;
+    sendJson(response, status, { error: errorMessage(error) });
+  }
+}
+
+/** @param {string} message @returns {Error & {code: string}} */
+function notFound(message) {
+  return fail("not_found", message);
+}
+
+/** @param {string} message @returns {Error & {code: string}} */
+function badRequest(message) {
+  return fail("bad_request", message);
+}
+
+/** @param {ServerResponse} response @param {number} status @param {unknown} payload */
+function sendJson(response, status, payload) {
+  response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+  response.end(JSON.stringify(payload));
+}
+
+/** @param {string} value @returns {string} */
+function safeSegment(value) {
+  if (!SAFE_SEGMENT.test(value)) throw notFound("no such path");
+  return value;
+}
+
+/** @param {ApiContext} context @param {string} id @returns {{path: string, campaign: import("../campaign/index.mjs").Campaign}} */
+function findCampaign(context, id) {
+  const found = discoverCampaigns(context.runsDir).campaigns.find(({ campaign }) => campaign.id === id);
+  if (!found) throw notFound(`unknown campaign: ${id}`);
+  return found;
+}
+
+/** The phone-sized run row: three states and two counters, nothing the dashboard snapshot does not already compute better. @param {string} runsDir @param {string} runId @returns {Record<string, unknown>} */
+function runRow(runsDir, runId) {
+  const status = readJsonTolerant(join(runsDir, runId, "status.json"));
+  const nodes = status && typeof status === "object" && Array.isArray(/** @type {any} */ (status).nodes) ? /** @type {any[]} */ (/** @type {any} */ (status).nodes) : [];
+  return {
+    id: runId,
+    state: nodes.some((node) => RUN_ATTENTION_STATUSES.has(String(node.status)))
+      ? "attention"
+      : nodes.length > 0 && nodes.every((node) => RUN_TERMINAL_STATUSES.has(String(node.status))) ? "done" : "active",
+    nodesDone: nodes.filter((node) => RUN_DONE_STATUSES.has(String(node.status))).length,
+    nodesTotal: nodes.length,
+    costUsd: typeof /** @type {any} */ (status)?.usage?.costUsd === "number" ? /** @type {any} */ (status).usage.costUsd : null,
+  };
+}
+
+/** Linked runs that still have a node in flight — the only ones pause or resume can change. @param {ApiContext} context @param {import("../campaign/index.mjs").Campaign} campaign @returns {string[]} */
+function runsInFlight(context, campaign) {
+  return campaign.linkedRunIds.filter((runId) => {
+    const status = readJsonTolerant(join(context.runsDir, runId, "status.json"));
+    const nodes = status && typeof status === "object" && Array.isArray(/** @type {any} */ (status).nodes) ? /** @type {any[]} */ (/** @type {any} */ (status).nodes) : [];
+    return nodes.some((node) => !RUN_TERMINAL_STATUSES.has(String(node.status)));
+  });
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response */
+async function listCampaigns(context, response) {
+  const { campaigns, corrupt } = discoverCampaigns(context.runsDir);
+  sendJson(response, 200, {
+    schemaVersion: 1,
+    campaigns: campaigns.map(({ campaign }) => ({
+      id: campaign.id,
+      goal: truncateChars(String(campaign.goal ?? "").replace(/\s+/gu, " ").trim(), LIST_GOAL_CHARS),
+      status: campaign.status,
+      updatedAt: campaign.updatedAt,
+      runCount: campaign.linkedRunIds.length,
+    })),
+    corrupt: corrupt.map((entry) => entry.id),
+  });
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response @param {string[]} params */
+async function showCampaign(context, response, params) {
+  const { campaign } = findCampaign(context, params[0]);
+  sendJson(response, 200, { campaign, runs: campaign.linkedRunIds.map((runId) => runRow(context.runsDir, runId)) });
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response @param {string[]} params */
+async function campaignEvents(context, response, params) {
+  const { campaign, path } = findCampaign(context, params[0]);
+  const afterRaw = context.url.searchParams.get("after") ?? "0";
+  if (!/^\d+$/u.test(afterRaw)) throw badRequest("after must be a non-negative integer cursor");
+  const page = readJournalWindow(join(path, JOURNAL_FILE), Number(afterRaw));
+  sendJson(response, 200, {
+    schemaVersion: 1,
+    campaignId: campaign.id,
+    after: Number(afterRaw),
+    next: page.next,
+    size: page.size,
+    complete: page.next >= page.size,
+    entries: page.entries,
+  });
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response @param {string[]} params */
+async function campaignBrief(context, response, params) {
+  const briefPath = join(findCampaign(context, params[0]).path, BRIEF_FILE);
+  if (!existsSync(briefPath)) throw notFound(`operator brief not generated yet: ${BRIEF_FILE}`);
+  response.writeHead(200, { "content-type": "text/markdown; charset=utf-8", "cache-control": "no-store" });
+  response.end(readFileSync(briefPath));
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response */
+async function listSeats(context, response) {
+  sendJson(response, 200, seatStatus());
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response @param {string[]} params */
+async function postNote(context, response, params) {
+  // The campaign is resolved before the CLI runs, like every other route: an
+  // unknown id used to reach `campaign note`, whose own refusal names the
+  // absolute path it looked in and handed the caller the server's directory
+  // layout.
+  findCampaign(context, params[0]);
+  const body = await readJsonObject(context.request);
+  const argv = ["campaign", "note", params[0], "--session-id", sessionOf(body), "--kind", requiredString(body.kind, "kind"), "--text", requiredString(body.text, "text")];
+  for (const [flag, key] of [["--decision-id", "decisionId"], ["--supersedes", "supersedes"], ["--question-id", "questionId"], ["--run-id", "runId"]]) {
+    if (typeof body[key] === "string" && /** @type {string} */ (body[key]).trim()) argv.push(flag, /** @type {string} */ (body[key]));
+  }
+  sendResult(response, await runCli(context, argv));
+}
+
+/** A pending operator decision is the journal's open question; resolving it is `campaign resolve`. @param {ApiContext} context @param {ServerResponse} response @param {string[]} params */
+async function postDecision(context, response, params) {
+  findCampaign(context, params[0]);
+  const body = await readJsonObject(context.request);
+  const argv = ["campaign", "resolve", params[0], "--session-id", sessionOf(body), "--question-id", params[1], "--text", requiredString(body.text, "text")];
+  sendResult(response, await runCli(context, argv));
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response @param {string[]} params */
+async function postPause(context, response, params) {
+  const targets = runsInFlight(context, findCampaign(context, params[0]).campaign);
+  const results = [];
+  for (const runId of targets) results.push({ runId, ...await runCli(context, ["cancel", join(context.runsDir, runId)]) });
+  sendResult(response, { ok: results.every((result) => result.exitCode === 0), results });
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response @param {string[]} params */
+async function postResume(context, response, params) {
+  const targets = runsInFlight(context, findCampaign(context, params[0]).campaign);
+  const results = [];
+  for (const runId of targets) results.push({ runId, ...await runCli(context, ["resume", join(context.runsDir, runId), "--detach"]) });
+  sendResult(response, { ok: results.every((result) => result.exitCode === 0), results });
+}
+
+/** @param {ApiContext} context @param {ServerResponse} response @param {string[]} params */
+async function postSeatSwitch(context, response, params) {
+  const body = await readJsonObject(context.request);
+  const argv = ["seat", "switch", params[0], "--harness", requiredString(body.harness, "harness")];
+  sendResult(response, await runCli(context, argv));
+}
+
+/** @param {ServerResponse} response @param {{ok: boolean, [key: string]: unknown}} envelope */
+function sendResult(response, envelope) {
+  sendJson(response, envelope.ok ? 200 : 500, { schemaVersion: 1, ...envelope });
+}
+
+/** @param {Record<string, unknown>} body @returns {string} */
+function sessionOf(body) {
+  return typeof body.sessionId === "string" && body.sessionId.trim() ? body.sessionId.trim() : WEB_SESSION_ID;
+}
+
+/** @param {unknown} value @param {string} label @returns {string} */
+function requiredString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw badRequest(`${label} is required`);
+  return value;
+}
+
+/** @param {IncomingMessage} request @returns {Promise<Record<string, unknown>>} */
+async function readJsonObject(request) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of request) {
+    total += chunk.length;
+    if (total > REQUEST_BODY_MAX_BYTES) throw badRequest(`request body exceeds ${REQUEST_BODY_MAX_BYTES} bytes`);
+    chunks.push(Buffer.from(chunk));
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw badRequest("request body is not valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw badRequest("request body must be a JSON object");
+  return /** @type {Record<string, unknown>} */ (parsed);
+}
+
+/**
+ * Fire one CLI verb and collect its verdict. The argv is an array handed to
+ * spawn, never a shell string, so note text can never become an option or a
+ * command.
+ *
+ * @param {ApiContext} context
+ * @param {string[]} argv
+ * @returns {Promise<{ok: boolean, command: string, exitCode: number, stdout: string, stderr: string}>}
+ */
+async function runCli(context, argv) {
+  const child = spawn(process.execPath, [context.cliEntry, ...argv], { cwd: context.repoRoot, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+  let stdout = "";
+  let stderr = "";
+  if (child.stdout) child.stdout.on("data", (chunk) => { stdout += String(chunk); });
+  if (child.stderr) child.stderr.on("data", (chunk) => { stderr += String(chunk); });
+  /** @type {Promise<number>} */
+  const closed = new Promise((resolve) => child.on("close", (code) => resolve(code ?? -1)));
+  const exitCode = await closed;
+  return {
+    ok: exitCode === 0,
+    command: argv.join(" "),
+    exitCode,
+    stdout: truncateChars(stdout.trim(), OUTPUT_TAIL_CHARS),
+    stderr: truncateChars(stderr.trim(), OUTPUT_TAIL_CHARS),
+  };
+}
+
+/**
+ * One bounded page of the campaign journal, read forward from the `after` byte
+ * cursor. A client that starts at zero gets the first window, never the whole
+ * file, however long the campaign has run; `next` is the cursor to send back.
+ * Only a line the window has seen ended by its own newline is an entry — a
+ * trailing fragment torn by a concurrent append is left for the next page, and
+ * legacy `liveness` heartbeats are skipped as narrative-free. A cursor beyond
+ * the file is a client bug and answers itself as a bad request.
+ *
+ * @param {string} path
+ * @param {number} after
+ * @returns {{entries: JournalRecord[], next: number, size: number}}
+ */
+function readJournalWindow(path, after) {
+  let size = 0;
+  try {
+    size = statSync(path).size;
+  } catch {
+    return { entries: [], next: 0, size: 0 };
+  }
+  if (after > size) throw badRequest(`cursor ${after} is beyond the journal size ${size}`);
+  const bytes = windowBytes(path, Math.min(size - after, EVENTS_WINDOW_BYTES), after);
+  /** @type {JournalRecord[]} */
+  const entries = [];
+  let start = 0;
+  let consumed = 0;
+  while (entries.length < EVENTS_WINDOW_ENTRIES) {
+    const newline = bytes.indexOf(0x0a, start);
+    if (newline === -1) break;
+    consumed = newline + 1;
+    const line = bytes.toString("utf8", start, newline).replace(/\r$/u, "");
+    if (line.trim()) {
+      try {
+        const entry = /** @type {JournalRecord} */ (JSON.parse(line));
+        if (entry.type !== "liveness") entries.push(entry);
+      } catch {
+        // dropped: a line torn by a concurrent append; the cursor advances past it
+      }
+    }
+    start = newline + 1;
+  }
+  return { entries, next: after + consumed, size };
+}
+
+/** Positioned read that loops until the window is full, because one readSync may return short. @param {string} path @param {number} length @param {number} position @returns {Buffer} */
+function windowBytes(path, length, position) {
+  const descriptor = openSync(path, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    let filled = 0;
+    while (filled < length) {
+      const readNow = readSync(descriptor, buffer, filled, length - filled, position + filled);
+      if (readNow === 0) break;
+      filled += readNow;
+    }
+    return buffer.subarray(0, filled);
+  } finally {
+    closeSync(descriptor);
+  }
+}

package/src/web/boundary.mjs

@@ -0,0 +1,88 @@
+/**
+ * The dashboard's network boundary: the decisions that must be settled before
+ * a socket exists. `server.mjs` serves routes; this module decides whether it
+ * may listen at all — which address the bind host resolves to, whether that
+ * address is private (loopback, RFC1918, or the 100.64.0.0/10 CGNAT range
+ * Tailscale assigns), and the bearer token file that is the second lock behind
+ * the private network. The address ranges decide, never the Tailscale binary:
+ * a literal classifies identically with or without the daemon, so nothing here
+ * shells out or resolves anything beyond the local resolver.
+ */
+import { lookup } from "node:dns/promises";
+import { readFileSync } from "node:fs";
+import net from "node:net";
+import { errorMessage, fail } from "../util.mjs";
+
+/** The admissible bind space: loopback, RFC1918 and CGNAT — the range Tailscale hands out. Everything else, wildcard or public, is refused. */
+const PRIVATE_BIND = new net.BlockList();
+PRIVATE_BIND.addSubnet("127.0.0.0", 8, "ipv4");
+PRIVATE_BIND.addSubnet("10.0.0.0", 8, "ipv4");
+PRIVATE_BIND.addSubnet("172.16.0.0", 12, "ipv4");
+PRIVATE_BIND.addSubnet("192.168.0.0", 16, "ipv4");
+PRIVATE_BIND.addSubnet("100.64.0.0", 10, "ipv4");
+PRIVATE_BIND.addSubnet("::1", 128, "ipv6");
+
+const BIND_HELP = "bind loopback, an RFC1918 address, or a 100.64.0.0/10 CGNAT address (the Tailscale range)";
+
+/**
+ * The address a bind host stands for: IP literals pass through untouched, and
+ * a name resolves through the host resolver (which reads /etc/hosts) with its
+ * first result standing in for the set.
+ *
+ * @param {string} host
+ * @returns {Promise<string>}
+ */
+export async function resolveBindAddress(host) {
+  if (net.isIP(host) !== 0) return host;
+  try {
+    return (await lookup(host)).address;
+  } catch (error) {
+    throw fail("bind_unresolvable", `cannot resolve bind host ${host}: ${errorMessage(error)}`);
+  }
+}
+
+/** An IPv6 form like `::ffff:203.0.113.10` classifies by the IPv4 address it carries. @param {string} address @returns {string} */
+function unwrapIPv4Mapped(address) {
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/iu.exec(address);
+  return mapped ? mapped[1] : address;
+}
+
+/**
+ * Passes when the address is private and returns the canonical address to
+ * bind; throws with the reason when it is a wildcard or public. Callers run
+ * this before `listen`: binding and closing again still exposed the port for
+ * the time it was open.
+ *
+ * @param {string} address
+ * @returns {string}
+ */
+export function assertPrivateBind(address) {
+  if (address === "0.0.0.0") throw fail("public_bind", `refusing to bind 0.0.0.0: the IPv4 wildcard accepts connections on every interface, the public ones included; ${BIND_HELP}`);
+  if (address === "::") throw fail("public_bind", `refusing to bind '::': the IPv6 wildcard accepts connections on every interface, the public ones included; ${BIND_HELP}`);
+  const plain = unwrapIPv4Mapped(address);
+  // The family must be stated: without it, BlockList.check misses IPv6 rules (measured on Node 26.8.1).
+  const family = net.isIPv4(plain) ? "ipv4" : "ipv6";
+  if (PRIVATE_BIND.check(plain, family)) return plain;
+  throw fail("public_bind", `refusing to bind ${address}: not a private address; ${BIND_HELP}`);
+}
+
+/**
+ * The bearer token from a local file — the second lock behind the private
+ * network; there is no login system. One trimmed, space-free line, and the
+ * value never appears in any message this module produces.
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+export function loadBearerToken(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    throw fail("token_unreadable", `bearer token file is missing or unreadable: ${path} (${errorMessage(error)})`);
+  }
+  const token = raw.trim();
+  if (!token) throw fail("token_empty", `bearer token file is empty: ${path}`);
+  if (/\s/u.test(token)) throw fail("token_invalid", `bearer token file must hold a single space-free line: ${path}`);
+  return token;
+}