omp-conductor 0.3.22 → 0.3.24

package/src/unblock.ts

@@ -43,19 +43,38 @@ export interface UnblockOutcome {
 }
 
 /**
- * Drop both terminal state labels, whichever the issue is actually carrying.
+ * Drop the state labels the issue could be carrying, as far as the store can
+ * prove they are droppable.
  *
- * Both unconditionally, because the tracker is the only source of truth for
- * which one is set and this process cannot read that back through the Tracker
- * port — inferring it from the newest run row would be a guess that goes wrong
- * exactly when a human has relabelled something by hand. Removing a label an
- * issue does not carry is a no-op: `gh issue edit --remove-label` exits 0 on an
- * absent label (verified against gh 2.97.0), and the adapter swallows the 404
- * older paths return for one.
+ * The two terminal labels come off unconditionally, because the tracker is the
+ * only source of truth for which one is set and this process cannot read that
+ * back through the Tracker port — inferring it from the newest run row would be
+ * a guess that goes wrong exactly when a human has relabelled something by
+ * hand. Removing a label an issue does not carry is a no-op: `gh issue edit
+ * --remove-label` exits 0 on an absent label (verified against gh 2.97.0), and
+ * the adapter swallows the 404 older paths return for one.
  *
- * `agent:in-progress` is deliberately not in the set. It means a worker process
- * exists, which is not something an operator can answer away, and clearing it
- * from under a live run is how two workers end up on one issue.
+ * `agent:in-progress` comes off only when the newest run row is terminal, and
+ * that condition is the whole safety argument. The label means a worker process
+ * exists, and clearing it from under a live run is how two workers end up on
+ * one issue, so it used to be excluded outright. What that cost showed up on
+ * 2026-08-09: veltro#331's newest row had already settled to `failed` (its PR
+ * #332 was closed unmerged), `unblock 331` reported `cleared agent:blocked,
+ * agent:failed` and `next tick eligible again`, and an immediate authoritative
+ * `gh issue view 331` still showed `agent:in-progress` — the one label that
+ * actually decides eligibility, with no verb anywhere able to remove it (#18).
+ * A terminal newest row is proof the process is gone rather than an opinion
+ * about it: it is written when the worker exits, by `reconcileOrphanedRuns` at
+ * startup for a worker that died with its daemon, or by settlement once the PR
+ * resolved. Once it is there, the interlock has nothing left to guard.
+ *
+ * No run row at all is deliberately *not* that proof, so that case still leaves
+ * the label alone. A missing row means the store never saw the run, which is
+ * indistinguishable from here to a claim that raced a store write — and being
+ * wrong in that direction is the two-workers bug, where being wrong in the
+ * other direction is a stuck issue an operator is already looking at. On the
+ * paths the daemon does own it releases the label itself, next to the store
+ * transition that proves the run ended (`releaseInProgress` in `daemon.ts`).
  */
 export async function unblockIssue(
   project: ProjectConfig,
@@ -63,13 +82,21 @@ export async function unblockIssue(
   store: Store,
   issue: number,
 ): Promise<UnblockOutcome> {
+  // 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);
+
   const cleared: string[] = [];
-  for (const label of new Set([project.stateLabels.blocked, project.stateLabels.failed])) {
+  for (const label of new Set([
+    project.stateLabels.blocked,
+    project.stateLabels.failed,
+    ...(terminal ? [project.stateLabels.inProgress] : []),
+  ])) {
     await tracker.removeLabel(issue, label);
     cleared.push(label);
   }
 
-  const latest = store.latestRun(project.name, issue);
   return {
     cleared,
     attemptsUsed: store.attemptsFor(project.name, issue),
@@ -81,9 +108,14 @@ export async function unblockIssue(
 
 /**
  * What the operator reads back. It promises a re-claim only when one can
- * actually happen: a live run still owns the issue through `agent:in-progress`,
- * and a spent attempt budget makes the next tick escalate rather than dispatch.
- * Either promised blindly would send someone away believing work had resumed.
+ * 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
+ * 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.
  */
 export function formatUnblock(
   issue: number,
@@ -95,7 +127,7 @@ export function formatUnblock(
   const lines = [`#${issue}: cleared ${o.cleared.join(", ")}`];
 
   if (latest === undefined) {
-    lines.push("  runs       none recorded — the labels were cleared anyway; eligibility is read off the tracker");
+    lines.push("  runs       none recorded — the terminal labels were cleared anyway; eligibility is read off the tracker");
   } else {
     lines.push(`  runs       ${o.attemptsUsed}, newest ${latest.state}`);
     lines.push(`  failures   ${o.failuresUsed} of ${caps.maxAttemptsPerIssue}`);
@@ -117,6 +149,12 @@ export function formatUnblock(
       `  next tick  not eligible: the ${caps.maxContinuationsPerIssue}-continuation budget was exceeded. ` +
         "Inspect progress or raise maxContinuationsPerIssue.",
     );
+  } else if (latest === undefined) {
+    lines.push(
+      `  next tick  eligible once the issue carries "${project.queueLabel}" and no state label — with no ` +
+        `run row to prove the worker is gone, "${project.stateLabels.inProgress}" was left in place, and ` +
+        "on its own it keeps the issue ineligible",
+    );
   } else {
     lines.push(`  next tick  eligible again, as long as the issue still carries "${project.queueLabel}"`);
   }