omp-conductor 0.7.1 → 0.9.0

package/src/daemon.ts

@@ -32,12 +32,13 @@ import { startOrchestrator } from "./orchestrator.ts";
 import type { OrchestratorHandle } from "./orchestrator.ts";
 import { createReportOutbox, formatOpenReports } from "./reports.ts";
 import { recordReleaseBlock } from "./release-policy.ts";
-import { branchName, route } from "./routing.ts";
+import { branchName, effectiveLabels, route } from "./routing.ts";
 import type { Routed, UnroutableReason } from "./routing.ts";
-import { evaluateDecisionConditions, probeNpmVersion } from "./decisions.ts";
+import { evaluateDecisionConditions, probeNpmVersion, probeRateLimitReset } from "./decisions.ts";
 import { classifyRun, type ClassifyFacts } from "./failure-class.ts";
-import { dbPath, openStore } from "./store.ts";
-import { makeTracker } from "./tracker/github.ts";
+import { projectLabels } from "./label-projection.ts";
+import { dbPath, openStore, utcDay } from "./store.ts";
+import { makeTracker, type RateLimitStatus } from "./tracker/github.ts";
 import { RELEASE_SHAPES } from "./types.ts";
 import type {
   AdmissionHoldReason,
@@ -323,11 +324,45 @@ export function pausedAt(): number | undefined {
   }
 }
 
-export function setPaused(v: boolean): void {
+/**
+ * Who paused the fleet and why, read from line 2 of the same sentinel
+ * {@link setPaused} writes — `undefined` when the fleet is not paused or the
+ * file has no (parseable) line 2. Provenance lives on its own line so line 1
+ * stays a pure ISO timestamp that {@link pausedAt} can `Date.parse`; the `armed
+ * <ISO> owner=<id>` marker `armTicks` writes is the same one-key-per-line
+ * precedent.
+ */
+export function pauseProvenance(): { source: string; reason?: string } | undefined {
+  const f = join(stateDir(), "paused");
+  if (!existsSync(f)) return undefined;
+  try {
+    const second = readFileSync(f, "utf8").split("\n")[1];
+    if (second === undefined) return undefined;
+    const match = /^source=(\S+)(?: reason="(.*)")?$/.exec(second.trim());
+    if (match === null) return undefined;
+    const source = match[1]!; // the regex guarantees group 1 on a match
+    const reason = match[2];
+    return { source, ...(reason === undefined ? {} : { reason }) };
+  } catch {
+    // Unreadable sentinel: no provenance to name, and the refuse-everything
+    // posture of an unknown pause is unchanged.
+    return undefined;
+  }
+}
+
+export function setPaused(v: boolean, why?: { source: string; reason?: string }): void {
   const f = join(stateDir(), "paused");
   if (v) {
     mkdirSync(dirname(f), { recursive: true });
-    writeFileSync(f, `${new Date().toISOString()}\n`);
+    const line1 = `${new Date().toISOString()}\n`;
+    if (why === undefined) {
+      writeFileSync(f, line1);
+    } else {
+      // Quotes are stripped before embedding so a reason cannot break out of
+      // the `reason="..."` field of line 2.
+      const reason = why.reason === undefined ? "" : ` reason="${why.reason.replaceAll('"', "")}"`;
+      writeFileSync(f, `${line1}source=${why.source}${reason}\n`);
+    }
   } else {
     rmSync(f, { force: true });
   }
@@ -481,13 +516,17 @@ function acceptanceCriteria(issue: ReadyIssue): string {
 }
 
 /**
- * Add the new label before dropping the old one. The reverse order leaves a
- * window where the issue carries no state label at all, which is exactly the
- * shape `isEligible` treats as fresh work.
+ * Record a state-label swap for projection (#201). The add enqueues before the
+ * remove — the reverse order would leave a window where the issue carries no
+ * state label at all, which is exactly the shape `isEligible` treats as fresh
+ * work. Synchronous: enqueueing is a local store write and cannot fail on the
+ * tracker; the projector applies the pair in order and retries on refusal.
  */
-async function swapLabel(tracker: Tracker, issue: number, from: string, to: string): Promise<void> {
-  await tracker.addLabel(issue, to);
-  await tracker.removeLabel(issue, from);
+function swapLabel(store: Store, projectName: string, issue: number, from: string, to: string): void {
+  store.enqueueLabelOps(projectName, [
+    { issue, op: "add", label: to },
+    { issue, op: "remove", label: from },
+  ]);
 }
 
 /**
@@ -821,13 +860,18 @@ export async function verifyPushedGreenClaim(
  */
 export async function collectSettlementFlags(
   tracker: Pick<Tracker, "prDiff">,
-  claim: { prUrl?: string; report: string; issueText: string },
+  claim: { prUrl?: string; report: string; priorReports?: readonly string[]; issueText: string },
 ): Promise<{ flags: SettlementFlag[]; truncated: boolean } | undefined> {
   if (claim.prUrl === undefined) return undefined;
   const diff = await tracker.prDiff(claim.prUrl);
   if (diff === undefined) return undefined;
   return {
-    flags: analyseSettlement({ report: claim.report, issueText: claim.issueText, diff }),
+    flags: analyseSettlement({
+      report: claim.report,
+      issueText: claim.issueText,
+      diff,
+      priorReports: claim.priorReports,
+    }),
     truncated: diff.truncated,
   };
 }
@@ -904,12 +948,17 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
   };
 
   try {
-    // Claim on the tracker FIRST, before any local work. The label — not the
-    // store — is the crash-safe guard against double dispatch: if this process
-    // dies mid-run, the next daemon sees the label, `isEligible` filters the
-    // issue out, and a human decides what to do with the orphan.
-    await tracker.addLabel(issue, inProgress);
-    claimed = true;
+    // Claim on the STORE first, before anything that can fail. The run row —
+    // not the label — is the crash-safe guard against double dispatch: rows
+    // are local, written before any network call, and the startup orphan
+    // sweep marks process-less claimed/running rows `orphaned`, so a daemon
+    // dying mid-claim leaves a row a human can triage instead of a label only
+    // the orchestrator may touch. The in-progress label is a write-behind
+    // projection of that row: enqueued here, flushed by the post-admission
+    // projection pass in the same tick on the healthy path, and — while
+    // pending — kept effective off the ready set by the routing overlay, so a
+    // crash between the row and its label cannot double-dispatch either
+    // (#201).
     // Read before this attempt's own row exists, so `latestRun` still means the
     // attempt whose work this one inherits.
     const priorSalvage = store.latestRun(project.name, issue)?.salvageSha;
@@ -929,6 +978,8 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       startedAt: Date.now(),
     });
     const runId = run.id;
+    store.enqueueLabelOps(project.name, [{ issue, op: "add", label: inProgress }]);
+    claimed = true;
     turnLimit = d.turnLimits.open(project.name, issue, runId, caps.workerMaxTurns);
 
     // A run's tree is <workspaceRoot>/<issue> and addRunRepo refuses to reuse
@@ -1068,6 +1119,15 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         ? await collectSettlementFlags(tracker, {
             prUrl: result.prUrl,
             report: result.report,
+            // Earlier attempts' reports pool as disclosure coverage (#199). The
+            // current row has not settled yet, so this is exactly the prior set;
+            // the strict `< attempt` guard keeps an already-persisted copy of
+            // this attempt out just in case. Pre-#199 rows have NULL reports and
+            // contribute nothing — today's behaviour.
+            priorReports: store
+              .attemptReports(project.name, issue)
+              .filter((r) => r.attempt < attempt)
+              .map((r) => r.report),
             issueText: `${r.issue.title}\n${r.issue.body}`,
           })
         : undefined;
@@ -1076,7 +1136,9 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       else if (audit.truncated) log(`#${issue} settlement audit read a truncated PR diff`);
     }
     const auditLines =
-      audit === undefined ? [] : formatSettlementFlags(audit.flags, { truncated: audit.truncated });
+      audit === undefined
+        ? []
+        : formatSettlementFlags(audit.flags, { truncated: audit.truncated, attempts: attempt });
 
     const finalReport = [
       ...(verified.reason === undefined ? [] : [verified.reason, ""]),
@@ -1126,6 +1188,10 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       prUrl: result.prUrl,
       headSha: result.headSha,
       sessionFile: result.sessionFile,
+      // Every terminal state persists the worker's report, not just a green
+      // push: the report of a killed attempt is exactly the one a later
+      // continuation must pool its disclosures from (#199).
+      report: result.report,
       ...(verified.reason === undefined ? {} : { lastError: verified.reason }),
       ...settlement?.patch,
       ...(audit === undefined || audit.flags.length === 0
@@ -1136,7 +1202,7 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
     const salvaged = settlement?.lines ?? [];
 
     if (state === "blocked") {
-      await swapLabel(tracker, issue, inProgress, project.stateLabels.blocked);
+      swapLabel(store, project.name, issue, inProgress, project.stateLabels.blocked);
       await safeEscalate(d, {
         tier: 1,
         project: project.name,
@@ -1159,8 +1225,12 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       });
 
       if (continueTurns) {
-        await tracker.removeLabel(issue, inProgress);
-        await tracker.addLabel(issue, project.queueLabel);
+        // Requeue as one ordered pair: the in-progress removal before the
+        // queue add, exactly the order the projector will apply them in (#201).
+        store.enqueueLabelOps(project.name, [
+          { issue, op: "remove", label: inProgress },
+          { issue, op: "add", label: project.queueLabel },
+        ]);
         log(
           `#${issue} turns-cap on run ${attempt}, continuation ` +
             `${continuation}/${caps.maxContinuationsPerIssue} — salvaged and re-queued`,
@@ -1184,7 +1254,7 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
           ].join("\n"),
         });
       } else {
-        await swapLabel(tracker, issue, inProgress, project.stateLabels.failed);
+        swapLabel(store, project.name, issue, inProgress, project.stateLabels.failed);
         await safeEscalate(d, {
           tier: 1,
           project: project.name,
@@ -1282,11 +1352,9 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
     if (claimed) {
       // Leaving the issue stuck as in-progress would hide it from both the
       // queue and the human, so relabel even on the error path.
-      try {
-        await swapLabel(tracker, issue, inProgress, project.stateLabels.failed);
-      } catch (relabelErr) {
-        log(`#${issue} could not be relabelled: ${errText(relabelErr)}`);
-      }
+      // The failure-path relabel cannot throw: it is a local outbox write, and
+      // the projector retries until the tracker takes it (#201).
+      swapLabel(store, project.name, issue, inProgress, project.stateLabels.failed);
     }
 
     const salvaged = settlement?.lines ?? [];
@@ -1360,46 +1428,35 @@ export function settlementFor(pr: PrState | undefined, prUrl: string): Settlemen
 }
 
 /**
- * Drops the in-progress label from an issue whose run is provably over.
+ * Records the in-progress label's release as a projection op (#201).
  *
  * Settlement used to write only half of what it knew. On 2026-08-09 that cost
  * the reference fleet two issues in one night: veltro#331 settled to `failed`
  * at 23:53Z once the orchestrator closed veltro#332 unmerged, and veltro#344
  * settled to `merged` at 05:54Z once chad#452 squash-merged. Both rows left the
  * active set correctly; an authoritative `gh issue view` on each afterwards
- * still showed `agent:in-progress`. `routing.isEligible` rejects any issue
- * carrying a state label, the composed brief forbids the orchestrator from
- * hand-editing one, and `unblock` refused to clear that particular label — so
- * both issues were permanently unclaimable with no supported way back (#18).
+ * still showed `agent:in-progress` — permanently unclaimable with no supported
+ * way back (#18).
  *
- * Never throws, and reports whether the label is provably gone, because the
- * caller has to decide what to write to the store on the strength of it. A
- * sweep must not lose the rest of its rows to one unreachable tracker, and it
- * must not terminalise a row whose label it failed to drop: the settlement
- * sweep only ever revisits `pushed-*` rows, so a row written terminal is a row
- * nothing asks about again, and swallowing the failure under it would recreate
- * the exact permanent-`agent:in-progress` state of #18 in the one case that
- * still reaches it. Answering false instead leaves the row where the next tick
- * will find it.
+ * The outbox makes the row transition and the label one fact again: the
+ * removal is enqueued in the same breath as the row is terminalised, the
+ * projector applies it with unbounded retry, and while it is pending the
+ * eligibility overlay treats the label as already gone. A tracker that refuses
+ * the write (403, rate limit) can no longer strand the row — that is `#184`
+ * and `#198` closed. No `pushed-*` row is ever written terminal with its
+ * label release owed but unrecorded, because enqueueing is a local store write
+ * that cannot fail on the tracker.
  *
- * Removing a label the issue does not carry is success, not failure: the GitHub
- * adapter treats an absent label as a no-op, so false means the tracker could
- * not be reached or refused — a condition that passes.
+ * Synchronous. The op is durable the moment this returns.
  */
-export async function releaseInProgress(
-  d: Pick<Deps, "project" | "tracker">,
+export function releaseInProgress(
+  d: Pick<Deps, "project" | "store">,
   issue: number,
   why: string,
-): Promise<boolean> {
+): void {
   const label = d.project.stateLabels.inProgress;
-  try {
-    await d.tracker.removeLabel(issue, label);
-    log(`#${issue} released ${label}: ${why}`);
-    return true;
-  } catch (err) {
-    log(`#${issue} could not release ${label} (${errText(err)}) — ${why}; retrying next tick`);
-    return false;
-  }
+  d.store.enqueueLabelOps(d.project.name, [{ issue, op: "remove", label }]);
+  log(`#${issue} released ${label} (queued): ${why}`);
 }
 
 /**
@@ -1473,15 +1530,15 @@ export async function settlePushedGreen(
 
     const settlement = settlementFor(pr, run.prUrl);
     if (settlement !== undefined) {
-      // Label first, row second, and the order is the whole safety argument.
-      // The sweep only ever revisits `pushed-*` rows, so writing the terminal
-      // state first would put this row beyond every later tick — and a tracker
-      // that failed on the label in that instant would strand
-      // `agent:in-progress` permanently, which is #18 again in the one window
-      // still able to reach it. Leaving the row `pushed-*` costs a stale active
-      // row until the tracker answers, and the busy set keeps the issue
-      // occupied meanwhile, so nothing can be dispatched onto it in between.
-      if (!(await releaseInProgress(d, run.issue, settlement.reason))) continue;
+      // The label removal and the terminal row are one fact again (#201): the
+      // release is enqueued — a durable local write that cannot fail on the
+      // tracker — in the same breath as the row is terminalised, so there is
+      // no window in which a row beyond every later tick still owes its label.
+      // The projector applies it with retry; while pending, the eligibility
+      // overlay treats the label as already gone, so #18's
+      // permanent-`agent:in-progress` cannot re-form even when GitHub refuses
+      // the write.
+      releaseInProgress(d, run.issue, settlement.reason);
       const patch: Partial<RunRecord> = { state: settlement.state, endedAt: Date.now() };
       if (settlement.state === "failed") patch.lastError = settlement.reason;
       store.updateRun(run.id, patch);
@@ -1502,11 +1559,11 @@ export async function settlePushedGreen(
       store.updateRun(run.id, { state: "pushed-green", lastError: undefined });
       log(`#${run.issue} checks settled: ${verification.reason}`);
     } else if (verification.status === "failed") {
-      // Equally terminal, so the same label-first order for the same reason:
-      // this row is about to leave the sweep's reach. The green branch above
-      // releases nothing — that row is still awaiting a merge, and its live PR
-      // is exactly the work the label must keep guarding.
-      if (!(await releaseInProgress(d, run.issue, verification.reason))) continue;
+      // Equally terminal, so the release is enqueued before the row writes,
+      // for the same reason as the settlement branch above (see there). The
+      // green branch releases nothing — that row is still awaiting a merge,
+      // and its live PR is exactly the work the label must keep guarding.
+      releaseInProgress(d, run.issue, verification.reason);
       store.updateRun(run.id, { state: "failed", lastError: verification.reason });
       log(`#${run.issue} checks failed: ${verification.reason}`);
     } else {
@@ -1757,6 +1814,13 @@ export async function admitCandidates(
     if (list === undefined) activeByIssue.set(run.issue, [run]);
     else list.push(run);
   }
+  // Live worker count per repo, seeded from live runs and incremented as this
+  // same pass admits — so two same-repo candidates can never both clear the
+  // per-repo cap in one tick (#186).
+  const liveByRepo = new Map<string, number>();
+  for (const run of store.liveRuns(project.name)) {
+    liveByRepo.set(run.repo, (liveByRepo.get(run.repo) ?? 0) + 1);
+  }
   const holds: AdmissionHold[] = [];
   const hold = (issue: number, reason: AdmissionHoldReason): void => {
     holds.push({ issue, reason });
@@ -1781,10 +1845,12 @@ export async function admitCandidates(
     return { admitted: [], holds };
   }
 
-  // parent -> blocking issue. Seeded from active runs (including pushed-green),
-  // then extended by candidates admitted earlier in this same pass so two
-  // siblings never both clear the gate in one tick.
-  const occupiedParents = new Map<number, number>();
+  // parent -> repo name -> blocking issue. Seeded from active runs (including
+  // pushed-green), then extended by candidates admitted earlier in this same
+  // pass so two siblings of one epic never both clear the gate in one tick.
+  // A busy issue whose run row cannot be resolved occupies the sentinel repo
+  // "" — treated as matching every repo, failing toward holding (#197).
+  const occupiedParents = new Map<number, Map<string, number>>();
   const parentCache = new Map<number, number | undefined>();
 
   const resolveParent = async (issue: number): Promise<number | undefined> => {
@@ -1799,8 +1865,18 @@ export async function admitCandidates(
   for (const issue of busyIssues) {
     try {
       const parent = await resolveParent(issue);
-      if (parent !== undefined && !occupiedParents.has(parent)) {
-        occupiedParents.set(parent, issue);
+      if (parent === undefined) continue;
+      // The runs table records which repo each attempt worked in, and sibling
+      // holds are now per-repo, so a busy child only occupies its epic under
+      // that repo's name (same spelling as `createRun` writes from
+      // `r.repo.name`). A busy issue with no resolvable run row occupies the
+      // sentinel "" instead — matching every repo, failing toward holding.
+      const repo = store.latestRun(project.name, issue)?.repo ?? "";
+      const siblings = occupiedParents.get(parent);
+      if (siblings === undefined) {
+        occupiedParents.set(parent, new Map([[repo, issue]]));
+      } else if (!siblings.has(repo) && !siblings.has("")) {
+        siblings.set(repo, issue);
       }
     } catch (err) {
       log(`#${issue} parent lookup failed while seeding epic occupancy (${errText(err)})`);
@@ -1828,6 +1904,16 @@ export async function admitCandidates(
       }
     }
 
+    // Per-repo concurrency: the mirror, branch-protection staleness and shared
+    // CI egress are all per-repo collision domains, so extra slots should land
+    // on other repos rather than stacking workers into the same one (#186).
+    const liveInRepo = liveByRepo.get(r.repo.name) ?? 0;
+    if (liveInRepo >= caps.maxConcurrentWorkersPerRepo) {
+      hold(issue, "repo-active");
+      log(`#${issue} skipped: ${liveInRepo} live worker(s) already in ${r.repo.name} (cap ${caps.maxConcurrentWorkersPerRepo})`);
+      continue;
+    }
+
     const priorRuns = store.attemptsFor(project.name, issue);
     const failures = store.failuresFor(project.name, issue);
     if (failures >= caps.maxAttemptsPerIssue) {
@@ -1890,10 +1976,13 @@ export async function admitCandidates(
       continue;
     }
 
-    // Soft concurrency per epic: at most one in-flight child of a given parent.
-    // No parent means today's concurrent admission. Cheap local filters already
-    // ran; this sits before the open-PR API call so a held sibling frees the
-    // slot for unrelated work without spending a closers query.
+    // Soft concurrency per epic, per repository: at most one in-flight child of
+    // a given parent in each repo. Children of one epic in *different* repos
+    // parallelise freely — `repo-active` / `maxConcurrentWorkersPerRepo` owns
+    // the same-repo collision domain (#197). The "" sentinel matches every
+    // repo. No parent means today's concurrent admission. Cheap local filters
+    // already ran; this sits before the open-PR API call so a held sibling
+    // frees the slot for unrelated work without spending a closers query.
     let parent: number | undefined;
     try {
       parent = await resolveParent(issue);
@@ -1903,10 +1992,11 @@ export async function admitCandidates(
       continue;
     }
     if (parent !== undefined) {
-      const blocker = occupiedParents.get(parent);
+      const occupied = occupiedParents.get(parent);
+      const blocker = occupied?.get(r.repo.name) ?? occupied?.get("");
       if (blocker !== undefined) {
         hold(issue, "sibling-active");
-        log(`#${issue} skipped: sibling #${blocker} in flight under epic #${parent}`);
+        log(`#${issue} skipped: sibling #${blocker} in flight under epic #${parent} in ${r.repo.name}`);
         continue;
       }
     }
@@ -1976,7 +2066,18 @@ export async function admitCandidates(
     }
 
     admitted.push({ r, attempt: priorRuns + 1 });
-    if (parent !== undefined) occupiedParents.set(parent, issue);
+    liveByRepo.set(r.repo.name, (liveByRepo.get(r.repo.name) ?? 0) + 1);
+    if (parent !== undefined) {
+      // Extend the epic's occupancy under this repo (slot empty by construction
+      // here — the gate above would have held the candidate otherwise) so a
+      // same-repo sibling later in this pass does not clear the gate (#197).
+      let siblings = occupiedParents.get(parent);
+      if (siblings === undefined) {
+        siblings = new Map();
+        occupiedParents.set(parent, siblings);
+      }
+      if (!siblings.has(r.repo.name)) siblings.set(r.repo.name, issue);
+    }
   }
 
   return { admitted, holds };
@@ -2072,6 +2173,18 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
     log(`label reconcile failed: ${errText(err)}`);
   }
 
+  // Drain the label projection outbox (#201). The maintenance phases above may
+  // have enqueued ops (settlement releases, recovery requeues, reconciles);
+  // each due op is applied now — or deferred with backoff for the next tick —
+  // before the queue is read, so dispatch sees labels converging on what the
+  // store decided. A refusing tracker defers ops instead of taking the tick
+  // down.
+  try {
+    await projectLabels(d.store, d.tracker, d.project);
+  } catch (err) {
+    log(`label projection failed: ${errText(err)}`);
+  }
+
   // Ledger maintenance, above the pause gate for the same reason the stall watch
   // is: a paused fleet still owes its operator the questions it asked, and a
   // condition that came true while dispatch was parked is exactly the thing the
@@ -2083,7 +2196,13 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   for (const expired of d.store.expireDueDecisions(d.project.name, Date.now())) {
     log(`decision ${expired.id} expired unanswered after seven days: ${expired.question}`);
   }
-  void evaluateDecisionConditions(d.store, d.project.name, d.tracker, probeNpmVersion, Date.now)
+  void evaluateDecisionConditions(
+    d.store,
+    d.project.name,
+    d.tracker,
+    { npm: probeNpmVersion, rateLimit: probeRateLimitReset },
+    Date.now,
+  )
     .then((met) => {
       for (const decision of met) {
         log(`decision ${decision.id} condition met (${decision.condition ?? "?"}) — surfacing on the next tick`);
@@ -2122,7 +2241,7 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
       `ERROR: the installed conductor changed under this daemon — ${integrity.diff.length} file(s) differ ` +
         `(${shown.join(", ")}${integrity.diff.length > shown.length ? ", …" : ""}) — pausing`,
     );
-    setPaused(true);
+    setPaused(true, { source: "integrity", reason: "installed package changed under the daemon" });
     if (integrity.page) {
       const delivered = await safeEscalate(d, {
         tier: 2,
@@ -2158,7 +2277,17 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
     new Set(ready.map((issue) => issue.number)),
     d.cleanup ?? { next: 0 },
   );
-  const { routed, unroutable } = route(ready, project);
+  // Label-projection overlay (#201): an issue whose outbox ops have not
+  // reached GitHub yet is judged on what its labels *will* be. A pending
+  // state-label removal stops a stale GitHub label from blocking redispatch,
+  // and a pending queue-label removal drops the issue out of eligibility even
+  // though the label is still physically present. isEligible stays pure; the
+  // overlay happens here.
+  const effective = ready.map((issue) => {
+    const pending = store.pendingLabelOpsFor(project.name, issue.number);
+    return pending.length === 0 ? issue : { ...issue, labels: effectiveLabels(issue.labels, pending) };
+  });
+  const { routed, unroutable } = route(effective, project);
   const routingHolds: AdmissionHold[] = unroutable.map((u) => ({
     issue: u.issue.number,
     reason: `unroutable:${u.reason}`,
@@ -2197,7 +2326,7 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   // operator opted out — turns and wall-clock still brake every run (#46).
   const spent = store.spendSince(project.name, since);
   if (caps.dailySpendUsd !== null && spent >= caps.dailySpendUsd) {
-    setPaused(true);
+    setPaused(true, { source: "spend-cap", reason: `daily spend reached $${caps.dailySpendUsd}` });
     await safeEscalate(d, {
       tier: 2,
       project: project.name,
@@ -2242,6 +2371,16 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
     (a) => handleIssue(d, a.r, a.attempt),
     workers,
   );
+
+  // Post-admission flush: freshly claimed runs enqueued their in-progress
+  // label inside `handleIssue`; applying it now means the guard label lands on
+  // GitHub within the same tick on the healthy path, not five minutes later
+  // (#201).
+  try {
+    await projectLabels(store, d.tracker, project);
+  } catch (err) {
+    log(`label projection failed: ${errText(err)}`);
+  }
 }
 
 // --------------------------------------------------------------- read-only views
@@ -2403,6 +2542,28 @@ export interface StatusSnapshot {
    * than print a percentage nobody measured (#110).
    */
   planUsage?: PlanUsageStatus;
+  /**
+   * The GitHub API rate-limit budget, when the caller read one. Optional for
+   * the same reason as `planUsage` — the read is I/O and the snapshot is
+   * synchronous — and a broken `gh` must cost one status row, not the report
+   * (#188).
+   */
+  github?: RateLimitStatus;
+  /**
+   * Observed GitHub rate-limit refusals within the last five minutes, and the
+   * daemon's tracked per-source `gh` call counts for the UTC day. Unlike
+   * `github`, which a caller polls, these are written by the tracker's hooks —
+   * the polled budget sat beside what actually happened (#198).
+   */
+  ghRefusals?: { count: number; latestAt?: number };
+  ghCallsToday?: readonly { source: string; calls: number }[];
+  /**
+   * Label-projection ops still owed to the tracker (#201). Present only while
+   * one is pending: GitHub has not yet converged on what the store decided —
+   * a refused or deferred label write is exactly the state an operator should
+   * see rather than a silent gap.
+   */
+  labelOps?: { pending: number; oldestAgeMs: number };
 }
 
 /** Builds a status reading from an already-open store. Long-lived operator
@@ -2416,6 +2577,8 @@ export function statusSnapshotFromStore(
 ): StatusSnapshot {
   const since = startOfToday();
   const dispatch = store.latestDispatch(p.name);
+  const labelOpsPending = store.countPendingLabelOps(p.name);
+  const oldestLabelOpAt = store.oldestPendingLabelOpAt(p.name);
   return {
     project: p.name,
     configPath: configPath(),
@@ -2432,6 +2595,13 @@ export function statusSnapshotFromStore(
     spendTodayUsd: store.spendSince(p.name, since),
     ...(dispatch === undefined ? {} : { dispatch }),
     ...(planUsage === undefined ? {} : { planUsage }),
+    // Written by the tracker's hooks rather than polled, so the renderer does
+    // not re-read GitHub to know it is being refused (#198).
+    ghRefusals: store.ghRefusalsSince?.(Date.now() - 5 * 60_000),
+    ghCallsToday: store.ghCallsToday?.(utcDay()),
+    ...(labelOpsPending === 0 || oldestLabelOpAt === undefined
+      ? {}
+      : { labelOps: { pending: labelOpsPending, oldestAgeMs: Date.now() - oldestLabelOpAt } }),
   };
 }
 
@@ -2629,7 +2799,7 @@ export async function previewQueue(project?: string): Promise<QueuePreview> {
  */
 export function prepareConductor(): void {
   openStore(dbPath()).close();
-  setPaused(true);
+  setPaused(true, { source: "setup" });
 }
 
 /** Bounded per tick: each row costs tracker calls to gather facts for. */
@@ -2764,11 +2934,11 @@ async function recoverRun(
   const inProgress = project.stateLabels.inProgress;
 
   if (recovery === "settle") {
-    // Label before row, copied from `settlePushedGreen` where the order is the
-    // whole safety argument: writing the terminal state first would put this row
-    // beyond every later tick, and a tracker that then failed on the label would
-    // strand `agent:in-progress` with nothing left to retry it (#18).
-    if (!(await releaseInProgress(d, run.issue, `PR merged: ${evidence}`))) return;
+    // Enqueue the release with the terminal write (see `settlePushedGreen`):
+    // the outbox keeps the label and the row one fact, so a tracker refusal
+    // can no longer strand `agent:in-progress` with nothing left to retry it
+    // (#18, #201).
+    releaseInProgress(d, run.issue, `PR merged: ${evidence}`);
     store.updateRun(run.id, { state: "merged", endedAt: Date.now(), recoveredAt: Date.now() });
     log(`#${run.issue} settled from ${cls}: ${evidence}`);
     return;
@@ -2794,13 +2964,15 @@ async function recoverRun(
     // `merge-conflict`: the branch is retained and its PR is open, so #50's
     // continuation guard admits it and the next tick briefs a rebase.
     //
-    // The tracker write goes FIRST, and that ordering is the whole retry
-    // contract. Writing `recoveredAt` before the swap took the row out of
-    // `runsNeedingClassification` — which selects on `recoveredAt IS NULL` — so a
-    // refused label swap stranded the row permanently under a log line promising
-    // a retry. That was the defect 0.4.4 claimed to have fixed and did not, for
-    // this one recovery.
-    if (!(await swapToQueue(d, run.issue, inProgress))) return;
+    // The outbox makes the retry contract one-sided: the swap is enqueued — a
+    // durable local write that cannot fail on the tracker — before
+    // `recoveredAt` is written, so the row can never again be taken out of
+    // `runsNeedingClassification` with its label swap still owed. That was
+    // the defect 0.4.4 claimed to have fixed and did not, for this one
+    // recovery; the projector retries until the tracker takes the swap, and
+    // while it is pending the eligibility overlay keeps the issue coherent
+    // (#201).
+    swapToQueue(d, run.issue, inProgress);
     store.updateRun(run.id, {
       state: "killed",
       lastError:
@@ -2841,7 +3013,7 @@ async function recoverRun(
       return;
     }
     const label = cls === "orphan-clean" ? inProgress : project.stateLabels.failed;
-    if (!(await swapToQueue(d, run.issue, label))) return;
+    swapToQueue(d, run.issue, label);
     store.updateRun(run.id, { recoveredAt: Date.now() });
     log(`#${run.issue} requeued from ${cls}: ${evidence}`);
     return;
@@ -2907,26 +3079,22 @@ async function recoverRun(
 }
 
 /**
- * Swap a state label for the queue label, in that order.
+ * Enqueue a state-label → queue-label swap for projection (#201).
  *
- * Both writes go through the same Tracker port the dispatcher claimed with, so
- * orphan detection stays trustworthy. Returns false when either half failed, so
- * the caller leaves the row for the next tick rather than recording a recovery
- * that did not happen.
+ * The swap is two ops in id order — remove first, then add — which is the
+ * atomicity the projector guarantees: the issue never sits newly eligible
+ * without a queue label on its way back, and the add never lands before the
+ * remove when GitHub fails between them. Enqueueing is a durable local write
+ * that cannot fail on the tracker, so the caller records its recovery
+ * immediately and the projector retries the swap until the tracker takes it —
+ * that closes the 0.4.4 hole where a refused label swap stranded the row
+ * permanently under a log line promising a retry.
  */
-async function swapToQueue(
-  d: Pick<Deps, "project" | "tracker">,
-  issue: number,
-  label: string,
-): Promise<boolean> {
-  try {
-    await d.tracker.removeLabel(issue, label);
-    await d.tracker.addLabel(issue, d.project.queueLabel);
-    return true;
-  } catch (err) {
-    log(`#${issue} could not be requeued (${errText(err)}) — retrying next tick`);
-    return false;
-  }
+function swapToQueue(d: Pick<Deps, "project" | "store">, issue: number, label: string): void {
+  d.store.enqueueLabelOps(d.project.name, [
+    { issue, op: "remove", label },
+    { issue, op: "add", label: d.project.queueLabel },
+  ]);
 }
 
 /** Bounded listing per state label, so one reconcile cannot walk a whole repo. */
@@ -2956,13 +3124,11 @@ export async function reconcileStaleLabels(d: Deps): Promise<void> {
     for (const issue of carrying) {
       if (issue.state === "closed") {
         // Never retain an `agent:*` label on a closed issue: the work is done by
-        // some route, and the label only makes the board lie about it.
-        try {
-          await tracker.removeLabel(issue.number, label);
-          log(`#${issue.number} reconciled: closed issue no longer carries ${label}`);
-        } catch (err) {
-          log(`#${issue.number} could not drop ${label} (${errText(err)}) — retrying next tick`);
-        }
+        // some route, and the label only makes the board lie about it. Enqueue
+        // rather than call — a refused write must not lose the decision; the
+        // projector retries the removal until the tracker takes it (#201).
+        store.enqueueLabelOps(project.name, [{ issue: issue.number, op: "remove", label }]);
+        log(`#${issue.number} reconciled: closed issue no longer carries ${label} (queued)`);
         continue;
       }
 
@@ -2973,8 +3139,8 @@ export async function reconcileStaleLabels(d: Deps): Promise<void> {
       const key = `${project.name}:superseded:${issue.number}`;
       if (store.wasNotified(key)) continue;
       const list = children.map((c) => `#${c.number}`).join(", ");
+      store.enqueueLabelOps(project.name, [{ issue: issue.number, op: "remove", label }]);
       try {
-        await tracker.removeLabel(issue.number, label);
         await tracker.comment(
           issue.number,
           `superseded: all sub-issues closed (${list}) — this label was stale; propose closing if the ` +
@@ -2983,7 +3149,9 @@ export async function reconcileStaleLabels(d: Deps): Promise<void> {
         store.markNotified(key);
         log(`#${issue.number} reconciled: superseded by ${list}`);
       } catch (err) {
-        log(`#${issue.number} could not be reconciled (${errText(err)}) — retrying next tick`);
+        // The label removal is already queued and will land regardless; the
+        // comment is the only half that can fail here (#201).
+        log(`#${issue.number} could not comment the superseded note (${errText(err)}) — retrying next tick`);
       }
     }
   }
@@ -3059,7 +3227,19 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   const project = findProject(cfg, o.project);
   const caps = resolveCaps(project, cfg.defaults);
   const store = openStore(dbPath());
-  const tracker = makeTracker(project);
+  // The tracker's single `gh` funnel is bound to the store so the operator sees
+  // observed truth (#198): every spawn is counted per UTC day, and every
+  // rate-limit refusal is recorded for `status`'s 5m window. Board's ad-hoc
+  // trackers and the polled `fetchRateLimit` probe are deliberately not bound —
+  // this row is the daemon's own traffic.
+  const tracker = makeTracker(project, undefined, {
+    onCall: () => store.bumpGhCalls?.(utcDay(), "daemon"),
+    onRefusal: (at) => store.recordGhRefusal?.(at),
+    // A conditional 304 revalidation is a spawn but not a billed read (#203);
+    // counted separately so `status`'s call row keeps telling the truth once
+    // most spawns are free revalidations.
+    onNotModified: () => store.bumpGhCalls?.(utcDay(), "daemon-304"),
+  });
 
   // #126's transport, stated at startup rather than guessed at first use. The
   // banner names what this host can actually enforce — whether the kernel will