omp-conductor 0.9.0 → 0.10.0

package/README.md

@@ -538,7 +538,8 @@ 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.
+Claimed, Running, Green, Blocked, Failed, Orphaned, Merged, Settled, and
+Parked.
 
 Every column is a claim about an issue's state **now**, and each issue appears
 in exactly one of them. Claimed, Running, and Green come from the store, because
@@ -549,10 +550,17 @@ label, Blocked is the blocked state label, and Orphaned is an issue the
 in-progress label still claims with no worker running it — a protected orphan
 whose worktree is kept because it may hold uncommitted work. So a requeued issue
 is queue work even when its last attempt failed, and a closed issue is not
-active work at all. Merged and History are the two backward-looking columns,
-both bounded to the last 24 hours and neither one an action list: History holds
+active work at all. Merged and Settled are the two backward-looking columns,
+both bounded to the last 24 hours and neither one an action list: Settled holds
 recently finished runs that no current label claims, so the board stays
-operational rather than becoming an analytics archive.
+operational rather than becoming an analytics archive. Parked is the issue's
+last word when the tracker has **not** confirmed it closed — a terminal run
+whose issue wears no state or queue label (still open, or a label read that
+failed), so nothing dispatches it until a human labels it. Unlike Merged and
+Settled it is not bounded to 24 hours, because parked work does not stop being
+the issue's only remaining record; Settled alone asserts the issue is closed,
+so an unreadable probe parks rather than letting a run masquerade as finished
+work.
 
 The board refreshes run, spend, turn, and dispatch values from SQLite every
 second. It refreshes the slower daemon, Herdr, Telegram, code-graph, and tracker
@@ -1458,6 +1466,7 @@ persists the class on the row, and performs the one recovery that class names.
 | `admin-kill` | killed *below* its own ceiling — a restart or a drain | requeue | none |
 | `ci-infra` | PR open, every unresolved check cancelled / timed out / stale | re-run the failed jobs | none |
 | `ci-deterministic` | PR open, a check genuinely reports `FAILURE` | escalate with the failing check names and links | failed attempt |
+| `provider-credit` | the provider refused the run for credit (HTTP 402, or its own out-of-credit text read off the transcript) | pause the fleet and require `omp-conductor resume` once the provider has credit | none |
 | `unknown` | anything unrecognised | escalate | as recorded |
 
 **Unknown escalates; it never silently retries.** A shape this table does not
@@ -1466,11 +1475,14 @@ cause nobody has named — the behaviour this exists to end.
 
 ### The budgets follow the cause
 
-`failuresFor` (implementation attempts) excludes `ci-infra`, `settlement-stuck`
-and `env-start-failure`; `continuationsFor` excludes `admin-kill`,
-`settlement-stuck` and `env-start-failure`. An environment fault charges neither:
-the session never started, so nothing about the issue was attempted. A merge conflict *is* charged as a continuation, because a
-rebase is real work — just never as a failed implementation attempt.
+`failuresFor` (implementation attempts) excludes `ci-infra`, `settlement-stuck`,
+`env-start-failure` and `provider-credit`; `continuationsFor` excludes
+`admin-kill`, `settlement-stuck`, `env-start-failure` and `provider-credit`. An
+environment fault charges neither: the session never started, so nothing about
+the issue was attempted, and nor does a provider-credit refusal, which is a
+billing state rather than an implementation failure. A merge conflict *is*
+charged as a continuation, because a rebase is real work — just never as a
+failed implementation attempt.
 
 An **unclassified** row (every row written before 0.4.3) counts exactly as it
 did before classification existed. Upgrading therefore changes no existing
@@ -1971,7 +1983,7 @@ omp-conductor help
 | `upgrade [--to VERSION] [--project NAME]` | Deterministically update the Bun-global CLI, omp plugin, Herdr recovery plugin, and managed brief as one release. Resolves the npm version and exact `gitHead`, pauses only new claims, drains active workers, installs all surfaces, reloads Herdr and the daemon, waits for pane recovery, verifies identities and fleet health twice, then restores the original dispatch state. A no-op when already current. Failure leaves dispatch paused. Must run outside a Herdr-managed session. |
 | `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `brief` / `decisions` / optional `failure classes` and `code graph` / `daemon`, then the project body. The project body includes the latest completed dispatch timestamp, ready/routed/admitted counts, bounded hold groups, and the GitHub API budget (`graphql` / `core` remaining and reset, in the caps block); API failures are marked `DEGRADED` so queue starvation cannot look idle. The next tick comes from the live heartbeat process, not a guess from log timestamps. Telegram health uses `getMe` to prove API authentication without sending a message and reports inbound bridge configuration separately. Configured graphs report prerequisites, indexed repos, timer state, and refresh freshness without blocking dispatch. A `reports` block lists everything the outbox has not delivered, with its age, and prints `pending` (nobody has it) differently from `SENDING` (outcome unknown, it may already have arrived) — see [Report delivery](#report-delivery-the-outbox). The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
 | `ledger [--issue N] [--limit N]` | Every [mediated-verb](#the-mediated-verbs-126) call and how the daemon decided it: the verb, the arguments it was given, allow or refuse, the named refusal reason, and any resulting SHA. Sessions cannot push, open a PR, merge, label or release except through those verbs, so this is the record of what they *tried* as well as what they did — the thing an escalation cites. Reads (`conductor_pr_status`) are deliberately absent: a poll every thirty seconds would bury the refusals. `--issue` narrows to one issue's run; `--limit` defaults to 50. The newest few also appear in `status`. |
-| `board [--project NAME]` | Live keyboard-driven kanban over the same SQLite and `/healthz` truth as `status`, plus the tracker's current labels: Queue, Claimed, Running, Green, Blocked, Failed, Orphaned, and the last 24 hours of Merged and History. Columns are mutually exclusive and describe current state, not the newest run row, so a requeued issue is queued rather than failed and a closed issue is neither. Refreshes run/spend/turn values every second, and health plus the label read every ten seconds. `Enter` follows the selected transcript in place; `u` invokes the existing unblock workflow on a Blocked, Failed, or Orphaned card; `i` / `p` open the issue / PR; `r` refreshes health; `?` shows all keys. Requires an interactive terminal of at least 50×20. |
+| `board [--project NAME]` | Live keyboard-driven kanban over the same SQLite and `/healthz` truth as `status`, plus the tracker's current labels: Queue, Claimed, Running, Green, Blocked, Failed, Orphaned, the last 24 hours of Merged and Settled, and Parked (an issue the tracker has not confirmed closed — still open, or a label read that failed — so nothing dispatches it until a human labels it). Columns are mutually exclusive and describe current state, not the newest run row, so a requeued issue is queued rather than failed and a closed issue is neither. Refreshes run/spend/turn values every second, and health plus the label read every ten seconds. `Enter` follows the selected transcript in place; `u` invokes the existing unblock workflow on a Blocked, Failed, or Orphaned card; `i` / `p` open the issue / PR; `r` refreshes health; `?` shows all keys. Requires an interactive terminal of at least 50×20. |
 | `hold [--project NAME]` | Soft stop: pause claiming **and** disarm ticks. Daemon and pane stay up. Prefer this over `pause` when the intent is "stop the conductor" without killing processes. See [Stop the conductor](#stop-the-conductor-hold--halt). |
 | `halt [--pane] [--project NAME]` | `hold`, then stop the dispatch daemon (systemctl-aware). Pane stays up unless `--pane` is passed. `halt --pane` also pins herdr-conductor recovery off for the conductor agent only — it does **not** stop `herdr-fleet.service` or any other herdr session. Fail-closed: exits nonzero unless the agent is proven gone. |
 | `arm [--project NAME]` | Proof-gated: send a Telegram challenge and write the arm marker only after your reply appears as a user turn in the orchestrator transcript. Never auto-armed by `resume` / `hold`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.9.0",
+  "version": "0.10.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/board.ts

@@ -72,9 +72,9 @@ const COLUMN_DEFS = [
   { key: "blocked", title: "BLOCKED" },
   { key: "failed", title: "FAILED" },
   { key: "orphaned", title: "ORPHANED" },
-  { key: "parked", title: "PARKED" },
   { key: "merged", title: "MERGED" },
-  { key: "history", title: "HISTORY" },
+  { key: "settled", title: "SETTLED" },
+  { key: "parked", title: "PARKED" },
 ] as const satisfies readonly { key: string; title: string }[];
 
 export type BoardLane = (typeof COLUMN_DEFS)[number]["key"];
@@ -151,11 +151,15 @@ export interface BoardLabels {
   inProgress: ReadonlySet<number>;
   blocked: ReadonlySet<number>;
   failed: ReadonlySet<number>;
-  /** Issues whose newest run is terminal and unlabelled but that are still open
-   *  on the tracker — the PARKED lane (#173), probed on the same 10s cadence as
-   *  the label sets. An issue missing from this set (closed, or the probe could
-   *  not tell) keeps today's HISTORY/undefined behaviour rather than parking. */
-  open: ReadonlySet<number>;
+  /**
+   * Issues the tracker reports CLOSED, derived only from a *successful* label
+   * snapshot on the same 10s cadence as the other sets. This is the one fact
+   * that separates SETTLED (finished work, issue closed) from PARKED (a human
+   * still has to look): absence from this set means open **or** the probe could
+   * not tell, and either way the run parks rather than falsely asserting
+   * closure. On a failed read the last good set survives behind {@link error}.
+   */
+  closed: ReadonlySet<number>;
   /** Epoch ms of the last read that succeeded; 0 when none has. */
   readAt: number;
   /** Message from the most recent failed read. The sets above are then the last
@@ -171,7 +175,7 @@ const UNREAD_LABELS: BoardLabels = {
   inProgress: new Set<number>(),
   blocked: new Set<number>(),
   failed: new Set<number>(),
-  open: new Set<number>(),
+  closed: new Set<number>(),
   readAt: 0,
 };
 
@@ -225,7 +229,7 @@ function ansiColor(key: BoardLane): string {
       return YELLOW;
     case "failed":
       return RED;
-    case "history":
+    case "settled":
       return DIM;
     default:
       return MAGENTA;
@@ -285,10 +289,11 @@ function humanDuration(ms: number): string {
  * parent issues a human had already cleared (#81, #86) — every one of them a
  * historical terminal run, not one of them failed work.
  *
- * So: the store decides the live lanes, because a running worker is the most
+ * so: the store decides the live lanes, because a running worker is the most
  * current fact there is; the tracker's current labels decide every stopped
  * lane; each issue matches exactly once, first branch wins; and last-run
- * history is answered in HISTORY, under its own name.
+ * history is answered in SETTLED (issue closed) and PARKED (issue still open,
+ * labels cleared), under their own names.
  */
 function laneOf(
   snapshot: BoardSnapshot,
@@ -322,17 +327,19 @@ function laneOf(
   if (queued.has(issue)) return "queue";
   if (run?.state === "merged") return "merged";
   if (run === undefined) return undefined;
-  // PARKED (#173): a terminal run row with no state or queue label left on it,
-  // on an issue the tracker says is still open. A human cleared the labels but
-  // has not acted — the blank lane the four labels used to imply is a lie, and
-  // closed or unreadable issues keep the HISTORY/undefined fallthrough below.
-  // Deliberately not subject to MERGED_HISTORY_MS: parked work does not stop
-  // being the issue's last word after 24 hours.
-  if (PARKED_STATES.has(run.state) && labels.open.has(issue)) return "parked";
-  // What is left is a terminal run row with no current claim on it — a closed
-  // issue, or one a human already cleared. Recent rows stay readable under
-  // HISTORY for the same 24 hours MERGED uses; older ones are not news.
-  return (run.endedAt ?? run.startedAt) >= snapshot.now - MERGED_HISTORY_MS ? "history" : undefined;
+  // SETTLED vs PARKED, decided by the one fact the board can prove: whether the
+  // tracker confirmed the issue closed. Absence from `closed` means open OR the
+  // probe could not tell, and either way the run parks — a failed label read
+  // must render the issue as "a human has to look", never as finished work
+  // (#218). PARKED is deliberately not subject to MERGED_HISTORY_MS: parked work
+  // does not stop being the issue's last word after 24 hours.
+  if (PARKED_STATES.has(run.state) && !labels.closed.has(issue)) return "parked";
+  // What is left is a confirmed-closed issue with a terminal run row. Recent
+  // rows stay readable under SETTLED for the same 24 hours MERGED uses; older
+  // ones are not news. Named for what it means — the run settled and the issue
+  // is closed — not for the vague archive HISTORY read as, which is how one lane
+  // came to look like two different things (#218).
+  return (run.endedAt ?? run.startedAt) >= snapshot.now - MERGED_HISTORY_MS ? "settled" : undefined;
 }
 
 /** Description lines for an issue the store has no run row for. Only the lanes
@@ -467,7 +474,7 @@ export function boardLabelsEqual(a: BoardLabels, b: BoardLabels): boolean {
     sameIssueSet(a.inProgress, b.inProgress) &&
     sameIssueSet(a.blocked, b.blocked) &&
     sameIssueSet(a.failed, b.failed) &&
-    sameIssueSet(a.open, b.open) &&
+    sameIssueSet(a.closed, b.closed) &&
     (a.error === undefined) === (b.error === undefined)
   );
 }
@@ -551,7 +558,7 @@ function normalizeCursor(snapshot: BoardSnapshot, cursor: BoardCursor): void {
   cursor.transcriptOffset = Math.max(0, cursor.transcriptOffset);
 }
 
-function runCardLines(run: RunRecord, snapshot: BoardSnapshot): string[] {
+function runCardLines(run: RunRecord, snapshot: BoardSnapshot, lane: BoardLane): string[] {
   const endedAt = run.endedAt ?? snapshot.now;
   const duration = humanDuration(endedAt - run.startedAt);
   const lines = [
@@ -564,30 +571,39 @@ function runCardLines(run: RunRecord, snapshot: BoardSnapshot): string[] {
     `attempt ${run.attempt} · ${run.turns}/${run.maxTurns}t`,
     `$${run.spendUsd.toFixed(2)} · ${duration}`,
   ];
-  // #173: a live re-verification of a pushed row, when the 60s probe has one.
-  // Guarded on the pushed states: a stale entry must not follow a row that
-  // settled into another lane and keep claiming "now: green" about a PR that
-  // already merged or failed.
-  const live =
-    run.state === "pushed-green" || run.state === "pushed-pending" ? snapshot.pr.get(run.id) : undefined;
-  if (live !== undefined) {
-    const reason = live.reason.split(/\s+/, 1)[0] ?? "";
-    lines.push(
-      live.status === "failed" ? `now: red — ${reason === "" ? "failed" : reason}` : `now: ${prLabel(live.status)}`,
-    );
-  }
-  // #173: a terminal blocked/failed run whose state label is gone reads as the
-  // lane it sits in — which the label being absent made PARKED, not the truth.
-  if (isLastRun(run, snapshot.labels)) lines.push(`last run: ${run.state}`);
-  // Ordered by what needs a human first. An unsalvaged tree outranks even a
-  // last error: the error describes a run that is over, the tree is work that
-  // is still at risk and an issue that will not dispatch (#118).
+  // Exactly one fourth line, so a card stays within the four content lines that
+  // renderColumn's slot arithmetic (`slots = floor((height - 2) / 5)`) allocates
+  // for it. Every fact a card can carry folds into this single priority:
+  // an unsalvaged tree outranks even a live verdict (#118) — the error describes
+  // a run that is over, the tree is work still at risk — then the live probe for
+  // a pushed row, then the word the lane name cannot carry, then the run's own
+  // evidence.
+  //
+  // `isLastRun` is deliberately not a card line: it belongs in the detail header
+  // (renderDetail's `stateShown`), where a full width can spell out `last run:
+  // blocked`. Putting it here too would blow the budget and repeat the #218
+  // conflation on the two-line boundary.
   if (run.salvageError !== undefined && run.salvageAckAt === undefined) lines.push("UNSALVAGED WIP");
-  else if (run.state === "pushed-pending") lines.push("checks pending");
-  else if (run.salvageSha !== undefined) lines.push(`wip @ ${run.salvageSha.slice(0, 7)}`);
-  else if (run.lastError !== undefined) lines.push(run.lastError.replace(/\s+/g, " "));
-  else if (run.prUrl !== undefined) lines.push(run.prUrl.replace(/^https?:\/\//, ""));
-  else lines.push(run.branch);
+  else {
+    // #173: a live re-verification of a pushed row, when the 60s probe has one.
+    // Guarded on the pushed states: a stale entry must not follow a row that
+    // settled into another lane and keep claiming "now: green" about a PR that
+    // already merged or failed.
+    const live =
+      run.state === "pushed-green" || run.state === "pushed-pending" ? snapshot.pr.get(run.id) : undefined;
+    if (live !== undefined) {
+      const reason = live.reason.split(/\s+/, 1)[0] ?? "";
+      lines.push(
+        live.status === "failed" ? `now: red — ${reason === "" ? "failed" : reason}` : `now: ${prLabel(live.status)}`,
+      );
+    } else if (lane === "settled") lines.push("issue closed");
+    else if (lane === "parked") lines.push("needs a label");
+    else if (run.state === "pushed-pending") lines.push("checks pending");
+    else if (run.salvageSha !== undefined) lines.push(`wip @ ${run.salvageSha.slice(0, 7)}`);
+    else if (run.lastError !== undefined) lines.push(run.lastError.replace(/\s+/g, " "));
+    else if (run.prUrl !== undefined) lines.push(run.prUrl.replace(/^https?:\/\//, ""));
+    else lines.push(run.branch);
+  }
   return lines;
 }
 
@@ -616,7 +632,7 @@ function renderColumn(
     lines.push(styledCell(" (empty)", width, DIM));
   } else {
     for (const [offset, card] of shown.entries()) {
-      const raw = card.kind === "run" ? runCardLines(card.run, snapshot) : [`#${card.issue}`, card.reason, card.note];
+      const raw = card.kind === "run" ? runCardLines(card.run, snapshot, key) : [`#${card.issue}`, card.reason, card.note];
       while (raw.length < 4) raw.push("");
       const selected = selectedColumn && start + offset === selectedCard;
       for (const [lineIndex, value] of raw.entries()) {
@@ -834,6 +850,8 @@ function renderHelp(width: number, height: number): string[] {
     "?             close help",
     "Esc           back, then quit",
     "q / Ctrl-C    back, then quit",
+    "",
+    "PARKED = issue open, no label — nothing dispatches it until you label it",
   ];
   const top = Math.max(0, Math.floor((height - lines.length) / 2));
   return [
@@ -916,7 +934,7 @@ async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealth> {
  *
  * 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
+ * and SETTLED closure 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.
@@ -947,11 +965,19 @@ export async function probeBoardLabels(
     const parkedCandidates = [...newestRun.values()].filter(
       (run) => PARKED_STATES.has(run.state) && !labelled.has(run.issue),
     );
-    // The snapshot IS the set of open issues, so openness needs no per-issue
-    // lookup: a candidate whose issue appears in it is open.
+    // The snapshot IS the set of open issues, so closure needs no per-issue
+    // lookup: a candidate whose issue does NOT appear in it is closed, *because
+    // this read succeeded*. That last clause is the whole distinction on the
+    // failed path — `closed` is only ever derived here, inside the try, so an
+    // unreadable probe survives as the previous set (or empty) and an issue the
+    // board could not confirm closed keeps parking rather than falsely reading
+    // as SETTLED (#218). Absence from `closed` is therefore open OR unknown,
+    // and both mean PARKED.
     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() };
+    const closed = new Set(
+      parkedCandidates.map((run) => run.issue).filter((n) => !openNumbers.has(n)),
+    );
+    return { queued, inProgress, blocked, failed, closed, readAt: Date.now() };
   } catch (err) {
     return {
       ...(previous ?? UNREAD_LABELS),

package/src/briefs/orchestrator.md

@@ -191,6 +191,34 @@ Keep the queue worth draining.
   every attempt.
 - An issue that has exhausted its attempts is not a retry candidate. Diagnose it,
   split it, or hand it back to a human.
+- **Grooming is throughput-bound, so delegate the finding.** N workers drain the
+  queue in parallel while you refill it alone: on a three-worker fleet grooming
+  has to produce roughly three well-specced issues in the time one worker takes
+  to finish one. Auditing candidates serially cannot keep up, and the board then
+  reads "0 ready / workers idle" while you are doing exactly what this duty asks.
+  When the queue is below the grooming trigger, fan out read-only `scout`
+  subagents over backlog clusters **in one batch** rather than auditing one issue
+  at a time. Scouts do the finding; you still do the deciding and you still write
+  the brief. The quality bar above does not move.
+- **Give every scout the same return contract**, or it comes back with prose
+  nobody can act on:
+  - verdict — `ALREADY DONE` / `PROMOTABLE` / `NEEDS DECOMPOSITION` / `BLOCKED` /
+    `NEEDS PRODUCT DECISION`
+  - routing — exactly one repo, or `MULTI` with the split
+  - evidence — the file or symbol proving `ALREADY DONE`, never a title match
+  - entry points — the 3-6 files to change or read first
+  - existing tests covering the behaviour, by path
+  - the one thing most likely to be silently faked
+- **Disqualifying an issue is a successful grooming outcome.** Measured on this
+  package's own fleet: four scouts over sixteen backlog issues promoted four and
+  *disqualified six* that looked promotable from their titles — four written
+  against a tenancy model a later epic retired, two blocked behind open
+  prerequisites named in their own bodies. Each would have burned a worker's whole
+  attempt to discover. On anything old, check first whether a later epic has
+  invalidated the issue's premise; that check is mechanical, read-only, and
+  exactly what a scout is cheap at and you are expensive at.
+- Examine widely, promote narrowly. Sixteen examined and four promoted is the
+  shape to aim for — the cap is on what you **promote**, never on what you look at.
 
 ## Duty 3 — report
 

package/src/daemon.ts

@@ -35,7 +35,7 @@ import { recordReleaseBlock } from "./release-policy.ts";
 import { branchName, effectiveLabels, route } from "./routing.ts";
 import type { Routed, UnroutableReason } from "./routing.ts";
 import { evaluateDecisionConditions, probeNpmVersion, probeRateLimitReset } from "./decisions.ts";
-import { classifyRun, type ClassifyFacts } from "./failure-class.ts";
+import { classifyRun, providerCreditRefusal, type ClassifyFacts } from "./failure-class.ts";
 import { projectLabels } from "./label-projection.ts";
 import { dbPath, openStore, utcDay } from "./store.ts";
 import { makeTracker, type RateLimitStatus } from "./tracker/github.ts";
@@ -1108,6 +1108,16 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         : { state: result.state };
     const state = verified.state;
 
+    // Read before the row is written so `lastError` carries the provider's own
+    // message — it names the fix and the URL, which no classification can.
+    const providerCredit =
+      state === "failed" || state === "killed"
+        ? (() => {
+            const err = readSessionError(result.sessionFile);
+            return err === undefined ? undefined : providerCreditRefusal(err);
+          })()
+        : undefined;
+
     // The other half of not believing a worker about its own run (#128). The
     // claim being audited is `state: pushed-green`, so the audit runs on the
     // worker's claim rather than on what verification made of it: a claim that
@@ -1192,7 +1202,11 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       // 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 }),
+      ...(providerCredit !== undefined
+        ? { lastError: providerCredit }
+        : verified.reason === undefined
+          ? {}
+          : { lastError: verified.reason }),
       ...settlement?.patch,
       ...(audit === undefined || audit.flags.length === 0
         ? {}
@@ -1224,7 +1238,32 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         maxContinuations: caps.maxContinuationsPerIssue,
       });
 
-      if (continueTurns) {
+      if (providerCredit !== undefined) {
+        // Pause here rather than at classification: the sweep runs on the tick,
+        // and three issues each burned an attempt in the fifteen minutes between
+        // the first 402 and a human noticing (#220).
+        setPaused(true, { source: "provider-credit", reason: providerCredit });
+        log(`#${issue} provider refused for credit — dispatch paused: ${providerCredit}`);
+        swapLabel(store, project.name, issue, inProgress, project.stateLabels.failed);
+        // Fleet-scoped and run-independent on purpose. The notification ledger
+        // dedupes on `project:issue:tier:summary`, so `NO_ISSUE` plus a summary
+        // carrying no run or attempt is what makes this page once for the fleet
+        // instead of once per affected run.
+        await safeEscalate(d, {
+          tier: 2,
+          project: project.name,
+          issue: NO_ISSUE,
+          summary: `Model provider refused for credit — ${project.name} is paused`,
+          detail: [
+            providerCredit,
+            "",
+            "No implementation attempt was charged: this is a billing state, not a",
+            "failed implementation. Each affected issue keeps its queue label and",
+            "re-dispatches on `omp-conductor resume` once the provider has credit.",
+            `Session: ${result.sessionFile ?? "(no transcript)"}`,
+          ].join("\n"),
+        });
+      } else if (continueTurns) {
         // 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, [
@@ -2505,6 +2544,12 @@ export interface StatusSnapshot {
   configPath: string;
   stateDir: string;
   paused: boolean;
+  /**
+   * Why the fleet is paused, when whatever paused it said. Rendered beside
+   * `(PAUSED)` so a pause an operator did not issue names itself instead of
+   * reading like a mistake (#220).
+   */
+  pauseReason?: string;
   caps: Caps;
   /**
    * The effective per-shape release grants. On the snapshot rather than re-read
@@ -2579,11 +2624,15 @@ export function statusSnapshotFromStore(
   const dispatch = store.latestDispatch(p.name);
   const labelOpsPending = store.countPendingLabelOps(p.name);
   const oldestLabelOpAt = store.oldestPendingLabelOpAt(p.name);
+  // Read once: the provenance read touches the filesystem, and the renderer
+  // should never pay for it twice per status.
+  const reason = pauseProvenance()?.reason;
   return {
     project: p.name,
     configPath: configPath(),
     stateDir: stateDir(),
     paused: isPaused(),
+    ...(reason === undefined ? {} : { pauseReason: reason }),
     caps,
     releaseGrants: resolveReleaseGrants(p),
     activeRuns: store.activeRuns(p.name),
@@ -2857,6 +2906,57 @@ export function lastToolCalls(sessionFile: string | undefined, limit = SPIN_EVID
   return names.slice(-limit);
 }
 
+/** A provider refusal a session recorded before dying, or undefined for none. */
+export interface SessionError {
+  status?: number;
+  message: string;
+}
+
+/**
+ * The last error a transcript recorded, or undefined when it recorded none.
+ *
+ * The harness writes `{"stopReason":"error","errorStatus":402,"errorId":402,
+ * "errorMessage":"402 This request requires more credits, ..."}`. The daemon
+ * read none of it, so three runs died `unknown` with an empty `lastError` and
+ * charged an attempt each for a billing state (#220).
+ *
+ * Scanned newest-first: a session that recovered from an early error and then
+ * died of something else must report the something else, and a session that
+ * recovered from its only error and finished cleanly reports the error anyway
+ * because there is no terminal verdict to outrank it (#220).
+ */
+export function readSessionError(sessionFile: string | undefined): SessionError | undefined {
+  if (sessionFile === undefined) return undefined;
+  let text: string;
+  try {
+    text = readFileSync(sessionFile, "utf8");
+  } catch {
+    return undefined;
+  }
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (line === undefined || line.length === 0) continue;
+    let row: unknown;
+    try {
+      row = JSON.parse(line) as unknown;
+    } catch {
+      continue;
+    }
+    if (row === null || typeof row !== "object") continue;
+    const rec = row as { readonly [key: string]: unknown };
+    if (rec["stopReason"] !== "error") continue;
+    const message = rec["errorMessage"];
+    if (typeof message !== "string" || message.trim() === "") continue;
+    const status = rec["errorStatus"];
+    return {
+      ...(typeof status === "number" && Number.isFinite(status) ? { status } : {}),
+      message: message.trim(),
+    };
+  }
+  return undefined;
+}
+
 /**
  * Classify every unclassified terminal run, persist the verdict, and perform the
  * one recovery its class names (#132).

package/src/failure-class.ts

@@ -113,6 +113,37 @@ export function startFailure(lastError: string | undefined): string | undefined
   return hit === undefined ? undefined : lastError.split("\n")[0]?.trim();
 }
 
+/**
+ * Provider messages that mean "this key is out of money", matched on the text
+ * the provider itself prints.
+ */
+const CREDIT_REFUSAL_SIGNATURES = [
+  "requires more credits",
+  "insufficient credits",
+  "insufficient_quota",
+  "exceeded your current quota",
+  "credit balance is too low",
+] as const;
+
+/**
+ * Evidence that a model provider refused this run for credit, or `undefined`
+ * when it did not.
+ *
+ * Two independent signals, either sufficient: HTTP 402, which means exactly
+ * this and nothing else, and the refusal text providers print when a key is out
+ * of allowance without using 402. Deliberately narrow — a generic 429 is rate
+ * limiting, which is a different failure with a different remedy.
+ */
+export function providerCreditRefusal(error: {
+  status?: number;
+  message: string;
+}): string | undefined {
+  const text = error.message.toLowerCase();
+  const named = CREDIT_REFUSAL_SIGNATURES.some((signature) => text.includes(signature));
+  if (error.status !== 402 && !named) return undefined;
+  return error.message.split("\n")[0]?.trim() ?? error.message;
+}
+
 /**
  * Evidence that this run never started, or `undefined` when something did happen.
  *
@@ -201,6 +232,22 @@ export function classifyRun(run: RunRecord, facts: ClassifyFacts): Classificatio
     };
   }
 
+  // A billing state, not an implementation failure. Its own class because it is
+  // the one outage an operator fixes with a card rather than a diagnosis, and
+  // because burying a self-describing provider error in `unknown` erodes what
+  // `unknown` means (#220). Ahead of `neverStarted` on purpose: a 402 on the
+  // first request produces a turn-0 row with no artifacts, which
+  // `env-start-failure` would otherwise absorb and lose the cause.
+  if (run.state === "failed" || run.state === "killed") {
+    const credit =
+      run.lastError === undefined
+        ? undefined
+        : providerCreditRefusal({ message: run.lastError });
+    if (credit !== undefined) {
+      return { cls: "provider-credit", recovery: "requeue", evidence: credit };
+    }
+  }
+
   // A run that never started is the most classifiable failure there is, and the
   // least deserving of an implementation attempt: the session did not get as far
   // as reading the issue. See {@link neverStarted} for the two shapes and why the

package/src/fleet.ts

@@ -1062,6 +1062,7 @@ export function formatFleetStatus(
 function formatProjectBody(s: StatusSnapshot): string {
   const lines = [
     `project   ${s.project}${s.paused ? "  (PAUSED)" : ""}`,
+    ...(s.pauseReason === undefined ? [] : [`paused    ${s.pauseReason}`]),
     `config    ${s.configPath}`,
     `state     ${s.stateDir}`,
     "",

package/src/store.ts

@@ -902,12 +902,12 @@ export function openStore(dbPath: string): Store {
   const countFailures = db.query<{ n: number }, [string, number]>(
     `SELECT COUNT(*) AS n FROM runs
       WHERE project = ? AND issue = ? AND state = 'failed'
-        AND (failureClass IS NULL OR failureClass NOT IN ('ci-infra', 'settlement-stuck', 'env-start-failure', 'dispatch-infra'))`,
+        AND (failureClass IS NULL OR failureClass NOT IN ('ci-infra', 'settlement-stuck', 'env-start-failure', 'dispatch-infra', 'provider-credit'))`,
   );
   const countContinuations = db.query<{ n: number }, [string, number]>(
     `SELECT COUNT(*) AS n FROM runs
       WHERE project = ? AND issue = ? AND state IN ('killed', 'orphaned', 'blocked')
-        AND (failureClass IS NULL OR failureClass NOT IN ('admin-kill', 'settlement-stuck', 'env-start-failure', 'dispatch-infra'))`,
+        AND (failureClass IS NULL OR failureClass NOT IN ('admin-kill', 'settlement-stuck', 'env-start-failure', 'dispatch-infra', 'provider-credit'))`,
   );
   // How many times one issue reached a given class. Recovery uses it to bound a
   // retry loop whose cause is persistent (e.g. a mirror that will not refresh):

package/src/types.ts

@@ -831,6 +831,7 @@ export const FAILURE_CLASSES = [
   "orphan-clean",
   "orphan-dirty",
   "settlement-stuck",
+  "provider-credit",
   "unknown",
 ] as const;
 

package/src/unblock.ts

@@ -73,11 +73,11 @@ export interface UnblockOutcome {
   requeueSkipped?: true;
   /** Set when the tracker refused one or more of this verb's label ops, so
    *  the label sync is owed rather than done: the intended label state is
-   *  durable in the store and the daemon retries it (#201). Safety is
-   *  preserved either way, but the issue is only claimable once the queue
-   *  label itself has landed — `listReady` reads the tracker by label, so a
-   *  queue-label add that has not been applied is invisible to dispatch. The
-   *  number is what is still pending. */
+   *  durable in the store and the daemon retries it (#201). This says nothing
+   *  about claimability — `listReady` reads the tracker by label, so an issue
+   *  is dispatchable only once the queue label is physically present, which a
+   *  pending add has not delivered and `--no-requeue` never enqueues at all.
+   *  The number is what is still pending. */
   labelSyncQueued?: number;
 }
 
@@ -268,7 +268,7 @@ export function formatUnblock(
   const labelsPending = o.labelSyncQueued !== undefined;
   if (o.labelSyncQueued !== undefined) {
     lines.push(
-      `  label sync queued (${o.labelSyncQueued} pending) — the daemon retries; the intended labels are durable, and the issue is claimable once they land`,
+      `  label sync queued (${o.labelSyncQueued} pending) — the daemon retries until the tracker matches`,
     );
   }
   if (o.forced === true) {
@@ -321,7 +321,7 @@ export function formatUnblock(
     lines.push(
       latest.prUrl === undefined
         ? labelsPending
-          ? `  next tick  label sync queued (${o.labelSyncQueued} pending) — the daemon retries; eligibility is recorded in the store, not yet on the tracker`
+          ? `  next tick  label sync queued (${o.labelSyncQueued} pending) — the daemon retries until the tracker matches`
           : o.requeued === true
             ? `  next tick  eligible again — "${project.queueLabel}" restored (no-op if it was already present; ` +
               "the dispatcher still applies its open-PR check at claim time)"
@@ -352,7 +352,7 @@ export function formatUnblock(
       );
       if (labelsPending) {
         lines.push(
-          `  queue      label sync queued (${o.labelSyncQueued} pending) — the daemon retries; the intended labels are durable, and the issue is claimable once they land`,
+          `  queue      label sync queued (${o.labelSyncQueued} pending) — the daemon retries until the tracker matches`,
         );
       } else if (o.requeued === true) {
         lines.push(`  queue      "${project.queueLabel}" restored (no-op if it was already present)`);
@@ -361,7 +361,7 @@ export function formatUnblock(
   } else {
     lines.push(
       labelsPending
-        ? `  next tick  label sync queued (${o.labelSyncQueued} pending) — the daemon retries; the intended labels are durable, and the issue is claimable once they land`
+        ? `  next tick  label sync queued (${o.labelSyncQueued} pending) — the daemon retries until the tracker matches`
         : o.requeued === true
           ? `  next tick  eligible again — "${project.queueLabel}" restored (no-op if it was already present; ` +
             "the dispatcher still applies its open-PR check at claim time)"

package/src/worker.ts

@@ -19,6 +19,9 @@ const HEAD_SHA_PATTERN = /^head:\s*([0-9a-f]{40})\s*$/im;
 const PUSHED_GREEN_PATTERN = /^state:\s*pushed-green\s*$/im;
 const BLOCKED_PATTERN = /^state:\s*blocked\s*$/im;
 
+/** Any explicit verdict line, whatever it claims. */
+const STATE_LINE_PATTERN = /^state:\s*\S+\s*$/im;
+
 /** `{{KEY}}` placeholders in a brief template. */
 const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+)\}\}/g;
 
@@ -160,6 +163,19 @@ export function deriveResult(report: string): {
   };
 }
 
+/**
+ * Did this report state a verdict at all?
+ *
+ * The discriminator between "the worker said something about its outcome" and
+ * "the worker said something else entirely". A finished worker woken by its own
+ * stale polling timers emits neither `state: pushed-green` nor `state: blocked`
+ * — it emits prose — and that is the only case where an earlier verdict is
+ * still the run's real answer.
+ */
+export function hasVerdictLine(report: string): boolean {
+  return STATE_LINE_PATTERN.test(report);
+}
+
 /**
  * Is this `agent_end` the end of the run?
  *
@@ -224,6 +240,14 @@ export async function runWorker(
   let turns = 0;
   let spendUsd = 0;
   let report = "";
+  // The newest COMPLETE `pushed-green` verdict this session emitted. Tracked
+  // apart from `report` because `report` is deliberately the newest non-empty
+  // text — a run cut off mid-sentence must still report what it said last —
+  // and a worker that finishes, then wakes on its own stale polling timers,
+  // overwrites its own verdict with "nothing to resume" chatter. veltro#406
+  // burned 180/180 turns that way and charged an attempt against a PR that
+  // merged (#217).
+  let claim: { prUrl: string; headSha: string } | undefined;
   let killedBy: KilledBy | undefined;
   // Bun's global timer handle; cleared on every exit path below.
   let timer: Timer | undefined;
@@ -265,7 +289,13 @@ export async function runWorker(
     // Keep the newest non-empty assistant text: whatever the worker said last
     // is its report, whether it finished cleanly or was cut off.
     const text = reportText(field(message, "content"));
-    if (text !== "") report = text;
+    if (text !== "") {
+      report = text;
+      const stated = deriveResult(text);
+      if (stated.state === "pushed-green" && stated.prUrl !== undefined && stated.headSha !== undefined) {
+        claim = { prUrl: stated.prUrl, headSha: stated.headSha };
+      }
+    }
 
     // Real cost lives on assistant messages as `usage.cost.total` (live hermes
     // transcripts, 2026-08-07). The earlier agent_end.telemetry path never
@@ -337,9 +367,26 @@ export async function runWorker(
   }
 
   if (killedBy !== undefined) {
-    return withSessionFacts({ state: "killed", turns, spendUsd, report, killedBy });
+    // The PR and head are facts the session already established, so they
+    // survive the kill. Without them `shouldContinueAfterTurnsCap` sees no
+    // artifacts and charges an implementation attempt for a cap kill that had
+    // real work to continue from.
+    return withSessionFacts({
+      state: "killed",
+      turns,
+      spendUsd,
+      report,
+      killedBy,
+      ...(claim === undefined ? {} : { prUrl: claim.prUrl, headSha: claim.headSha }),
+    });
   }
 
+  // An explicit later verdict always wins: a worker that pushed green and then
+  // stopped to ask a question means the question. The earlier claim is only
+  // restored when the last thing said was not a verdict at all.
+  if (claim !== undefined && !hasVerdictLine(report)) {
+    return withSessionFacts({ state: "pushed-green", ...claim, turns, spendUsd, report });
+  }
   return withSessionFacts({
     ...deriveResult(report),
     turns,