omp-conductor 0.19.7 → 0.20.0

package/src/groom.ts

@@ -0,0 +1,461 @@
+/**
+ * Grooming candidate selection: the one shared rule set that answers "which
+ * backlog issues may a to-spec pass be spent on right now".
+ *
+ * #772 shipped the strict to-spec contract (`TO_SPEC_SCHEMA` +
+ * `recordToSpecGrooming`) and #777 shipped the launch half as a per-tick
+ * capability token redeemed by a `task` tool-call gate inside the tick
+ * extension. That made grooming tick-bound: one batch per low-queue tick, and
+ * an operator message that consumed the tick consumed the batch with it
+ * (#1040). This module is what remains when the token goes away — the
+ * mechanical selection itself, extracted so the dispatch daemon owns launching
+ * (#1041) and the tick is free to audit rather than authorize.
+ *
+ * Where each fact lives decides who enforces it, and every exclusion is
+ * enforced mechanically from authoritative data, never by prose:
+ *
+ *  - Tracker facts — the open-issue pool, the park label, the parent/epic
+ *    probe — are read through the existing Tracker adapter
+ *    (`listOpenIssues`/`childrenOf`) via {@link ToSpecTrackerSeam}, and turned
+ *    into the pool by {@link toSpecPoolFromSnapshot}. If the snapshot cannot be
+ *    read, no batch is selected at all: the selection fails closed rather than
+ *    trusting a model to self-filter parked/parent/epic candidates.
+ *  - Store facts — durable grooming rows (#735), admission's lane/dependency
+ *    holds, active runs, in-flight launches — are enforced by
+ *    {@link toSpecCandidateExclusion}, the single predicate every reader of
+ *    "is this issue already groomed?" goes through.
+ *  - The live source ref for each item cannot be known synchronously without a
+ *    fresh per-repo read, so the launcher stamps the observation time it
+ *    launched at and the strict parser's 24h freshness ceiling re-vets it at
+ *    persistence time — the boundary #772 set, tightened by #1000.
+ *
+ * The module deliberately imports nothing from the tick extension, the harness
+ * or the pi surface: both the daemon and the tick read it, and a selection rule
+ * that could only run inside a session is how grooming became tick-bound in the
+ * first place.
+ */
+
+import { repoSlugFor } from "./gitops.ts";
+import {
+  parseToSpecEvidence,
+  parseToSpecFailureEvidence,
+  TO_SPEC_MAX_SOURCE_AGE_MS,
+  type ToSpecFailure,
+  type ToSpecResult,
+} from "./to-spec.ts";
+import type {
+  DispatchSummary,
+  GroomingRecord,
+  GroomTrigger,
+  IssueState,
+  ProjectConfig,
+  ReadyIssue,
+} from "./types.ts";
+
+/** Routable candidates below which the grooming duty fires (#181). */
+export const DEFAULT_GROOM_BELOW = 4;
+
+/**
+ * Whether the count-based half of the grooming duty fires for one dispatch
+ * row's routable count (#988): below a numeric threshold as always, while
+ * `"always"` leaves this gate open on purpose — the selectors then answer
+ * "is anything left to groom?" from candidate state (ungroomed, unrefused,
+ * unparked), and the caller renders the truthful finding either way. Never
+ * substitute a large number for `"always"`: a big queue must not silence the
+ * duty.
+ */
+export function groomingDue(routed: number, groomBelow: GroomTrigger): boolean {
+  return groomBelow === "always" || routed < groomBelow;
+}
+
+/** The `to-spec` agent every batch item runs under (shipped in
+ *  `omp/agents/to-spec.md`, discovered through OMP's native task-agent
+ *  discovery — never a custom process runtime). */
+export const TO_SPEC_AGENT = "to-spec";
+
+/** The maximum number of candidates one batch may carry (#679's "small
+ *  per-tick candidate limit"; the daemon's own concurrency bounds the
+ *  sessions underneath). */
+export const TO_SPEC_BATCH_MAX = 3;
+
+/** The grooming-table verdict row a launched-but-unfinished batch leaves behind
+ *  (reason, on a `blocked` verdict): the durable in-flight marker that stops
+ *  the next pass — or a restarted daemon — from re-launching the same item.
+ *  `blocked` is deliberate: `recordToSpecGrooming` replaces the row when the
+ *  result lands, and refusing-to-parse output must *not* be swallowed by the
+ *  kept-prior path that protects prior `promotable`/`considered` verdicts. */
+export const TO_SPEC_IN_FLIGHT_REASON = "in-flight";
+
+/**
+ * The grooming-row `reason` a `PROMOTABLE` verdict carries when the daemon's
+ * ready gate refused to queue it (#1041). The verdict itself stays
+ * `promotable` and `promotedAt`/`promotedBy` stay unset: the to-spec pass was
+ * valid and must not be re-spent, but the spec is not queueable yet. One
+ * constant, two writers-and-readers — the daemon stamps it, the tick's
+ * promotion audit renders it — because the last time this fleet hand-copied a
+ * reason string into a second file the two drifted apart (`status-render.ts`'s
+ * duplicate of {@link TO_SPEC_IN_FLIGHT_REASON}).
+ */
+export const TO_SPEC_GATE_REJECTED_REASON = "gate-rejected";
+
+/** What the ready gate found missing, as the rejected row records it. */
+export interface ReadyGateRejection {
+  /** The gate's own `missing[]`, verbatim and in order. */
+  missing: string[];
+  /** When the gate ran, so an audit can say how stale its finding is. */
+  checkedAt: number;
+}
+
+/**
+ * Recover a ready-gate rejection from a grooming row's evidence, or
+ * `undefined` when the row is not one. The daemon writes the rejection as one
+ * added top-level sibling of the untouched to-spec `result`
+ * (`{kind:"to-spec", result:{…}, readyGate:{missing, checkedAt}}`), so
+ * {@link toSpecDurableVerdict} still recovers the verdict and the candidate is
+ * not re-groomed — the spec is rejected, not ungroomed.
+ *
+ * Fails closed on anything it cannot read: an empty `missing` array is not a
+ * rejection (a gate that found nothing missing passed), and a non-string entry
+ * would render as `undefined` in a digest line an operator is asked to act on.
+ */
+export function parseReadyGateRejection(evidence: string): ReadyGateRejection | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(evidence);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const row = parsed as Record<string, unknown>;
+  if (row["kind"] !== "to-spec") return undefined;
+  const gate = row["readyGate"];
+  if (gate === null || typeof gate !== "object" || Array.isArray(gate)) return undefined;
+  const { missing, checkedAt } = gate as { missing?: unknown; checkedAt?: unknown };
+  if (!Array.isArray(missing) || missing.length === 0) return undefined;
+  if (!missing.every((entry) => typeof entry === "string" && entry.length > 0)) return undefined;
+  return {
+    missing: missing as string[],
+    checkedAt: typeof checkedAt === "number" && Number.isFinite(checkedAt) ? checkedAt : 0,
+  };
+}
+
+/**
+ * How long a launch row may sit before it is treated as a dead batch and the
+ * candidate becomes eligible again. A batch that dies with the process (a
+ * daemon stop between launch and settlement) must not park a candidate
+ * forever; the 24h ceiling matches the source-freshness ceiling, so a
+ * relaunched pass always reads new source evidence anyway.
+ */
+export const TO_SPEC_IN_FLIGHT_TTL_MS = 24 * 60 * 60 * 1_000;
+
+/**
+ * How long a refused pass parks its candidate before another batch may be
+ * spent on it. Deliberately the same 24h number as the source-freshness
+ * ceiling and the in-flight TTL — one granularity for this whole lifecycle,
+ * not a third threshold to keep in sync: within that window neither the
+ * authoritative source nor the issue has produced new evidence, so a retry
+ * re-runs the identical prompt and refuses the identical way.
+ *
+ * Without it, a candidate whose delegated pass returns malformed,
+ * source-less or stale output is immediately eligible again, so every
+ * low-queue pass spends a full delegated batch re-grooming it — measured on
+ * this fleet as five permanently-refused rows (#295, #296, #297, #679, #806)
+ * re-offered on every pass, and as #807 groomed twice seven minutes apart
+ * (#887).
+ */
+export const TO_SPEC_REFUSED_RETRY_COOLDOWN_MS = TO_SPEC_MAX_SOURCE_AGE_MS;
+
+/**
+ * The one durability rule for a grooming row: the validated to-spec result it
+ * carries when that result is still fresh, or `undefined` when the row is not
+ * durable grooming at all (no to-spec payload — a hand-edited or pre-#772
+ * row — or a source observed past the freshness ceiling).
+ *
+ * Every reader of "is this issue already groomed?" MUST go through this:
+ * {@link toSpecCandidateExclusion} (selection), the daemon's promotion gate,
+ * and the queue digest's already-considered inventory. Two readers with two
+ * predicates is exactly the #887 defect — the digest told the orchestrator
+ * "never re-groom these" about rows the mechanical selection was
+ * simultaneously offering.
+ */
+export function toSpecDurableVerdict(row: GroomingRecord, now: number): ToSpecResult | undefined {
+  const result = parseToSpecEvidence(row.evidence);
+  if (result === undefined) return undefined;
+  return now - result.source.freshAt <= TO_SPEC_MAX_SOURCE_AGE_MS ? result : undefined;
+}
+
+/** The refusal a row records when its pass produced nothing usable, while the
+ *  cooldown above still holds it out of a new batch; `undefined` for any
+ *  other row, including a refusal whose cooldown has expired. */
+export function toSpecRefusalOnCooldown(row: GroomingRecord, now: number): ToSpecFailure | undefined {
+  const failure = parseToSpecFailureEvidence(row.evidence);
+  if (failure === undefined) return undefined;
+  return now - row.recordedAt <= TO_SPEC_REFUSED_RETRY_COOLDOWN_MS ? failure : undefined;
+}
+
+/** One backlog candidate the mechanical gate can judge. The tracker facts
+ *  (labels, epics) are read from the authoritative open-issue snapshot at
+ *  selection time; they travel in this view so the selector stays
+ *  deterministic and testable. */
+export interface ToSpecCandidateView {
+  issue: number;
+  title: string;
+  /** The routing target — a routed `owner/repo` (from the issue's one
+   *  `routing.labelPrefix<key>` label, resolved through `routing.repos`). */
+  routing: string;
+  /** Operator-parked (`project.stateLabels.backlog`); read from tracker labels. */
+  parked?: boolean;
+  /** A parent/epic with no independently runnable slice; read from the
+   *  tracker's sub-issue probe. */
+  parent?: boolean;
+}
+
+/**
+ * Why one candidate is not eligible for a batch right now, or undefined when
+ * it is. The single rule source for the selection helper and the launcher's
+ * own re-vet at dispatch time — one rule, every reader, so a candidate
+ * excluded in a digest line is excluded at launch for the same reason.
+ *
+ *  - `in-flight`: a launch row recorded within the TTL (a dead batch's row
+ *    expires and the candidate becomes eligible again);
+ *  - `file-lane` / `depends-on`: admission's durable mechanical holds (#735);
+ *  - a fresh valid `to-spec` result in the grooming table: the candidate was
+ *    already groomed at an observed source within the freshness ceiling, so
+ *    re-running it would recompute a verdict that is still valid. New source
+ *    evidence reconsiders it: once the recorded `freshAt` crosses the ceiling
+ *    the row no longer reads as groomed, and a fresh pass overrides it;
+ *  - a refused pass inside {@link TO_SPEC_REFUSED_RETRY_COOLDOWN_MS}: a full
+ *    delegated batch was already spent and produced nothing usable
+ *    (malformed, source-less or stale output). Retrying inside the cooldown
+ *    re-runs the identical prompt against the same source and refuses the
+ *    same way, which is how one broken candidate consumed a batch on every
+ *    low-queue tick (#887);
+ *  - `active`: a run is in flight on the issue right now.
+ */
+export function toSpecCandidateExclusion(
+  candidate: { issue: number },
+  facts: { grooming: GroomingRecord | undefined; active: boolean },
+  now: number,
+): string | undefined {
+  const row = facts.grooming;
+  if (row !== undefined) {
+    if (row.reason === TO_SPEC_IN_FLIGHT_REASON) {
+      if (now - row.recordedAt <= TO_SPEC_IN_FLIGHT_TTL_MS) {
+        return `#${candidate.issue} is already in a to-spec batch (launched ${new Date(row.recordedAt).toISOString()})`;
+      }
+    } else if (row.reason === "file-lane" || row.reason === "depends-on") {
+      return `#${candidate.issue} is mechanically blocked (${row.reason}) — the hold clears by itself`;
+    } else {
+      const durable = toSpecDurableVerdict(row, now);
+      if (durable !== undefined) {
+        return (
+          `#${candidate.issue} was already groomed ${durable.verdict} (source ${durable.source.name}@` +
+          `${durable.source.ref}, observed ${new Date(durable.source.freshAt).toISOString()}) — re-groom only ` +
+          "with new source evidence"
+        );
+      }
+      const refusal = toSpecRefusalOnCooldown(row, now);
+      if (refusal !== undefined) {
+        const retryAt = new Date(row.recordedAt + TO_SPEC_REFUSED_RETRY_COOLDOWN_MS).toISOString();
+        return (
+          `#${candidate.issue} already spent a to-spec batch that was refused as ${refusal.kind} ` +
+          `(${new Date(row.recordedAt).toISOString()}) — eligible again after ${retryAt}, or once the ` +
+          "issue or its source changes"
+        );
+      }
+    }
+  }
+  if (facts.active) return `#${candidate.issue} has a dispatched run in flight`;
+  return undefined;
+}
+
+/**
+ * The mechanical half of grooming: deterministic, bounded selection of the
+ * eligible candidates, smallest issue numbers first, never more than
+ * {@link TO_SPEC_BATCH_MAX} per batch, nothing at/above a numeric grooming
+ * trigger (`"always"` opens that gate and lets candidate state decide, #988),
+ * nothing before the first dispatch summary exists (queue health unknown —
+ * the same gate the queue digest uses). Parked and parent views are honored
+ * when the caller supplies them.
+ *
+ * Production reaches this selector through
+ * {@link selectToSpecCandidates}, which fills the views from the
+ * authoritative tracker snapshot (park label from the open-issue labels,
+ * parent/epic from the sub-issue probe) and streams the store-side exclusions
+ * before the selector runs — so parked and parent exclusions are enforced on
+ * the live path, not only on test inputs.
+ */
+export function selectToSpecBatch(input: {
+  candidates: readonly ToSpecCandidateView[];
+  summary: DispatchSummary | undefined;
+  groomBelow: GroomTrigger;
+  grooming: readonly GroomingRecord[];
+  active: readonly { issue: number }[];
+  now: number;
+}): ToSpecCandidateView[] {
+  if (input.summary === undefined) return [];
+  if (!groomingDue(input.summary.routed, input.groomBelow)) return [];
+  const groomingByIssue = new Map(input.grooming.map((row) => [row.issue, row]));
+  const activeIssues = new Set(input.active.map((run) => run.issue));
+  const selected: ToSpecCandidateView[] = [];
+  for (const candidate of [...input.candidates].sort((a, b) => a.issue - b.issue)) {
+    if (candidate.parked) continue;
+    if (candidate.parent) continue;
+    if (
+      toSpecCandidateExclusion(
+        { issue: candidate.issue },
+        { grooming: groomingByIssue.get(candidate.issue), active: activeIssues.has(candidate.issue) },
+        input.now,
+      ) !== undefined
+    ) {
+      continue;
+    }
+    selected.push(candidate);
+    if (selected.length >= TO_SPEC_BATCH_MAX) break;
+  }
+  return selected;
+}
+
+/**
+ * The authoritative tracker surface the selection is built from (#777): the
+ * two reads through the existing Tracker adapter that answer "which open
+ * backlog issues are actually eligible right now". Production implements this
+ * with `makeTracker(...).listOpenIssues()` / `.childrenOf(...)`; tests inject
+ * deterministic fakes. `listOpenIssues` is the one open-issue snapshot with
+ * labels (#203) — it answers the park label and the routing label
+ * mechanically — and `childrenOf` answers whether a candidate is a parent/epic
+ * (its sub-issues exist, so it has no independently runnable slice of its
+ * own). Both fail closed: an unreadable snapshot means no batch is selected,
+ * while an unreadable parent probe skips that candidate because eligibility
+ * was not mechanically established.
+ */
+export interface ToSpecTrackerSeam {
+  /** Every open issue in the tracker repo, labels included
+   *  (`Tracker.listOpenIssues`). Throws when the tracker cannot be read. */
+  listOpenIssues(project: ProjectConfig): Promise<ReadyIssue[]>;
+  /** Sub-issues of one issue (`Tracker.childrenOf`). */
+  childrenOf(project: ProjectConfig, issue: number): Promise<{ number: number; state: IssueState }[]>;
+}
+
+/**
+ * The tracker half of the candidate views: map one open-issue snapshot onto
+ * the pool the selector can judge. Issues still carrying the queue label are
+ * already queued — not backlog — and leave the pool; issues with zero or
+ * several `routing.labelPrefix` labels (or a label mapping to no configured
+ * repo) cannot name an authoritative source to read and leave the pool,
+ * exactly like admission's unroutable partition. The park label lands on the
+ * view for the selector to drop; the parent/epic probe is separate (one
+ * tracker read per candidate) and stays with {@link selectToSpecCandidates},
+ * which runs it only for candidates the store-side exclusions did not already
+ * reject.
+ */
+export function toSpecPoolFromSnapshot(
+  issues: readonly ReadyIssue[],
+  project: ProjectConfig,
+): ToSpecCandidateView[] {
+  const queueLabel = project.queueLabel;
+  const parkLabel = project.stateLabels.backlog;
+  const { labelPrefix, repos } = project.routing;
+  const views: ToSpecCandidateView[] = [];
+  for (const issue of issues) {
+    if (issue.labels.includes(queueLabel)) continue;
+    const matched = [...new Set(issue.labels.filter((l) => l.startsWith(labelPrefix)))];
+    if (matched.length !== 1) continue;
+    const key = matched[0]!.slice(labelPrefix.length);
+    const target = Object.hasOwn(repos, key) ? repos[key]! : undefined;
+    if (target === undefined) continue;
+    views.push({
+      issue: issue.number,
+      title: issue.title,
+      routing: repoSlugFor(target),
+      parked: issue.labels.includes(parkLabel) ? true : undefined,
+    });
+  }
+  views.sort((a, b) => a.issue - b.issue);
+  return views;
+}
+
+/**
+ * The production selection for one grooming pass: the complete mechanical
+ * selection, from the authoritative tracker snapshot through every exclusion,
+ * ending in the candidates a launcher may spend to-spec sessions on. All of
+ * the following yield an empty batch:
+ *
+ *  - no dispatch row yet, or the routable queue is at/above a numeric
+ *    grooming trigger (`"always"` opens that gate; candidate state decides,
+ *    #988 — the same gate the queue digest uses);
+ *  - the snapshot cannot be read — the selection fails closed rather than
+ *    letting an agent self-filter parked/parent/epic candidates;
+ *  - nothing survives the exclusions (parked, parent/epic, already groomed,
+ *    in-flight, lane/dependency holds, dispatched runs).
+ *
+ * The parent/epic probe runs only for candidates the store-side exclusions
+ * have not already rejected, in issue order, and stops as soon as
+ * {@link TO_SPEC_BATCH_MAX} candidates are collected — a bounded set of
+ * tracker reads per pass, never one per open issue.
+ */
+export async function selectToSpecCandidates(input: {
+  project: ProjectConfig;
+  seam: ToSpecTrackerSeam;
+  summary: DispatchSummary | undefined;
+  groomBelow: GroomTrigger;
+  grooming: readonly GroomingRecord[];
+  active: readonly { issue: number }[];
+  /** An open-issue snapshot the caller already read from the tracker. Shared
+   *  so one pass cannot describe two queues (#848); absent when that read
+   *  failed or was never made, in which case the selection reads its own
+   *  snapshot and fails closed on the same terms. */
+  issues?: readonly ReadyIssue[];
+  now: number;
+}): Promise<ToSpecCandidateView[]> {
+  if (input.summary === undefined) return [];
+  if (!groomingDue(input.summary.routed, input.groomBelow)) return [];
+  let issues = input.issues;
+  if (issues === undefined) {
+    try {
+      issues = await input.seam.listOpenIssues(input.project);
+    } catch {
+      // No authoritative snapshot, no batch: launching without one would make
+      // the agent the selector, which is exactly the defect this module
+      // removes. The next pass retries the read.
+      return [];
+    }
+  }
+  const views = toSpecPoolFromSnapshot(issues, input.project);
+  const groomingByIssue = new Map(input.grooming.map((row) => [row.issue, row]));
+  const activeIssues = new Set(input.active.map((run) => run.issue));
+  const pool: ToSpecCandidateView[] = [];
+  for (const view of views) {
+    if (view.parked) continue;
+    if (
+      toSpecCandidateExclusion(
+        { issue: view.issue },
+        { grooming: groomingByIssue.get(view.issue), active: activeIssues.has(view.issue) },
+        input.now,
+      ) !== undefined
+    ) {
+      continue;
+    }
+    let children: { number: number; state: IssueState }[];
+    try {
+      children = await input.seam.childrenOf(input.project, view.issue);
+    } catch {
+      // Eligibility was not mechanically established for this candidate, so it
+      // sits out this pass rather than being launched on an unproven fact.
+      continue;
+    }
+    if (children.length > 0) continue; // parent/epic with sub-issues: no runnable slice
+    pool.push(view);
+    if (pool.length >= TO_SPEC_BATCH_MAX) break;
+  }
+  // The one shared rule set re-runs on the tracker-vetted pool, so the pure
+  // selector — not a prose instruction — answers what may be launched.
+  return selectToSpecBatch({
+    candidates: pool,
+    summary: input.summary,
+    groomBelow: input.groomBelow,
+    grooming: input.grooming,
+    active: input.active,
+    now: input.now,
+  });
+}

package/src/http-token.ts

@@ -0,0 +1,142 @@
+/**
+ * The daemon HTTP surface's bearer token (Phase 4, chokepoints).
+ *
+ * The daemon's loopback port used to be deliberately unauthenticated: the
+ * comment above its `Bun.serve` called the surface loopback-only by design and
+ * left `POST /wake` and `PUT /runs/:issue/*` open. On a shared host that is a
+ * mutating surface any local process — any browser page that can reach
+ * 127.0.0.1, any other tenant's job — can drive: stop a live worker, raise a
+ * turn ceiling, wake dispatch in a loop. This module is the credential that
+ * closes it. `GET /healthz` stays open, because `requireDaemonControl` probes
+ * it to find a live unit-owned daemon *before* it has any reason to hold a
+ * token, and a health probe mutates nothing.
+ *
+ * ## Why not the dashboard's token
+ *
+ * The discipline here is copied verbatim from `dashboard/server.ts`'s
+ * `ensureDashboardToken` — 0700 state dir, 0600 temp file, atomic rename,
+ * explicit chmod, hash-then-compare — but the *token* is a separate file on
+ * purpose:
+ *
+ *   - Different surface. The dashboard token guards a read-only HTTP server in
+ *     its own process; this one guards the daemon's mutating run control.
+ *   - Different lifetime. The dashboard mints on dashboard start; this one is
+ *     minted by the daemon at start. Either can be rotated by deleting its file
+ *     and restarting only that process.
+ *   - Different blast radius. This token is handed to every CLI caller
+ *     (`extend`, `worker`, `board`, `wake`) and to the dashboard process.
+ *     Handing those the dashboard's token would mean any of them could also
+ *     drive the dashboard's whole `/api/*` surface, and a leak from a CLI
+ *     invocation would compromise both. One credential per surface keeps the
+ *     failure contained.
+ *
+ * ## Minting is the daemon's job, never a client's
+ *
+ * {@link ensureHttpToken} is called by the daemon at start. Clients call
+ * {@link readHttpToken} and refuse when it is absent: an absent token means the
+ * daemon has never run under this `$OMP_CONDUCTOR_HOME`, so a client that
+ * minted one would be inventing a credential the daemon does not know and
+ * turning a clear "the daemon is not running" into a 401 nobody can explain.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateDir } from "./config.ts";
+
+/** The token's filename under `$OMP_CONDUCTOR_HOME`, beside `dashboard-token`. */
+export const HTTP_TOKEN_FILE = "http-token";
+
+/** Where the daemon's bearer token lives, next to config.json. */
+export function httpTokenPath(): string {
+  return join(stateDir(), HTTP_TOKEN_FILE);
+}
+
+/** The stored token, or undefined when the daemon has never started here. */
+export function readHttpToken(): string | undefined {
+  try {
+    const raw = readFileSync(httpTokenPath(), "utf8").trim();
+    return raw.length > 0 ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function hashToken(value: string): Buffer {
+  return createHash("sha256").update(value).digest();
+}
+
+/**
+ * Mints `<stateDir()>/http-token` on first daemon start; later starts reuse the
+ * existing token so every already-configured client keeps working across a
+ * restart. Write discipline is `writeConfigRaw`'s: the state dir is created
+ * 0700 (chmod only what this call created, so an operator-chosen mode
+ * survives), and the token is written 0600 through a same-directory temp file
+ * plus an atomic rename, so a crash mid-write leaves the previous token intact
+ * rather than a truncated one that authenticates nobody.
+ */
+export function ensureHttpToken(): string {
+  const existing = readHttpToken();
+  if (existing !== undefined) return existing;
+
+  const token = randomBytes(32).toString("base64url");
+  const dir = stateDir();
+  const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (created !== undefined) chmodSync(dir, 0o700);
+
+  const target = httpTokenPath();
+  const tmp = join(dir, `.${HTTP_TOKEN_FILE}.${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;
+}
+
+/**
+ * Constant-time `Authorization: Bearer <token>` check.
+ *
+ * Takes the raw header (or null, which is what `Headers.get` returns when it is
+ * absent) so every route checks the same way and no caller has to remember to
+ * strip the scheme. Both sides are hashed to a fixed 32 bytes before the
+ * compare, so a wrong-length candidate cannot leak the stored token's length
+ * through `timingSafeEqual`'s length check — the same reason
+ * `verifyDashboardToken` hashes first.
+ */
+export function verifyHttpToken(header: string | null, token: string): boolean {
+  if (header === null || token.length === 0) return false;
+  const match = /^Bearer[ \t]+(\S+)$/.exec(header.trim());
+  if (match === null) return false;
+  return timingSafeEqual(hashToken(match[1]!), hashToken(token));
+}
+
+/**
+ * The refusal every client prints when the token file is absent, worded once so
+ * `extend`, `worker`, `board`, `wake` and the dashboard proxy cannot drift.
+ * Names the file and the cause: the daemon mints it at start, so no file means
+ * no daemon has run here.
+ */
+export function missingHttpTokenMessage(): string {
+  return (
+    `no daemon HTTP token at ${httpTokenPath()} — the daemon mints it at start, ` +
+    "so this means no daemon has run under this OMP_CONDUCTOR_HOME. " +
+    "Start it with `omp-conductor start` and retry."
+  );
+}
+
+/**
+ * The `Authorization` header every mutating client must send, or `undefined`
+ * when there is no token to send. Callers turn `undefined` into
+ * {@link missingHttpTokenMessage} — never into an unauthenticated request that
+ * would come back as a bare 401.
+ */
+export function httpAuthHeader(): { authorization: string } | undefined {
+  const token = readHttpToken();
+  return token === undefined ? undefined : { authorization: `Bearer ${token}` };
+}