omp-conductor 0.3.21 → 0.3.23

package/src/daemon.ts

@@ -28,6 +28,7 @@ import type {
   Caps,
   DispatchSummary,
   Escalation,
+  OpenCloser,
   PrState,
   ProjectConfig,
   ReadyIssue,
@@ -879,6 +880,42 @@ export function settlementFor(pr: PrState | undefined, prUrl: string): Settlemen
   return undefined;
 }
 
+/**
+ * Drops the in-progress label from an issue whose run is provably over.
+ *
+ * Settlement used to write only half of what it knew. On 2026-08-09 that cost
+ * the reference fleet two issues in one night: veltro#331 settled to `failed`
+ * at 23:53Z once the orchestrator closed veltro#332 unmerged, and veltro#344
+ * settled to `merged` at 05:54Z once chad#452 squash-merged. Both rows left the
+ * active set correctly; an authoritative `gh issue view` on each afterwards
+ * still showed `agent:in-progress`. `routing.isEligible` rejects any issue
+ * carrying a state label, the composed brief forbids the orchestrator from
+ * hand-editing one, and `unblock` refused to clear that particular label — so
+ * both issues were permanently unclaimable with no supported way back (#18).
+ *
+ * Never throws, and that is the point of it being a function rather than a
+ * bare `removeLabel`. Callers are sweeps: the store transition this accompanies
+ * has already been written, so a tracker that fails here must cost one label,
+ * not the remaining rows. There is no retry — the row is terminal, so no later
+ * tick revisits it — which makes the log line the entire record of the miss and
+ * why it names both the label and the reason. The operator's recovery for that
+ * rare case is `omp-conductor unblock`, which clears the label itself once the
+ * newest run is terminal.
+ */
+export async function releaseInProgress(
+  d: Pick<Deps, "project" | "tracker">,
+  issue: number,
+  why: string,
+): Promise<void> {
+  const label = d.project.stateLabels.inProgress;
+  try {
+    await d.tracker.removeLabel(issue, label);
+    log(`#${issue} released ${label}: ${why}`);
+  } catch (err) {
+    log(`#${issue} could not release ${label} (${errText(err)}) — ${why}; clear it with \`unblock\``);
+  }
+}
+
 /**
  * Asks the tracker about every `pushed-green` PR and settles the ones that
  * resolved.
@@ -889,11 +926,26 @@ export function settlementFor(pr: PrState | undefined, prUrl: string): Settlemen
  * and not the mapping: that a row without a PR costs no API call, and that one
  * unreachable PR does not stop the others from settling.
  *
- * Tracker labels are deliberately not touched, exactly as
- * {@link reconcileOrphanedRuns} does not touch them. A merge normally closes the
- * issue, and a human who closed a PR is already looking at it; deciding what an
- * issue's labels should say next is the orchestrator's drain duty, which reads
- * these very rows through `omp-conductor status`.
+ * The label is released too, which reverses what this function first promised.
+ * It used to leave tracker labels alone exactly as {@link reconcileOrphanedRuns}
+ * does, reasoning that a merge closes the issue anyway and that deciding what an
+ * issue's labels should say next is the orchestrator's drain duty. There turned
+ * out to be no such path: on 2026-08-09 two settled rows left their issues
+ * carrying `agent:in-progress` forever, with the brief forbidding the
+ * orchestrator from touching it and `unblock` declining to (see
+ * {@link releaseInProgress}). The row transition and the label are one fact, and
+ * writing half of it is the whole of that bug.
+ *
+ * Releasing it is safe here specifically because of what these rows are. A
+ * `pushed-green` or `pushed-pending` row has no process behind it — its worker
+ * exited and its worktree is gone — so a terminal answer about its PR proves no
+ * worker owns the issue, and the duplicate-dispatch interlock the label exists
+ * for is spent. {@link reconcileOrphanedRuns} still leaves labels alone for the
+ * opposite reason: an orphaned `running` row is work nobody has read yet. And
+ * the brief's rule stays absolute, because this is a daemon-owned write through
+ * the same Tracker port the dispatcher claimed the issue with — orphan detection
+ * is only trustworthy while every state label on the tracker came from this
+ * package.
  */
 export async function settlePushedGreen(
   d: Pick<Deps, "project" | "tracker" | "store">,
@@ -930,6 +982,10 @@ export async function settlePushedGreen(
       if (settlement.state === "failed") patch.lastError = settlement.reason;
       store.updateRun(run.id, patch);
       log(`#${run.issue} settled: ${settlement.reason}`);
+      // Store and tracker in the same breath, for the reason above: the row is
+      // terminal, so the label's interlock is spent. `releaseInProgress` never
+      // throws, so a tracker hiccup costs this label and not the later rows.
+      await releaseInProgress(d, run.issue, settlement.reason);
       continue;
     }
 
@@ -948,6 +1004,11 @@ export async function settlePushedGreen(
     } else if (verification.status === "failed") {
       store.updateRun(run.id, { state: "failed", lastError: verification.reason });
       log(`#${run.issue} checks failed: ${verification.reason}`);
+      // Equally terminal: a red check on a pushed row ends the attempt, so the
+      // same release applies. The green branch above deliberately does not —
+      // that row is still awaiting a merge, and its live PR is exactly the work
+      // the label must keep guarding.
+      await releaseInProgress(d, run.issue, verification.reason);
     } else {
       store.updateRun(run.id, { lastError: verification.reason });
     }
@@ -1224,7 +1285,7 @@ export async function admitCandidates(
     // tracker is the only party that remembers, so it is asked. The cost is
     // bounded by free slots, not by queue depth: the call sits behind the two
     // cheap local filters and candidates beyond capacity skip it.
-    let closer: string | undefined;
+    let closer: OpenCloser | undefined;
     try {
       closer = await tracker.openCloserFor(issue);
     } catch (err) {
@@ -1241,18 +1302,43 @@ export async function admitCandidates(
     }
     if (closer !== undefined) {
       const latest = store.latestRun(project.name, issue);
-      const retainedContinuation =
-        latest?.prUrl === closer &&
-        (latest.state === "blocked" ||
-          latest.state === "failed" ||
-          latest.state === "killed" ||
-          latest.state === "orphaned");
-      if (!retainedContinuation) {
+      // Terminality is the first half of the test and is not negotiable: while a
+      // run is live its worker is still pushing to that branch, and a second
+      // worker sent at the same PR is exactly the duplicate-work failure this
+      // guard exists to kill. Only a run that has stopped can be continued.
+      const retained =
+        latest?.state === "blocked" ||
+        latest?.state === "failed" ||
+        latest?.state === "killed" ||
+        latest?.state === "orphaned"
+          ? latest
+          : undefined;
+      // The second half asks "is this open PR our retained work", and accepts
+      // two identities for it, because the branch is the durable artefact of a
+      // retained run and the PR is not. A cap kill can end a run before any PR
+      // exists: veltro#324 attempt 1 was killed at the turns cap on
+      // 2026-08-09T00:47Z before its worker opened one, so the row kept `branch`
+      // and `prUrl` stayed NULL. chad#438 was opened from that exact branch
+      // afterwards, and URL equality — the only test 0.3.20 had — can never match
+      // a URL the terminal run never recorded, so every tick held #324 as
+      // `open-pr` until an operator closed recoverable work to free the branch
+      // (#50). An ordinary issue whose open PR is unrelated still fails both
+      // identities and stays ineligible, and an empty `headRefName` (a reply that
+      // did not carry the field) is never a match: unknown is not identity.
+      let resume: string | undefined;
+      if (retained !== undefined) {
+        if (retained.prUrl === closer.url) {
+          resume = `from ${retained.state} run (matched recorded PR URL)`;
+        } else if (closer.headRefName !== "" && retained.branch === closer.headRefName) {
+          resume = `from ${retained.state} run (matched retained branch ${closer.headRefName})`;
+        }
+      }
+      if (resume === undefined) {
         hold(issue, "open-pr");
-        log(`#${issue} skipped: open PR ${closer} already closes it`);
+        log(`#${issue} skipped: open PR ${closer.url} already closes it`);
         continue;
       }
-      log(`#${issue} continuing retained PR ${closer} from ${latest.state} run`);
+      log(`#${issue} continuing retained PR ${closer.url} ${resume}`);
     }
 
     admitted.push({ r, attempt: priorRuns + 1 });

package/src/fleet.ts

@@ -1081,6 +1081,64 @@ function readPairedChannel(path: string): Channel {
   return { kind: "up", owner: String(owner) };
 }
 
+/**
+ * Whether the *approval* half of the Telegram surface works, which is a
+ * different question from whether inbound works and was never asked before.
+ *
+ * `telegram_ask` is mounted by omp-telegram's `before_agent_start` handler only
+ * for a turn whose prompt resolves a notify target. A Telegram-originated turn
+ * resolves one from its own `<telegram-message>` wrapper; a locally injected
+ * orchestrator tick has no wrapper, so it resolves one only through
+ * `notifyTarget()` — which needs `notifyMode` set to "away" or "always" *and* a
+ * destination, this session's forum topic under `topicsChat` or the flat
+ * `notifyChat`. With neither, the tool is simply absent from the tick.
+ *
+ * That is exactly what happened on 2026-08-09 06:17Z: the fleet's access.json
+ * had no `notifyMode`, so the locally injected tick could not ask the
+ * Learning-loop yes/no question the package floor requires — while this very
+ * status line reported `telegram  ok  (@tbcoder_bot; inbound configured)`
+ * throughout (#114). A health row that stays green through a broken contract is
+ * worse than no row, so the approval surface is now part of it.
+ *
+ * The legacy `away: true` boolean counts: `loadAccess()` migrates it to
+ * `notifyMode: "away"` on read, so a fleet still carrying it resolves a target
+ * and must not be reported as broken.
+ */
+type ApprovalSurface = { kind: "ready" } | { kind: "missing"; reason: string };
+
+function readApprovalSurface(path: string): ApprovalSurface {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { kind: "missing", reason: `telegram_ask unavailable on local ticks: cannot read ${path}` };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { kind: "missing", reason: `telegram_ask unavailable on local ticks: ${path} is not an object` };
+  }
+  const access = parsed as { readonly [key: string]: unknown };
+  const mode = access["notifyMode"];
+  const active = mode === "away" || mode === "always" || access["away"] === true;
+  if (!active) {
+    return {
+      kind: "missing",
+      reason:
+        `telegram_ask unavailable on local ticks: no notifyMode in ${path} — ` +
+        `set it to "always" and give it a destination (notifyChat, or topicsChat for a forum)`,
+    };
+  }
+  const destination = access["notifyChat"] ?? access["topicsChat"];
+  if (typeof destination !== "string" || destination.length === 0) {
+    return {
+      kind: "missing",
+      reason:
+        `telegram_ask unavailable on local ticks: notifyMode is set but ${path} names no destination — ` +
+        "set notifyChat to the paired owner id (or topicsChat for a forum)",
+    };
+  }
+  return { kind: "ready" };
+}
+
 function readBotToken(): string | undefined {
   const env = process.env["TELEGRAM_BOT_TOKEN"];
   if (env !== undefined && env.length > 0) return env;
@@ -1144,8 +1202,14 @@ export async function probeTelegramHealth(
       ? (result["result"] as Record<string, unknown>)
       : undefined;
   const username = typeof user?.["username"] === "string" ? `@${user["username"]}` : "authenticated";
+  // Inbound first: a bridge that is down says nothing about the approval
+  // surface, and stacking two remedies on one row buries the one to act on.
   if (channel.kind === "down") return { kind: "degraded", detail: `${username}; inbound ${channel.reason}` };
-  return { kind: "ok", detail: `${username}; inbound configured` };
+  const approval = readApprovalSurface(accessPath);
+  if (approval.kind === "missing") {
+    return { kind: "degraded", detail: `${username}; inbound configured; ${approval.reason}` };
+  }
+  return { kind: "ok", detail: `${username}; inbound configured; telegram_ask available` };
 }
 
 export function sessionDirForCwd(cwd: string): string {

package/src/orchestrator-tick.ts

@@ -29,7 +29,11 @@
  * waiting for a session restart — and one delivery rule
  * ({@link TICK_DELIVERY_RULE}), because a tick is injected locally and a report
  * written as end-of-turn text on such a turn reaches nobody. An operator's own
- * `message` replaces both, and is re-read per tick for the same reason.
+ * `message` replaces both, and is re-read per tick for the same reason. One
+ * clause is not the operator's to replace: a tick composed on a surface that
+ * has no `telegram_ask` says so ({@link TICK_APPROVAL_UNAVAILABLE_RULE}),
+ * custom prompt included, because the floor's amendment approval names a tool
+ * that surface cannot call.
  *
  * The extension is inert unless `<cwd>/.conductor-tick.json` exists, so shipping
  * it inside `omp-conductor` costs an ordinary session nothing. That file is a
@@ -336,6 +340,46 @@ export const TICK_SCOPE_CONSTRAINTS: { readonly [K in ReportScope]: string } = {
 export const TICK_DELIVERY_RULE =
   "This tick was injected locally, not sent from Telegram, so your end-of-turn text does NOT reach your operator. Deliver anything reportable this turn by calling the telegram_send tool and confirming success; never claim a report was sent otherwise.";
 
+/**
+ * The tool the package floor names for the Learning-loop yes/no amendment
+ * approval (`## Learning loop`, step 2, in `briefs/orchestrator.md`).
+ *
+ * Held as a constant because two things must agree on it: the prose that tells
+ * the turn to call it, and the preflight that checks whether it is callable at
+ * all.
+ */
+export const TELEGRAM_APPROVAL_TOOL = "telegram_ask";
+
+/**
+ * Appended to every tick — the shipped prompt or the operator's own — composed
+ * on a surface where {@link TELEGRAM_APPROVAL_TOOL} is not mounted.
+ *
+ * The floor mandates a call the ordinary tick cannot make. On 2026-08-09 06:17Z
+ * a locally injected veltrosecurity tick reached the amendment step and found
+ * no `telegram_ask` at all (`read xd://telegram_ask` answered `No such tool`);
+ * the very next turn, which began as an inbound Telegram message at 06:33Z,
+ * found the same tool mounted. Availability tracks turn origin, and an
+ * amendment proposal normally arises on the locally injected half — issue #114.
+ *
+ * Fails closed in the only sense that helps a fleet: the duties still run, but
+ * the turn is told the approval primitive is missing *before* it can reach the
+ * step that needs one. The fallback named here is the one the floor already
+ * documents for a `telegram_ask` that never delivered — re-deliver with
+ * `telegram_send` — so a session has one answer to "the ask did not happen",
+ * not two. The last clause is the actual hazard #114 exposed: a turn that knows
+ * it must ask, and cannot, is one inference away from recording an approval
+ * nobody gave.
+ *
+ * Unlike {@link TICK_DELIVERY_RULE} this is appended to a configured `message`
+ * too. An operator's prompt owns the reporting contract and is theirs to get
+ * wrong; it cannot consent, on the orchestrator's behalf, to a tool being
+ * absent from the surface the turn actually runs on.
+ */
+export const TICK_APPROVAL_UNAVAILABLE_RULE =
+  `The ${TELEGRAM_APPROVAL_TOOL} tool is NOT mounted on this tick, so the package floor's yes/no amendment approval cannot be asked here. ` +
+  `If you have an amendment to propose, deliver the question with telegram_send and wait for your operator's reply on a later turn; ` +
+  `never apply an amendment, or record one as approved, without an explicit answer you actually received.`;
+
 function frictionLabel(kind: FrictionSignal["kind"]): string {
   if (kind.startsWith("admission:")) return `admission hold ${kind.slice("admission:".length)}`;
   if (kind === "feedback:escalation-should-digest") return "escalations classified as digest material";
@@ -983,6 +1027,15 @@ interface TickSession {
    * file every interval, for as long as the session lives.
    */
   scopeFallbackLogged: boolean;
+  /**
+   * Whether the missing {@link TELEGRAM_APPROVAL_TOOL} has been logged. Latched
+   * for {@link TickSession.scopeFallbackLogged}'s reason and then some: on the
+   * surface #114 reports, the tool is absent on *every* locally injected tick,
+   * so an unguarded line would be one error per interval — 144 a day at the
+   * ten-minute heartbeat this fleet runs — which is how a real fault becomes
+   * background noise.
+   */
+  approvalToolMissingLogged: boolean;
   /** Consecutive {@link PENDING_REASON} skips — see {@link STALL_MARKER_FILE}. */
   pendingSkips: number;
 }
@@ -1062,6 +1115,37 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
     }
   }
 
+  // The floor's approval primitive, checked against the live mounted set at the
+  // moment this tick is composed — not once at session start, because the
+  // mounted set is exactly what differed between two consecutive turns of the
+  // same session on 2026-08-09 (#114). Appended last, after the friction
+  // digest: the digest is what provokes an amendment, so the sentence that says
+  // the amendment cannot be approved here is the one that should read last.
+  if (!pi.getActiveTools().includes(TELEGRAM_APPROVAL_TOOL)) {
+    content = `${content}\n${TICK_APPROVAL_UNAVAILABLE_RULE}`;
+    if (!session.approvalToolMissingLogged) {
+      session.approvalToolMissingLogged = true;
+      // Error level, and once: `status` reported `telegram ok (@tbcoder_bot;
+      // inbound configured)` throughout the incident, so nothing else told the
+      // operator the approval contract was unsatisfiable. A line buried at
+      // info, beside one "tick sent" per interval, would not be found.
+      //
+      // It names the cause, not just the symptom, because the remedy is a file
+      // the operator owns: omp-telegram mounts the tool only for a turn whose
+      // prompt resolves a notify target, and a locally injected tick resolves
+      // one only through `notifyTarget()` — `notifyMode` "away" or "always",
+      // plus a destination.
+      pi.logger.error(
+        `[omp-conductor] ${TELEGRAM_APPROVAL_TOOL} is not mounted on this tick surface: omp-telegram mounts it ` +
+          "only for a turn that resolves a notify target, and a locally injected tick resolves one only when " +
+          `notifyMode is "away" or "always" with a destination (notifyChat, or topicsChat for a forum) in ` +
+          `${config.accessFile ?? "the omp-telegram access.json"} — until then ticks instruct the orchestrator ` +
+          "to deliver amendment questions with telegram_send and never to assume an answer",
+        { tool: TELEGRAM_APPROVAL_TOOL, ...(config.accessFile === undefined ? {} : { accessFile: config.accessFile }) },
+      );
+    }
+  }
+
   try {
     pi.sendMessage(
       { customType: TICK_CUSTOM_TYPE, content, display: true, attribution: "user" },
@@ -1136,10 +1220,14 @@ export default function orchestratorTickExtension(pi: TickApi): void {
   // is the line that tells an operator which session is driving the fleet.
   let decided = false;
   // Held per registration for the same reason: the "using the default reporting
-  // scope, because ..." line is logged once for this heartbeat, and the stall
-  // counter is about this session's own queue. A second session in the same
-  // process starts with both at zero.
-  const session: TickSession = { scopeFallbackLogged: false, pendingSkips: 0 };
+  // scope, because ..." line and the missing-approval-tool line are each logged
+  // once for this heartbeat, and the stall counter is about this session's own
+  // queue. A second session in the same process starts with all three at zero.
+  const session: TickSession = {
+    scopeFallbackLogged: false,
+    approvalToolMissingLogged: false,
+    pendingSkips: 0,
+  };
   let releaseGateArmed = false;
   // An activation file makes this a fleet directory before Herdr can prove
   // which pane owns it. The gate therefore starts closed and only honours an

package/src/tracker/github.ts

@@ -15,6 +15,7 @@
 
 import type {
   IssueState,
+  OpenCloser,
   PrState,
   PrVerification,
   ProjectConfig,
@@ -54,7 +55,7 @@ const CLOSERS_QUERY = `query($owner:String!,$repo:String!,$n:Int!){
   repository(owner:$owner,name:$repo){
     issue(number:$n){
       closedByPullRequestsReferences(first:10){
-        nodes{ number state isDraft url repository{ nameWithOwner } }
+        nodes{ number state isDraft url headRefName repository{ nameWithOwner } }
       }
     }
   }
@@ -73,7 +74,9 @@ interface ClosersResponse {
     repository?: {
       issue?: {
         closedByPullRequestsReferences?: {
-          nodes?: ({ state: string; isDraft: boolean; url: string } | null)[] | null;
+          nodes?:
+            | ({ state: string; isDraft: boolean; url: string; headRefName?: string } | null)[]
+            | null;
         } | null;
       } | null;
     } | null;
@@ -166,7 +169,7 @@ function isLabelNoop(err: unknown, op: "add" | "remove"): boolean {
 }
 
 /**
- * The URL of the first OPEN closer in a `gh api graphql` reply, if any.
+ * The first OPEN closer in a `gh api graphql` reply, if any.
  *
  * Split from the call so the state filter — the only real logic in this file —
  * is pinned against recorded payloads instead of a live repo.
@@ -176,12 +179,22 @@ function isLabelNoop(err: unknown, op: "add" | "remove"): boolean {
  * and the branch behind a draft still holds the only copy of the work. Sending
  * a second worker at it duplicates that work exactly as much as a ready PR
  * would, so OPEN is the whole test.
+ *
+ * `headRefName` is selected because admission needs to recognise a PR opened on
+ * a run's retained branch *after* that run ended — veltro#324 on 2026-08-09,
+ * killed at the turns cap before its worker opened a PR, so the row kept the
+ * branch and `prUrl` stayed NULL (#50). A node without it is not a crash and
+ * not a hold: an empty string simply never equals a stored branch, so such a
+ * reply degrades to the URL-equality identity that shipped before.
  */
-export function firstOpenCloser(raw: string): string | undefined {
+export function firstOpenCloser(raw: string): OpenCloser | undefined {
   const nodes =
     (JSON.parse(raw) as ClosersResponse).data?.repository?.issue?.closedByPullRequestsReferences
       ?.nodes ?? [];
-  return nodes.find((n) => n !== null && n.state === "OPEN")?.url;
+  const open = nodes.find((n) => n !== null && n.state === "OPEN");
+  return open === undefined || open === null
+    ? undefined
+    : { url: open.url, headRefName: open.headRefName ?? "" };
 }
 
 /**
@@ -433,7 +446,7 @@ export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
       );
     },
 
-    async openCloserFor(issue: number): Promise<string | undefined> {
+    async openCloserFor(issue: number): Promise<OpenCloser | undefined> {
       // GraphQL wants the halves of `owner/repo` separately. Config validates
       // that spelling, so an empty half means a hand-edited config: `gh` then
       // errors and the caller holds the candidate rather than guessing.

package/src/types.ts

@@ -247,6 +247,24 @@ export interface PrVerification {
 /** Tracker lifecycle state for an issue. Undefined means the adapter could not tell. */
 export type IssueState = "open" | "closed";
 
+/**
+ * An OPEN pull request that already closes an issue, as admission sees it.
+ *
+ * The head branch travels with the URL because admission has two different
+ * questions to answer about the same PR, and only one of them the URL can
+ * answer. "Is there finished work here" is a URL question. "Is this *our*
+ * retained work, resumed" is a branch question, because a run can retain a
+ * branch and never produce a PR: on 2026-08-09T00:47Z veltro#324 attempt 1 was
+ * killed at the turns cap before its worker opened one, and the PR that later
+ * appeared on that exact branch (chad#438) could never be matched by URL
+ * equality against a `prUrl` the terminal run never recorded (#50).
+ */
+export interface OpenCloser {
+  url: string;
+  /** Head branch of the open PR, for retained-continuation identity. */
+  headRefName: string;
+}
+
 /**
  * Deliberately narrow so a Gitea or local-file tracker can drop in later.
  * Nothing here is GitHub-shaped; the GitHub adapter owns `gh` entirely.
@@ -271,8 +289,8 @@ export interface Tracker {
    */
   parentOf(issue: number): Promise<number | undefined>;
   /**
-   * The URL of an OPEN pull request that already closes `issue`, or undefined
-   * when none does.
+   * The OPEN pull request that already closes `issue`, or undefined when none
+   * does.
    *
    * Admission has to ask the tracker because the store cannot answer. The busy
    * set is built from run rows, so it only knows work *this* database recorded:
@@ -280,8 +298,12 @@ export interface Tracker {
    * restore onto a new host, or simply a database younger than the PRs all
    * present pushed-and-open work as an untouched queue item. The tracker is the
    * only party that remembers across all of those.
+   *
+   * Returns {@link OpenCloser} rather than a bare URL because the branch is the
+   * half admission needs to recognise a continuation the store never saw a PR
+   * for; see that type for the veltro#324 case that forced the widening.
    */
-  openCloserFor(issue: number): Promise<string | undefined>;
+  openCloserFor(issue: number): Promise<OpenCloser | undefined>;
   /**
    * Whether an issue is still open, or undefined when tracker/network state is
    * ambiguous. Cleanup must never interpret undefined as permission to delete.

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}"`);
   }