omp-conductor 0.15.10 → 0.15.12

package/src/types.ts

@@ -250,6 +250,14 @@ export const RELEASE_SHAPES = [
   "package-publish",
   "github-release",
   "deploy",
+  /**
+   * Replace the running conductor itself: the Bun-global CLI, the omp plugin
+   * and the Herdr plugin, pinned to one published release and executed
+   * detached. This is the "nobody patches the running conductor" boundary
+   * moved deliberately, not worked around — a session that may cut a release
+   * still cannot install one until an operator grants this shape too.
+   */
+  "install",
 ] as const;
 
 export type ReleaseShape = (typeof RELEASE_SHAPES)[number];
@@ -293,6 +301,7 @@ export const DENIED_RELEASE_GRANTS: ResolvedGrants = {
   "package-publish": "human",
   "github-release": "human",
   deploy: "human",
+  install: "human",
 };
 
 /**
@@ -308,6 +317,9 @@ export const OPERATOR_BRIEF_GRANTS: ResolvedGrants = {
   "package-publish": "orchestrator",
   "github-release": "orchestrator",
   deploy: "human",
+  // Nobody expected a legacy "operator-brief" grant to cover patching the
+  // running conductor; like `deploy` it stays with the human.
+  install: "human",
 };
 
 /**
@@ -324,6 +336,16 @@ export const SESSION_ROLES = ["worker", "orchestrator"] as const;
 
 export type SessionRole = (typeof SESSION_ROLES)[number];
 
+/**
+ * Env var the daemon sets on a spawned session so the reporting CLI can tell a
+ * worker session from the operator's shell. The daemon stamps it on the
+ * session-host child (and thus on every tool process it spawns); a direct CLI
+ * run — the operator's shell or a systemd unit — has it absent and is treated
+ * as the orchestrator, preserving the historical surface. {@link SESSION_ROLES} is
+ * the closed vocabulary: a value outside it must be refused, never assumed.
+ */
+export const SESSION_ROLE_ENV = "OMP_CONDUCTOR_SESSION_ROLE";
+
 /**
  * Who holds an authority the daemon itself never exercises. Declared as data
  * for the same reason as {@link REPORT_SCOPES}: the validator, the wizard and
@@ -335,11 +357,16 @@ export const AUTHORITY_HOLDERS = ["human", "orchestrator"] as const;
 export type AuthorityHolder = (typeof AUTHORITY_HOLDERS)[number];
 
 /**
- * What a project that never answered the question gets: humans keep both. A
- * default that delegated merging would hand a fresh fleet write access to its
- * own main branch on the strength of an unread config file.
+ * What a project that never answered the question gets: humans keep all three.
+ * A default that delegated merging would hand a fresh fleet write access to
+ * its own main branch on the strength of an unread config file, and a default
+ * that delegated promotion would let the orchestrator start spend unasked.
  */
-export const DEFAULT_AUTHORITY: ProjectConfig["authority"] = { merge: "human", release: "human" };
+export const DEFAULT_AUTHORITY: ProjectConfig["authority"] & { promotion: AuthorityHolder } = {
+  merge: "human",
+  release: "human",
+  promotion: "human",
+};
 
 /**
  * Whether a merge candidate must be up to date with the branch it targets.
@@ -615,18 +642,38 @@ export interface ProjectConfig {
    * answered the question wants.
    */
   workerModel?: string;
+  /**
+   * Ordered fallback models for this project, tried after {@link workerModel}
+   * once a run chain has suffered enough consecutive provider-class failures
+   * (stream stalls and credit refusals). Each new issue still starts on the
+   * primary; recovery is sticky to the chain, never global (#286). Empty or
+   * absent preserves the pre-failover dispatch exactly: every attempt stays on
+   * the primary until the existing escalation path takes over.
+   */
+  modelFallbacks?: string[];
+  /**
+   * Consecutive provider-class failures on one run chain after which the next
+   * dispatch moves to the next model in {@link modelFallbacks}. Defaults to 2
+   * when absent or unusable.
+   */
+  modelFallbackThreshold?: number;
   /**
    * How a stuck run reaches a human, what to do when it cannot, and who runs
    * the session that triages it. See {@link ORCHESTRATOR_MODES}.
    */
   escalation: { telegramChatId?: string; telegramTopicId?: number; fallbackToIssueComment: boolean; orchestrator: OrchestratorMode };
   /**
-   * Who lands green PRs and who cuts releases. The daemon never acts on this
-   * itself — it words the orchestrator's standing orders and the rendered brief
-   * scaffold with it, so config and prompt can never disagree about which of
-   * them is holding the merge button.
+   * Who lands green PRs, who cuts releases and who promotes. The daemon never
+   * acts on this itself — it words the orchestrator's standing orders and the
+   * rendered brief scaffold with it, so config and prompt can never disagree
+   * about which of them is holding the merge button.
+   *
+   * `promotion` is the queue-label sign-off: adding the label to an issue lets
+   * a worker claim it and starts spend, so POLICY.md must state its owner and
+   * a config that never answered defaults to the human — a gate whose owner is
+   * unstated must never resolve to the orchestrator.
    */
-  authority: { merge: AuthorityHolder; release: AuthorityHolder };
+  authority: { merge: AuthorityHolder; release: AuthorityHolder; promotion?: AuthorityHolder };
   /**
    * Per-shape tool-call enforcement for releases and deploys. Optional only for
    * configs written before the tripwire existed; both omission and any shape key
@@ -666,6 +713,20 @@ export interface ProjectConfig {
   workspaceRoot: string;
   /** Cache of bare clones, so N runs share one fetch instead of N. */
   mirrorRoot: string;
+  /**
+   * Git treeish (commit SHAs or refs) on the base branch that every preserved
+   * continuation branch must contain before the dispatcher may reattach it
+   * (#428). A base safety fix protects only branches forked after it landed; a
+   * continuation forked before it still carries the dangerous code and, on a
+   * shared host, re-running the lifecycle suite it retains is what SIGTERMed
+   * the production daemon. With a marker configured, the dispatcher refuses to
+   * reattach any preserved branch missing it, holds the issue as `stale-base`
+   * (distinct from capacity or dependency holds), and never silently merges
+   * base into the user's work. Absent or empty, ordinary stale continuations
+   * keep today's behaviour. Optional and hand-edited, like
+   * {@link recoveryMerges}.
+   */
+  criticalBase?: string[];
 }
 
 /**
@@ -706,6 +767,16 @@ export interface ReadyIssue {
   updatedAt: string;
 }
 
+/**
+ * One issue comment as the worker brief renders it: author login and verbatim
+ * body, in the tracker's own order (oldest first), so a later correction
+ * visibly supersedes an earlier note.
+ */
+export interface IssueComment {
+  author: string;
+  body: string;
+}
+
 /**
  * How a pull request ended, in tracker-agnostic terms. Lowercase because the
  * loop's vocabulary is lowercase; mapping GitHub's `MERGED`/`CLOSED`/`OPEN` onto
@@ -755,17 +826,10 @@ export interface PrDiff {
  * vocabulary that lives in three places drifts in three directions.
  */
 export const SETTLEMENT_FLAG_KINDS = [
-  /** The PR touched a file the report's `changed:` line never mentioned — the
-   *  direction that matters, an undisclosed edit. */
-  "undisclosed-file",
-  /** The report carried no usable `changed:` line, so nothing was disclosed. */
+  /** The settlement could not read the PR's diff, so no `changed:` file list
+   *  could be derived — the one disclosure fault that survives, because a
+   *  tree no one can read has nothing to disclose. */
   "changed-line-missing",
-  /** `changed:` named a path the PR never touched. The weaker direction. */
-  "unmatched-claim",
-  /** The same file appears as both claimed-but-untouched and
-   *  touched-but-unclaimed — the `changed:` line's format defeated the parser;
-   *  read the diff directly. */
-  "report-format-unparsed",
   /** A test file left the tree and no rename in the PR accounts for it. */
   "test-file-deleted",
   /** A skip/only/focus marker appears on a line the PR added. */
@@ -864,6 +928,16 @@ export interface Tracker {
    * Complete — follows pagination to the end.
    */
   listOpenIssues(): Promise<ReadyIssue[]>;
+  /**
+   * The issue's comments, oldest first. The dispatcher renders them into the
+   * worker brief, so grooming the orchestrator posted as a comment reaches the
+   * worker's opening prompt without any runtime read.
+   *
+   * Throws when the tracker could not be read: the caller must never mistake
+   * "could not read" for "no comments", which is exactly the failure mode this
+   * read exists to prevent (#517).
+   */
+  listComments(issue: number): Promise<IssueComment[]>;
   addLabel(issue: number, label: string): Promise<void>;
   removeLabel(issue: number, label: string): Promise<void>;
   comment(issue: number, body: string): Promise<void>;
@@ -944,8 +1018,13 @@ export interface Tracker {
    * Verify that a pull request is open, ready, and has a non-empty
    * terminal-success check rollup. When `expectedHead` is supplied, also
    * require the live head to match it.
+   *
+   * `opts.read` switches from the merge gate's "may this merge" to the read
+   * surface's "what is this PR's state": a merged or closed PR is then a
+   * reported fact rather than an `expected OPEN` refusal. Mutating verbs never
+   * pass `read`, so their open-PR gate is unchanged.
    */
-  verifyPr(url: string, expectedHead?: string): Promise<PrVerification | undefined>;
+  verifyPr(url: string, expectedHead?: string, opts?: { read?: boolean }): Promise<PrVerification | undefined>;
   /**
    * The pull request's diff, or undefined when this adapter could not produce
    * one — an unparseable URL, a deleted PR, a flaky network.
@@ -1010,6 +1089,8 @@ export const FAILURE_CLASSES = [
   "env-start-failure",
   "turn-cap-progress",
   "turn-cap-spinning",
+  "wall-clock-cap-progress",
+  "wall-clock-cap-spinning",
   "admin-kill",
   "ci-infra",
   "ci-deterministic",
@@ -1132,6 +1213,16 @@ export interface RunRecord {
    *  copy of real work, so the tree was kept and the issue is held out of
    *  dispatch until an operator acknowledges it. */
   salvageError?: string;
+  /**
+   * The model this attempt actually dispatched on, written at dispatch when the
+   * project configures a failover chain (`modelFallbacks`). Absent means the
+   * run predates the column or the project has no chain — never "the harness
+   * downgraded"; the harness's own downgrade is carried as
+   * `modelFallbackMessage` on the worker result instead, because that is
+   * evidence about this run while this column is attribution for the chain
+   * (#286).
+   */
+  model?: string;
   /** When an operator accepted the loss or recovered the tree by hand
    *  (`unblock --force`). Clears the hold without erasing what happened. */
   salvageAckAt?: number;
@@ -1144,10 +1235,10 @@ export interface RunRecord {
    *  exactly as an unflagged one does, and the flags are evidence for whoever
    *  reviews the PR. Absent means the audit found nothing, or never ran. */
   settlementFlags?: SettlementFlag[];
-  /** The worker's settlement report text for this attempt, verbatim. Persisted
-   *  on every terminal update so the next attempt can pool its disclosures
-   *  (#199). Absent means the run predates the column, or was killed before the
-   *  worker returned a report. */
+  /** The worker's settlement report text for this attempt: the worker's own
+   *  narrative, with the `changed:` file list rewritten at settlement from
+   *  the PR's actual diff (#488). Absent means the run predates the column, or
+   *  was killed before the worker returned a report. */
   report?: string;
   /**
    * Why this run ended badly, and what the daemon did about it (#132). Absent
@@ -1162,6 +1253,15 @@ export interface RunRecord {
   recoveredAt?: number;
 }
 
+/**
+ * A partial patch for {@link updateRun}. Every key is optional; an absent key
+ * and an explicitly-`undefined` value both leave the column alone, while an
+ * explicit `null` clears it (#468). `null` exists only for the columns a
+ * caller may legitimately empty — a settle can never widen into a column it
+ * did not mean to write.
+ */
+export type RunPatch = { [K in keyof RunRecord]?: RunRecord[K] | null };
+
 /** A one-shot turn budget waiting for one issue's next claimed attempt. */
 export interface TurnOverride {
   project: string;
@@ -1187,6 +1287,7 @@ export type AdmissionHoldReason =
   | "daily-spend-cap"
   | "plan-usage-cap"
   | "shutting-down"
+  | "stale-base"
   | "unroutable:no-repo-label"
   | "unroutable:multiple-repo-labels"
   | "unroutable:unknown-repo";
@@ -1211,6 +1312,13 @@ export interface DispatchSummary {
   /** True only for system/API failures, never ordinary policy holds. */
   degraded: boolean;
   holds: AdmissionHoldSummary[];
+  /** Runs the pass settled while it ran — merged PRs terminalised by the settle
+   *  sweep and by classification recovery. Optional: persisted old rows lack
+   *  it, so readers use `?? 0`. (#497) */
+  settled?: number;
+  /** True for a held pass's own record (#497): the queue was never routed, so
+   *  ready/routed/claimed are absent queue facts, not an empty queue. */
+  paused?: boolean;
 }
 
 /** Admission holds that indicate repairable friction rather than normal flow control. */
@@ -1220,6 +1328,7 @@ export type FrictionAdmissionReason =
   | "parent-lookup-error"
   | "issue-state-lookup-error"
   | "open-pr-lookup-error"
+  | "stale-base"
   | "unroutable:no-repo-label"
   | "unroutable:multiple-repo-labels"
   | "unroutable:unknown-repo";
@@ -1261,11 +1370,22 @@ export interface FrictionSignal {
  * today's digest already been handed over?" without asking the model to
  * remember, which is the memory #123 found unreliable.
  *
+ * The remaining values are the interrupt categories themselves. Handing a
+ * report over as `fleet-stopped` or `tier2` (or `decision-needed`,
+ * `confirmed-failure`) is the escalation handoff: the project's reporting
+ * policy decides between sending now and holding, exactly as it does for a
+ * daemon escalation of that category, and an identical retry is refused only
+ * while the earlier handoff is still undelivered (#453).
+ *
  * Declared as data for the same reason as {@link REPORT_SCOPES}: the CLI verb
  * that accepts a kind and the outbox that renders one enumerate the same list,
  * so a third kind cannot be added while either still knows only two.
  */
-export const REPORT_KINDS = ["material", "digest"] as const;
+export const REPORT_KINDS = [
+  "material",
+  "digest",
+  ...INTERRUPT_CATEGORIES.filter((category) => category !== "material"),
+] as const;
 
 export type ReportKind = (typeof REPORT_KINDS)[number];
 
@@ -1377,7 +1497,41 @@ export interface DigestBacklog {
   heldNoticeCount: number;
   /** Subset held only for the next availability window. */
   availabilityHeldNoticeCount?: number;
+  /** Oldest held notice across both held groups. */
   heldNoticeOldestAt?: number;
+  /** Oldest held notice that is digest-bound (`releaseOnAvailable` false). */
+  digestHeldNoticeOldestAt?: number;
+  /** Oldest held notice waiting only for the availability window. */
+  availabilityHeldNoticeOldestAt?: number;
+}
+
+/** Where one captured raw idea is in its lifecycle (#298). `pending` is a raw
+ *  idea awaiting grooming; `groomed` became an issue (#300, which records the
+ *  issue URL); `dismissed` was dropped without becoming anything. */
+export const INTAKE_STATES = ["pending", "groomed", "dismissed"] as const;
+
+export type IntakeState = (typeof INTAKE_STATES)[number];
+
+/** One raw idea captured by `omp-conductor intake`, durable in the store so an
+ *  idea from 02:00 is still there after a restart (#299). */
+export interface IntakeItem {
+  id: string;
+  project: string;
+  /** The idea text verbatim, as captured. */
+  text: string;
+  createdAt: number;
+  state: IntakeState;
+  /** The issue this idea became, once #300 grooms it. */
+  issueUrl?: string;
+  /** When the item was resolved into an issue (#300) or dismissed. */
+  groomedAt?: number;
+}
+
+/** What a caller hands over. The store owns the id, the state and the timestamps. */
+export interface IntakeDraft {
+  project: string;
+  text: string;
+  at: number;
 }
 
 /**
@@ -1460,7 +1614,8 @@ export interface LabelOp {
 export interface Store {
   /** A claimed run atomically consumes and applies its issue's pending turn override. */
   createRun(r: Omit<RunRecord, "id">): RunRecord;
-  updateRun(id: string, patch: Partial<RunRecord>): void;
+  /** Partial patch; an explicit `null` clears a column, `undefined`/absence leaves it alone (#468). */
+  updateRun(id: string, patch: RunPatch): void;
   getRun(id: string): RunRecord | undefined;
   /** Runs whose issue is occupied: a live worker, or a green PR awaiting merge. */
   activeRuns(project: string): RunRecord[];
@@ -1471,6 +1626,11 @@ export interface Store {
   /** Newest attempt per issue for the live board. Non-merged work remains
    * visible; merged rows are bounded by the supplied recent-history cutoff. */
   recentRuns(project: string, mergedSinceEpochMs: number): RunRecord[];
+  /** Every attempt that recorded one PR URL, newest first. Mediated PR verbs
+   *  resolve ownership through this, not through `recentRuns`' newest-attempt-
+   *  per-issue view — a requeued continuation must never hide the PR its
+   *  predecessor opened. Merged rows keep the same recent-history bound. */
+  runsForProjectPr(project: string, prUrl: string, mergedSinceEpochMs: number): RunRecord[];
   /** Merged rows whose post-merge workflow verdict is still pending, oldest first. */
   runsNeedingBaseCheck(project: string, limit?: number): RunRecord[];
   /** Replace the current live-head health row for one routed repository. */
@@ -1500,6 +1660,9 @@ export interface Store {
    *  tail` resolves an issue number to a transcript through this; the number is
    *  what an operator has, the run id is not. */
   latestRun(project: string, issue: number): RunRecord | undefined;
+  /** Every attempt for one issue, oldest first, so an escalation can group the
+   *  continuation budget by failure class (#439). */
+  runsForIssue(project: string, issue: number): RunRecord[];
   /** Persist a one-shot ceiling and append the operator action to its audit ledger. */
   setTurnOverride(project: string, issue: number, maxTurns: number, setAt?: number): void;
   turnOverride(project: string, issue: number): number | undefined;
@@ -1511,16 +1674,24 @@ export interface Store {
     project: string,
     opts?: { issue?: number; limit?: number },
   ): TurnOverride[];
-  /** Every attempt of one issue that settled with a report, in attempt order.
-   *  The settlement audit pools these as prior disclosures when a later
-   *  attempt is reconciled (#199). Rows with no report (pre-#199, or killed
-   *  before the worker returned) are skipped. */
-  attemptReports(project: string, issue: number): { attempt: number; report: string }[];
   runsStartedSince(project: string, sinceEpochMs: number): number;
   spendSince(project: string, sinceEpochMs: number): number;
+  /** The rows one stats window needs (#282): every run settling at or after
+   *  `sinceEpochMs`, plus the full attempt chain of each issue whose merge
+   *  settled there (so continuation chains collapse into one journey), ordered
+   *  by issue then startedAt. Read-only. */
+  statsRuns(project: string, sinceEpochMs: number): RunRecord[];
+  /** Total tracked `gh` calls between two UTC day keys, inclusive (#198). */
+  ghCallsBetween(sinceDay: string, untilDay: string): number;
   /** Idempotence guard so a retry loop cannot page a human repeatedly for the
    *  same event. */
   wasNotified(key: string): boolean;
+  /** Whether an escalation handoff with this project, category and folded text
+   *  is still owed: a same-text report still in the outbox, or a same-text
+   *  held notice not yet digested. The CLI report surface refuses an identical
+   *  retry only while this is true (#453) — once the first handoff lands, the
+   *  same text is a new occurrence, not a double-send. */
+  hasOpenEscalationHandoff(project: string, category: InterruptCategory, body: string): boolean;
   recordDispatch(project: string, summary: DispatchSummary): void;
   latestDispatch(project: string): DispatchSummary | undefined;
   /** The newest `digest:` dedupe key a project has run toward without ending in
@@ -1544,6 +1715,13 @@ export interface Store {
   getMaterialEvent(id: string): MaterialEvent | undefined;
   /** Ordinary material outcomes still owed, oldest first and bounded. */
   undigestedMaterialEvents(project: string, limit?: number): MaterialEvent[];
+  /** Persist one raw idea, `pending`, for later grooming (#299). */
+  recordIntake(draft: IntakeDraft): IntakeItem;
+  /** Ideas still `pending`, oldest first — what `intake list` and `status` read. */
+  pendingIntake(project: string): IntakeItem[];
+  /** Resolve one idea to `groomed` (recording the issue URL #300 chose) or
+   *  `dismissed`. `false` when the id is unknown. */
+  resolveIntake(id: string, state: "groomed" | "dismissed", issueUrl?: string): boolean;
   /** Count and age source for status and digest prompt bounds. */
   digestBacklog(project: string): DigestBacklog;
   /** Add one bounded observation to the per-day friction rollup. */
@@ -1655,6 +1833,8 @@ export interface Store {
   createDecision(draft: DecisionDraft): DecisionRecord;
   /** Everything still owed an answer, oldest first — what a tick digest reads. */
   openDecisions(project: string): DecisionRecord[];
+  /** One row by id, whatever its state — what a bounded ask polls while waiting. */
+  decision(id: string): DecisionRecord | undefined;
   /** Answer or withdraw one. `false` when the id is unknown or already closed,
    *  so a double-resolve cannot overwrite the first answer. */
   resolveDecision(id: string, state: "answered" | "withdrawn", resolution: string, at: number): boolean;
@@ -1805,6 +1985,10 @@ export const VERB_NAMES = [
   "conductor_pr_merge",
   "conductor_label",
   "conductor_release",
+  /** Request the fleet upgrade itself to a published conductor release. The
+   *  install shape gates it like a release shape; execution detaches from this
+   *  session and the daemon, and the first tick after the restart verifies. */
+  "conductor_install",
   /** The one read verb. It answers with the merge gate's own verdict, so
    *  "pushed-green" is the dispatcher's reading of the PR rather than a claim the
    *  worker makes about itself from whatever it happened to run. */

package/src/unblock.ts

@@ -35,6 +35,7 @@
  * failed-attempt budget.
  */
 
+import { hasContinuationBudget, hasFailedAttemptBudget } from "./daemon.ts";
 import { projectLabels } from "./label-projection.ts";
 import { LIVE_STATES } from "./store.ts";
 import type { Caps, ProjectConfig, RunRecord, Store, Tracker } from "./types.ts";
@@ -64,11 +65,18 @@ export interface UnblockOutcome {
   /** Set when `--force` recorded an operator's acceptance of that loss. */
   forced?: true;
   /** Set when the queue label was re-added (the default); absent on
-   *  --no-requeue, on the refusal path, and when a live worker (claimed or
-   *  running) is still on the issue. A pushed-green/pushed-pending occupancy
+   *  --no-requeue, on the refusal path, when a live worker (claimed or
+   *  running) is still on the issue, and when a spent budget withheld the
+   *  re-queue (requeueWithheld). A pushed-green/pushed-pending occupancy
    *  is worker-free, so the label is still restored there (#175 bypasses it;
    *  `isEligible` needs the label once the PR resolves). */
   requeued?: true;
+  /** Set when the re-queue was withheld because the issue's failed-attempt or
+   *  continuation budget is spent — the same admission gate the dispatcher
+   *  holds on (failed-attempts / continuations), so the queue label would
+   *  manufacture a candidate that can never be admitted (#348). The lifecycle
+   *  clears still happened; only the add was skipped. */
+  requeueWithheld?: true;
   /** Set when `--no-requeue` skipped the queue-label re-add. */
   requeueSkipped?: true;
   /** Set when the tracker refused one or more of this verb's label ops, so
@@ -121,6 +129,7 @@ export async function unblockIssue(
   store: Store,
   issue: number,
   opts: { force?: boolean; requeue?: boolean } = {},
+  caps: Caps,
 ): Promise<UnblockOutcome> {
   const requeue = opts.requeue !== false;
   // Read before any label is touched: terminality is the whole of the argument
@@ -145,6 +154,16 @@ export async function unblockIssue(
     active,
   };
 
+  // The dispatcher's own admission gates, as daemon.ts computes them (#348):
+  // every failed-implementation slot spent, or the continuation budget
+  // exceeded, and the issue is held (`failed-attempts` / `continuations`) on
+  // every subsequent tick forever. A re-queued issue in that state is exactly
+  // the permanent admission hold this verb must not manufacture, so the
+  // re-queue half below is decided on the same predicates that decide the hold.
+  const budgetSpent =
+    !hasFailedAttemptBudget(counts.failuresUsed, caps.maxAttemptsPerIssue) ||
+    !hasContinuationBudget(counts.continuationsUsed, caps.maxContinuationsPerIssue);
+
   // The one case where this verb refuses. Clearing the labels here re-queues an
   // issue whose next claim starts by force-removing the worktree that holds the
   // only copy of the last attempt's work (#118) — and unlike every other state
@@ -185,14 +204,22 @@ export async function unblockIssue(
   // its PR is live but no process writes to its branch — so a pushed
   // continuation still gets the label: the dispatcher bypasses worker-free
   // pushed-green rows (#175), and `isEligible` requires the queue label once
-  // the PR resolves closed-unmerged.
+  // the PR resolves closed-unmerged. And never when the failed-attempt or
+  // continuation budget is spent (#348): the dispatcher holds such an issue
+  // forever, so the label would claim a candidacy the next admission cannot
+  // deliver — the clears still happen, the add is withheld.
   let requeued: true | undefined;
+  let requeueWithheld: true | undefined;
   let requeueSkipped: true | undefined;
   let labelSyncQueued: number | undefined;
   if (!live) {
     if (requeue) {
-      ops.push({ issue, op: "add", label: project.queueLabel });
-      requeued = true;
+      if (budgetSpent) {
+        requeueWithheld = true;
+      } else {
+        ops.push({ issue, op: "add", label: project.queueLabel });
+        requeued = true;
+      }
     } else {
       requeueSkipped = true;
     }
@@ -222,6 +249,7 @@ export async function unblockIssue(
     ...(latest === undefined ? {} : { latest }),
     ...(held === undefined ? {} : { forced: true as const }),
     ...(requeued === undefined ? {} : { requeued }),
+    ...(requeueWithheld === undefined ? {} : { requeueWithheld }),
     ...(requeueSkipped === undefined ? {} : { requeueSkipped }),
     ...(labelSyncQueued === undefined ? {} : { labelSyncQueued }),
   };
@@ -231,10 +259,14 @@ export async function unblockIssue(
  * What the operator reads back. It promises a re-claim only when one can
  * actually happen, because a promise made blindly sends someone away believing
  * work had resumed and they find out by waiting for it. Three things withhold
- * it: a live run still owns the issue through `agent:in-progress`, a spent
- * attempt budget makes the next tick escalate rather than dispatch, and — since
- * the in-progress label is only released for a terminal run — an issue with no
- * run row at all, where that label may still be sitting there unread. #18 was
+ * the re-claim promise: a live run still owns the issue through
+ * `agent:in-progress`, a spent attempt budget makes the next tick escalate
+ * rather than dispatch, and — since the in-progress label is only released for
+ * a terminal run — an issue with no run row at all, where that label may still
+ * be sitting there unread. A spent budget also withholds the queue label
+ * itself, on the same predicate the dispatcher holds on (#348): re-adding it
+ * would manufacture a candidate the next tick can never admit, and the report
+ * says so instead of claiming a restore that did not happen. #18 was
  * filed against this function saying `next tick eligible again` in a case where
  * it was not, so the wording is a contract rather than prose.
  *
@@ -297,16 +329,28 @@ export function formatUnblock(
         `"${project.stateLabels.inProgress}" until it ends — nothing is re-claimed before then`,
       `  queue      "${project.queueLabel}" not restored — a run is still active; re-run unblock once it settles`,
     );
-  } else if (o.failuresUsed >= caps.maxAttemptsPerIssue) {
+  } else if (!hasFailedAttemptBudget(o.failuresUsed, caps.maxAttemptsPerIssue)) {
     lines.push(
       `  next tick  not eligible: all ${caps.maxAttemptsPerIssue} failed attempts are spent. ` +
         "Rewrite the issue or raise maxAttemptsPerIssue.",
     );
-  } else if (o.continuationsUsed > caps.maxContinuationsPerIssue) {
+    if (o.requeueWithheld === true) {
+      lines.push(
+        `  queue      "${project.queueLabel}" withheld — re-adding it would manufacture a candidate the ` +
+          "dispatcher holds as failed-attempts forever; rewrite the issue or raise maxAttemptsPerIssue before re-queueing",
+      );
+    }
+  } else if (!hasContinuationBudget(o.continuationsUsed, caps.maxContinuationsPerIssue)) {
     lines.push(
       `  next tick  not eligible: the ${caps.maxContinuationsPerIssue}-continuation budget was exceeded. ` +
         "Inspect progress or raise maxContinuationsPerIssue.",
     );
+    if (o.requeueWithheld === true) {
+      lines.push(
+        `  queue      "${project.queueLabel}" withheld — re-adding it would manufacture a candidate the ` +
+          "dispatcher holds as continuations forever; inspect progress or raise maxContinuationsPerIssue before re-queueing",
+      );
+    }
   } else if (latest === undefined) {
     lines.push(
       `  next tick  eligible once the issue carries "${project.queueLabel}" and no state label — with no ` +