omp-conductor 0.8.0 → 0.9.0

package/README.md

@@ -524,6 +524,18 @@ Four control planes used to answer "stop" differently. The package verbs:
 
 `status` prints a layered header (`dispatch` / `ticks` / next tick time / `pane` / `recovery` / `herdr` / `telegram` / `daemon`) so a paused fleet cannot hide an armed orchestrator still spending turns. The Telegram line calls the official `getMe` endpoint to prove the token and API are usable without sending a message, then separately reports whether the inbound bridge is configured.
 
+When the tracker is behind what the store decided, `status` adds a
+`labels             projection N pending (oldest …)` row: those are label
+changes the dispatcher committed to and the [projector](#the-tick) has not been
+able to apply yet (a 403, a rate limit). The intended label state is durable, so
+nothing is lost and safety is preserved: for an issue the queue read already
+returns, a pending *state-label removal* is overlaid as applied, so a stale
+label cannot block redispatch. A pending *queue-label add* is different — the
+queue read asks GitHub for issues carrying the queue label, so that issue stays
+invisible to dispatch until the add actually lands. The row is the lag to
+watch: it should drain, and while it does not, work waiting on a queue-label
+add waits with it.
+
 `omp-conductor board [--project NAME]` opens the same facts as a live terminal
 kanban instead of a scrolling wall of status text. Its columns are Queue,
 Claimed, Running, Green, Blocked, Failed, Orphaned, Merged, and History.
@@ -649,14 +661,17 @@ Per tick, for the daemon's project:
 
 Then, per admitted issue:
 
-1. **Apply the `agent:in-progress` label — before any worktree or session exists.**
-   This ordering is the whole crash-safety story: the label, not the local
-   database, is the guard against dispatching the same issue twice. If the process
-   dies at any later point, the next daemon sees the label, eligibility filters the
-   issue out, and the orchestrator's drain duty triages the orphan (see below). A
-   store that is lost can be rebuilt from the tracker; a label that was written too
-   late cannot undo a duplicate PR.
-2. Create the run row (`claimed`).
+1. **Create the run row (`claimed`) — before any worktree or session exists.**
+   This ordering is the whole crash-safety story: the *row*, not a label, is the
+   guard against dispatching the same issue twice. It is local and written before
+   anything that can fail; if the process dies at any later point, the startup
+   orphan sweep marks the left-behind row `orphaned` and the orchestrator's drain
+   duty triages it (see below). The `agent:in-progress` label is a write-behind
+   projection of that row — enqueued in the same breath and applied to the tracker
+   by the projector with retry — so even a tracker that refuses the write cannot
+   recreate a duplicate PR while the guard is unavailable.
+2. Run the tick's post-admission projection pass, which applies freshly enqueued
+   label ops on the healthy path.
 3. Clear any stale tree for this issue, then add a fresh worktree at
    `<workspaceRoot>/<issue>` cut from the bare mirror at `<mirrorRoot>/<repo>.git`,
    on the run's branch off the repo's default branch.
@@ -679,9 +694,17 @@ Then, per admitted issue:
    settles gives up its `agent:in-progress` label. See
    [what settles a green PR](#what-settles-a-green-pr).
 
-   Label swaps add the new label before removing the old one: the reverse order
-   leaves a window in which the issue carries no state label at all, which is
-   exactly the shape eligibility reads as fresh work.
+   Every label write the dispatcher makes goes through the label projection
+   outbox and is applied to the tracker by the projector with retry, strictly in
+   the order it was enqueued per issue — a later op for one issue never lands
+   before an earlier one that is still owed. A state-label swap on a dispatch
+   outcome enqueues the new label ahead of the old one's removal, so the issue
+   is never briefly bare (the shape eligibility reads as fresh work), while a
+   requeue (`swapToQueue`, `unblock`) enqueues its removals ahead of the queue
+   add for the same reason in reverse: the issue must not look claimable before
+   its stale state label is gone. A refused write is deferred with backoff
+   instead of dropped, and `status` shows any un-applied lag on a
+   `labels projection` row.
 
    **Every continuable end salvages the tree first.** A turns-cap kill, a
    wall-clock kill, a crash and a graceful block all leave a tree the next
@@ -793,15 +816,16 @@ Run history is untouched. A PR closed without merging becomes a concrete failed
 attempt; a merge does not spend failure or continuation budget. A settled row also
 loses `agent:in-progress` from its issue: the row transition and the label are one
 fact, and a terminal answer about the PR proves no worker process owns the issue,
-so the duplicate-dispatch guard it exists for is spent. The label comes off
-*before* the row is written terminal, because this sweep is the only thing that
-revisits a `pushed-*` row: a tracker that refuses the removal therefore leaves the
-row pending and the next tick tries again, rather than stranding the label on an
-issue nothing will look at twice. The issue stays in the busy set while it waits,
-so nothing is dispatched onto it in between. Anything beyond that one release — a
-re-queue, a `blocked` marker — is still the orchestrator's drain-duty judgement.
-One unreachable PR costs its own row and nothing else; the rest of the sweep
-still settles.
+so the duplicate-dispatch guard it exists for is spent. The removal is *enqueued
+on the label projection outbox in the same breath as the terminal write* — a
+durable local write that cannot fail on the tracker — so the row settles at once
+and the projector applies the label with retry. A tracker that refuses the
+removal can no longer strand it: the op stays owed, eligibility overlays the
+pending removal so the issue is not held back by a label that is already decided
+gone, and `status` shows the lag. Anything beyond that one release — a re-queue,
+a `blocked` marker — is still the orchestrator's drain-duty judgement. One
+unreachable PR costs its own row and nothing else; the rest of the sweep still
+settles.
 
 Until this existed, nothing ever revisited a `pushed-green` row: the startup
 reconciler only settles rows that held a process, and `merged` went unwritten. On
@@ -1955,7 +1979,7 @@ omp-conductor help
 | `release-pane [--project NAME]` | Clear the `halt --pane` recovery pin so herdr-conductor may resume the fleet agent again. |
 | `tail <issue>` | Follow the newest run for that issue: the worker's assistant text as `assistant: …` and each tool it calls as `tool: <name>`, printed as they land. Workers are omp sessions inside the daemon rather than terminals, so this is the only way to watch one live — a herdr pane running it becomes an observation window. Starts from the top of the transcript, not the end, so attaching to a run that is already ten turns in shows those ten turns. Exits `1` with `no run recorded for #N` when the issue has never been dispatched, or `no transcript yet (state: …)` when the attempt has not opened one. Otherwise it runs until `Ctrl-C`, or until the run has finished and its transcript has been silent for five seconds, and prints `run ended: <state>`. |
 | `extend <issue> --turns N [--project NAME]` | Monotonically raise that live worker's effective turn ceiling through its owning daemon. The current omp session keeps running; no restart or continuation is created. The daemon persists the new ceiling for `status` and rejects missing, settled, cap-killed, equal, or lower requests instead of implying that an immutable session changed. |
-| `unblock <issue> [--force] [--no-requeue]` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again, and restore the project queue label by default so the dispatcher actually sees it. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label (and the queue label stays off until that run settles), and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. `--no-requeue` clears the state labels only, leaving the queue label untouched — the case where you are about to close the issue. **Refuses, clearing nothing and exiting `3`, when the newest attempt's work could not be committed and its worktree is the only copy** — re-claiming removes that tree. `--force` records the operator's acceptance on the run row and then clears; the salvage failure stays in history. Exits `2` when the issue number is missing or malformed. |
+| `unblock <issue> [--force] [--no-requeue]` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again, and restore the project queue label by default so the dispatcher actually sees it. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label (and the queue label stays off until that run settles), and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. The label changes go through the [label projection outbox](#the-tick): they are applied inline before the command returns, but **a tracker that refuses them (403, rate limit) no longer fails the verb** — it exits `0`, the intended label state is durable and the daemon retries it, and the output says `label sync queued (N pending) — the daemon retries` instead of claiming the labels were restored. Safety is preserved, but the issue is only claimable once the queue label itself lands: the queue read asks GitHub for issues carrying that label, so a refused queue-label add keeps the issue out of dispatch until projection succeeds. `--no-requeue` clears the state labels only, leaving the queue label untouched — the case where you are about to close the issue. **Refuses, clearing nothing and exiting `3`, when the newest attempt's work could not be committed and its worktree is the only copy** — re-claiming removes that tree. `--force` records the operator's acceptance on the run row and then clears; the salvage failure stays in history. Exits `2` when the issue number is missing or malformed. |
 | `verb <conductor_*> [--arg k=v ...]` | Run one [mediated verb](#the-mediated-verbs-126) as the orchestrator, from the CLI — the external-orchestrator half of the verb surface. Every argument goes in as a `--arg k=v` string; an orchestrator can merge (`conductor_pr_merge`), label (`conductor_label`), release (`conductor_release`), update a branch (`conductor_pr_update_branch`) or title/body (`conductor_pr_update`), or read PR state (`conductor_pr_status`). The daemon applies the same checks and writes the same ledger rows a session's call would; a missing `--arg` is refused exactly as a missing tool argument is, worker-only verbs (`conductor_push`, `conductor_pr_create`) are refused with `role-not-allowed`, and a refusal exits `3`. An unknown verb exits `2`. |
 | `friction <kind> --detail TEXT [--issue N]` | Record one bounded judgment the daemon cannot infer: an escalation belonged in a digest, or a tick report was noise/surprising. The detail is limited to 160 characters. One event never changes policy; three observations inside seven days make the aggregate eligible for one Learning-loop prompt, followed by a seven-day cooldown. |
 | `report --text TEXT [--kind material|digest]` | Hand a rendered report to the daemon's durable outbox. The text is persisted **before** anything is sent and the command prints a report id; the daemon then owns delivery, retries on a bounded backoff, and records the Telegram message id it actually got back. Delivery is [at-least-once](#report-delivery-the-outbox) — a crash mid-send is retried and the retry says it may be a repeat — so `delivered` is never proof of exactly one message. `--kind digest` is accepted at most once per local day, decided from the ledger rather than from what the session remembers sending; an unknown `--kind` exits `2` rather than quietly becoming a material report. Anything undelivered shows in `status` with its age. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/backups.ts

@@ -0,0 +1,46 @@
+/**
+ * Durable file backups under conductor state.
+ *
+ * Both the brief writer and the config writer keep a copy of every previous
+ * version of the file they replace, so a bad write — or a process dying
+ * mid-upgrade — never destroys the only copy of operator-owned bytes.
+ * Retention is intentionally unbounded, matching the brief backups.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  constants,
+  copyFileSync,
+  linkSync,
+  mkdirSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+
+/** A timestamp stem safe to embed in a file name. */
+export function backupTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/** Publishes `source` under `backupRoot` as `stem`, suffixing on collision. */
+export function copyToUniqueBackup(source: string, backupRoot: string, stem: string): string {
+  mkdirSync(backupRoot, { recursive: true });
+  const temporary = join(backupRoot, `.${stem}.${process.pid}.${randomUUID()}.tmp`);
+  copyFileSync(source, temporary, constants.COPYFILE_EXCL);
+  try {
+    for (let suffix = 0; ; suffix += 1) {
+      const destination = join(backupRoot, suffix === 0 ? stem : `${stem}-${suffix}`);
+      try {
+        // Linking a complete temp file publishes the backup atomically without
+        // overwriting a backup created concurrently at the same millisecond.
+        linkSync(temporary, destination);
+        return destination;
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "EEXIST") continue;
+        throw err;
+      }
+    }
+  } finally {
+    unlinkSync(temporary);
+  }
+}

package/src/board.ts

@@ -20,13 +20,21 @@ import type {
   AdmissionHoldReason,
   PrVerification,
   ProjectConfig,
+  ReadyIssue,
   RunRecord,
   RunState,
   Store,
+  Tracker,
 } from "./types.ts";
 
 const REFRESH_MS = 1_000;
 const HEALTH_REFRESH_MS = 10_000;
+/** Base cadence for the tracker label read, and the ceiling the idle backoff
+ *  in {@link nextLabelDelayMs} doubles toward. Separate from the health gate
+ *  above because only this one leaves the machine: daemon state and the plan
+ *  allowance are local reads and stay fresh at the base cadence regardless. */
+const LABEL_REFRESH_MS = 10_000;
+const LABEL_REFRESH_MAX_MS = 60_000;
 /** Cadence for re-verifying pushed rows against GitHub — deliberately slower
  *  than the board's health/label probe: it is one `gh` call per pushed row, and
  *  pull-request state does not move at 1 Hz. #173. */
@@ -176,6 +184,10 @@ export interface BoardSnapshot {
    *  the PR looks like now. Rendered as a `now:` suffix on the card. */
   pr: ReadonlyMap<string, { status: PrVerification["status"]; reason: string }>;
   runs: RunRecord[];
+  /** What this board itself has spent on the tracker in the last minute, and
+   *  how much of that was free 304s (#210). Absent in one-shot contexts like
+   *  `board --json`, which have no rate to report. */
+  trackerCost?: { calls: number; free: number };
   now: number;
 }
 
@@ -399,6 +411,83 @@ export function boardLanes(snapshot: BoardSnapshot): Map<BoardLane, number[]> {
   return lanes;
 }
 
+/**
+ * The four lifecycle label sets of one open-issue snapshot.
+ *
+ * Label compare is case-insensitive: GitHub label names are unique
+ * case-insensitively, and the server-side filter this replaces matched them
+ * that way. An issue carrying more than one of the four lands in each matching
+ * set, exactly as the four separate label queries did — `laneOf` already
+ * resolves that precedence.
+ */
+export function boardLabelSets(
+  issues: readonly ReadyIssue[],
+  project: ProjectConfig,
+): { queued: Set<number>; inProgress: Set<number>; blocked: Set<number>; failed: Set<number> } {
+  const queued = new Set<number>();
+  const inProgress = new Set<number>();
+  const blocked = new Set<number>();
+  const failed = new Set<number>();
+  const names: Record<"queued" | "inProgress" | "blocked" | "failed", string> = {
+    queued: project.queueLabel.toLowerCase(),
+    inProgress: project.stateLabels.inProgress.toLowerCase(),
+    blocked: project.stateLabels.blocked.toLowerCase(),
+    failed: project.stateLabels.failed.toLowerCase(),
+  };
+  for (const issue of issues) {
+    for (const label of issue.labels) {
+      const lower = label.toLowerCase();
+      if (lower === names.queued) queued.add(issue.number);
+      else if (lower === names.inProgress) inProgress.add(issue.number);
+      else if (lower === names.blocked) blocked.add(issue.number);
+      else if (lower === names.failed) failed.add(issue.number);
+    }
+  }
+  return { queued, inProgress, blocked, failed };
+}
+
+function sameIssueSet(a: ReadonlySet<number>, b: ReadonlySet<number>): boolean {
+  if (a.size !== b.size) return false;
+  for (const issue of a) if (!b.has(issue)) return false;
+  return true;
+}
+
+/**
+ * Whether two label reads say the same thing.
+ *
+ * Read outcome counts as well as membership, but only whether a read *failed*
+ * — never the message. GitHub's failures carry a fresh request id every time
+ * (`... request ID E05A:12929D:...`), so comparing text would score two
+ * identical failures as a change and pin the fast cadence on a tracker that is
+ * broken, which is exactly backwards.
+ */
+export function boardLabelsEqual(a: BoardLabels, b: BoardLabels): boolean {
+  return (
+    sameIssueSet(a.queued, b.queued) &&
+    sameIssueSet(a.inProgress, b.inProgress) &&
+    sameIssueSet(a.blocked, b.blocked) &&
+    sameIssueSet(a.failed, b.failed) &&
+    sameIssueSet(a.open, b.open) &&
+    (a.error === undefined) === (b.error === undefined)
+  );
+}
+
+/**
+ * How long to wait before the next tracker label read.
+ *
+ * #203 made that read a single conditional request that answers 304 while
+ * nothing changes, so an idle board no longer spends rate-limit budget — but a
+ * request nobody needs is still a request, and a board left open in a pane all
+ * day makes thousands of them. Each pass that finds nothing changed doubles the
+ * wait up to {@link LABEL_REFRESH_MAX_MS}; any change, and any operator
+ * keypress, drops it straight back to {@link LABEL_REFRESH_MS}. So the board is
+ * never more than a minute behind, and is back to base cadence the moment
+ * either the work or the operator moves.
+ */
+export function nextLabelDelayMs(current: number, unchanged: boolean): number {
+  return unchanged ? Math.min(current * 2, LABEL_REFRESH_MAX_MS) : LABEL_REFRESH_MS;
+}
+
 function cardIssue(card: BoardCard): number {
   return card.kind === "issue" ? card.issue : card.run.issue;
 }
@@ -562,15 +651,41 @@ function healthLine(snapshot: BoardSnapshot): string {
   ].join("  ·  ");
 }
 
-/** How current the label sets behind the lanes are. A lane rule is only as
- *  authoritative as its last successful read, so a stale one says so instead of
- *  letting an empty QUEUE read as an empty queue. */
+/**
+ * Sliding one-minute count of the board's own tracker requests, pruning what
+ * has aged out of the window.
+ *
+ * #210 asks for the board's request cost to be visible to a human: a board
+ * left open in a pane spent 95% of the fleet's GitHub budget for three and a
+ * half hours and nothing on screen said so. Mutates the two windows in place —
+ * they are the caller's ring buffers, kept small by this prune.
+ */
+export function trackerCostWindow(
+  calls: number[],
+  free: number[],
+  now: number,
+  windowMs = 60_000,
+): { calls: number; free: number } {
+  const cutoff = now - windowMs;
+  while (calls.length > 0 && calls[0]! < cutoff) calls.shift();
+  while (free.length > 0 && free[0]! < cutoff) free.shift();
+  return { calls: calls.length, free: free.length };
+}
+
+/** How current the label sets behind the lanes are, and what this board is
+ *  spending to keep them current. A lane rule is only as authoritative as its
+ *  last successful read, so a stale one says so instead of letting an empty
+ *  QUEUE read as an empty queue. */
 function labelFact(snapshot: BoardSnapshot): string {
   const { readAt, error } = snapshot.labels;
-  if (error === undefined) return "tracker ok";
+  const cost =
+    snapshot.trackerCost === undefined
+      ? ""
+      : ` · ${snapshot.trackerCost.calls}/min${snapshot.trackerCost.free === 0 ? "" : ` (${snapshot.trackerCost.free} free)`}`;
+  if (error === undefined) return `tracker ok${cost}`;
   const detail = error.replace(/\s+/g, " ").slice(0, 80);
-  if (readAt === 0) return `tracker unread — ${detail}`;
-  return `tracker stale ${humanDuration(snapshot.now - readAt)} — ${detail}`;
+  if (readAt === 0) return `tracker unread${cost} — ${detail}`;
+  return `tracker stale ${humanDuration(snapshot.now - readAt)}${cost} — ${detail}`;
 }
 
 function integrationLine(snapshot: BoardSnapshot): string {
@@ -799,36 +914,31 @@ async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealth> {
  * under a run row — are invisible to it, and a board built from run rows alone
  * reports last-run history as current work.
  *
- * "Open issues carrying label L" is a read the tracker port spells exactly
- * once, as `listReady`, taking the label from `queueLabel`. Substituting the
- * label reuses that one read for the state labels rather than adding a twelfth
- * method every future adapter would have to implement for a read-only surface.
- * Four `gh` calls in parallel, on the ten-second health cadence and never on
- * the one-second redraw path: the same order of cost as the health probe it
- * runs beside.
+ * One open-issue snapshot per pass, never one list call per label (#203): the
+ * four lifecycle sets are derived in memory from it by {@link boardLabelSets},
+ * and PARKED openness is read off the same snapshot instead of a per-candidate
+ * `issueState` fan-out. The single read rides the conditional-request cache, so
+ * an idle board costs no primary rate-limit budget at all. The cadence stays
+ * the ten-second health refresh, never the one-second redraw path.
  *
  * Never throws. A failed read keeps the previous sets on screen and records
  * why, because blanking QUEUE and FAILED is a louder lie than showing them
  * stale — {@link labelFact} puts the staleness in the header.
  */
-async function probeBoardLabels(
+export async function probeBoardLabels(
   project: ProjectConfig,
   store: Store,
   previous?: BoardLabels,
+  probeTracker?: Tracker,
 ): Promise<BoardLabels> {
-  const openIssuesLabelled = async (label: string): Promise<Set<number>> =>
-    new Set((await makeTracker({ ...project, queueLabel: label }).listReady()).map((issue) => issue.number));
   try {
-    const [queued, inProgress, blocked, failed] = await Promise.all([
-      openIssuesLabelled(project.queueLabel),
-      openIssuesLabelled(project.stateLabels.inProgress),
-      openIssuesLabelled(project.stateLabels.blocked),
-      openIssuesLabelled(project.stateLabels.failed),
-    ]);
+    const tracker = probeTracker ?? makeTracker(project);
+    const open = await tracker.listOpenIssues();
+    const { queued, inProgress, blocked, failed } = boardLabelSets(open, project);
     // PARKED candidates: the newest run per issue, terminal, non-merged, and
     // wearing no state or queue label. Exactly the rows {@link laneOf} would
-    // otherwise fall through on. Bounded by `recentRuns`' own recentJobs limit,
-    // issued in parallel, and cached: a failed read keeps the last set.
+    // otherwise fall through on. Bounded by `recentRuns`' own recentJobs limit
+    // and cached: a failed read keeps the last set.
     const labelled = new Set([...queued, ...inProgress, ...blocked, ...failed]);
     const newestRun = new Map<number, RunRecord>();
     for (const run of store.recentRuns(project.name, Date.now() - MERGED_HISTORY_MS)) {
@@ -837,14 +947,11 @@ async function probeBoardLabels(
     const parkedCandidates = [...newestRun.values()].filter(
       (run) => PARKED_STATES.has(run.state) && !labelled.has(run.issue),
     );
-    const open = new Set<number>();
-    await Promise.all(
-      parkedCandidates.map(async (run) => {
-        const state = await makeTracker(project).issueState(run.issue);
-        if (state === "open") open.add(run.issue);
-      }),
-    );
-    return { queued, inProgress, blocked, failed, open, readAt: Date.now() };
+    // The snapshot IS the set of open issues, so openness needs no per-issue
+    // lookup: a candidate whose issue appears in it is open.
+    const openNumbers = new Set(open.map((issue) => issue.number));
+    const openSet = new Set(parkedCandidates.map((run) => run.issue).filter((n) => openNumbers.has(n)));
+    return { queued, inProgress, blocked, failed, open: openSet, readAt: Date.now() };
   } catch (err) {
     return {
       ...(previous ?? UNREAD_LABELS),
@@ -905,6 +1012,81 @@ async function waitForInput(queue: KeyInput[], setWake: (wake?: () => void) => v
   return queue.shift() ?? { name: "refresh" };
 }
 
+/**
+ * One-shot snapshot for the headless board (#200): the same setup and one round
+ * of probes `runBoard` performs on entry, with the per-row PR re-verification
+ * probe deliberately skipped — a one-shot is a point-in-time read, so there is
+ * no live verdict map to keep warm.
+ */
+export async function boardSnapshotOnce(projectName?: string): Promise<BoardSnapshot> {
+  const cfg = loadConfig();
+  const project = findProject(cfg, projectName);
+  const caps = resolveCaps(project, cfg.defaults);
+  const store: Store = openStore(dbPath());
+  try {
+    const now = Date.now();
+    const [health, labels, planUsage] = await Promise.all([
+      probeBoardHealth(project),
+      probeBoardLabels(project, store),
+      readPlanUsage(caps.planUsage, sharedUsageSource()),
+    ]);
+    return {
+      project,
+      status: statusSnapshotFromStore(project, caps, store, planUsage),
+      health,
+      labels,
+      pr: new Map(),
+      runs: store.recentRuns(project.name, now - MERGED_HISTORY_MS),
+      now,
+    };
+  } finally {
+    store.close();
+  }
+}
+
+interface BoardJsonRun {
+  issue: number;
+  state: string;
+  attempt?: number;
+  prUrl?: string;
+}
+
+/**
+ * The headless board's JSON view (#200): one entry per issue per lane, fields
+ * read from the lane's newest run row. Issues the store has never run (queue
+ * members placed by label or hold) carry `"state": "queued"` instead. Every
+ * COLUMN_DEFS lane key is emitted, empty ones included, so consumers never
+ * key-check; keys and entries keep the board's stable render order.
+ */
+export function boardJson(snapshot: BoardSnapshot): string {
+  // `recentRuns` yields the newest attempt per issue first; indexing keeps one
+  // entry per issue even when a caller hands over a wider run list.
+  const newest = new Map<number, RunRecord>();
+  for (const run of snapshot.runs) if (!newest.has(run.issue)) newest.set(run.issue, run);
+
+  const lanesByKey = boardLanes(snapshot);
+  const lanes: Record<string, BoardJsonRun[]> = {};
+  for (const { key } of COLUMN_DEFS) {
+    lanes[key] = (lanesByKey.get(key) ?? []).map((issue) => {
+      const run = newest.get(issue);
+      if (run === undefined) {
+        // Label- or hold-placed issues the store never ran. The queue lane's
+        // state is its own word ("queued"); the other label-placed lanes keep
+        // their key as the state, which is exactly what they are.
+        return { issue, state: key === "queue" ? "queued" : key };
+      }
+      const entry: BoardJsonRun = { issue, state: run.state, attempt: run.attempt };
+      if (run.prUrl !== undefined) entry.prUrl = run.prUrl;
+      return entry;
+    });
+  }
+  return JSON.stringify(
+    { project: snapshot.project.name, generatedAt: new Date(snapshot.now).toISOString(), lanes },
+    null,
+    2,
+  );
+}
+
 export async function runBoard(projectName?: string): Promise<void> {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     throw new Error("board needs an interactive terminal (TTY)");
@@ -920,13 +1102,28 @@ export async function runBoard(projectName?: string): Promise<void> {
   let stopping = false;
   let help = false;
   let notice = "";
+  // One tracker for the whole board, bound to its own call counters (#210):
+  // every request this UI makes is counted where a human can see it, instead
+  // of only being visible to an external shim on `gh`.
+  const trackerCalls: number[] = [];
+  const trackerFree: number[] = [];
+  const boardTracker = makeTracker(project, undefined, {
+    onCall: () => trackerCalls.push(Date.now()),
+    onNotModified: () => trackerFree.push(Date.now()),
+  });
   let [health, labels, planUsage] = await Promise.all([
     probeBoardHealth(project),
-    probeBoardLabels(project, store),
+    probeBoardLabels(project, store, undefined, boardTracker),
     readPlanUsage(caps.planUsage, sharedUsageSource()),
   ]);
   let healthAt = Date.now();
   let healthRefresh: Promise<void> | undefined;
+  // The tracker read is gated separately from health and the plan allowance:
+  // those two are local reads that cost no API traffic, so they stay on the
+  // base cadence while this one backs off across unchanged passes.
+  let labelAt = Date.now();
+  let labelDelay = LABEL_REFRESH_MS;
+  let labelRefresh: Promise<void> | undefined;
   // Live re-verification of pushed rows (#173): cached per run id, refreshed on
   // the slow PR cadence so a `gh` call per pushed row does not ride the 1 Hz
   // repaint or the 10 s health gate.
@@ -956,14 +1153,12 @@ export async function runBoard(projectName?: string): Promise<void> {
         healthAt = now;
         healthRefresh = Promise.all([
           probeBoardHealth(project),
-          probeBoardLabels(project, store, labels),
           // On the health cadence, not the 1s repaint: the provider read is a
           // subprocess, and an allowance does not move at 1 Hz.
           readPlanUsage(caps.planUsage, sharedUsageSource()),
         ])
-          .then(([nextHealth, nextLabels, nextPlanUsage]) => {
+          .then(([nextHealth, nextPlanUsage]) => {
             health = nextHealth;
-            labels = nextLabels;
             planUsage = nextPlanUsage;
             enqueue(queue, { name: "refresh" }, wake);
           })
@@ -974,6 +1169,21 @@ export async function runBoard(projectName?: string): Promise<void> {
             healthRefresh = undefined;
           });
       }
+      if (now - labelAt >= labelDelay && labelRefresh === undefined) {
+        labelAt = now;
+        labelRefresh = probeBoardLabels(project, store, labels, boardTracker)
+          .then((nextLabels) => {
+            labelDelay = nextLabelDelayMs(labelDelay, boardLabelsEqual(labels, nextLabels));
+            labels = nextLabels;
+            enqueue(queue, { name: "refresh" }, wake);
+          })
+          .catch((err: unknown) => {
+            notice = `label refresh failed: ${err instanceof Error ? err.message : String(err)}`;
+          })
+          .finally(() => {
+            labelRefresh = undefined;
+          });
+      }
       // #173: re-verify pushed rows against the tracker on their own slow
       // cadence, so red-shown-as-green and a moved head surface without paying
       // for the read every second. A failed probe leaves the last verdicts in
@@ -984,10 +1194,9 @@ export async function runBoard(projectName?: string): Promise<void> {
           (run) => (run.state === "pushed-green" || run.state === "pushed-pending") && run.prUrl !== undefined && run.headSha !== undefined,
         );
         prProbeRun = (async () => {
-          const tracker = makeTracker(project);
           await Promise.all(
             rows.map(async (run) => {
-              const verified = await tracker.verifyPr(run.prUrl!, run.headSha!);
+              const verified = await boardTracker.verifyPr(run.prUrl!, run.headSha!);
               if (verified !== undefined) prProbe.set(run.id, { status: verified.status, reason: verified.reason });
             }),
           );
@@ -1006,6 +1215,7 @@ export async function runBoard(projectName?: string): Promise<void> {
         labels,
         pr: prProbe,
         runs: store.recentRuns(project.name, now - MERGED_HISTORY_MS),
+        trackerCost: trackerCostWindow(trackerCalls, trackerFree, now),
         now,
       };
       normalizeCursor(snapshot, cursor);
@@ -1017,6 +1227,9 @@ export async function runBoard(projectName?: string): Promise<void> {
       });
       const name = key.name ?? key.sequence;
       if (name === "refresh" || name === "resize") continue;
+      // Past this point the key came from a person, not the refresh timer:
+      // someone watching the board gets the base cadence back immediately.
+      labelDelay = LABEL_REFRESH_MS;
       if (name === "?" || key.sequence === "?") {
         help = !help;
         continue;
@@ -1037,6 +1250,7 @@ export async function runBoard(projectName?: string): Promise<void> {
       }
       if (name === "r") {
         healthAt = 0;
+        labelAt = 0;
         notice = "refresh requested";
         continue;
       }
@@ -1110,7 +1324,9 @@ export async function runBoard(projectName?: string): Promise<void> {
           notice = "unblock is available for blocked, failed or orphaned issues";
         } else {
           notice = await unblock(project, cardIssue(card));
+          // An unblock just changed labels: re-read both gates now.
           healthAt = 0;
+          labelAt = 0;
         }
       }
     }

package/src/brief-upgrade.ts

@@ -10,12 +10,8 @@
  * banner can `retrofit` one at a classified cut before migrating.
  */
 
-import { randomUUID } from "node:crypto";
 import {
-  constants,
-  copyFileSync,
   existsSync,
-  linkSync,
   mkdirSync,
   readFileSync,
   readdirSync,
@@ -23,6 +19,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { backupTimestamp, copyToUniqueBackup } from "./backups.ts";
 import { stateDir } from "./config.ts";
 
 /**
@@ -315,32 +312,6 @@ export function briefBackupDir(): string {
   return join(stateDir(), "backups", "briefs");
 }
 
-function backupTimestamp(): string {
-  return new Date().toISOString().replace(/[:.]/g, "-");
-}
-
-function copyToUniqueBackup(source: string, backupRoot: string, stem: string): string {
-  mkdirSync(backupRoot, { recursive: true });
-  const temporary = join(backupRoot, `.${stem}.${process.pid}.${randomUUID()}.tmp`);
-  copyFileSync(source, temporary, constants.COPYFILE_EXCL);
-  try {
-    for (let suffix = 0; ; suffix += 1) {
-      const destination = join(backupRoot, suffix === 0 ? stem : `${stem}-${suffix}`);
-      try {
-        // Linking a complete temp file publishes the backup atomically without
-        // overwriting a backup created concurrently at the same millisecond.
-        linkSync(temporary, destination);
-        return destination;
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).code === "EEXIST") continue;
-        throw err;
-      }
-    }
-  } finally {
-    unlinkSync(temporary);
-  }
-}
-
 /**
  * Moves only conductor's timestamp-shaped legacy sidecar backups into state.
  * Unknown `.bak` files remain operator-owned. Copy-before-unlink also works