omp-conductor 0.3.22 → 0.3.24

package/src/daemon.ts

@@ -28,6 +28,7 @@ import type {
   Caps,
   DispatchSummary,
   Escalation,
+  OpenCloser,
   PrState,
   ProjectConfig,
   ReadyIssue,
@@ -879,6 +880,49 @@ 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 reports whether the label is provably gone, because the
+ * caller has to decide what to write to the store on the strength of it. A
+ * sweep must not lose the rest of its rows to one unreachable tracker, and it
+ * must not terminalise a row whose label it failed to drop: the settlement
+ * sweep only ever revisits `pushed-*` rows, so a row written terminal is a row
+ * nothing asks about again, and swallowing the failure under it would recreate
+ * the exact permanent-`agent:in-progress` state of #18 in the one case that
+ * still reaches it. Answering false instead leaves the row where the next tick
+ * will find it.
+ *
+ * Removing a label the issue does not carry is success, not failure: the GitHub
+ * adapter treats an absent label as a no-op, so false means the tracker could
+ * not be reached or refused — a condition that passes.
+ */
+export async function releaseInProgress(
+  d: Pick<Deps, "project" | "tracker">,
+  issue: number,
+  why: string,
+): Promise<boolean> {
+  const label = d.project.stateLabels.inProgress;
+  try {
+    await d.tracker.removeLabel(issue, label);
+    log(`#${issue} released ${label}: ${why}`);
+    return true;
+  } catch (err) {
+    log(`#${issue} could not release ${label} (${errText(err)}) — ${why}; retrying next tick`);
+    return false;
+  }
+}
+
 /**
  * Asks the tracker about every `pushed-green` PR and settles the ones that
  * resolved.
@@ -889,11 +933,35 @@ 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.
+ *
+ * The two writes are ordered label-then-row, and the order is load-bearing. This
+ * sweep is the only thing that revisits a `pushed-*` row, so the terminal state
+ * is also the row's exit from it: written first, a tracker that then failed on
+ * the label would leave `agent:in-progress` with nothing left to retry it — #18
+ * exactly, in the last window able to reach it. Writing the label first makes
+ * failure cost a repeated `gh` call on the next tick instead, and the row stays
+ * in the busy set throughout, so no second worker can be sent at the issue while
+ * it waits.
  */
 export async function settlePushedGreen(
   d: Pick<Deps, "project" | "tracker" | "store">,
@@ -926,6 +994,15 @@ export async function settlePushedGreen(
 
     const settlement = settlementFor(pr, run.prUrl);
     if (settlement !== undefined) {
+      // Label first, row second, and the order is the whole safety argument.
+      // The sweep only ever revisits `pushed-*` rows, so writing the terminal
+      // state first would put this row beyond every later tick — and a tracker
+      // that failed on the label in that instant would strand
+      // `agent:in-progress` permanently, which is #18 again in the one window
+      // still able to reach it. Leaving the row `pushed-*` costs a stale active
+      // row until the tracker answers, and the busy set keeps the issue
+      // occupied meanwhile, so nothing can be dispatched onto it in between.
+      if (!(await releaseInProgress(d, run.issue, settlement.reason))) continue;
       const patch: Partial<RunRecord> = { state: settlement.state, endedAt: Date.now() };
       if (settlement.state === "failed") patch.lastError = settlement.reason;
       store.updateRun(run.id, patch);
@@ -946,6 +1023,11 @@ export async function settlePushedGreen(
       store.updateRun(run.id, { state: "pushed-green", lastError: undefined });
       log(`#${run.issue} checks settled: ${verification.reason}`);
     } else if (verification.status === "failed") {
+      // Equally terminal, so the same label-first order for the same reason:
+      // this row is about to leave the sweep's reach. The green branch above
+      // releases nothing — that row is still awaiting a merge, and its live PR
+      // is exactly the work the label must keep guarding.
+      if (!(await releaseInProgress(d, run.issue, verification.reason))) continue;
       store.updateRun(run.id, { state: "failed", lastError: verification.reason });
       log(`#${run.issue} checks failed: ${verification.reason}`);
     } else {
@@ -1224,7 +1306,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 +1323,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

@@ -28,6 +28,7 @@ import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { findProject, loadConfig, stateDir } from "./config.ts";
+import { readApprovalSurface } from "./approval-surface.ts";
 import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
 import { formatDispatchSummary, isPaused, setPaused, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
 import {
@@ -1081,6 +1082,13 @@ function readPairedChannel(path: string): Channel {
   return { kind: "up", owner: String(owner) };
 }
 
+/**
+ * The approval half of the Telegram surface is a different question from
+ * whether inbound works, and it is answered by {@link readApprovalSurface} —
+ * shared with the orchestrator tick so this row and the tick's own warning can
+ * never disagree about whether an amendment can be asked.
+ */
+
 function readBotToken(): string | undefined {
   const env = process.env["TELEGRAM_BOT_TOKEN"];
   if (env !== undefined && env.length > 0) return env;
@@ -1144,8 +1152,16 @@ 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` };
+  // The token is already proven: `getMe` succeeded above. What is left is
+  // whether an answer could come back, which is the access file's business.
+  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
@@ -42,8 +46,9 @@
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { findProject, loadConfig, resolveReleasePolicy } from "./config.ts";
+import { hasBotToken, readApprovalSurface, TELEGRAM_APPROVAL_TOOL } from "./approval-surface.ts";
 import {
   briefPathForProject,
   policyPathForProject,
@@ -336,6 +341,40 @@ 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.";
 
+/** Re-exported so the tick's own contract stays readable from one file: the
+ *  constant itself lives beside the check that decides whether it is callable. */
+export { TELEGRAM_APPROVAL_TOOL };
+
+/**
+ * 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";
@@ -873,21 +912,44 @@ export function tickDecision(input: {
 }
 
 /**
- * Whether the Telegram bridge can still reach a person: enabled, with exactly
- * one paired owner.
+ * Whether the Telegram bridge can still reach a person: a bot token, enabled,
+ * with exactly one paired owner.
  *
  * Fail-closed, and every failure mode collapses to the same answer on purpose —
  * missing file, truncated write, hand-edit that dropped `enabled`, a second
- * chat id pasted in, or the pairing revoked. Distinguishing them would only
- * tempt a future reader into treating one of them as benign, and none of them
- * are: each one means a tier-2 escalation lands nowhere.
+ * chat id pasted in, the pairing revoked, or no token for the bot to send with.
+ * Distinguishing them would only tempt a future reader into treating one of them
+ * as benign, and none of them are: each one means a tier-2 escalation lands
+ * nowhere.
+ *
+ * The token belongs in this gate rather than further down. Without one nothing
+ * outbound works, so a tick would carry a delivery rule ordering a
+ * `telegram_send` that cannot happen and an approval fallback naming the same
+ * unusable tool — an unattended fleet dispatching with no way to page anybody,
+ * which is the one thing the arm handshake exists to prevent. A missing token
+ * fails the whole channel; the narrower approval preflight is reserved for a
+ * bridge that can send but cannot ask.
  *
- * Re-read on every tick rather than cached at session start, because the bridge
- * is reconfigured by a long-lived operator out-of-band and a heartbeat that
- * trusted a startup snapshot would keep dispatching for days after the channel
- * went away.
+ * Re-read on every tick, and specifically *not* snapshotted at session start,
+ * because of what this gate is actually about. Tier 2 is paged by conductor
+ * itself: `escalate.ts` reads the same `.env` and calls `api.telegram.org`
+ * directly, never through omp-telegram's bridge. So the question "can an
+ * escalation still reach a person" is answered by the file as it stands now, and
+ * an operator who fixes a missing token has fixed paging immediately — a startup
+ * snapshot would keep a working fleet silent until somebody restarted the
+ * session, which is a worse failure than the one it would prevent. Re-reading
+ * also catches the reverse: a channel that goes away mid-session stops the
+ * heartbeat on the next tick rather than days later.
+ *
+ * What the file cannot answer is whether *omp-telegram* holds a token. It binds
+ * one in `startBot()` at session start and rebinds only on `/telegram token` and
+ * `/telegram on`, so a token added out-of-band leaves the bridge's own tools —
+ * `telegram_ask`, `telegram_send` — dead until one of those runs. That is real,
+ * and it is deliberately not modelled here: this gate protects paging, the
+ * README says to reload the bridge, and `omp-conductor status` shows the row.
  */
 function channelIsUp(path: string): boolean {
+  if (!hasBotToken(dirname(path))) return false;
   let parsed: unknown;
   try {
     parsed = JSON.parse(readFileSync(path, "utf8"));
@@ -983,6 +1045,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 +1133,46 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
     }
   }
 
+  // The floor's approval primitive, decided from configuration rather than from
+  // the live mounted set — and that is a correction, not a shortcut. The first
+  // attempt at this read `pi.getActiveTools()` here, which is wrong at exactly
+  // this point in the lifecycle: omp-telegram mounts `telegram_ask` in
+  // `before_agent_start` and takes it away again in `agent_end`
+  // (`restorePromptTools`), so it exists only *during* a turn. This runs between
+  // turns, composing the prompt that is about to start one, so the live set
+  // never contains the tool — a correctly configured fleet would have been told
+  // the approval was unavailable on every single tick, and the error line meant
+  // to flag a real fault would have fired 144 times a day saying nothing.
+  //
+  // What decides the mounting is knowable in advance and is shared with the
+  // status row, so the two cannot disagree: a locally injected tick has no
+  // `<telegram-message>` wrapper, so omp-telegram can only resolve a target
+  // through `notifyTarget()` — `notifyMode` plus a destination, both in the
+  // access file. Appended last, after the friction digest: the digest is what
+  // provokes an amendment, so the sentence saying the amendment cannot be
+  // approved here is the one that should read last.
+  //
+  // No access file configured means no fleet channel to judge, so nothing is
+  // claimed: the channel gate above already treats that as "not the fleet". A
+  // missing bot token is likewise not this check's business — it fails the
+  // channel gate outright, so a tick that reaches here can already send, and the
+  // only open question is whether an answer can come back.
+  const approval = config.accessFile === undefined ? undefined : readApprovalSurface(config.accessFile);
+  if (approval?.kind === "missing") {
+    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.
+      pi.logger.error(`[omp-conductor] ${approval.reason}`, {
+        tool: TELEGRAM_APPROVAL_TOOL,
+        accessFile: config.accessFile,
+      });
+    }
+  }
+
   try {
     pi.sendMessage(
       { customType: TICK_CUSTOM_TYPE, content, display: true, attribution: "user" },
@@ -1136,10 +1247,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.