omp-conductor 0.7.1 → 0.8.0

package/src/tracker/github.ts

@@ -34,17 +34,6 @@ import type {
   Tracker,
 } from "../types.ts";
 
-/** The subset of `gh issue list --json` output this adapter reads. Fields the
- *  API can return as null are typed as such so the mapping has to handle it. */
-interface GhIssue {
-  number: number;
-  title: string | null;
-  body: string | null;
-  labels: { name: string }[] | null;
-  url: string;
-  updatedAt: string;
-}
-
 /**
  * Pull requests that would close an issue, with the one field that decides it.
  *
@@ -172,24 +161,27 @@ async function gh(argv: string[], stdin?: string): Promise<string> {
 
 /**
  * True when a label edit failed only because the requested end state already
- * holds. Adding a label is idempotent server-side, but removing one that is not
- * present is a 404, and a concurrent daemon restart can easily race into both.
+ * holds. Adding a label is idempotent server-side — `gh api -X POST
+ * .../labels` answers 200 for an already-present label — but removing one that
+ * is not present is a 404, and a concurrent daemon restart can easily race into
+ * both.
  *
- * The quoted form is gh's own, and it is why the two operations are classified
- * separately: `gh issue edit --remove-label x` on a label the *repository* does
- * not define exits 1 with `'x' not found` (2.97.0), which for a removal is the
- * end state already holding — a label nobody defined cannot be on an issue —
- * while for an add it is a genuine failure. Removing a label the repo defines
- * but the issue does not carry is already a silent success, so this path is
- * reached only by the undefined-label case, most often a state label an
- * operator declined to create at setup.
+ * The quoted forms are gh's own: `gh issue edit --remove-label x` on a label
+ * the *repository* does not define exits 1 with `'x' not found` (2.97.0), and
+ * `gh api -X DELETE .../labels/x` on an absent label fails with the API's
+ * `Label does not exist` / `HTTP 404`. For a removal both are the end state
+ * already holding — a label nobody defined cannot be on an issue — while for
+ * an add they are a genuine failure. Removing a label the repo defines but the
+ * issue does not carry is already a silent success, so this path is reached
+ * only by the undefined-label case, most often a state label an operator
+ * declined to create at setup.
  */
 function isLabelNoop(err: unknown, op: "add" | "remove"): boolean {
   if (!(err instanceof GhError)) return false;
   const stderr = err.stderr;
   return op === "add"
     ? /already (?:has|had|exists|applied|added)|label .* already/i.test(stderr)
-    : /label does not exist|not labeled|does not have (?:that|the|this) label|label .* not found|not found on (?:this )?issue|'[^']+' not found/i.test(
+    : /label does not exist|not labeled|does not have (?:that|the|this) label|label .* not found|not found on (?:this )?issue|'[^']+' not found|HTTP 404|Not Found/i.test(
         stderr,
       );
 }
@@ -234,6 +226,22 @@ export function firstOpenCloser(raw: string): OpenCloser | undefined {
  */
 const PR_URL = /^https?:\/\/[^\s/]+\/[^\s/]+\/[^\s/]+\/pull\/\d+\/?$/;
 
+/**
+ * Split a pull request URL into the owner, repo and number the REST API path
+ * spelling needs. The same shape {@link PR_URL} guards, with the parts
+ * captured; undefined for anything that guard would reject, so callers can use
+ * the two interchangeably.
+ */
+export function prUrlParts(
+  url: string,
+): { owner: string; repo: string; number: number } | undefined {
+  const match = /^https?:\/\/[^\s/]+\/([^\s/]+)\/([^\s/]+)\/pull\/(\d+)\/?$/.exec(url);
+  if (match === null || match[1] === undefined || match[2] === undefined || match[3] === undefined) {
+    return undefined;
+  }
+  return { owner: match[1], repo: match[2], number: Number.parseInt(match[3], 10) };
+}
+
 /**
  * How much of a pull request's diff the settlement audit will hold in memory.
  *
@@ -372,6 +380,29 @@ export function issueStateFrom(raw: string): IssueState | undefined {
   }
 }
 
+/**
+ * GitHub's REST pull-request shape (`{state, merged_at}`) mapped onto
+ * {@link PrState}. `merged_at` is what distinguishes a merged PR from a
+ * closed-unmerged one under REST — `state` alone answers "closed" for both, and
+ * a settle sweep that read only state would rewrite a merged row as
+ * closed-unmerged. Anything unrecognised is "could not tell", the same
+ * fail-closed answer {@link prStateFrom} gives.
+ */
+export function prStateFromRest(raw: string): PrState | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const row = parsed as { readonly [key: string]: unknown };
+  if (row["merged_at"] != null) return "merged";
+  if (row["state"] === "closed") return "closed";
+  if (row["state"] === "open") return "open";
+  return undefined;
+}
+
 /**
  * Parent number from a raw GraphQL response, or undefined when the issue has
  * no parent. Throws when the issue or claimed parent is malformed — admission
@@ -438,6 +469,26 @@ export function mergeableFrom(raw: string): "conflicting" | "clean" | "unknown"
   }
 }
 
+/**
+ * The REST mergeability spelling onto the same fail-open triple. `--jq
+ * .mergeable` prints the bare JSON token, so `"true"` and `"false"` are the
+ * only clean answers; `null` (printed verbatim by `--jq`) is GitHub still
+ * computing the merge, and everything else means the API changed under us.
+ */
+export function mergeableFromRest(raw: string): "conflicting" | "clean" | "unknown" {
+  switch (raw.trim()) {
+    case "true":
+      return "clean";
+    case "false":
+      return "conflicting";
+    default:
+      // `null` is GitHub still computing the merge on a PR pushed seconds ago.
+      // Reading it as clean would let a conflict recovery fire on a PR nobody
+      // has assessed yet — the same reasoning as `UNKNOWN` above.
+      return "unknown";
+  }
+}
+
 /**
  * Distinct workflow-run ids behind the non-success checks of a PR.
  *
@@ -483,6 +534,107 @@ export function labeledIssuesFrom(raw: string): { number: number; state: IssueSt
   return issues;
 }
 
+/**
+ * Parse the REST `/repos/{owner}/{repo}/issues` array onto {@link ReadyIssue}.
+ *
+ * The endpoint returns pull requests as well as issues — every PR is an issue
+ * with a `pull_request` key — so that key is the filter that keeps a routed
+ * repo's PR backlog out of the ready queue (#188). The REST field spelling is
+ * snake_case (`html_url`, `updated_at`); nulls are tolerated the same way the
+ * mapping this replaces tolerated them, because the API answers null for any
+ * of these fields.
+ */
+export function readyIssuesFromRest(raw: string): ReadyIssue[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const issues: ReadyIssue[] = [];
+  for (const entry of parsed) {
+    if (entry === null || typeof entry !== "object") continue;
+    const row = entry as { readonly [key: string]: unknown };
+    // The endpoint mixes in pull requests; the queue must never claim one.
+    if (row["pull_request"] != null) continue;
+    const number = row["number"];
+    const title = row["title"];
+    const body = row["body"];
+    const labels = row["labels"];
+    const url = row["html_url"];
+    const updatedAt = row["updated_at"];
+    if (typeof number !== "number" || !Number.isInteger(number)) continue;
+    if (typeof url !== "string" || typeof updatedAt !== "string") continue;
+    const names: string[] = [];
+    if (Array.isArray(labels)) {
+      for (const label of labels) {
+        if (label === null || typeof label !== "object") continue;
+        const name = (label as { readonly name?: unknown }).name;
+        if (typeof name === "string") names.push(name);
+      }
+    }
+    issues.push({
+      number,
+      title: typeof title === "string" ? title : "",
+      body: typeof body === "string" ? body : "",
+      labels: names,
+      url,
+      updatedAt,
+    });
+  }
+  return issues;
+}
+
+/** The two GitHub API budgets this adapter spends: GraphQL for the
+ *  closers/parent/rollup reads, core for everything else. `reset` is the REST
+ *  spelling — epoch seconds. */
+export interface RateLimitStatus {
+  graphql: { remaining: number; limit: number; reset: number };
+  core: { remaining: number; limit: number; reset: number };
+}
+
+function rateLimitBucket(
+  raw: unknown,
+): { remaining: number; limit: number; reset: number } | undefined {
+  if (raw === null || typeof raw !== "object") return undefined;
+  const row = raw as { readonly [key: string]: unknown };
+  const remaining = row["remaining"];
+  const limit = row["limit"];
+  const reset = row["reset"];
+  if (typeof remaining !== "number" || typeof limit !== "number" || typeof reset !== "number") {
+    return undefined;
+  }
+  return { remaining, limit, reset };
+}
+
+/**
+ * Read the GitHub API rate-limit budget for `status` (the tracker layer's
+ * counterpart to the decision probe: the layers differ, so the two stay
+ * independent).
+ *
+ * Any failure — a revoked token, a flaky network, a payload shape this build
+ * does not recognise — answers undefined: a broken `gh` must cost one status
+ * row, never the whole report.
+ */
+export async function fetchRateLimit(
+  runGh: typeof gh = gh,
+): Promise<RateLimitStatus | undefined> {
+  try {
+    const parsed = JSON.parse(
+      await runGh(["api", "rate_limit", "--jq", "{graphql: .resources.graphql, core: .resources.core}"]),
+    ) as unknown;
+    if (parsed === null || typeof parsed !== "object") return undefined;
+    const row = parsed as { readonly [key: string]: unknown };
+    const graphql = rateLimitBucket(row["graphql"]);
+    const core = rateLimitBucket(row["core"]);
+    if (graphql === undefined || core === undefined) return undefined;
+    return { graphql, core };
+  } catch {
+    return undefined;
+  }
+}
+
 export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
   const repo = p.tracker.repo;
 
@@ -490,43 +642,35 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
   // `checkConclusions` instead of re-implementing the same `gh` call.
   const tracker: Tracker = {
     async listReady(): Promise<ReadyIssue[]> {
+      // REST, not `issue list --json`: the ready-queue read is a hot-path poll
+      // on every dispatch pass, and GraphQL budget is the scarce one (#188).
+      // ponytail: one page is the cap. A queue deeper than 100 ready issues
+      // truncates silently; upgrade path is `--paginate`, but a backlog that
+      // size is a staffing problem before it is a paging one.
       const raw = await runGh([
-        "issue",
-        "list",
-        "--repo",
-        repo,
-        "--state",
-        "open",
-        "--label",
-        p.queueLabel,
-        // ponytail: one page is the cap. A queue deeper than 100 ready issues
-        // truncates silently; upgrade path is `--paginate` via the API, but a
-        // backlog that size is a staffing problem before it is a paging one.
-        "--limit",
-        "100",
-        "--json",
-        "number,title,body,labels,url,updatedAt",
+        "api",
+        `repos/${repo}/issues?state=open&labels=${encodeURIComponent(p.queueLabel)}&per_page=100`,
       ]);
 
-      const text = raw.trim();
-      // `gh` prints nothing at all in some no-match paths; an empty queue is
-      // the normal steady state, not an error.
-      if (!text) return [];
-
-      const issues = JSON.parse(text) as GhIssue[];
-      return issues.map((issue) => ({
-        number: issue.number,
-        title: issue.title ?? "",
-        body: issue.body ?? "",
-        labels: (issue.labels ?? []).map((label) => label.name),
-        url: issue.url,
-        updatedAt: issue.updatedAt,
-      }));
+      // The REST endpoint always answers a JSON array — an empty queue is `[]`,
+      // not empty text — but an empty body still parses to no issues here, and
+      // the empty queue is the normal steady state, not an error.
+      return readyIssuesFromRest(raw);
     },
 
     async addLabel(issue: number, label: string): Promise<void> {
       try {
-        await runGh(["issue", "edit", String(issue), "--repo", repo, "--add-label", label]);
+        // REST POST is natively idempotent: re-adding a label the issue already
+        // carries answers 200 with the label, so the noop classification below
+        // is reachable only on a genuinely odd failure — kept for parity.
+        await runGh([
+          "api",
+          "-X",
+          "POST",
+          `repos/${repo}/issues/${issue}/labels`,
+          "-f",
+          `labels[]=${label}`,
+        ]);
       } catch (err) {
         if (!isLabelNoop(err, "add")) throw err;
       }
@@ -534,7 +678,12 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
 
     async removeLabel(issue: number, label: string): Promise<void> {
       try {
-        await runGh(["issue", "edit", String(issue), "--repo", repo, "--remove-label", label]);
+        await runGh([
+          "api",
+          "-X",
+          "DELETE",
+          `repos/${repo}/issues/${issue}/labels/${encodeURIComponent(label)}`,
+        ]);
       } catch (err) {
         if (!isLabelNoop(err, "remove")) throw err;
       }
@@ -602,8 +751,10 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
 
     async issueState(issue: number): Promise<IssueState | undefined> {
       try {
+        // REST answers lowercase `open`/`closed`; the shared parser expects the
+        // CLI's uppercase spelling, so the answer is normalised before it.
         return issueStateFrom(
-          await runGh(["issue", "view", String(issue), "--repo", repo, "--json", "state", "--jq", ".state"]),
+          (await runGh(["api", `repos/${repo}/issues/${issue}`, "--jq", ".state"])).trim().toUpperCase(),
         );
       } catch {
         return undefined;
@@ -611,14 +762,21 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
     },
 
     async prState(url: string): Promise<PrState | undefined> {
-      // No `--repo`: a full URL is self-locating, and verified so on gh 2.97.0
-      // from a directory that is not a git repository at all — which is exactly
-      // where the daemon runs (its state directory), while the PR lives in one
-      // of the routed repos. Deriving `--repo` from the URL would only re-state
-      // what the URL already says.
+      // No `--repo`: the full URL names the repository, and the daemon runs
+      // from its own state directory rather than a checkout — so the REST path
+      // halves come out of the URL itself, never out of the current directory.
       if (!PR_URL.test(url)) return undefined;
+      const parts = prUrlParts(url);
+      if (parts === undefined) return undefined;
       try {
-        return prStateFrom(await runGh(["pr", "view", url, "--json", "state", "--jq", ".state"]));
+        return prStateFromRest(
+          await runGh([
+            "api",
+            `repos/${parts.owner}/${parts.repo}/pulls/${parts.number}`,
+            "--jq",
+            "{state, merged_at}",
+          ]),
+        );
       } catch {
         // Never throws, per the port's contract. A deleted PR, a revoked token
         // and a flaky network all mean "could not tell", and the caller's whole
@@ -713,8 +871,17 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
 
     async mergeable(prUrl: string): Promise<"conflicting" | "clean" | "unknown"> {
       if (!PR_URL.test(prUrl)) return "unknown";
+      const parts = prUrlParts(prUrl);
+      if (parts === undefined) return "unknown";
       try {
-        return mergeableFrom(await runGh(["pr", "view", prUrl, "--json", "mergeable", "--jq", ".mergeable"]));
+        return mergeableFromRest(
+          await runGh([
+            "api",
+            `repos/${parts.owner}/${parts.repo}/pulls/${parts.number}`,
+            "--jq",
+            ".mergeable",
+          ]),
+        );
       } catch {
         return "unknown";
       }
@@ -737,18 +904,12 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
       try {
         return labeledIssuesFrom(
           await runGh([
-            "issue",
-            "list",
-            "--repo",
-            repo,
-            "--label",
-            label,
-            "--state",
-            "all",
-            "--json",
-            "number,state",
-            "--limit",
-            String(limit),
+            "api",
+            `repos/${repo}/issues?state=all&labels=${encodeURIComponent(label)}&per_page=${limit}`,
+            "--jq",
+            // The endpoint mixes pull requests into the issue list; the
+            // reconcile must not remove labels off PRs.
+            "[.[] | select(.pull_request == null) | {number, state}]",
           ]),
         );
       } catch {

package/src/types.ts

@@ -42,6 +42,10 @@ export interface Caps {
   /** Parallel omp sessions. Two by default: on a small self-hosted runner pool
    *  a third worker would starve its own PR checks. */
   maxConcurrentWorkers: number;
+  /** Max live workers per repository. 1 by default: the mirror, branch-protection
+   *  staleness and shared CI egress are all per-repo collision domains (#186), so
+   *  extra slots should land on other repos. */
+  maxConcurrentWorkersPerRepo: number;
   /**
    * Rolling-day spend ceiling. `null` means no spend gate (turns + wall-clock
    * still apply). `0` is a hard stop — deliberate, not "unset".
@@ -479,6 +483,10 @@ export interface ProjectConfig {
   tracker: { kind: "github"; repo: string };
   /** The one label that means "a human has signed this off as agent-ready". */
   queueLabel: string;
+  /** Routable-candidate count below which the tick prompt tells the orchestrator
+   *  to groom the queue. Optional; defaults to {@link DEFAULT_GROOM_BELOW} in
+   *  orchestrator-tick.ts. */
+  groomBelow?: number;
   /** Labels the dispatcher writes back so the tracker alone shows live state
    *  to a human who never opens the daemon's logs. */
   stateLabels: { inProgress: string; blocked: string; failed: string };
@@ -923,6 +931,7 @@ export type AdmissionHoldReason =
   | "continuations"
   | "parent-lookup-error"
   | "sibling-active"
+  | "repo-active"
   | "open-pr-lookup-error"
   | "open-pr"
   | "unsalvaged-wip"
@@ -1311,6 +1320,7 @@ export interface Escalation {
  */
 export const DEFAULT_CAPS: Caps = {
   maxConcurrentWorkers: 2,
+  maxConcurrentWorkersPerRepo: 1,
   dailySpendUsd: 25,
   // Off unless an operator names a window. A default threshold would need a
   // default window id, and guessing which allowance a fleet lives on is how a

package/src/unblock.ts

@@ -15,7 +15,10 @@
  * dispatcher writes labels with, and the brief's rule stays absolute. That
  * absoluteness is worth more than the exception it replaces: orphan detection
  * is only trustworthy while every state label on the tracker was written by
- * this package.
+ * this package. The re-queue is the same port and the same principle: the
+ * queue label goes back on by default (#184) so an answered block is
+ * dispatchable again, and it stays off under `--no-requeue` or while any run
+ * for the issue is still active.
  *
  * Nothing here writes to the store, and that is a decision rather than an
  * omission. `RunState` describes what a worker process did; an answer is the
@@ -44,11 +47,24 @@ export interface UnblockOutcome {
    *  to "will the dispatcher hold this issue as issue-active?" that #178
    *  found this verb guessing at. */
   active: boolean;
+  /** Set when a live worker (a claimed/running run) is on the issue. The
+   *  dispatcher holds a worker-backed run as issue-active unconditionally,
+   *  while worker-free pushed occupancy can bypass it (#175) — so this is
+   *  the signal the queue label and the in-flight wording follow. */
+  live?: true;
   /** Set when nothing was cleared because the newest attempt's work exists
    *  only in its worktree. Carries the salvage failure verbatim. */
   refused?: string;
   /** 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
+   *  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 `--no-requeue` skipped the queue-label re-add. */
+  requeueSkipped?: true;
 }
 
 /**
@@ -90,13 +106,24 @@ export async function unblockIssue(
   tracker: Tracker,
   store: Store,
   issue: number,
-  opts: { force?: boolean } = {},
+  opts: { force?: boolean; requeue?: boolean } = {},
 ): Promise<UnblockOutcome> {
+  const requeue = opts.requeue !== false;
   // Read before any label is touched: terminality is the whole of the argument
   // for clearing in-progress, so the row that carries it decides the set.
   const latest = store.latestRun(project.name, issue);
   const terminal = latest !== undefined && !LIVE_STATES.includes(latest.state);
+  // Two different occupancies, and the label decisions each follow its own:
+  // `active` (ACTIVE_STATES) is what *occupies the issue* — a pushed-green or
+  // pushed-pending run has no worker process but its PR is live, so dispatch
+  // must not start a fresh attempt behind it. `live` (LIVE_STATES) is what
+  // *holds a worker process* (claimed/running). The queue label follows
+  // `live`: the dispatcher only holds a claim as issue-active for a
+  // worker-backed run (#175 bypasses worker-free pushed-green rows), so an
+  // issue whose occupancy is pushed-only is genuinely re-queueable and
+  // `isEligible` requires the label once that PR resolves closed-unmerged.
   const active = store.activeRuns(project.name).some((r) => r.issue === issue);
+  const live = store.liveRuns(project.name).some((r) => r.issue === issue);
   const counts = {
     attemptsUsed: store.attemptsFor(project.name, issue),
     failuresUsed: store.failuresFor(project.name, issue),
@@ -132,11 +159,37 @@ export async function unblockIssue(
     cleared.push(label);
   }
 
+  // The re-queue half of the verb. Clearing the state labels makes the issue
+  // *eligible*, but the dispatcher never sees an issue that does not carry the
+  // queue label — without this the unblock ends in the same alive-but-inert
+  // state it exists to end (#184). The label goes back on by default;
+  // `--no-requeue` is the "about to close it" case and leaves dispatch alone.
+  // Never under a *live worker*: the dispatcher holds a worker-backed run as
+  // issue-active anyway, and restoring the label under one is exactly the
+  // #178 inverted state. A pushed-green/pushed-pending run is worker-free —
+  // 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.
+  let requeued: true | undefined;
+  let requeueSkipped: true | undefined;
+  if (!live) {
+    if (requeue) {
+      await tracker.addLabel(issue, project.queueLabel);
+      requeued = true;
+    } else {
+      requeueSkipped = true;
+    }
+  }
+
   return {
     cleared,
     ...counts,
+    ...(live ? { live: true as const } : {}),
     ...(latest === undefined ? {} : { latest }),
     ...(held === undefined ? {} : { forced: true as const }),
+    ...(requeued === undefined ? {} : { requeued }),
+    ...(requeueSkipped === undefined ? {} : { requeueSkipped }),
   };
 }
 
@@ -191,9 +244,15 @@ export function formatUnblock(
   }
 
   if (latest !== undefined && LIVE_STATES.includes(latest.state)) {
+    // The newest run is live, so `active` is necessarily true and the queue
+    // label was NOT re-added (unblockIssue only re-queues when no run for the
+    // issue is active). Say that, like the sibling-active branch below does —
+    // the label outcome is part of the contract (#184), and a live newest run
+    // reaches this branch instead of `else if (o.active)`.
     lines.push(
       `  in flight  attempt ${latest.attempt} is ${latest.state}, so the issue keeps ` +
         `"${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) {
     lines.push(
@@ -218,25 +277,51 @@ export function formatUnblock(
     // instead of promising a re-claim the next tick withholds.
     lines.push(
       latest.prUrl === undefined
-        ? `  next tick  eligible again, as long as the issue still carries "${project.queueLabel}" ` +
-            `(newest run is ${latest.state} with no recorded PR; the dispatcher still applies its open-PR check at claim time)`
+        ? o.requeued === true
+          ? `  next tick  eligible again — "${project.queueLabel}" restored (no-op if it was already present; ` +
+            "the dispatcher still applies its open-PR check at claim time)"
+          : `  next tick  eligible again, as long as the issue still carries "${project.queueLabel}" ` +
+              `(newest run is ${latest.state} with no recorded PR; the dispatcher still applies its open-PR check at claim time)`
         : `  next tick  eligible as a continuation of ${latest.prUrl} — the pushed run stays active until ` +
             "that PR resolves; dispatch continues on its branch",
     );
   } else if (o.active) {
-    // A run other than the newest is still active (e.g. a live sibling under a
-    // terminal newest row), so the dispatcher will hold the issue as
-    // issue-active whatever the labels now say. #178's misleading case.
-    lines.push(
-      `  in flight  a run for this issue is still active, so the dispatcher holds the issue until it settles — ` +
-        `nothing is re-claimed before then ("${project.stateLabels.inProgress}" stays unless already released)`,
-    );
+    // A run other than the newest still occupies the issue. Two shapes hide
+    // under `active`, and they demand opposite reports: a *live worker*
+    // (claimed/running) holds the issue unconditionally — #178's misleading
+    // case — while worker-free pushed runs (pushed-green/pushed-pending) are
+    // the continuation shape, because #175 lets the dispatcher admit
+    // pushed-green rows whose workers are gone. The queue label follows the
+    // same split: off under a live worker, restored under pushed-only
+    // occupancy.
+    if (o.live === true) {
+      lines.push(
+        `  in flight  a live worker is still on this issue, so the dispatcher holds it until that run settles — ` +
+          `nothing is re-claimed before then ("${project.stateLabels.inProgress}" stays unless already released)`,
+        `  queue      "${project.queueLabel}" not restored — a live worker is still on this issue; re-run unblock once it settles`,
+      );
+    } else {
+      lines.push(
+        `  next tick  no live worker is on this issue — its active run(s) are worker-free pushes; ` +
+          "dispatch continues their branch once its holds and open-PR check clear",
+      );
+      if (o.requeued === true) {
+        lines.push(`  queue      "${project.queueLabel}" restored (no-op if it was already present)`);
+      }
+    }
   } else {
     lines.push(
-      `  next tick  eligible again, as long as the issue still carries "${project.queueLabel}" ` +
-        "(the dispatcher still applies its open-PR check at claim time)",
+      o.requeued === true
+        ? `  next tick  eligible again — "${project.queueLabel}" restored (no-op if it was already present; ` +
+          "the dispatcher still applies its open-PR check at claim time)"
+        : `  next tick  eligible again, as long as the issue still carries "${project.queueLabel}" ` +
+          "(the dispatcher still applies its open-PR check at claim time)",
     );
   }
 
+  if (o.requeueSkipped === true) {
+    lines.push(`  queue      "${project.queueLabel}" left untouched (--no-requeue)`);
+  }
+
   return lines.join("\n");
 }