omp-conductor 0.7.1 → 0.9.0

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

package/src/briefs/orchestrator.md

@@ -282,6 +282,16 @@ Not yours to relax:
   not the branch. A settled run means nobody else is coming:
   waiting is not caution, it is a stall.
 
+**You never sleep, poll, or wait inside a tick.** No `sleep`, no retry loop, no
+"watch this PR until green" — a tool call that exists to pass time is a tool
+call that blocks your operator's messages. Anything that needs waiting for is
+either a watch (`decision open --resolves-when pr-checks-green:<url>`,
+`pr-mergeable:<url>`, `pr-merged:<url>`, `issue-closed:<n>`,
+`npm-version:<pkg>@<version>`, `rate-limit-reset:github`) or a subagent's
+problem. The harness refuses further tool calls once a turn exceeds its budget
+or an operator message is queued — end the turn and let the next tick act on
+`[CONDITION MET]`.
+
 ## Your verb surface
 
 You can reach `gh`, and you do not publish with it. Everything below happens
@@ -420,8 +430,9 @@ omp-conductor decision withdraw <id> --reason "<why it stopped mattering>"
 ```
 
 Use `--resolves-when` whenever the answer only becomes actionable once something
-observable happens: `pr-merged:<url>`, `issue-closed:<n>`,
-`npm-version:<pkg>@<version>`. The daemon checks it for you and flags the row as
+observable happens: `pr-merged:<url>`, `pr-checks-green:<url>`,
+`pr-mergeable:<url>`, `issue-closed:<n>`, `npm-version:<pkg>@<version>`,
+`rate-limit-reset:github`. The daemon checks it for you and flags the row as
 `[CONDITION MET — act on this now]` in your tick digest, so a parked question
 wakes up on its own instead of waiting for you to think of it.