omp-conductor 0.15.9 → 0.15.11

package/src/dashboard/app.js

@@ -0,0 +1,120 @@
+// The dashboard UI (conductor #293): ask for the bearer token once, keep it in
+// localStorage, and render `/api/projects` with every daemon state explicit —
+// a stopped, unreachable or foreign daemon renders as down, never as an empty
+// healthy fleet.
+//
+// Plain browser JS, no runtime deps: the page is served unauthenticated and
+// the token lives only in the browser's localStorage, never in a URL.
+
+const TOKEN_KEY = "omp-conductor-dashboard-token";
+const tokenPanel = document.getElementById("token-panel");
+const tokenForm = document.getElementById("token-form");
+const tokenInput = document.getElementById("token-input");
+const tokenError = document.getElementById("token-error");
+const fleet = document.getElementById("fleet");
+const projects = document.getElementById("projects");
+
+/** Human verdict per daemon state — "down" spelled out by design. */
+const STATE_TEXT = {
+  ok: "daemon up",
+  stopped: "daemon down",
+  unreachable: "daemon down — not answering /healthz",
+  "other-project": "daemon down — serves another project",
+};
+
+async function apiProjects(token) {
+  const res = await fetch("/api/projects", {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (res.status === 401) return null;
+  if (!res.ok) throw new Error(`/api/projects answered ${res.status}`);
+  return res.json();
+}
+
+function showTokenPrompt() {
+  localStorage.removeItem(TOKEN_KEY);
+  tokenInput.value = "";
+  tokenError.hidden = true;
+  tokenPanel.hidden = false;
+  fleet.hidden = true;
+  tokenInput.focus();
+}
+
+function daemonLine(view) {
+  const { daemon } = view;
+  const text =
+    daemon.state === "other-project" && daemon.serves !== undefined
+      ? `daemon down — it serves "${daemon.serves}"`
+      : STATE_TEXT[daemon.state];
+  const parts = [text];
+  if (daemon.port !== null && daemon.port !== undefined) parts.push(`port ${daemon.port}`);
+  if (daemon.state === "ok") parts.push("healthz answering");
+  return parts.join(" · ");
+}
+
+function showProject(view) {
+  const li = document.createElement("li");
+  li.className = "project";
+  const dot = document.createElement("span");
+  dot.className = `dot dot-${view.daemon.state}`;
+  dot.setAttribute("aria-hidden", "true");
+  const body = document.createElement("div");
+  body.className = "body";
+  const name = document.createElement("span");
+  name.className = "name";
+  name.textContent = view.name;
+  const repo = document.createElement("span");
+  repo.className = "repo";
+  repo.textContent = view.repo;
+  const state = document.createElement("span");
+  state.className = `state state-${view.daemon.state}`;
+  state.textContent = daemonLine(view);
+  body.append(name, repo, state);
+  li.append(dot, body);
+  projects.appendChild(li);
+}
+
+function showFleet(list) {
+  projects.replaceChildren();
+  if (list.length === 0) {
+    const li = document.createElement("li");
+    li.className = "project";
+    li.textContent = "No projects configured.";
+    projects.appendChild(li);
+  } else {
+    for (const view of list) showProject(view);
+  }
+  tokenPanel.hidden = true;
+  fleet.hidden = false;
+}
+
+async function start(token) {
+  tokenError.hidden = true;
+  const list = await apiProjects(token);
+  if (list === null) {
+    showTokenPrompt();
+    return;
+  }
+  localStorage.setItem(TOKEN_KEY, token);
+  showFleet(list);
+}
+
+tokenForm.addEventListener("submit", (event) => {
+  event.preventDefault();
+  start(tokenInput.value.trim()).catch((err) => {
+    tokenError.textContent = `Could not load the fleet: ${err.message}`;
+    tokenError.hidden = false;
+  });
+});
+
+// A stored token skips the prompt, but a 401 still clears it and asks again —
+// the server, not the storage, is the source of truth.
+const stored = localStorage.getItem(TOKEN_KEY);
+if (stored === null) {
+  showTokenPrompt();
+} else {
+  start(stored).catch((err) => {
+    tokenError.textContent = `Could not load the fleet: ${err.message}`;
+    showTokenPrompt();
+  });
+}

package/src/dashboard/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Conductor fleet</title>
+<link rel="stylesheet" href="/style.css" />
+</head>
+<body>
+<header>
+  <h1>Conductor fleet</h1>
+</header>
+<main>
+  <section id="token-panel" hidden>
+    <p>
+      The dashboard is bearer-authenticated. The token is the file
+      <code>dashboard-token</code> next to <code>config.json</code> under
+      <code>$OMP_CONDUCTOR_HOME</code> on the fleet host (minted 0600 the first
+      time <code>omp-conductor dashboard</code> started).
+    </p>
+    <form id="token-form">
+      <label for="token-input">Token</label>
+      <input id="token-input" type="password" autocomplete="off" required spellcheck="false" />
+      <button type="submit">Show fleet</button>
+      <p id="token-error" class="error" hidden>That token was refused.</p>
+    </form>
+  </section>
+  <section id="fleet" hidden>
+    <ul id="projects" class="projects"></ul>
+  </section>
+</main>
+<script src="/app.js"></script>
+</body>
+</html>

package/src/dashboard/server.ts

@@ -0,0 +1,267 @@
+/**
+ * The fleet dashboard server (epic #292, slice 1/5): a separate `Bun.serve`
+ * process that renders the fleet in a browser.
+ *
+ * Deliberately NOT a route on the daemon port: that surface is unauthenticated
+ * and loopback-only by design, and `verbs/server.test.ts` pins every non-daemon
+ * path (and every mutating method) to 404. The dashboard is its own process
+ * with its own bearer token, and it only ever *reads* fleet state — it never
+ * starts, stops or mutates a daemon.
+ *
+ * The token is minted once at `<stateDir()>/dashboard-token` — the same
+ * 0700-dir / 0600-file atomic discipline `writeConfigRaw` uses — and reused on
+ * every later start. Every `/api/*` request must present it as
+ * `Authorization: Bearer <token>`; anything else is a bare 401 with no body
+ * detail. Static assets ship on disk next to this module and are served
+ * unauthenticated; the UI asks for the token once and keeps it in
+ * localStorage.
+ *
+ * Project liveness is the one membership convention `status` and `board`
+ * already share (#379): `livingDaemon()` + `healthCheck(port)`, classified by
+ * `classifyDaemonProjectHealth`. A project whose record is absent, whose
+ * daemon will not answer `/healthz`, or whose record is pinned to another
+ * project renders as down — never as an empty healthy fleet.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig, stateDir } from "../config.ts";
+import { healthCheck, livingDaemon, type DaemonRecord } from "../lifecycle.ts";
+import { classifyDaemonProjectHealth } from "../fleet.ts";
+import type { ProjectConfig } from "../types.ts";
+
+/** The dashboard's default bind address — loopback, like the daemon port. */
+export const DASHBOARD_HOST = "127.0.0.1";
+/** The dashboard's default port. Away from the daemon's 8787 and the verbs. */
+export const DASHBOARD_PORT = 8788;
+
+const TOKEN_FILE = "dashboard-token";
+
+/** Where the bearer token lives, next to config.json under `$OMP_CONDUCTOR_HOME`. */
+export function tokenPath(): string {
+  return join(stateDir(), TOKEN_FILE);
+}
+
+/** The stored token, or undefined when the dashboard has never been started. */
+export function readDashboardToken(): string | undefined {
+  try {
+    const raw = readFileSync(tokenPath(), "utf8").trim();
+    return raw.length > 0 ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function hashToken(value: string): Buffer {
+  return createHash("sha256").update(value).digest();
+}
+
+/**
+ * Constant-time bearer check. Both sides are hashed to fixed length first so a
+ * wrong-length candidate cannot leak the stored token's length through the
+ * compare — the arm-challenge spirit: verify by hash, never by a plaintext
+ * comparison that leaks shape in timing.
+ */
+export function verifyDashboardToken(presented: string | undefined, stored: string): boolean {
+  if (presented === undefined || presented.length === 0) return false;
+  return timingSafeEqual(hashToken(presented), hashToken(stored));
+}
+
+/**
+ * Mints `<stateDir()>/dashboard-token` on first start; later starts reuse the
+ * existing token. The write discipline is `writeConfigRaw`'s: the state dir is
+ * created 0700 (chmod only what this call created, so an operator-chosen mode
+ * survives), the file is written 0600 through a same-directory temp file and
+ * an atomic rename so a crash mid-write leaves the previous token intact
+ * rather than a truncated one.
+ */
+export function ensureDashboardToken(): string {
+  const existing = readDashboardToken();
+  if (existing !== undefined) return existing;
+
+  const token = randomBytes(32).toString("base64url");
+  const dir = stateDir();
+  const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // mkdir's mode is masked by umask; chmod only what we just created so an
+  // existing directory keeps whatever the user chose for it.
+  if (created !== undefined) chmodSync(dir, 0o700);
+
+  const target = tokenPath();
+  const tmp = join(dir, `.dashboard-token.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`);
+  try {
+    writeFileSync(tmp, `${token}\n`, { mode: 0o600 });
+    renameSync(tmp, target);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+  // The rename preserves the temp's 0600; state it anyway so the promise never
+  // leans on umask moods.
+  chmodSync(target, 0o600);
+  return token;
+}
+
+/** One configured project as `/api/projects` reports it. */
+export interface DashboardProjectView {
+  name: string;
+  /** `tracker.repo` — the issue source the project dispatches. */
+  repo: string;
+  daemon: {
+    /** The shared verdict every viewer uses (#379). */
+    state: "ok" | "stopped" | "unreachable" | "other-project";
+    /** The living daemon's port when a record exists; null when there is none. */
+    port: number | null;
+    /** The raw `/healthz` body, parsed, when this project's daemon answered it. */
+    healthz?: unknown;
+    /** Which project a foreign living record is pinned to, when state is other-project. */
+    serves?: string;
+  };
+}
+
+/**
+ * One project against a record already read for the request. The record is
+ * shared across projects so one pidfile read serves one whole request.
+ */
+async function probeProject(project: ProjectConfig, record: DaemonRecord | undefined): Promise<DashboardProjectView> {
+  // The status/board gate (#379): never health-check a record pinned to
+  // another project — its `/healthz` would describe a daemon that does not
+  // serve this one, and mixing the two is how an empty fleet reads as healthy.
+  const pinnedElsewhere =
+    record !== undefined && record.project !== undefined && record.project !== project.name;
+  const health =
+    record !== undefined && !pinnedElsewhere ? await healthCheck(record.port) : undefined;
+  const classified = classifyDaemonProjectHealth(record, health, project.name);
+
+  const view: DashboardProjectView = {
+    name: project.name,
+    repo: project.tracker.repo,
+    daemon: { state: classified.kind, port: record?.port ?? null },
+  };
+  if (classified.kind === "ok") {
+    let healthz: unknown;
+    try {
+      healthz = JSON.parse(health?.body ?? "null") as unknown;
+    } catch {
+      healthz = undefined;
+    }
+    view.daemon.healthz = healthz;
+  } else if (classified.kind === "other-project") {
+    view.daemon.serves = classified.serves;
+  }
+  return view;
+}
+
+/**
+ * Every configured project, annotated for the dashboard. Read-only: never
+ * starts a daemon, never touches a pidfile beyond `livingDaemon()`'s read.
+ */
+export async function dashboardProjects(): Promise<DashboardProjectView[]> {
+  const cfg = loadConfig();
+  const record = livingDaemon();
+  return Promise.all(cfg.projects.map((project) => probeProject(project, record)));
+}
+
+export interface DashboardHttpDeps {
+  /** The bearer token every `/api/*` request must carry. */
+  token: string;
+  /** The `/api/projects` payload. */
+  projects(): Promise<DashboardProjectView[]>;
+}
+
+const STATIC_FILES: Record<string, string> = {
+  "/": "index.html",
+  "/index.html": "index.html",
+  "/app.js": "app.js",
+  "/style.css": "style.css",
+};
+
+const STATIC_MIME: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+};
+
+/** The value of `Authorization: Bearer <token>`, or undefined for any other form. */
+function bearerToken(req: Request): string | undefined {
+  const header = req.headers.get("authorization");
+  if (header === null) return undefined;
+  const prefix = "Bearer ";
+  return header.startsWith(prefix) ? header.slice(prefix.length).trim() : undefined;
+}
+
+/**
+ * The dashboard's whole HTTP surface, separated from the socket exactly like
+ * `daemonHttpResponse` so a test can drive it without binding a port. The UI
+ * ships on disk and is served without auth; `/api/*` is bearer-authenticated.
+ */
+export async function dashboardResponse(req: Request, d: DashboardHttpDeps): Promise<Response> {
+  const path = new URL(req.url).pathname;
+  if (path.startsWith("/api/")) {
+    const presented = bearerToken(req);
+    if (presented === undefined || !verifyDashboardToken(presented, d.token)) {
+      // Bare 401: no body, no scheme hint — nothing about the token leaks.
+      return new Response("", { status: 401 });
+    }
+    if (req.method === "GET" && path === "/api/projects") {
+      return Response.json(await d.projects());
+    }
+    return new Response("", { status: 404 });
+  }
+  // Everything outside /api is static UI, unauthenticated by contract.
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    return new Response("", { status: 405 });
+  }
+  const name = STATIC_FILES[path];
+  if (name === undefined) return new Response("not found", { status: 404 });
+  // Small fixed set of files, read on demand like the config: no cache to go
+  // stale when an operator edits the UI beside a running dashboard.
+  const body = readFileSync(join(import.meta.dir, name));
+  const mime = STATIC_MIME[name.slice(name.lastIndexOf("."))] ?? "application/octet-stream";
+  return new Response(body, { headers: { "content-type": mime } });
+}
+
+export interface DashboardStartOpts {
+  port?: number;
+  /** Bind address; defaults to loopback. A non-loopback host still starts,
+   *  with a one-line warning naming the token file. */
+  host?: string;
+}
+
+/** Loopback is the safe posture; anything else gets the token warning. */
+function isLoopbackHost(host: string): boolean {
+  return host === "localhost" || host === "::1" || host.startsWith("127.");
+}
+
+/**
+ * Runs the dashboard until SIGINT/SIGTERM, like the foreground daemon. Mints
+ * the token on first start and prints where the server is listening.
+ */
+export async function startDashboard(opts: DashboardStartOpts = {}): Promise<void> {
+  const token = ensureDashboardToken();
+  const host = opts.host ?? DASHBOARD_HOST;
+  const server = Bun.serve({
+    hostname: host,
+    port: opts.port ?? DASHBOARD_PORT,
+    fetch: (req) => dashboardResponse(req, { token, projects: dashboardProjects }),
+  });
+  // An IPv6 literal needs brackets to be a clickable URL.
+  const displayHost = host.includes(":") ? `[${host}]` : host;
+  process.stdout.write(`dashboard on http://${displayHost}:${server.port}\n`);
+  if (!isLoopbackHost(host)) {
+    // The one-line warning the contract promises: the token file is the only
+    // door onto the project list, so say where it is before a request arrives.
+    process.stderr.write(
+      `warning: dashboard bound to ${host} — anyone who can reach it can use the token at ${tokenPath()}; keep it secret\n`,
+    );
+  }
+  await new Promise<void>((resolve) => {
+    const stop = (): void => {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      void server.stop(true).finally(() => resolve());
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+}

package/src/dashboard/style.css

@@ -0,0 +1,180 @@
+/* Conductor fleet dashboard — minimal, no framework. */
+:root {
+  color-scheme: light dark;
+  --bg: #f6f6f4;
+  --card: #ffffff;
+  --ink: #1c1c1a;
+  --muted: #6b6b64;
+  --line: #dcdcd6;
+  --up: #2e7d32;
+  --down: #b3261e;
+  --warn: #b26a00;
+  --foreign: #8a5a00;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  background: var(--bg);
+  color: var(--ink);
+  line-height: 1.5;
+}
+
+header {
+  padding: 1.25rem 1.5rem 0.5rem;
+}
+
+h1 {
+  font-size: 1.35rem;
+  margin: 0;
+}
+
+main {
+  padding: 0 1.5rem 2rem;
+  max-width: 56rem;
+}
+
+code {
+  font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  font-size: 0.9em;
+  background: color-mix(in srgb, var(--ink) 8%, transparent);
+  padding: 0.05em 0.3em;
+  border-radius: 4px;
+}
+
+#token-panel {
+  background: var(--card);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  padding: 1.25rem;
+  margin-top: 1rem;
+}
+
+#token-panel p {
+  margin: 0 0 0.75rem;
+  color: var(--muted);
+}
+
+form {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  align-items: center;
+}
+
+label {
+  font-weight: 600;
+}
+
+input[type="password"] {
+  flex: 1;
+  min-width: 14rem;
+  padding: 0.45rem 0.6rem;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  font: inherit;
+  background: var(--bg);
+  color: var(--ink);
+}
+
+button {
+  padding: 0.45rem 1rem;
+  border: 0;
+  border-radius: 6px;
+  font: inherit;
+  font-weight: 600;
+  background: var(--ink);
+  color: var(--bg);
+  cursor: pointer;
+}
+
+.error {
+  color: var(--down);
+  font-weight: 600;
+  margin: 0.75rem 0 0;
+  width: 100%;
+}
+
+.projects {
+  list-style: none;
+  margin: 1rem 0 0;
+  padding: 0;
+  display: grid;
+  gap: 0.75rem;
+}
+
+.project {
+  display: flex;
+  gap: 0.85rem;
+  align-items: flex-start;
+  background: var(--card);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  padding: 0.9rem 1rem;
+}
+
+.dot {
+  flex: 0 0 auto;
+  width: 0.7rem;
+  height: 0.7rem;
+  border-radius: 50%;
+  margin-top: 0.4rem;
+}
+
+.dot-ok {
+  background: var(--up);
+}
+
+.dot-stopped,
+.dot-unreachable,
+.dot-other-project {
+  background: var(--down);
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+  min-width: 0;
+}
+
+.name {
+  font-weight: 700;
+}
+
+.repo {
+  color: var(--muted);
+  font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  font-size: 0.85rem;
+}
+
+.state {
+  font-size: 0.9rem;
+}
+
+.state-ok {
+  color: var(--up);
+}
+
+.state-stopped,
+.state-unreachable,
+.state-other-project {
+  color: var(--down);
+  font-weight: 600;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #17171a;
+    --card: #202024;
+    --ink: #ececea;
+    --muted: #9b9b93;
+    --line: #33333a;
+    --up: #7fc97f;
+    --down: #ff8a80;
+  }
+}

package/src/decisions.ts

@@ -13,6 +13,7 @@
  */
 
 import type { DecisionRecord, Store, Tracker } from "./types.ts";
+import { fetchRateLimit, RATE_LIMIT_COOLDOWN_MS } from "./tracker/github.ts";
 
 /**
  * A precondition whose truth this package can check on its own.
@@ -112,29 +113,45 @@ export const probeNpmVersion: NpmProbe = async (spec) => {
 /** Probe for `rate-limit-reset`, injectable so tests never reach the network. */
 export type RateLimitProbe = () => Promise<boolean>;
 
+/** The `gh`-shaped runner {@link probeRateLimitReset} drives (#349). */
+type RateLimitGh = (argv: string[], stdin?: string) => Promise<string>;
+
 /**
- * `gh api rate_limit` — any remaining GraphQL quota means the limit has reset
- * (or never bound). Bounded at 10 s like {@link probeNpmVersion}, for the same
- * reason: this runs inside a tick, and a hung `gh` must cost one unevaluated
- * decision, not the tick.
+ * Run `gh api rate_limit` under a 10 s bound — a hung `gh` must cost one
+ * unevaluated decision, never the tick, the same reason as
+ * {@link probeNpmVersion}.
  */
-export const probeRateLimitReset: RateLimitProbe = async () => {
-  const proc = Bun.spawn(
-    ["gh", "api", "rate_limit", "--jq", ".resources.graphql.remaining"],
-    { stdout: "pipe", stderr: "ignore" },
-  );
+async function ghRateLimit(argv: string[]): Promise<string> {
+  const proc = Bun.spawn(["gh", ...argv], { stdout: "pipe", stderr: "pipe" });
   const timer = setTimeout(() => {
     proc.kill();
   }, 10_000);
   try {
     const [text, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
-    return code === 0 && Number.parseInt(text.trim(), 10) > 0;
-  } catch {
-    return false;
+    if (code !== 0) throw new Error(`gh rate_limit exited ${code}`);
+    return text;
   } finally {
     clearTimeout(timer);
   }
-};
+}
+
+/**
+ * `gh api rate_limit` reports a budget on every GitHub resource the app's
+ * token serves from, and this probe is met only when **both** buckets have
+ * quota left. REST `core` exhaustion alongside a still-warm GraphQL budget is
+ * the exact false positive this probe used to raise (#349), so one warm bucket
+ * must never stand in for recovery on the resource that was actually refused.
+ *
+ * This is half the recovery evidence. The enforced half — no rate refusal on
+ * the tracker's recent breaker ledger — is applied where the store is in view,
+ * in {@link evaluateDecisionConditions}. `rate_limit` alone can report quota
+ * an app would still refuse, so the probe answers a necessary condition, not a
+ * sufficient one.
+ */
+export async function probeRateLimitReset(runGh: RateLimitGh = ghRateLimit): Promise<boolean> {
+  const status = await fetchRateLimit(runGh);
+  return status !== undefined && status.graphql.remaining > 0 && status.core.remaining > 0;
+}
 
 /**
  * Check every open decision that carries a condition and has not met it yet.
@@ -180,7 +197,15 @@ export async function evaluateDecisionConditions(
         // conflict are both unsatisfied (#189).
         satisfied = (await tracker.mergeable(condition.url)) === "clean";
       } else {
-        satisfied = await probes.rateLimit();
+        // `rate-limit-reset` (#349). The probe above (both GitHub buckets warm)
+        // is only half the evidence; recovery is proven by the enforced refusal
+        // ledger — no rate refusal inside the breaker's cooldown window.
+        // `/rate_limit` alone can report quota an app would still refuse, which
+        // is exactly the false positive this fixes, so a recent refusal on the
+        // tracker's breaker keeps the row unmet. A store that cannot report
+        // refusals cannot prove the enforced half, so it fails closed too.
+        const refusals = store.ghRefusalsSince?.(now() - RATE_LIMIT_COOLDOWN_MS);
+        satisfied = (await probes.rateLimit()) && refusals !== undefined && refusals.count === 0;
       }
     } catch {
       continue;