omp-conductor 0.17.1 → 0.18.0

package/src/settlement.ts

@@ -0,0 +1,1728 @@
+/**
+ * The settlement half of the dispatcher — push-result sweeps, orphan
+ * reconciliation, worktree settlement and failure classification recovery
+ * (`daemon.ts` composes; this owns the region).
+ *
+ * Extracted from `daemon.ts` (TerrifiedBug/conductor#705) so the second most
+ * contested region of the composition root is a lane of its own: a settlement
+ * diff must not have to touch the composition root. This is a move, not a
+ * rewrite — behaviour is byte-identical; a later slice reworks the seams.
+ *
+ * The module is a leaf: it never imports `daemon.ts`, and `daemon.ts` never
+ * re-exports it. What it needs from the daemon that only the daemon owns —
+ * the pause-sentinel ops used by the provider-credit recovery — arrives as
+ * fields of the structural {@link SettlementDeps}, wired at the call sites.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { log, errText, safeEscalate } from "./log.ts";
+import { hasContinuationBudget } from "./admission.ts";
+import {
+  UNREADABLE_TREE_FLAG,
+  analyseSettlement,
+  deriveChangedLine,
+} from "./diff-flags.ts";
+import { classifyRun, normalise, type ClassifyFacts } from "./failure-class.ts";
+import { formatModelsTried, modelsTried } from "./model-fallback.ts";
+import { PR_LOOKUP_WINDOW_MS } from "./verbs/server.ts";
+import {
+  removeWorktree,
+  salvageWip,
+  type RunPublisher,
+  type SalvageOutcome,
+} from "./worktree.ts";
+import type {
+  Caps,
+  Escalation,
+  FailureClass,
+  MergedPrInfo,
+  OpenCloser,
+  PrState,
+  ProjectConfig,
+  RecoveryAction,
+  RunRecord,
+  RunState,
+  SettlementFlag,
+  Store,
+  Tracker,
+} from "./types.ts";
+
+/** Fleet-wide escalations still need an issue number in the payload; 0 is the
+* sentinel that reads as "no issue" in every renderer. One per module —
+ * `admission.ts`, `daemon.ts` and this module each hold their own copy. */
+const NO_ISSUE = 0;
+
+/**
+ * The slice of the daemon's `Deps` settlement reads. Defined here rather than
+ * imported from `daemon.ts` (that would be the cycle this leaf exists to
+ * avoid); the composition root wires it at the call sites, and
+ * `daemon.test.ts`'s shared fake satisfies it (its `deps()` helper gained the
+ * two pause-op passthroughs below when this module landed).
+ *
+ * `isPaused`/`setPaused` are the pause-sentinel ops, owned by the daemon
+ * (the pause cluster has a long list of other consumers that import them from
+ * there); the composition root wires them in. Keeping them off the object is
+ * what lets this module stay a leaf.
+ */
+export interface SettlementDeps {
+  project: ProjectConfig;
+  caps: Caps;
+  tracker: Tracker;
+  store: Store;
+  escalate(e: Escalation): Promise<void>;
+  /** Whether the pause sentinel is set, daemon-owned. */
+  isPaused(project?: string): boolean;
+  /** Writes the pause sentinel, daemon-owned. */
+  setPaused(
+    paused: boolean,
+    provenance: { source: string; reason?: string },
+    project?: string,
+  ): void;
+}
+
+/** What the settlement audit of one green run produced: the advisory flags
+ *  (test weakening only — the file-list disclosure is derived, not flagged),
+ *  whether the diff was cut short, and the `changed:` line composed from the
+ *  PR's own diff. */
+export interface SettlementAuditResult {
+  flags: SettlementFlag[];
+  truncated: boolean;
+  /** The `changed:` file list derived from the PR's diff, present whenever the
+   *  diff could be read. Absent means the tree could not be read, and `flags`
+   *  then carries exactly {@link UNREADABLE_TREE_FLAG}. */
+  changedLine?: string;
+}
+
+/**
+ * Audit a worker's own account of its work against the pull request it pushed.
+ *
+ * The thin half of the split #85 established: this fetches, {@link
+ * analyseSettlement} decides. It runs beside {@link verifyPushedGreenClaim} and
+ * shares none of its authority — that function decides a run's state, this one
+ * cannot, by construction. It returns evidence and the caller appends it.
+ *
+ * A diff that cannot be read is a finding (`changed-line-missing`), never an
+ * empty flag list: nothing was derived and nothing was checked, and that must
+ * not read as a clean bill.
+ */
+export async function collectSettlementFlags(
+  tracker: Pick<Tracker, "prDiff" | "prBody">,
+  claim: { prUrl?: string; issueText: string; sessionFile?: string },
+): Promise<SettlementAuditResult> {
+  if (claim.prUrl === undefined) return { flags: [UNREADABLE_TREE_FLAG], truncated: false };
+  // The diff and the claimed-proof body read in parallel; both are advisory,
+  // and an unreadable either one costs that half of the audit and never a
+  // run's state.
+  const [diff, prBody] = await Promise.all([
+    tracker.prDiff(claim.prUrl),
+    tracker.prBody(claim.prUrl),
+  ]);
+  if (diff === undefined) return { flags: [UNREADABLE_TREE_FLAG], truncated: false };
+  // Absent session/transcript stays silent — no command can be checked —
+  // never "every claim is verified", the same "could not read" posture as
+  // `changed-line-missing`.
+  let transcript: string | undefined;
+  if (claim.sessionFile !== undefined) {
+    try {
+      transcript = readFileSync(claim.sessionFile, "utf8");
+    } catch {
+      transcript = undefined;
+    }
+  }
+  return {
+    flags: analyseSettlement({
+      issueText: claim.issueText,
+      diff,
+      ...(prBody === undefined ? {} : { prBody }),
+      ...(transcript === undefined ? {} : { transcript }),
+    }),
+    truncated: diff.truncated,
+    changedLine: deriveChangedLine(diff),
+  };
+}
+
+
+
+// ------------------------------------------------------------------- pushed-green settlement
+
+/** What a resolved PR turns its `pushed-green` row into. */
+export interface Settlement {
+  state: "merged" | "failed";
+  /** The log line after `#<n> settled: `, and — for a rejection — the row's own
+   *  `lastError`, because a `failed` row whose worker succeeded has to say so. */
+  reason: string;
+}
+
+/**
+ * What one `pushed-green` row becomes now its PR has an answer, or undefined to
+ * leave the row exactly as it is.
+ *
+ * A `pushed-green` row is the only one nothing ever revisited: the worker is
+ * finished, `reconcileOrphanedRuns` only settles rows that held a process, and
+ * `merged` went unwritten from day one. So they accumulated — three of them on
+ * the reference fleet on 2026-08-07, every PR merged and every issue closed,
+ * with `/healthz` still reporting three active runs and their issues
+ * permanently unclaimable, because the busy set *is* the active set (#18).
+ *
+ * The mapping, and why each answer is the only honest one:
+ *
+ * - `merged` — the work landed. That is what `merged` was reserved for.
+ * - `closed` — a human read the work and said no. Leaving it `pushed-green`
+ *   forever is a lie; `failed` records that it did not land and releases the
+ *   busy guard, so an issue a human re-queues can be attempted again. A row
+ *   that had reached `pushed-green` or `pushed-pending` is classified
+ *   `returned-for-revision` at settlement. A review decision asks for another
+ *   implementation pass, not a failure, so it consumes the continuation budget
+ *   instead of the failed-attempt budget.
+ * - `open`, and undefined — nothing changes. Undefined is "could not tell": a
+ *   flaky network, a revoked token, a deleted PR. Settling on it would record a
+ *   merge that never happened, and the next tick asks again for free. An
+ *   ambiguous answer must never settle a row.
+ */
+export function settlementFor(pr: PrState | undefined, prUrl: string): Settlement | undefined {
+  if (pr === "merged") return { state: "merged", reason: `${prUrl} merged` };
+  if (pr === "closed") return { state: "failed", reason: `${prUrl} closed without merging` };
+  return undefined;
+}
+
+/**
+ * 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` — permanently unclaimable with no supported
+ * way back (#18).
+ *
+ * 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.
+ *
+ * Synchronous. The op is durable the moment this returns.
+ */
+export function releaseInProgress(
+  d: Pick<SettlementDeps, "project" | "store">,
+  issue: number,
+  why: string,
+): void {
+  const label = d.project.stateLabels.inProgress;
+  d.store.enqueueLabelOps(d.project.name, [{ issue, op: "remove", label }]);
+  log(`#${issue} released ${label} (queued): ${why}`);
+}
+
+/**
+ * Records the queue label's release as a projection op (#607).
+ *
+ * A settled merge means the work landed. Whether the merge closed the issue or
+ * the PR carried no closing keyword and left it open, the issue must not stay
+ * claimable — and the queue label is the claim gate. Before this function
+ * existed nothing ever took it off a settled issue: the claim path only adds
+ * the in-progress label, so `ready-for-agent` rode along through the run and
+ * outlived the merge. By 2026-08-17 the closed-issue backlog still carrying it
+ * exceeded GitHub's 50-result listing page on this fleet's tracker.
+ *
+ * Same outbox discipline as {@link releaseInProgress}: the removal is a
+ * durable local write enqueued in the same breath as the terminal row, the
+ * projector applies it with unbounded retry, and while it is pending the
+ * eligibility overlay treats the label as already gone. A removal that races a
+ * human's own removal lands as a no-op on the tracker (REST DELETE of an
+ * absent label is idempotent), so it can never resurrect a label the operator
+ * took off.
+ *
+ * Synchronous. The op is durable the moment this returns.
+ */
+export function releaseQueueLabel(
+  d: Pick<SettlementDeps, "project" | "store">,
+  issue: number,
+  why: string,
+): void {
+  const label = d.project.queueLabel;
+  d.store.enqueueLabelOps(d.project.name, [{ issue, op: "remove", label }]);
+  log(`#${issue} released ${label} (queued): ${why}`);
+}
+
+
+/**
+ * Asks the tracker about every `pushed-green` PR and settles the ones that
+ * resolved.
+ *
+ * Effects at the call site, decision in {@link settlementFor} — the same split
+ * as `checkIntegrity`/`watchOrchestrator`. Exported like `admitCandidates`
+ * rather than kept private, because half of what has to hold is about the sweep
+ * and not the mapping: that a row without a PR costs no API call, and that one
+ * unreachable PR does not stop the others from settling.
+ *
+ * The label is released too, which reverses what this function first promised.
+ * It used to leave tracker labels alone exactly as {@link reconcileOrphanedRuns}
+ * does, reasoning that a merge closes the issue anyway and that deciding what an
+ * issue's labels should say next is the orchestrator's drain duty. There turned
+ * out to be no such path: on 2026-08-09 two settled rows left their issues
+ * carrying `agent:in-progress` forever, with the brief forbidding the
+ * orchestrator from touching it and `unblock` declining to (see
+ * {@link releaseInProgress}). The row transition and the label are one fact, and
+ * writing half of it is the whole of that bug.
+ *
+ * Releasing it is safe here specifically because of what these rows are. A
+ * `pushed-green` or `pushed-pending` row has no process behind it — its worker
+ * exited and its worktree is gone — so a terminal answer about its PR proves no
+ * worker owns the issue, and the duplicate-dispatch interlock the label exists
+ * for is spent. {@link reconcileOrphanedRuns} still leaves labels alone for the
+ * opposite reason: an orphaned `running` row is work nobody has read yet. And
+ * the brief's rule stays absolute, because this is a daemon-owned write through
+ * the same Tracker port the dispatcher claimed the issue with — orphan detection
+ * is only trustworthy while every state label on the tracker came from this
+ * package.
+ *
+ * The two writes are ordered label-then-row, and the order is load-bearing. This
+ * sweep is the only thing that revisits a `pushed-*` row, so the terminal state
+ * is also the row's exit from it: written first, a tracker that then failed on
+ * the label would leave `agent:in-progress` with nothing left to retry it — #18
+ * exactly, in the last window able to reach it. Writing the label first makes
+ * failure cost a repeated `gh` call on the next tick instead, and the row stays
+ * in the busy set throughout, so no second worker can be sent at the issue while
+ * it waits.
+ */
+export async function settlePushedGreen(
+  d: Pick<SettlementDeps, "project" | "tracker" | "store">,
+): Promise<number> {
+  const { project, tracker, store } = d;
+  // Runs the sweep resolved by terminalising the row. Every terminal write
+  // below increments it; the tick attributes it as `settled` on the pass's
+  // dispatch record, so a held pass is visible as work done, not just as a
+  // clock that moved (#497).
+  let settled = 0;
+  // Filtered from the active set rather than asked for with a new query: active
+  // is live workers plus these, so the list is bounded by the worker cap plus
+  // the number of PRs awaiting a merge — a handful, by construction. A fleet
+  // where that is not a handful has a merge problem, not a dispatch one.
+  const pending = store
+    .activeRuns(project.name)
+    .filter((r) => r.state === "pushed-green" || r.state === "pushed-pending");
+
+  for (const run of pending) {
+    // Nothing to ask about. A pushed result requires a PR, so a malformed row
+    // must not buy a `gh` call every five minutes forever.
+    if (run.prUrl === undefined) continue;
+
+    let pr: PrState | undefined;
+    try {
+      pr = await tracker.prState(run.prUrl);
+    } catch (err) {
+      // Per row, like admission's held candidate. The GitHub adapter already
+      // answers undefined instead of throwing, so this catch is the port's
+      // contract rather than that adapter's behaviour — and a tracker that does
+      // throw must cost its own row, not the whole sweep.
+      log(`#${run.issue} not settled: PR state lookup failed (${errText(err)}) — retrying next tick`);
+      continue;
+    }
+
+    const settlement = settlementFor(pr, run.prUrl);
+    if (settlement !== undefined) {
+      // A mediated merge enters a second, bounded observation phase. Record the
+      // exact merge commit before the row leaves the active set; if GitHub cannot
+      // supply it yet, retry this settlement next tick rather than create a
+      // merged row whose base result can never be attributed.
+      let merged: MergedPrInfo | undefined;
+      if (settlement.state === "merged") {
+        try {
+          merged = await tracker.mergedPrInfo(run.prUrl);
+        } catch (err) {
+          log(`#${run.issue} not settled: merge identity lookup failed (${errText(err)}) — retrying next tick`);
+          continue;
+        }
+        if (merged === undefined) {
+          log(`#${run.issue} not settled: merge identity unavailable — retrying next tick`);
+          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.
+      releaseInProgress(d, run.issue, settlement.reason);
+      if (settlement.state === "merged") {
+        // #607: merged work is done — whether the merge closed the issue or
+        // the PR carried no closing keyword and left it open — so the claim
+        // gate comes off too, through the same durable projection. A failed
+        // settlement (closed without merging) keeps the queue label: the
+        // issue is meant to return to the queue for another attempt.
+        releaseQueueLabel(d, run.issue, settlement.reason);
+      }
+      const patch: Partial<RunRecord> = {
+        state: settlement.state,
+        endedAt: Date.now(),
+        ...(merged === undefined
+          ? {}
+          : {
+              mergeSha: merged.mergeSha,
+              baseRef: merged.baseRef,
+              baseCheck: "pending",
+            }),
+      };
+      if (settlement.state === "failed") {
+        patch.lastError = settlement.reason;
+        patch.failureClass = "returned-for-revision";
+        patch.recoveryAction = "none";
+      }
+      store.updateRun(run.id, patch);
+      settled += 1;
+      log(`#${run.issue} settled: ${settlement.reason}`);
+      continue;
+    }
+
+    if (run.state !== "pushed-pending" || pr !== "open" || run.headSha === undefined) continue;
+    let verification;
+    try {
+      verification = await tracker.verifyPr(run.prUrl, run.headSha);
+    } catch (err) {
+      log(`#${run.issue} checks not settled (${errText(err)}) — retrying next tick`);
+      continue;
+    }
+    if (verification === undefined) continue;
+    if (verification.status === "green") {
+      store.updateRun(run.id, { state: "pushed-green", lastError: null });
+      log(`#${run.issue} checks settled: ${verification.reason}`);
+    } else if (verification.status === "failed") {
+      // 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 });
+      settled += 1;
+      log(`#${run.issue} checks failed: ${verification.reason}`);
+    } else {
+      store.updateRun(run.id, { lastError: verification.reason });
+    }
+  }
+  return settled;
+}
+
+
+// ------------------------------------------------------------------- salvaged-PR adoption
+
+const ADOPTABLE_PR_STATES: Partial<Record<RunState, true>> = {
+  failed: true,
+  killed: true,
+  orphaned: true,
+  blocked: true,
+};
+
+/**
+ * Reattaches a recovered PR to the terminal run that owns it (#245).
+ *
+ * A worker can fail before its completion report records `prUrl`, then have its
+ * dirty tree committed and pushed by salvage. If that branch already has a PR,
+ * the orchestrator otherwise has no policy-compliant path to inspect or merge
+ * it: ownership is store-backed. Adoption is deliberately stricter than
+ * admission. The tracker query proves the PR closes this run's issue; exact
+ * branch and canonical repository matches prove it is this run's recovered
+ * work, not an unrelated closer. Missing identity is refusal, never a guess.
+ *
+ * The newest run per issue is inspected, at most ten per tick and only inside
+ * the same 30-day window as mediated PR verbs. The cursor advances through the
+ * full eligible set so persistent non-matches cannot starve older recovered
+ * work. Successful adoption is idempotent because the row gains `prUrl`;
+ * non-matches are logged once per daemon process.
+ */
+const rejectedSalvagedPrRuns = new Set<string>();
+const salvagedPrCursor = new Map<string, string>();
+
+export async function adoptSalvagedPrs(
+  d: Pick<SettlementDeps, "project" | "tracker" | "store">,
+  now = Date.now(),
+): Promise<void> {
+  const { project, tracker, store } = d;
+  const eligible = store
+    .recentRuns(project.name, now - PR_LOOKUP_WINDOW_MS)
+    .filter(
+      (run) =>
+        ADOPTABLE_PR_STATES[run.state] === true &&
+        run.prUrl === undefined &&
+        run.branch.trim() !== "",
+    );
+  const previous = salvagedPrCursor.get(project.name);
+  const previousIndex =
+    previous === undefined ? -1 : eligible.findIndex((run) => run.id === previous);
+  const start = previousIndex === -1 ? 0 : (previousIndex + 1) % eligible.length;
+  const candidates = Array.from(
+    { length: Math.min(SALVAGED_PR_ADOPTION_BATCH, eligible.length) },
+    (_, offset) => eligible[(start + offset) % eligible.length]!,
+  );
+  const last = candidates.at(-1);
+  if (last !== undefined) salvagedPrCursor.set(project.name, last.id);
+
+  for (const run of candidates) {
+    const repo = project.routing.repos[run.repo];
+    const repoIdentity = repo === undefined ? undefined : githubRepo(repo.cloneUrl);
+    let closers: OpenCloser[];
+    try {
+      closers = await tracker.openClosersFor(run.issue);
+    } catch (err) {
+      log(`#${run.issue} PR adoption lookup failed (${errText(err)}) — retrying next tick`);
+      continue;
+    }
+
+    const closer = closers.find(
+      (candidate) =>
+        candidate.headRefName !== "" &&
+        candidate.headRefName === run.branch &&
+        repo !== undefined &&
+        candidate.repo !== "" &&
+        candidate.repo === repoIdentity,
+    );
+    if (closer === undefined) {
+      if (!rejectedSalvagedPrRuns.has(run.id)) {
+        const observed = closers[0];
+        const reason =
+          observed === undefined
+            ? "no open closing PR"
+            : observed.headRefName === ""
+              ? "closer has no head branch identity"
+              : observed.headRefName !== run.branch
+                ? `closer head ${observed.headRefName} does not match retained branch ${run.branch}`
+                : observed.repo === ""
+                  ? "closer has no repository identity"
+                  : `closer repository ${observed.repo} does not match routed repository`;
+        log(`#${run.issue} PR not adopted onto attempt ${run.attempt}: ${reason}`);
+        rejectedSalvagedPrRuns.add(run.id);
+      }
+      continue;
+    }
+
+    const flag: SettlementFlag = {
+      kind: "pr-adopted",
+      file: "(recovery)",
+      detail: `${closer.url} matched retained branch ${run.branch} in ${closer.repo}`,
+    };
+    store.updateRun(run.id, {
+      prUrl: closer.url,
+      settlementFlags: [...(run.settlementFlags ?? []), flag],
+    });
+    rejectedSalvagedPrRuns.delete(run.id);
+    log(
+      `#${run.issue} adopted PR ${closer.url} onto attempt ${run.attempt}` +
+        (run.salvageSha === undefined ? "" : ` (salvaged head ${run.salvageSha})`),
+    );
+  }
+}
+
+/** Canonical `owner/repo` identity from a configured network clone URL. */
+function githubRepo(cloneUrl: string): string | undefined {
+  const normalized = cloneUrl.replace(/\/$/, "").replace(/\.git$/, "");
+  const match = /^(?:https?:\/\/[^/]+\/|ssh:\/\/git@[^/]+\/|git@[^:]+:)([^/\s]+\/[^/\s]+)$/.exec(
+    normalized,
+  );
+  return match?.[1];
+}
+
+
+// ------------------------------------------------------------------- worktree settlement
+
+/**
+ * Persist the operator-stop transition before releasing its live controller.
+ * The row is terminal first, then its in-progress label is removed through the
+ * same durable projection outbox as every other lifecycle transition.
+ */
+export function recordOperatorStop(
+  store: Pick<Store, "updateRun" | "enqueueLabelOps">,
+  args: {
+    project: string;
+    issue: number;
+    runId: string;
+    inProgress: string;
+    reason: string;
+    patch: Partial<RunRecord>;
+  },
+): void {
+  store.updateRun(args.runId, {
+    ...args.patch,
+    state: "stopped",
+    lastError: `operator stopped: ${args.reason}`,
+  });
+  store.enqueueLabelOps(args.project, [
+    { issue: args.issue, op: "remove", label: args.inProgress },
+  ]);
+}
+
+/**
+ * What a salvage attempt contributes to the escalation: where the work went, or
+ * that it went nowhere. Split from the effects below for the same reason
+ * `checkIntegrity` is — this wording is the whole thing a human acts on, so it
+ * is worth a test holding it, and the sha in it is the only pointer to work
+ * that no longer has any other copy.
+ *
+ * `retained` is not cosmetic. These lines used to promise a tree "kept for
+ * inspection" unconditionally, which was true only because salvage ran only on
+ * the paths that keep one. A blocked run's tree is removed the moment its work
+ * is safely on the branch, and sending an operator to a path this process just
+ * deleted is the same class of mistake as #118 itself.
+ */
+export function salvageLines(
+  outcome: SalvageOutcome,
+  worktree: string,
+  retained: boolean,
+): string[] {
+  const fate = retained
+    ? `Worktree kept for inspection: ${worktree}`
+    : `Worktree removed: ${worktree}`;
+
+  if (outcome.kind === "nothing") return [`${fate} — nothing uncommitted to salvage`];
+
+  if (outcome.kind === "failed") {
+    return [
+      `WIP SALVAGE FAILED: ${outcome.error}`,
+      `Uncommitted work in ${worktree} is the only copy of it, so the tree was kept.`,
+      "This issue is held out of dispatch until the tree is recovered by hand and",
+      "`omp-conductor unblock <n> --force` records that you accepted it.",
+    ];
+  }
+
+  const where =
+    `WIP committed to ${outcome.branch} @ ${outcome.sha}` +
+    (outcome.pushed
+      ? " and pushed — the work outlives this worktree"
+      : ` but NOT pushed (${outcome.pushError ?? "no reason given"}) — it lives only in this host's mirror`);
+  // Manifest belongs in the escalation too: opening the commit is how the
+  // orchestrator talked itself into scrubbing a worker tree (#38).
+  const n = outcome.files.length;
+  const count = `${n} file${n === 1 ? "" : "s"}`;
+  const manifest =
+    outcome.newPaths.length === 0
+      ? `${count} (all modifications to tracked paths)`
+      : `${count}; new: ${outcome.newPaths.slice(0, 12).join(", ")}${
+          outcome.newPaths.length > 12 ? `, … +${outcome.newPaths.length - 12} more` : ""
+        }`;
+  return [where, manifest, fate];
+}
+
+/** Everything a settled run has to record and say about its worktree. */
+export interface WorktreeSettlement {
+  outcome: SalvageOutcome;
+  /** Whether the tree still exists now the run is over. */
+  retained: boolean;
+  /** Escalation lines naming where the work went. */
+  lines: string[];
+  /** Row fields recording the durable ref, or the failure that blocks a re-claim. */
+  patch: Pick<RunRecord, "salvageSha" | "salvageError">;
+}
+
+/**
+ * Decides what becomes of a finished run's worktree: save the work, then keep
+ * or remove the tree, then say which.
+ *
+ * One function because the two halves are one decision and splitting them is
+ * how #118 happened — the removal at the end of dispatch had no idea whether
+ * anything had been saved, and the salvage at the top of the failure branch had
+ * no idea the blocked branch fell through to a `--force` removal.
+ *
+ * A salvage that *fails* retains the tree whatever the caller asked for. There
+ * was real work, git refused to commit it, and the tree is now the only copy in
+ * existence: deleting it on schedule would be the data loss this whole path
+ * exists to prevent. The issue is held out of dispatch until an operator says
+ * otherwise, because the next attempt's `worktree remove --force` would finish
+ * the job (see `admitCandidates`).
+ *
+ * Exported so a test can drive the real decision against a real git tree.
+ */
+export async function settleWorktree(
+  args: {
+    issue: number;
+    attempt: number;
+    /** Clause for the commit subject: "killed by the turns cap", "blocked …". */
+    ending: string;
+    worktree: string;
+    /** The run's branch, so the pre-removal publish names the right ref. */
+    branch: string;
+    /**
+     * Publishes the run branch on the privileged side. Required rather than
+     * optional: the run's commits live in a repository of its own,
+     * so a removal that did not publish first would delete the only copy —
+     * which is #121's data loss with one extra step. `undefined` is a visible
+     * decision at the call site, never an omission.
+     */
+    publish: RunPublisher | undefined;
+  } & (
+    | /** Terminal-failure and orphan trees are evidence, and are kept even when clean. */
+    { tree: "keep" }
+    | { tree: "remove"; mirrorPath: string }
+  ),
+): Promise<WorktreeSettlement> {
+  const { issue, attempt, ending, worktree, branch, publish } = args;
+  const outcome = await salvageWip(worktree, issue, attempt, ending, publish);
+  const retained = args.tree === "keep" || outcome.kind === "failed";
+  if (!retained && args.tree === "remove") {
+    // Before the removal, always — not only when salvage found something. A run
+    // that *committed* and could not publish has its work in its own repository
+    // and nowhere else, and salvage never sees a committed tree because it is
+    // clean. The mirror fetch inside `publish` is what preserves it; the push
+    // to GitHub can fail (no network, protected ref) and the work still lives.
+    const published = await publish?.(branch);
+    if (published !== undefined && !published.ok) {
+      log(`#${issue} publish before removal failed, work is preserved in the mirror: ${published.stderr}`);
+    }
+    await removeWorktree(args.mirrorPath, worktree);
+  }
+
+  const lines = salvageLines(outcome, worktree, retained);
+  log(`#${issue} salvage: ${lines.join(" ")}`);
+  return {
+    outcome,
+    retained,
+    lines,
+    patch:
+      outcome.kind === "salvaged"
+        ? { salvageSha: outcome.sha }
+        : outcome.kind === "failed"
+          ? { salvageError: outcome.error }
+          : {},
+  };
+}
+
+
+// ------------------------------------------------------------------- orphan & stale-label reconciliation
+
+/** Bounded listing per state label, so one reconcile cannot walk a whole repo. */
+const RECONCILE_LIMIT = 50;
+
+/**
+ * Clear labels from issues that no longer need them (#132's `superseded`).
+ *
+ * Three structural signals, all cheap and all observed on this fleet: an issue
+ * that is closed but still carries an `agent:*` state label, a closed issue
+ * still carrying the queue label — the claim gate on work that can never be
+ * claimed again, which the merge path only recently learned to remove itself
+ * (#607), leaving a 50+-issue backlog — and an open issue carrying `failed`
+ * whose sub-issues have all closed. On 2026-08-09 four issues (#307,
+ * #297, #140, #82) carried `agent:failed` while every one of them was already
+ * complete — the label was residue of a turns-cap kill from two days earlier,
+ * and nothing in the loop ever revisited it. The board counted four phantom
+ * failures while the genuinely stuck issues were invisible.
+ *
+ * The queue label is swept off closed issues only: an open issue carrying it
+ * is claimable work by definition, and a reconcile that guessed would strip
+ * the interlock that keeps two workers off one issue.
+ *
+ * Positive evidence only. A tracker that cannot list answers empty, and an empty
+ * answer removes nothing: a reconcile that guessed would strip the interlock
+ * that keeps two workers off one issue.
+ */
+export async function reconcileStaleLabels(d: Pick<SettlementDeps, "project" | "tracker" | "store">): Promise<void> {
+  const { project, tracker, store } = d;
+  const labels = [
+    project.stateLabels.failed,
+    project.stateLabels.blocked,
+    project.stateLabels.inProgress,
+    project.queueLabel,
+  ];
+
+  for (const label of labels) {
+    const carrying = await tracker.listLabeled(label, RECONCILE_LIMIT).catch(() => []);
+    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. 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;
+      }
+
+      if (label !== project.stateLabels.failed) continue;
+      const children = await tracker.childrenOf(issue.number).catch(() => []);
+      if (children.length === 0 || children.some((c) => c.state !== "closed")) continue;
+
+      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.comment(
+          issue.number,
+          `superseded: all sub-issues closed (${list}) — this label was stale; propose closing if the ` +
+            `acceptance criteria are met on the default branch.`,
+        );
+        store.markNotified(key);
+        log(`#${issue.number} reconciled: superseded by ${list}`);
+      } catch (err) {
+        // 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`);
+      }
+    }
+  }
+}
+
+/**
+ * Settles `claimed`/`running` rows left by a dead daemon process and, before
+ * marking each one `orphaned`, salvages any dirty worktree.
+ *
+ * Found live after a host restart killed two workers mid-run, and again on
+ * every package deploy that restarted while workers were live (#35): without
+ * the salvage call the next attempt's `worktree remove --force` destroyed
+ * uncommitted edits that had no other copy. Cap-kills already salvaged (#27);
+ * this is the same call site for the restart path.
+ *
+ * Only the rows change. The issue keeps its in-progress label — that label is
+ * the crash guard against double-dispatch, and deciding what a dead worker's
+ * remains are worth (an open PR? a salvaged sha? a clean tree?) is the
+ * orchestrator's drain-duty judgement, not something to automate here. The
+ * rows also keep counting toward `maxAttemptsPerIssue`, so a loop of deaths
+ * still escalates instead of retrying forever.
+ *
+ * `pushed-green` rows are deliberately left alone: they hold no process — they
+ * are finished work waiting on a human merge, and they must keep occupying the
+ * issue so a second attempt cannot land on a live PR. What eventually settles
+ * them is {@link settlePushedGreen}, on the tick, by asking the tracker what
+ * became of the PR — the one question a restart cannot answer by inference.
+ */
+export async function reconcileOrphanedRuns(
+  store: Store,
+  project: string,
+  /**
+   * Resolves the privileged publisher for one orphaned run. Optional because a
+   * test driving the row transitions has no repo to publish to; production
+   * always passes it, and without it a salvaged WIP commit stays local — which
+   * is the half of #121 that reaches a human.
+   */
+  publish?: (run: RunRecord) => RunPublisher,
+): Promise<RunRecord[]> {
+  // Live runs only: `pushed-green` holds no process, so it cannot be orphaned by
+  // a process dying — it is finished work waiting on a human merge.
+  const stale = store.liveRuns(project);
+  const endedAt = Date.now();
+  for (const r of stale) {
+    // Salvage before the row flips: the worktree path is on the record, and
+    // salvageWip is a no-op for a missing/clean tree. The clause matches the
+    // cap-kill wording so triage reads the same either way, and the tree is
+    // kept because an orphan's remains are the orchestrator's drain-duty call.
+    const settlement =
+      r.worktree === ""
+        ? undefined
+        : await settleWorktree({
+            issue: r.issue,
+            attempt: r.attempt,
+            ending: "killed by a daemon restart",
+            worktree: r.worktree,
+            branch: r.branch,
+            // An orphan's tree is kept, so its commits are not about to be
+            // deleted — but a WIP salvage still has to reach GitHub, which is
+            // #121's whole point and is now the daemon's hop to make.
+            publish: publish?.(r),
+            tree: "keep",
+          });
+    store.updateRun(r.id, { state: "orphaned", endedAt, ...settlement?.patch });
+  }
+  return stale;
+}
+
+
+
+
+// ------------------------------------------------------------------- classification & recovery
+
+/** A dispatch-infra run (turn-0 git failure) is requeued so the next tick
+ *  retries — but only a bounded number of times. Three strikes for one issue
+ *  means the mirror itself is broken, not unlucky, and the sweep escalates
+ *  instead of burning a turn-0 run per tick forever (#168, #177). */
+const DISPATCH_INFRA_MAX_STRIKES = 3;
+/** A provider-transient requeue (stream stalled mid-run) is retried, but only a
+ *  bounded number of times: three aborted streams for one issue means the
+ *  provider itself is degraded, not unlucky, and the sweep escalates to a
+ *  human instead of requeueing into a down provider forever (#220). */
+const PROVIDER_TRANSIENT_MAX_STRIKES = 3;
+/** A provider-capacity requeue (sustained in-session rate limiting) is retried,
+ *  but only a bounded number of times: three throttled runs for one issue mean
+ *  the provider is at capacity, not unlucky, and the sweep escalates to a human
+ *  instead of requeueing into a throttled provider forever (#573). The issue's
+ *  own chain moves onto its next model per strike (via {@link FAILOVER_CLASSES}),
+ *  so a bounded chain is exhaustible; this caps the unbounded no-chain case. */
+const PROVIDER_CAPACITY_MAX_STRIKES = 3;
+/** Terminal rows inspected for a salvaged PR per tick. GitHub provenance reads
+ *  are maintenance, but a backlog must not turn one tick into an API burst. */
+const SALVAGED_PR_ADOPTION_BATCH = 10;
+
+/** The failure classes `countContinuations` deliberately does not charge — the
+ *  inverted copy of its exclusions, kept beside the breakdown that consumes it
+ *  so the two can only drift together (#439). `orphan-clean` is absent on
+ *  purpose: daemon orphans consume the continuation budget, which is exactly
+ *  why the requeue side has to respect the ceiling instead of racing it. */
+const NON_CONTINUATION_CLASSES: Partial<Record<FailureClass, true>> = {
+  "admin-kill": true,
+  "settlement-stuck": true,
+  "env-start-failure": true,
+  "dispatch-infra": true,
+  "provider-credit": true,
+  "provider-transient": true,
+  "provider-capacity": true,
+};
+
+/** How one issue spent its continuation budget, grouped by failure class —
+ *  the exact rows `continuationsFor` charges, so an exhaustion escalation
+ *  reports the same budget it says is spent. `unclassified` groups rows that
+ *  charged before the class was written (a pre-upgrade NULL). */
+function continuationBreakdown(runs: readonly RunRecord[]): Map<string, number> {
+  const perClass = new Map<string, number>();
+  for (const r of runs) {
+    const chargedAsKilledOrOrphaned =
+      (r.state === "killed" || r.state === "orphaned" || r.state === "blocked") &&
+      (r.failureClass === undefined || NON_CONTINUATION_CLASSES[r.failureClass] === undefined);
+    const chargedAsReturned = r.state === "failed" && r.failureClass === "returned-for-revision";
+    if (!chargedAsKilledOrOrphaned && !chargedAsReturned) continue;
+    const cls = r.failureClass ?? "unclassified";
+    perClass.set(cls, (perClass.get(cls) ?? 0) + 1);
+  }
+  return perClass;
+}
+
+/** The newest attempt's preserved work, if any, so an exhaustion escalation can
+ *  say whether continuing is worthwhile: `salvageSha`/`headSha`/`prUrl` are the
+ *  three artifacts a run can leave, and all null on a branch nothing reached. */
+function newestContinuableRun(runs: readonly RunRecord[]): RunRecord | undefined {
+  const newestFirst = [...runs].reverse();
+  return newestFirst.find(
+    (r) => r.salvageSha !== undefined || r.headSha !== undefined || r.prUrl !== undefined,
+  );
+}
+
+/** The fenced-block info string that marks an exhaustion postmortem comment, so
+ *  a grooming scout re-slicing the issue can find and parse the whole block by
+ *  grepping for it. */
+export const POSTMORTEM_MARKER = "conductor-postmortem";
+
+/** How one issue's attempt chain failed, as "3× ci-deterministic, 1× …" — the
+ *  digest shape for naming what the exhaustion was. Groups every row by its
+ *  failure class, whether or not it charged the continuation budget, because
+ *  the postmortem tells the whole story and not just the budget half (#290). */
+export function attemptClassBreakdown(runs: readonly RunRecord[]): string {
+  const perClass = new Map<string, number>();
+  for (const r of runs) {
+    const cls = r.failureClass ?? "unclassified";
+    perClass.set(cls, (perClass.get(cls) ?? 0) + 1);
+  }
+  if (perClass.size === 0) return "unclassified";
+  return Array.from(perClass, ([cls, n]) => `${n}× ${cls}`).join(", ");
+}
+
+/** Wall-clock duration of one run as a compact human string ("45m", "1h30m"). */
+export function humanDuration(ms: number): string {
+  const seconds = Math.max(0, Math.round(ms / 1_000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest === 0 ? `${hours}h` : `${hours}h${rest}m`;
+}
+
+/** Flatten and bound a run's last error to one greppable table line. */
+export function oneLineBrief(text: string | undefined): string | undefined {
+  if (text === undefined || text.trim() === "") return undefined;
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > 90 ? `${flat.slice(0, 89)}…` : flat;
+}
+
+/**
+ * The exhaustion postmortem block: one greppable fenced block covering every
+ * attempt in the chain — continuation rows included — with per-attempt turns,
+ * wall clock, failure class and a one-line last error, the explicit salvage
+ * state, the spend total and the transcript paths for local inspection.
+ *
+ * Pure so the tests hold the shape, not the transport: the writer below owns
+ * the once-only guarantee, this owns what "once" looks like.
+ */
+export function formatExhaustionPostmortem(args: {
+  issue: number;
+  runs: readonly RunRecord[];
+  reason: string;
+}): string {
+  const { issue, runs, reason } = args;
+  const artifact = newestContinuableRun(runs);
+  const totalSpend = runs.reduce((sum, r) => sum + r.spendUsd, 0);
+  const spend = `$${totalSpend.toFixed(2)}`;
+  const attemptLines = runs.map((r) => {
+    const wall = r.endedAt === undefined ? "—" : humanDuration(r.endedAt - r.startedAt);
+    const cls = r.failureClass ?? "unclassified";
+    const error = oneLineBrief(r.lastError) ?? "—";
+    return (
+      `  attempt ${r.attempt}  ${r.state.padEnd(12)}  turns ${r.turns}/${r.maxTurns}  ` +
+      `${cls.padEnd(24)}  ${wall.padStart(4)}  last error: ${error}`
+    );
+  });
+  const salvage =
+    artifact === undefined
+      ? "Salvaged WIP: absent — no attempt preserved a branch, head SHA or pull request."
+      : `Salvaged WIP: present — branch ${artifact.branch} at ${artifact.headSha ?? artifact.salvageSha}` +
+        `${artifact.prUrl === undefined ? "" : ` (PR ${artifact.prUrl})`}.`;
+  return [
+    `\`\`\`${POSTMORTEM_MARKER}`,
+    `#${issue} exhausted: ${attemptClassBreakdown(runs)}`,
+    reason,
+    "",
+    `Attempts (${runs.length} total, ${spend} spend):`,
+    ...attemptLines,
+    salvage,
+    `Spend total: ${spend} across ${runs.length} attempts.`,
+    "Transcripts:",
+    ...runs.map((r) => (r.sessionFile === undefined ? "  (none)" : `  ${r.sessionFile}`)),
+    "```",
+  ].join("\n");
+}
+
+/** Dedupe key prefix for the exhaustion postmortem comment, per issue. */
+function postmortemDedupeKey(project: string, issue: number): string {
+  return `${project}:postmortem:${issue}`;
+}
+
+/**
+ * The exhaustion postmortem: written exactly once per issue, at the point the
+ * continuation budget is spent and the issue is settled toward a human.
+ *
+ * The comment and the material event are both gated by the store's notification
+ * ledger — the same idempotence guard the escalator uses — so re-settling an
+ * already-postmortemed issue posts nothing and records nothing. A body-string
+ * match on the issue would be the wrong guard: an issue re-scoped and re-run
+ * would still carry the old block, and the guarantee asked of this is "decided
+ * once", not "deduped against what is already written".
+ *
+ * The digest must name the exhaustion even if the comment write fails, so the
+ * material event is recorded before the write and unconditionally (the ledger
+ * is append-only, and the gate above already ran once). The comment failure is
+ * logged rather than taking the sweep down with it.
+ */
+async function postExhaustionPostmortem(d: Pick<SettlementDeps, "project" | "tracker" | "store">, run: RunRecord, reason: string): Promise<void> {
+  const { project, tracker, store } = d;
+  const key = postmortemDedupeKey(project.name, run.issue);
+  if (store.wasNotified(key)) return;
+  const runs = store.runsForIssue(project.name, run.issue);
+  const body = formatExhaustionPostmortem({ issue: run.issue, runs, reason });
+  const occurredAt = Date.now();
+  store.recordMaterialEvent({
+    project: project.name,
+    category: "exhaustion",
+    summary: `#${run.issue} exhausted: ${attemptClassBreakdown(runs)}`,
+    evidence: body,
+    occurredAt,
+    recordedAt: occurredAt,
+  });
+  try {
+    await tracker.comment(run.issue, body);
+    store.markNotified(key);
+    log(`#${run.issue} posted exhaustion postmortem (${runs.length} attempts)`);
+  } catch (err) {
+    log(`#${run.issue} postmortem comment could not be posted (${errText(err)})`);
+  }
+}
+
+/**
+ * The escalator throws when no transport is configured or Telegram rejects, and
+ * only records the dedup marker on success. A page that cannot be delivered
+ * must not take the tick down with it — log it and let the next tick retry.
+ *
+ * Returns whether it actually went out, because "page once" and "page once
+ * *successfully*" are different promises: a caller that latches a once-only
+ * gate on the attempt turns one failed delivery into permanent silence about a
+ * condition that is still true.
+ */
+
+export async function reactToProviderCredit(
+  d: Pick<SettlementDeps, "project" | "escalate" | "isPaused" | "setPaused">,
+  issue: number,
+  message: string,
+  sessionFile: string | undefined,
+): Promise<void> {
+  const { project } = d;
+  const alreadyPaused = d.isPaused(project.name);
+  if (!alreadyPaused) d.setPaused(true, { source: "provider-credit", reason: message }, project.name);
+  log(
+    `#${issue} provider refused for credit — dispatch ${alreadyPaused ? "remains paused" : "paused"}: ${message}`,
+  );
+  // 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 pages once for the fleet, not once per run.
+  await safeEscalate(d, {
+    tier: 2,
+    category: "fleet-stopped",
+    project: project.name,
+    issue: NO_ISSUE,
+    summary: `Model provider refused for credit — ${project.name} is paused`,
+    detail: [
+      message,
+      "",
+      "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: ${sessionFile ?? "(no transcript)"}`,
+    ].join("\n"),
+  });
+}
+
+/** Bounded per tick: each row costs tracker calls to gather facts for. */
+const CLASSIFY_BATCH = 20;
+
+/** Tool calls quoted as evidence for a run that spun to its turn cap. */
+const SPIN_EVIDENCE_CALLS = 10;
+
+/**
+ * The last few tool names a transcript recorded, newest last.
+ *
+ * `turn-cap-spinning` escalates rather than requeueing, and the acceptance
+ * criterion is that the escalation carries evidence of what the worker was doing
+ * when it hit the cap — otherwise the orchestrator opens the transcript and
+ * re-derives it, which is the manual triage this whole sweep removes.
+ */
+export function lastToolCalls(sessionFile: string | undefined, limit = SPIN_EVIDENCE_CALLS): string[] {
+  if (sessionFile === undefined) return [];
+  let text: string;
+  try {
+    text = readFileSync(sessionFile, "utf8");
+  } catch {
+    return [];
+  }
+  const names: string[] = [];
+  for (const line of text.split("\n")) {
+    if (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 };
+    // Both shapes the harness has written: a top-level tool event, and a tool
+    // block inside an assistant message.
+    const direct = rec["toolName"];
+    if (typeof direct === "string") {
+      names.push(direct);
+      continue;
+    }
+    const message = rec["message"];
+    if (message === null || typeof message !== "object") continue;
+    const content = (message as { readonly [key: string]: unknown })["content"];
+    if (!Array.isArray(content)) continue;
+    for (const part of content) {
+      if (part === null || typeof part !== "object") continue;
+      const p = part as { readonly [key: string]: unknown };
+      if (p["type"] !== "tool_use") continue;
+      const name = p["name"];
+      if (typeof name === "string") names.push(name);
+    }
+  }
+  return names.slice(-limit);
+}
+
+/**
+ * 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).
+ */
+/** Transcript error shape — the daemon owns the same interface for
+ *  `completionLastError`; declared inline here so this leaf never imports it.
+ *
+ *  `kind: "provider-stream"` marks a record the harness itself attributed to a
+ *  provider abort (see {@link assistantStopError}), so the classifier can trust
+ *  the attribution without matching any vendor's wording (#743). */
+export type TranscriptError = {
+  status?: number;
+  message: string;
+  kind?: "provider-stream";
+};
+
+/**
+ * The provider's own message in a synthetic tool-result record, or undefined
+ * when the record is not the harness attributing a mid-stream provider abort
+ * (#743).
+ *
+ * The harness writes this when the provider dies while the assistant is still
+ * producing and a pending tool call never runs:
+ *
+ *   {"type":"message","message":{"role":"toolResult","isError":true,
+ *    "toolName":"edit","content":[{"type":"text","text":"Tool call was not
+ *    executed because the provider stream ended with an error before the tool
+ *    could run: …"}],"details":{"__synthetic":true,
+ *    "source":"assistant_stop_error","executed":false,
+ *    "upstreamError":"server_error: Upstream error from DeepInfra:
+ *    Exception: Response payload is not completed"}}}
+ *
+ * The `source` field is the harness's own marker, so recognition survives any
+ * provider's wording; `upstreamError` (falling back to the record's text) is
+ * the provider's own prose, carried as evidence.
+ *
+ * Deliberately narrower than "any isError toolResult": the marker is what makes
+ * the attribution structural. An `isError` tool result without it is a tool
+ * call that failed on its own — the session's work, not a provider fault — and
+ * must keep falling through.
+ */
+function assistantStopError(rec: { readonly [key: string]: unknown }): string | undefined {
+  if (rec["type"] !== "message") return undefined;
+  const message = rec["message"];
+  if (message === null || typeof message !== "object") return undefined;
+  const msg = message as { readonly [key: string]: unknown };
+  if (msg["role"] !== "toolResult" || msg["isError"] !== true) return undefined;
+  const details = msg["details"];
+  if (details === null || typeof details !== "object") return undefined;
+  const detail = details as { readonly [key: string]: unknown };
+  if (detail["source"] !== "assistant_stop_error") return undefined;
+  const upstream = detail["upstreamError"];
+  if (typeof upstream === "string" && upstream.trim() !== "") return upstream.trim();
+  const content = msg["content"];
+  if (!Array.isArray(content)) return undefined;
+  for (const part of content) {
+    if (part === null || typeof part !== "object") continue;
+    const p = part as { readonly [key: string]: unknown };
+    if (p["type"] !== "text" || typeof p["text"] !== "string") continue;
+    if (p["text"].trim() !== "") return p["text"].trim();
+  }
+  return undefined;
+}
+
+export function readSessionError(sessionFile: string | undefined): TranscriptError | 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 };
+    // A provider abort mid-stream lands as a synthetic tool-result record, not
+    // a `stopReason:error` row: the pending tool call "was not executed because
+    // the provider stream ended with an error". The harness's own `source`
+    // marker is the attribution — no vendor prose to match — and the provider's
+    // own text rides along as evidence (#743).
+    if (rec["type"] === "message") {
+      const providerText = assistantStopError(rec);
+      if (providerText !== undefined) {
+        return { message: providerText, kind: "provider-stream" };
+      }
+    }
+    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).
+ *
+ * Half this fleet's spend produced no merged PR, and every one of those runs
+ * ended at a human who re-derived the same triage by hand and then threw the
+ * conclusion away. The mechanical classes — a cancelled runner, a kill from a
+ * daemon restart, a green PR whose base moved, a row whose PR had already merged
+ * — need no judgement at all; the genuinely human ones are worth a person's
+ * attention only if they arrive with their evidence already gathered.
+ *
+ * Facts are fetched per row and only the ones that row needs: a `killed` row
+ * costs nothing, a `failed` row with a PR costs a state read and a check read.
+ * A `pushed-green` row that classifies to nothing is left completely untouched —
+ * it is healthy, and writing a class onto it would take it out of this sweep for
+ * good.
+ */
+export async function classifyAndRecover(d: SettlementDeps): Promise<number> {
+  const { project, caps, tracker, store } = d;
+  // Settle recoveries, counted for the pass's dispatch record — a row whose PR
+  // merged is settled here when the settle sweep could not establish identity
+  // (#497). Every other exit returns 0.
+  let settled = 0;
+  for (const run of store.runsNeedingClassification(project.name, CLASSIFY_BATCH)) {
+    const facts: ClassifyFacts = {};
+    let classifiedRun = run;
+    if (run.state === "failed" || run.state === "killed") {
+      const sessionError = readSessionError(run.sessionFile);
+      if (sessionError !== undefined) {
+        if (run.lastError === undefined || run.lastError === sessionError.message) {
+          facts.sessionError = sessionError;
+        }
+        if (run.lastError === undefined) {
+          store.updateRun(run.id, { lastError: sessionError.message });
+          classifiedRun = { ...run, lastError: sessionError.message };
+        }
+      }
+    }
+    try {
+      if (run.prUrl !== undefined) {
+        const pr = await tracker.prState(run.prUrl);
+        if (pr !== undefined) facts.pr = pr;
+        if (run.state === "pushed-green" && facts.pr === "open") {
+          facts.mergeable = await tracker.mergeable(run.prUrl);
+        }
+        if (run.state === "failed" && facts.pr === "open") {
+          facts.checks = await tracker.checkConclusions(run.prUrl);
+          // When a check failed with a reachable log, pull its tail so the
+          // table can tell an infra outage (#177) from a real test failure by
+          // the log's own words. First failure wins; a log that cannot be
+          // fetched is left undefined and classification stays conservative.
+          // GitHub reports check states as `FAILURE` while the classifier reads
+          // them lowercased — normalise so the live seam and the table agree on
+          // which check is the failure whose log we pull (#177).
+          const firstFailure = facts.checks.find((c) => normalise(c.state) === "failure" && c.link !== undefined);
+          if (firstFailure?.link !== undefined) {
+            facts.failingLog = await tracker.checkLog(firstFailure.link);
+          }
+        }
+      }
+    } catch (err) {
+      // Per row, like every other sweep here: one unreachable PR must not stop
+      // the rest from being classified. The next tick asks again for free.
+      log(`#${run.issue} not classified: fact gathering failed (${errText(err)}) — retrying next tick`);
+      continue;
+    }
+
+    const { cls, recovery, evidence } = classifyRun(classifiedRun, facts, caps);
+
+    // A healthy green PR is not a failure of any class. Leaving the row
+    // unclassified is what keeps it eligible for the sweep on the tick where its
+    // base does move under it.
+    if (run.state === "pushed-green" && cls === "unknown") continue;
+
+    const retry = run.failureClass !== undefined;
+    store.updateRun(run.id, { failureClass: cls, recoveryAction: recovery });
+    log(
+      retry
+        ? `#${run.issue} retrying ${recovery} for ${cls}: ${evidence}`
+        : `#${run.issue} classified ${cls} → ${recovery}: ${evidence}`,
+    );
+    if (recovery === "settle") settled += 1;
+    await recoverRun(d, classifiedRun, cls, recovery, evidence);
+  }
+  return settled;
+}
+
+/** Performs the one action a class names. Never chooses one of its own. */
+async function recoverRun(
+  d: SettlementDeps,
+  run: RunRecord,
+  cls: FailureClass,
+  recovery: RecoveryAction,
+  evidence: string,
+): Promise<void> {
+  const { project, caps, tracker, store } = d;
+  const inProgress = project.stateLabels.inProgress;
+
+  if (recovery === "settle") {
+    // 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}`);
+    // #607: a recovered row whose PR is observed merged is settled work, so
+    // the claim gate comes off with the same projection as the sweep does.
+    releaseQueueLabel(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;
+  }
+
+  if (recovery === "continue") {
+    // Two classes recover by continuing, and only one of them has anything left
+    // to do here.
+    //
+    // `turn-cap-progress` was already handed back by the completion path, which
+    // swapped its labels and left the branch retained. There is nothing to
+    // perform, and writing anything would be actively wrong: overwriting
+    // `lastError` with a rebase brief tells the continuation worker to rebase a
+    // run that simply ran out of turns, and re-swapping labels the completion
+    // path already swapped is a pair of no-op `gh` calls. Record-only, so the
+    // sweep stops re-offering it.
+    if (cls === "turn-cap-progress") {
+      store.updateRun(run.id, { recoveredAt: Date.now() });
+      log(`#${run.issue} already continuing from ${cls}: ${evidence}`);
+      return;
+    }
+
+    // `wall-clock-cap-progress`: the completion path only auto-continues
+    // turn-cap kills, so a wall-clock kill with work to show reaches this
+    // sweep still holding the failed label. Swap it for the queue — the branch
+    // is retained, so the next dispatch reattaches it and briefs a resume from
+    // the recorded work. Killed rows gathered no tracker facts, so the
+    // issue-open guard mirrors the requeue path's. The continuation gate is
+    // the same one the turns path applies at kill time
+    // (`shouldContinueAfterTurnsCap`): the row is already charged, and once
+    // the ceiling is spent, handing back the queue label would offer a
+    // candidate admission can never accept — only the failed label comes off,
+    // and the exhaustion reaches a human (#490, #348).
+    if (cls === "wall-clock-cap-progress") {
+      const state = await tracker.issueState(run.issue).catch(() => undefined);
+      if (state !== "open") {
+        log(`#${run.issue} not continued from ${cls}: issue is ${state ?? "unreadable"}`);
+        return;
+      }
+      const continuation = store.continuationsFor(project.name, run.issue);
+      if (hasContinuationBudget(continuation, caps.maxContinuationsPerIssue)) {
+        swapToQueue(d, run.issue, project.stateLabels.failed);
+        store.updateRun(run.id, { recoveredAt: Date.now() });
+        log(`#${run.issue} requeued for a wall-clock continuation: ${evidence}`);
+      } else {
+        store.enqueueLabelOps(project.name, [
+          { issue: run.issue, op: "remove", label: project.stateLabels.failed },
+        ]);
+        store.updateRun(run.id, { recoveredAt: Date.now() });
+        await safeEscalate(d, {
+          tier: 1,
+          project: project.name,
+          issue: run.issue,
+          summary: `#${run.issue} exhausted its continuation budget on wall-clock cap kills`,
+          detail: [
+            `Attempt ${run.attempt} hit the wall-clock cap with work to continue from, but ${continuation} continuation(s) are already charged against a cap of ${caps.maxContinuationsPerIssue}.`,
+            evidence,
+            `Work to continue: branch ${run.branch} at ${run.headSha ?? run.salvageSha}${run.prUrl === undefined ? "" : ` — ${run.prUrl}`}.`,
+            "The issue cannot finish inside the wall-clock cap, so another run would burn a worker slot for the same outcome. Re-scope it, raise maxContinuationsPerIssue for it, or finish the remaining work by hand.",
+          ].join("\n"),
+        });
+        await postExhaustionPostmortem(
+          d,
+          run,
+          `Attempt ${run.attempt} hit the wall-clock cap with work to continue from, but ${continuation} continuation(s) are already charged against a cap of ${caps.maxContinuationsPerIssue}.`,
+        );
+        log(`#${run.issue} not continued from ${cls}: continuation budget exhausted`);
+      }
+      return;
+    }
+
+    // `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 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:
+        "merge-conflict: base moved under a green PR — rebase, regenerate recorded artifacts, push without force",
+      recoveredAt: Date.now(),
+    });
+    log(`#${run.issue} requeued for a rebase continuation: ${evidence}`);
+    return;
+  }
+
+  if (recovery === "requeue") {
+    if (cls === "provider-credit") {
+      await reactToProviderCredit(d, run.issue, evidence, run.sessionFile);
+    }
+    // A dispatch-infra requeue that keeps landing on the same issue means the
+    // mirror for its repo is persistently broken — a ref-lock that retry already
+    // exhausted, a dead remote. Requeueing forever spends a turn-0 run per tick
+    // with no chance of success, so after a bounded number of strikes this
+    // escalates to a human instead (#168, #177).
+    if (cls === "dispatch-infra" && store.classCountFor(project.name, run.issue, "dispatch-infra") >= DISPATCH_INFRA_MAX_STRIKES) {
+      await safeEscalate(d, {
+        tier: 1,
+        project: project.name,
+        issue: run.issue,
+        summary: `[dispatch-infra] #${run.issue}: the mirror for ${run.repo} is failing persistently — ${evidence}`,
+        detail: [
+          `The dispatcher could not provision a worktree for #${run.issue} ${DISPATCH_INFRA_MAX_STRIKES} times in a row, all before the worker's first turn.`,
+          "The mirror on this host needs attention (check disk, SSH/HTTPS credentials, and the mirror root).",
+        ].join("\n"),
+      });
+      store.updateRun(run.id, { recoveredAt: Date.now() });
+      log(`#${run.issue} escalated from persistent ${cls}: ${evidence}`);
+      return;
+    }
+    // Same bound for provider-transient: an issue whose stream keeps stalling
+    // mid-run is requeued free (no attempt, no continuation charged) — but a
+    // provider that aborts three times for one issue is down, and a human has
+    // to check its status before hand-requeueing (#220). The escalation names
+    // every model the chain tried, so a merged branch built on a different
+    // model is attributable (#286).
+    if (
+      cls === "provider-transient" &&
+      store.classCountFor(project.name, run.issue, "provider-transient") >= PROVIDER_TRANSIENT_MAX_STRIKES
+    ) {
+      const tried = formatModelsTried(modelsTried(store.runsForIssue(project.name, run.issue)));
+      await safeEscalate(d, {
+        tier: 1,
+        project: project.name,
+        issue: run.issue,
+        summary: `[provider-transient] #${run.issue}: the provider keeps aborting mid-stream — ${evidence}`,
+        detail: [
+          `The provider aborted the stream for #${run.issue} ${PROVIDER_TRANSIENT_MAX_STRIKES} times without the run ever producing a verdict (0 tokens billed each time).`,
+          ...(tried === ""
+            ? []
+            : [`Models tried: ${tried}.`]),
+          "Check provider status before requeueing by hand.",
+        ].join("\n"),
+      });
+      store.updateRun(run.id, { recoveredAt: Date.now() });
+      log(`#${run.issue} escalated from persistent ${cls}: ${evidence}`);
+      return;
+    }
+    // Same bound for provider-capacity: a run the provider throttled into the
+    // ground is requeued free (no attempt charged) — but a provider that
+    // throttles the same issue three times is at capacity, and a human has to
+    // check its status before hand-requeueing (#573). On a chain-configured
+    // project each requeue already moved the next attempt to the next chain
+    // model, so this escalation is what catches the no-chain case and the
+    // exhausted chain; it names every model the chain tried.
+    if (
+      cls === "provider-capacity" &&
+      store.classCountFor(project.name, run.issue, "provider-capacity") >= PROVIDER_CAPACITY_MAX_STRIKES
+    ) {
+      const tried = formatModelsTried(modelsTried(store.runsForIssue(project.name, run.issue)));
+      await safeEscalate(d, {
+        tier: 1,
+        project: project.name,
+        issue: run.issue,
+        summary: `[provider-capacity] #${run.issue}: the model provider is throttling this run into the ground — ${evidence}`,
+        detail: [
+          `The provider answered #${run.issue} with sustained in-session rate limits ${PROVIDER_CAPACITY_MAX_STRIKES} times in a row; the harness retried each and was exhausted.`,
+          ...(tried === ""
+            ? []
+            : [`Models tried: ${tried}.`]),
+          "Check the provider's rate-limit status (and its throughput-oriented routes) before requeueing by hand.",
+        ].join("\n"),
+      });
+      store.updateRun(run.id, { recoveredAt: Date.now() });
+      log(`#${run.issue} escalated from persistent ${cls}: ${evidence}`);
+      return;
+    }
+    // Only when the tracker still shows this issue as ours to hand back. An
+    // issue that is closed, or has no state label, was resolved by another route
+    // and requeueing it would dispatch work nobody asked for.
+    const state = await tracker.issueState(run.issue).catch(() => undefined);
+    if (state !== "open") {
+      log(`#${run.issue} not requeued from ${cls}: issue is ${state ?? "unreadable"}`);
+      return;
+    }
+    // A clean orphan whose queue label is already absent is a deliberate
+    // withdrawal — the operator took the issue out of the queue (e.g. so a
+    // daemon restart could not re-dispatch work known to be unsafe) — and
+    // recovery must not recreate that intent (#423). Read the live label set;
+    // when the queue label is gone, release the dispatcher-owned in-progress
+    // label and stop, leaving the operator's withdrawal to survive recovery.
+    if (cls === "orphan-clean") {
+      const snapshot = await tracker.issueSnapshot(run.issue).catch(() => undefined);
+      if (snapshot === undefined) {
+        log(`#${run.issue} not requeued from orphan-clean: cannot confirm ${project.queueLabel} (unreadable, retrying)`);
+        return;
+      }
+      if (!snapshot.labels.includes(project.queueLabel)) {
+        store.enqueueLabelOps(project.name, [{ issue: run.issue, op: "remove", label: inProgress }]);
+        store.updateRun(run.id, { recoveredAt: Date.now() });
+        log(`#${run.issue} not requeued from orphan-clean: ${project.queueLabel} removed before recovery (operator withdrawal)`);
+        return;
+      }
+      // #439: an orphan-clean row charges the continuation budget, so once
+      // `hasContinuationBudget` is spent — exactly the predicate `admitCandidates`
+      // holds the issue on — requeueing re-adds a queue label for a candidate the
+      // dispatcher can never admit. Stop handing it back and hold it instead: the
+      // queue label comes off (so admission never re-holds on every dispatch),
+      // the in-progress label is released, and a single diagnosis escalates once.
+      // `orphan-clean` is deliberately NOT a global exclusion from the budget (a
+      // worker that genuinely keeps dying mid-work must still be bounded); this is
+      // the missing ceiling check this path never had (#348's invariant).
+      const continuations = store.continuationsFor(project.name, run.issue);
+      if (!hasContinuationBudget(continuations, caps.maxContinuationsPerIssue)) {
+        const runs = store.runsForIssue(project.name, run.issue);
+        const breakdown = continuationBreakdown(runs);
+        const artifact = newestContinuableRun(runs);
+        const onlyDaemonStops = breakdown.size === 1 && breakdown.get("orphan-clean") === continuations;
+        const classLine = Array.from(breakdown, ([cls, n]) => `${n} ${cls}`).join(", ");
+        const artifactLine =
+          artifact === undefined
+            ? "The attempts left no salvage commit, head SHA or PR — the branch is empty, so start clean from a re-scope rather than continuing from nothing."
+            : `Work to continue: branch ${artifact.branch} at ${artifact.headSha ?? artifact.salvageSha}${artifact.prUrl === undefined ? "" : ` — ${artifact.prUrl}`}.`;
+        store.enqueueLabelOps(project.name, [
+          { issue: run.issue, op: "remove", label: inProgress },
+          { issue: run.issue, op: "remove", label: project.queueLabel },
+        ]);
+        store.updateRun(run.id, { recoveredAt: Date.now() });
+        await safeEscalate(d, {
+          tier: 1,
+          project: project.name,
+          issue: run.issue,
+          summary: `#${run.issue} exhausted its ${caps.maxContinuationsPerIssue}-continuation budget on ${cls}`,
+          detail: [
+            `Attempt ${run.attempt} is not requeued: ${continuations} continuation(s) charged against a cap of ${caps.maxContinuationsPerIssue}.`,
+            `Continuations by failure class: ${classLine}.`,
+            onlyDaemonStops
+              ? "Every continuation was a daemon stop — the work never failed; the budget was spent by daemon deaths, not the issue."
+              : "Continuations span real work — inspect what each attempt left behind before continuing.",
+            artifactLine,
+            "What you can do: raise maxContinuationsPerIssue for this issue, re-scope it, or continue from the preserved work (or start clean if none).",
+          ].join("\n"),
+        });
+        await postExhaustionPostmortem(
+          d,
+          run,
+          `Attempt ${run.attempt} is not requeued: ${continuations} continuation(s) charged against a cap of ${caps.maxContinuationsPerIssue}.`,
+        );
+        log(`#${run.issue} not requeued from orphan-clean: continuation budget exhausted`);
+        return;
+      }
+    }
+    const label = cls === "orphan-clean" ? inProgress : project.stateLabels.failed;
+    swapToQueue(d, run.issue, label);
+    store.updateRun(run.id, { recoveredAt: Date.now() });
+    log(`#${run.issue} requeued from ${cls}: ${evidence}`);
+    return;
+  }
+
+  if (recovery === "rerun-checks") {
+    if (run.prUrl === undefined) return;
+    try {
+      await tracker.rerunFailedChecks(run.prUrl);
+    } catch (err) {
+      log(`#${run.issue} check re-run failed (${errText(err)}) — retrying next tick`);
+      return;
+    }
+    // Back to pending rather than green: the existing settle sweep re-verifies
+    // it against the recorded head on a later tick, so nothing here has to guess
+    // whether the re-run passed.
+    store.updateRun(run.id, { state: "pushed-pending", lastError: null, recoveredAt: Date.now() });
+    log(`#${run.issue} re-ran infrastructure checks: ${evidence}`);
+    return;
+  }
+
+  if (recovery === "escalate") {
+    const detail = [evidence];
+    if (cls === "turn-cap-spinning" || cls === "wall-clock-cap-spinning") {
+      const calls = lastToolCalls(run.sessionFile);
+      detail.push(
+        calls.length === 0
+          ? "transcript unreadable — no tool calls could be recovered"
+          : `Last ${calls.length} tool calls: ${calls.join(" → ")}`,
+      );
+    }
+    if (run.lastError !== undefined && cls !== "question") detail.push(run.lastError);
+    // #172: an unwritten transcript is "the run died before it flushed", not a
+    // link to a file the operator will open and find missing.
+    detail.push(
+      run.sessionFile === undefined
+        ? "Session: (no transcript)"
+        : existsSync(run.sessionFile)
+          ? `Session: ${run.sessionFile}`
+          : `Session: ${run.sessionFile} (file was never written — the run died before its transcript was flushed)`,
+    );
+    // The class and the run are in the summary, which is what the notifications
+    // ledger dedupes on — so one class escalates once per run rather than every
+    // five minutes.
+    await safeEscalate(d, {
+      tier: 1,
+      project: project.name,
+      issue: run.issue,
+      runId: run.id,
+      summary: `[${cls}] #${run.issue} attempt ${run.attempt}: ${evidence}`,
+      detail: detail.join("\n"),
+    });
+    // The hand-off IS the recovery for these classes: there is nothing else this
+    // package can do, and leaving the row unrecovered would re-escalate forever.
+    store.updateRun(run.id, { recoveredAt: Date.now() });
+    return;
+  }
+
+  // `hold` (orphan-dirty) and `none`: recorded, nothing performed. The existing
+  // unsalvaged-WIP admission hold already fails dispatch closed until an
+  // operator acknowledges the tree, which is the only safe move when the
+  // worktree holds the only copy of real work.
+}
+
+/**
+ * Enqueue a state-label → queue-label swap for projection (#201).
+ *
+ * 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.
+ */
+export function swapToQueue(d: Pick<SettlementDeps, "project" | "store">, issue: number, label: string): void {
+  d.store.enqueueLabelOps(d.project.name, [
+    { issue, op: "remove", label },
+    { issue, op: "add", label: d.project.queueLabel },
+  ]);
+}
+
+
+// ------------------------------------------------------------------- status rendering of salvaged runs
+
+/**
+ * The WIP block: every issue whose newest attempt left work behind, and
+ * whether that work is safe.
+ *
+ * Blocked runs used to be invisible here, which is exactly how #118 stayed
+ * invisible for a full attempt cycle — the operator saw a blocked issue and had
+ * no way to tell "stopped with 34 uncommitted files" from "stopped clean".
+ * A preserved line is informational; an UNSALVAGED line is an alarm, and it
+ * names the directory because that directory is the work.
+ */
+export function formatSalvagedRuns(runs: readonly RunRecord[]): string[] {
+  if (runs.length === 0) return [];
+  const lines = ["", "wip"];
+  for (const r of runs) {
+    lines.push(
+      r.salvageError !== undefined && r.salvageAckAt === undefined
+        ? `  #${r.issue}  UNSALVAGED  ${r.worktree === "" ? "(path not recorded)" : r.worktree} — ` +
+          `only copy, dispatch held (${r.salvageError})`
+        : r.salvageError !== undefined
+          ? `  #${r.issue}  accepted as lost  attempt ${r.attempt} (${r.salvageError})`
+          : `  #${r.issue}  preserved  ${r.salvageSha ?? "?"} on ${r.branch} (attempt ${r.attempt}, ${r.state})`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * The quarantined block (#737): retained worktrees whose object store could
+ * not be made sound, so the daemon refused to fetch into them and their
+ * commits cannot be verified against any remote. Distinct from the `wip` block
+ * on purpose — quarantine is not work the exit left behind, it is a tree the
+ * daemon is refusing to trust, and "potentially stranded" outranks any
+ * wording that reads like routine retention. The line names the directory
+ * because the directory is the work.
+ */
+export function formatQuarantinedRuns(runs: readonly RunRecord[]): string[] {
+  if (runs.length === 0) return [];
+  const lines = ["", "quarantined"];
+  for (const r of runs) {
+    lines.push(
+      `  #${r.issue}  QUARANTINED  ${r.worktree === "" ? "(path not recorded)" : r.worktree} — ` +
+        (r.quarantineDetail ?? "object store could not be made sound"),
+    );
+  }
+  return lines;
+}