omp-conductor 0.8.0 → 0.9.0

package/src/tracker/github.ts

@@ -510,7 +510,17 @@ export function failedRunIds(
   return ids;
 }
 
-/** Parse `[{number, state}]` from `gh issue list` or the sub-issues API. */
+/**
+ * Parse `[{number, state}]` from `gh issue list` or the sub-issues API.
+ *
+ * The REST issues endpoint mixes pull requests into the list, and the reconcile
+ * must never remove labels off a PR — so rows carrying a `pull_request` key are
+ * dropped before the caller sees them. This replaces the `--jq
+ * select(.pull_request == null)` projection listLabeled used to send: `-i`
+ * output (needed for conditional revalidation) cannot carry a jq projection,
+ * so the filter moved in-process where it also covers every future caller.
+ * `childrenOf` rows never carry the key, so the guard is a no-op there.
+ */
 export function labeledIssuesFrom(raw: string): { number: number; state: IssueState }[] {
   let parsed: unknown;
   try {
@@ -523,6 +533,7 @@ export function labeledIssuesFrom(raw: string): { number: number; state: IssueSt
   for (const entry of parsed) {
     if (entry === null || typeof entry !== "object") continue;
     const row = entry as { readonly [key: string]: unknown };
+    if (row["pull_request"] != null) continue;
     const number = row["number"];
     const rawState = row["state"];
     if (typeof number !== "number" || !Number.isInteger(number) || typeof rawState !== "string") continue;
@@ -586,6 +597,118 @@ export function readyIssuesFromRest(raw: string): ReadyIssue[] {
   return issues;
 }
 
+/** One cached page per request URL: the ETag GitHub answered, the raw JSON
+ *  body it covered, and whether that page advertised a rel="next" successor.
+ *  Module-level default so every makeTracker() in the process (board probe,
+ *  tick, preview) shares it; keyed by exact URL, so repos, labels and page
+ *  numbers never collide. */
+export type RestListCache = Map<string, { etag: string; body: string; hasNext: boolean }>;
+const sharedRestListCache: RestListCache = new Map();
+
+/**
+ * Split a `gh api -i` answer into status, etag, rel="next" presence, body.
+ *
+ * `gh api -i` prints the status line and response headers, a blank line, then
+ * the body. A page's ETag is its identity for conditional revalidation, and
+ * the `Link` header is the only place the adapter can learn a successor page
+ * exists without parsing the body. Throws on a payload that is not an HTTP
+ * response at all — the caller must not guess what an unrecognisable answer
+ * means.
+ */
+export function splitApiInclude(raw: string): {
+  status: number;
+  etag?: string;
+  hasNext: boolean;
+  body: string;
+} {
+  const blank = /\r?\n\r?\n/.exec(raw);
+  const headerBlock = blank === null ? raw : raw.slice(0, blank.index);
+  const body = blank === null ? "" : raw.slice(blank.index + blank[0].length);
+  const [statusLine = ""] = headerBlock.split(/\r?\n/);
+  const statusMatch = /^HTTP\/[\d.]+ (\d{3})/.exec(statusLine);
+  if (statusMatch === null) {
+    throw new Error("unrecognised gh api -i response");
+  }
+  let etag: string | undefined;
+  let hasNext = false;
+  for (const line of headerBlock.split(/\r?\n/)) {
+    const colon = line.indexOf(":");
+    if (colon <= 0) continue;
+    const name = line.slice(0, colon).trim().toLowerCase();
+    const value = line.slice(colon + 1).trim();
+    if (name === "etag") etag = value;
+    else if (name === "link" && /rel="next"/.test(value)) hasNext = true;
+  }
+  return { status: Number(statusMatch[1]), etag, hasNext, body };
+}
+
+/**
+ * GET a REST list path page by page, revalidating each known page with
+ * If-None-Match. A 304 reuses that page's cached body and costs no primary
+ * rate-limit budget; a changed page answers 200 and replaces its cache entry.
+ * Every known page is requested on every pass, so a change on page N is
+ * detected even when earlier pages are unchanged. Follows rel="next" with no
+ * page cap when `paginate`; entries past the final page are pruned. Returns
+ * one raw JSON-array body per page.
+ */
+async function conditionalListPages(
+  runGh: typeof gh,
+  cache: RestListCache,
+  path: string,
+  paginate: boolean,
+  onNotModified?: () => void,
+): Promise<string[]> {
+  const bodies: string[] = [];
+  let n = 1;
+  for (;;) {
+    const url = n === 1 ? path : `${path}&page=${n}`;
+    const cached = cache.get(url);
+    const argv = ["api", "-i", ...(cached ? ["-H", `If-None-Match: ${cached.etag}`] : []), url];
+    let raw: string;
+    try {
+      raw = await runGh(argv);
+    } catch (err) {
+      if (!(err instanceof GhError) || !/^HTTP\/[\d.]+ 304\b/.test(err.stdout)) throw err;
+      // A 304 is gh's documented answer for an unchanged conditional request:
+      // exit 1, with the status line still on stdout. `cached` must exist —
+      // we only send If-None-Match when we hold an etag — so rethrow if not,
+      // fail-loud, never serve a page we did not cache.
+      if (cached === undefined) throw err;
+      bodies.push(cached.body);
+      onNotModified?.();
+      if (!paginate || !cached.hasNext) break;
+      n += 1;
+      continue;
+    }
+    const r = splitApiInclude(raw);
+    if (r.status === 304) {
+      // A future `gh` that exits 0 on a 304 would land here instead of the
+      // catch above; both arms answer identically. The cache entry keeps its
+      // stored etag — the 304's echo comes back strong-form, while the stored
+      // weak form keeps matching.
+      if (cached === undefined) {
+        throw new Error("a 304 answered a page never sent If-None-Match for");
+      }
+      bodies.push(cached.body);
+      onNotModified?.();
+      if (!paginate || !cached.hasNext) break;
+      n += 1;
+      continue;
+    }
+    if (r.etag !== undefined) cache.set(url, { etag: r.etag, body: r.body, hasNext: r.hasNext });
+    else cache.delete(url);
+    bodies.push(r.body);
+    if (!paginate || !r.hasNext) break;
+    n += 1;
+  }
+  // The list shrank: without this a later pass would revalidate pages that no
+  // longer exist. `n` is the last page fetched; prune every successor key.
+  for (let k = n + 1; cache.has(`${path}&page=${k}`); k += 1) {
+    cache.delete(`${path}&page=${k}`);
+  }
+  return bodies;
+}
+
 /** 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. */
@@ -635,8 +758,115 @@ export async function fetchRateLimit(
   }
 }
 
-export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
+/**
+ * True when a `gh` failure is GitHub refusing us at the rate-limit layer.
+ *
+ * Three distinct bodies arrive through the CLI and all mean "stop sending":
+ * the primary budget exhausted (`API rate limit exceeded`, or the 403 the REST
+ * layer reports as `HTTP 403 ... rate limit`), the secondary budget
+ * (`secondary rate limit`), and an abuse-control trip (`abuse detection`).
+ * gh's stderr carries none of the header values (`Retry-After`, `reset`) that
+ * would drive a precise backoff, so the cooldown is the tracker's fixed window
+ * below rather than a header-driven one.
+ */
+export function isRateLimitRefusal(err: unknown): boolean {
+  return (
+    err instanceof GhError &&
+    /API rate limit exceeded|secondary rate limit|abuse detection|HTTP 403.*rate limit/i.test(
+      err.stderr,
+    )
+  );
+}
+
+/**
+ * A rate-limit refusal rethrown by {@link makeTracker}. This is the one
+ * failure class the tracker names instead of swallowing: the circuit breaker
+ * throws it without spawning `gh`, and it is what a caller can distinguish
+ * from an ordinary transport fault.
+ */
+export class GhRateLimitError extends GhError {
+  /** Wall-clock millis after which a call may be attempted again. */
+  readonly retryAtMs: number;
+
+  constructor(argv: string[], code: number, stderr: string, retryAtMs: number, stdout = "") {
+    super(argv, code, stderr, stdout);
+    this.name = "GhRateLimitError";
+    this.retryAtMs = retryAtMs;
+    this.message = `${this.message} — GitHub rate limit; retry at ${new Date(retryAtMs).toISOString()}`;
+  }
+}
+
+/** How long a rate-limit refusal holds the circuit breaker open. */
+export const RATE_LIMIT_COOLDOWN_MS = 60_000;
+
+/** Instrumentation hooks the daemon binds the tracker to (#198). */
+export interface TrackerHooks {
+  /** Fired immediately before each `gh` spawn, so the daemon can count its own
+   *  API spend. Not fired for a breaker fast-fail, which spawns nothing. */
+  onCall?: () => void;
+  /** Fired once per observed refusal, with the wall-clock moment. */
+  onRefusal?: (at: number) => void;
+  /** Fired once per list page GitHub answered 304 for — a spawn that cost no
+   *  primary-rate-limit budget. Lets the daemon's call counter tell billed
+   *  reads from free revalidations (#203 on top of #198's counting). */
+  onNotModified?: () => void;
+}
+
+interface TrackerOpts {
+  /** Override {@link RATE_LIMIT_COOLDOWN_MS} (tests use a 0ms window). */
+  rateLimitCooldownMs?: number;
+  /** Conditional-request cache for REST list reads; defaults to the shared
+   *  module-level cache. Tests pass a fresh Map. */
+  listCache?: RestListCache;
+}
+
+export function makeTracker(
+  p: ProjectConfig,
+  injectedRunGh: typeof gh = gh,
+  hooks: TrackerHooks = {},
+  opts: TrackerOpts = {},
+): Tracker {
   const repo = p.tracker.repo;
+  const refuseForMs = opts.rateLimitCooldownMs ?? RATE_LIMIT_COOLDOWN_MS;
+  const cache = opts.listCache ?? sharedRestListCache;
+
+  // The single funnel around the injected `gh`. A caught refusal records the
+  // user-observed moment, opens the 60s breaker and rethrows named; while the
+  // breaker is open every call fails fast WITHOUT spawning gh — a burst under a
+  // persistent limit degrades the tick into holds (`open-pr-lookup-error` /
+  // `parent-lookup-error` fail closed per candidate and retry next tick)
+  // instead of an error storm or a stalled loop. No in-wrapper sleeps.
+  let refusedUntil = 0;
+  const runGh = async (argv: string[], stdin?: string): Promise<string> => {
+    const now = Date.now();
+    if (now < refusedUntil) {
+      throw new GhRateLimitError(
+        argv,
+        0,
+        "circuit breaker open (a prior GitHub rate-limit refusal holds the cooldown)",
+        refusedUntil,
+      );
+    }
+    hooks.onCall?.();
+    try {
+      return await injectedRunGh(argv, stdin);
+    } catch (err) {
+      if (isRateLimitRefusal(err)) {
+        const at = Date.now();
+        refusedUntil = at + refuseForMs;
+        hooks.onRefusal?.(at);
+        const cause = err instanceof GhError ? err : undefined;
+        throw new GhRateLimitError(
+          argv,
+          cause?.code ?? 1,
+          cause?.stderr ?? String(err),
+          refusedUntil,
+          cause?.stdout ?? "",
+        );
+      }
+      throw err;
+    }
+  };
 
   // Named rather than returned inline, so `rerunFailedChecks` can reuse
   // `checkConclusions` instead of re-implementing the same `gh` call.
@@ -644,18 +874,33 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): 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([
-        "api",
+      // Paginated rather than one page of 100 — now that an idle revalidation
+      // costs an unconditional-200's worth of nothing, truncating a deep queue
+      // to save calls saves nothing that matters; the cap was the call count,
+      // and the conditional path changed what a call costs.
+      const pages = await conditionalListPages(
+        runGh,
+        cache,
         `repos/${repo}/issues?state=open&labels=${encodeURIComponent(p.queueLabel)}&per_page=100`,
-      ]);
+        /* paginate */ true,
+        hooks.onNotModified,
+      );
 
       // 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);
+      return pages.flatMap(readyIssuesFromRest);
+    },
+
+    async listOpenIssues(): Promise<ReadyIssue[]> {
+      const pages = await conditionalListPages(
+        runGh,
+        cache,
+        `repos/${repo}/issues?state=open&per_page=100`,
+        /* paginate */ true,
+        hooks.onNotModified,
+      );
+      return pages.flatMap(readyIssuesFromRest);
     },
 
     async addLabel(issue: number, label: string): Promise<void> {
@@ -902,16 +1147,19 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
 
     async listLabeled(label: string, limit = 50): Promise<{ number: number; state: IssueState }[]> {
       try {
-        return labeledIssuesFrom(
-          await runGh([
-            "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}]",
-          ]),
+        // One page, deliberately: `limit` is the caller's work bound
+        // (RECONCILE_LIMIT), not a queue-depth cap, and the reconcile only
+        // ever acts on the page it reads. The conditional cache still makes a
+        // steady-state pass cost nothing even though the response is big.
+        const pages = await conditionalListPages(
+          runGh,
+          cache,
+          `repos/${repo}/issues?state=all&labels=${encodeURIComponent(label)}&per_page=${limit}`,
+          /* paginate */ false,
+          hooks.onNotModified,
         );
+        // paginate: false means exactly one body, always a JSON array.
+        return labeledIssuesFrom(pages[0] ?? "");
       } catch {
         // A reconcile that cannot list must remove no labels: an empty answer is
         // read as "no evidence", never as "nothing carries this label".

package/src/types.ts

@@ -694,6 +694,14 @@ export interface OpenCloser {
  */
 export interface Tracker {
   listReady(): Promise<ReadyIssue[]>;
+  /**
+   * Every open issue in the tracker repo (never PRs), labels included: one
+   * read that covers all lifecycle-label queries of a pass, so consumers
+   * needing several label sets pay one fetch instead of one per label, and
+   * openness itself is answerable without a per-issue lookup (#203).
+   * Complete — follows pagination to the end.
+   */
+  listOpenIssues(): Promise<ReadyIssue[]>;
   addLabel(issue: number, label: string): Promise<void>;
   removeLabel(issue: number, label: string): Promise<void>;
   comment(issue: number, body: string): Promise<void>;
@@ -911,6 +919,11 @@ 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. */
+  report?: string;
   /**
    * Why this run ended badly, and what the daemon did about it (#132). Absent
    * means the sweep has not looked at the row yet — never "nothing was wrong":
@@ -1143,10 +1156,28 @@ export interface DecisionDraft {
   at: number;
 }
 
+/** One decided GitHub label change waiting to be projected (#201). */
+export interface LabelOp {
+  id: number;
+  project: string;
+  issue: number;
+  op: "add" | "remove";
+  label: string;
+  createdAt: number;
+  attempts: number;
+  nextAttemptAt: number;
+  lastError?: string;
+}
+
 /**
- * Bookkeeping only — GitHub labels remain the source of truth. The store
- * exists to answer cap questions cheaply and to survive a restart; if it is
- * ever lost, the tracker can rebuild the world.
+ * Dispatch state is store-authoritative; GitHub labels are a retried
+ * write-behind projection of it (#201). `isEligible` still consults the label
+ * set a candidate *effectively* carries — physical labels overlaid with the
+ * outbox's pending ops — so a label GitHub refuses to move cannot strand an
+ * issue the daemon has already decided to move on. A store loss no longer
+ * rebuilds the world: it also forgets what labels the tracker was told to
+ * carry, so the operator reconciles by hand, which is the only safe move once
+ * the two disagree.
  */
 export interface Store {
   createRun(r: Omit<RunRecord, "id">): RunRecord;
@@ -1179,6 +1210,11 @@ 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 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;
   /** Idempotence guard so a retry loop cannot page a human repeatedly for the
@@ -1198,6 +1234,15 @@ export interface Store {
   /** Start the cooldown only after a tick carrying these signals was sent. */
   markFrictionSurfaced(project: string, kinds: readonly FrictionKind[], at: number): void;
   markNotified(key: string): void;
+  /** Record one observed GitHub rate-limit refusal (the tracker's hook). Rows
+   *  older than 24h are pruned in the same write (#198). */
+  recordGhRefusal?(at: number): void;
+  /** Refusals observed at or after `sinceMs` — `status` reads the last 5m. */
+  ghRefusalsSince?(sinceMs: number): { count: number; latestAt?: number };
+  /** Count one daemon-held `gh` call for the UTC day (`YYYY-MM-DD`). */
+  bumpGhCalls?(day: string, source: string): void;
+  /** The tracked call counts for a UTC day, per source. */
+  ghCallsToday?(day: string): { source: string; calls: number }[];
   /**
    * Persist a rendered report `pending`, before anything is sent — the whole
    * point of #123 is that an undelivered report is a queryable row rather than
@@ -1292,6 +1337,33 @@ export interface Store {
   releaseMergeLock(project: string, holder: string): void;
   /** The live lock, for `status` and for tests. */
   mergeLock(project: string): MergeLock | undefined;
+  /**
+   * Append decided GitHub label changes to the projection outbox (#201). One
+   * transaction: either every op lands as a pending row or none do, so the
+   * daemon's record of its own intent cannot disagree with itself. Ops for one
+   * issue apply in enqueue (id) order, which is what makes a swap atomic — the
+   * remove lands before the add exactly as enqueued.
+   */
+  enqueueLabelOps(
+    project: string,
+    ops: readonly { issue: number; op: "add" | "remove"; label: string }[],
+  ): void;
+  /** Unapplied ops whose retry backoff has elapsed, oldest first (#201). */
+  pendingLabelOps(project: string, now: number): LabelOp[];
+  /** Every unapplied op for one issue, enqueue order — the eligibility overlay
+   *  reads this so a stale GitHub label cannot outlive the daemon's intent
+   *  (#201). */
+  pendingLabelOpsFor(project: string, issue: number): LabelOp[];
+  /** The op applied; forget it. */
+  settleLabelOp(id: number): void;
+  /** The op failed; count the attempt and park it behind `nextAttemptAt`. Pass
+   *  `countAttempt: false` for a refusal that is not the op's fault (a shared
+   *  rate limit), so it does not burn the backoff escalation (#208). */
+  deferLabelOp(id: number, error: string, nextAttemptAt: number, countAttempt?: boolean): void;
+  /** Unapplied ops still owed — `status` shows the projection lag (#201). */
+  countPendingLabelOps(project: string): number;
+  /** `createdAt` of the oldest unapplied op, or `undefined` for none. */
+  oldestPendingLabelOpAt(project: string): number | undefined;
   close(): void;
 }
 

package/src/unblock.ts

@@ -20,16 +20,22 @@
  * 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
+ * Nothing here writes to the run history, and that is a decision rather than
+ * an omission. `RunState` describes what a worker process did; an answer is the
  * one event that happens outside every run, so no member fits it — folding it
  * into `merged` or `killed` would make `status` describe a run that never
- * reached either. Eligibility is read off the tracker's labels and never off a
- * run row, so the store has nothing to say here. Leaving history alone keeps
- * both budgets honest: a block consumes an operational continuation, while a
- * real implementation failure consumes the separate failed-attempt budget.
+ * reached either. The one store write is the label projection outbox (#201):
+ * a decided label change is durable locally and projected with retry, so a 403
+ * defers it instead of throwing the verb, and the daemon's next tick applies it
+ * even if this process dies before it does. Eligibility is read off the label
+ * set an issue effectively carries — physical labels overlaid with that outbox —
+ * and never off a run row, so the store has nothing else to say here. Leaving
+ * history alone keeps both budgets honest: a block consumes an operational
+ * continuation, while a real implementation failure consumes the separate
+ * failed-attempt budget.
  */
 
+import { projectLabels } from "./label-projection.ts";
 import { LIVE_STATES } from "./store.ts";
 import type { Caps, ProjectConfig, RunRecord, Store, Tracker } from "./types.ts";
 
@@ -65,6 +71,14 @@ export interface UnblockOutcome {
   requeued?: 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
+   *  the label sync is owed rather than done: the intended label state is
+   *  durable in the store and the daemon retries it (#201). Safety is
+   *  preserved either way, but the issue is only claimable once the queue
+   *  label itself has landed — `listReady` reads the tracker by label, so a
+   *  queue-label add that has not been applied is invisible to dispatch. The
+   *  number is what is still pending. */
+  labelSyncQueued?: number;
 }
 
 /**
@@ -150,12 +164,13 @@ export async function unblockIssue(
   if (held !== undefined) store.updateRun(held.id, { salvageAckAt: Date.now() });
 
   const cleared: string[] = [];
+  const ops: { issue: number; op: "add" | "remove"; label: string }[] = [];
   for (const label of new Set([
     project.stateLabels.blocked,
     project.stateLabels.failed,
     ...(terminal ? [project.stateLabels.inProgress] : []),
   ])) {
-    await tracker.removeLabel(issue, label);
+    ops.push({ issue, op: "remove", label });
     cleared.push(label);
   }
 
@@ -173,15 +188,33 @@ export async function unblockIssue(
   // the PR resolves closed-unmerged.
   let requeued: true | undefined;
   let requeueSkipped: true | undefined;
+  let labelSyncQueued: number | undefined;
   if (!live) {
     if (requeue) {
-      await tracker.addLabel(issue, project.queueLabel);
+      ops.push({ issue, op: "add", label: project.queueLabel });
       requeued = true;
     } else {
       requeueSkipped = true;
     }
   }
 
+  // Apply through the same projector the daemon drains (#201): the clears and
+  // the queue restore land in enqueue order, and a tracker that refuses (403,
+  // rate limit) defers them with backoff instead of throwing the verb — which
+  // is the concrete #184/#198 kill: `unblock` stops breaking on a 403. The
+  // intended label state is durable; the daemon converges the tracker. The
+  // issue only becomes claimable once the queue label itself lands —
+  // `listReady` queries by label, so a pending queue-label add is invisible to
+  // dispatch until projection succeeds.
+  if (ops.length > 0) {
+    store.enqueueLabelOps(project.name, ops);
+    await projectLabels(store, tracker, project);
+    // How much of THIS issue's sync is still owed (not the whole fleet's outbox):
+    // a backlog on other issues is not this verb's lag to report.
+    const stillPending = store.pendingLabelOpsFor(project.name, issue).length;
+    if (stillPending > 0) labelSyncQueued = stillPending;
+  }
+
   return {
     cleared,
     ...counts,
@@ -190,6 +223,7 @@ export async function unblockIssue(
     ...(held === undefined ? {} : { forced: true as const }),
     ...(requeued === undefined ? {} : { requeued }),
     ...(requeueSkipped === undefined ? {} : { requeueSkipped }),
+    ...(labelSyncQueued === undefined ? {} : { labelSyncQueued }),
   };
 }
 
@@ -228,6 +262,15 @@ export function formatUnblock(
   }
 
   const lines = [`#${issue}: cleared ${o.cleared.join(", ")}`];
+  // When the tracker refused the sync, NO label is provably applied — the
+  // "restored / eligible again" claims below would be a lie, so they branch to
+  // the queued/retry wording instead (#201).
+  const labelsPending = o.labelSyncQueued !== undefined;
+  if (o.labelSyncQueued !== undefined) {
+    lines.push(
+      `  label sync queued (${o.labelSyncQueued} pending) — the daemon retries; the intended labels are durable, and the issue is claimable once they land`,
+    );
+  }
   if (o.forced === true) {
     lines.push(
       `  forced     the unsalvaged worktree was accepted as lost or already recovered by hand — ` +
@@ -277,11 +320,13 @@ export function formatUnblock(
     // instead of promising a re-claim the next tick withholds.
     lines.push(
       latest.prUrl === undefined
-        ? 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)`
+        ? labelsPending
+          ? `  next tick  label sync queued (${o.labelSyncQueued} pending) — the daemon retries; eligibility is recorded in the store, not yet on the tracker`
+          : 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",
     );
@@ -305,17 +350,23 @@ export function formatUnblock(
         `  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) {
+      if (labelsPending) {
+        lines.push(
+          `  queue      label sync queued (${o.labelSyncQueued} pending) — the daemon retries; the intended labels are durable, and the issue is claimable once they land`,
+        );
+      } else if (o.requeued === true) {
         lines.push(`  queue      "${project.queueLabel}" restored (no-op if it was already present)`);
       }
     }
   } else {
     lines.push(
-      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)",
+      labelsPending
+        ? `  next tick  label sync queued (${o.labelSyncQueued} pending) — the daemon retries; the intended labels are durable, and the issue is claimable once they land`
+        : 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)",
     );
   }