@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/watch-delivery.mjs

@@ -0,0 +1,893 @@
+// watch-delivery — wait for a PR to reach a terminal delivery state, ONCE,
+// outside the orchestrator's context.
+//
+// On enqueueTrigger ∈ {hybrid, auto} the PR may merge without ever being enqueued
+// (@mergifyio queue never posted). This script still observes MERGED — it does not
+// require everQueued / prior enqueue (#791 / issue-664 / identity#669).
+//
+// Why this is a script and not a loop the orchestrator writes each time.
+//
+// The orchestrator is meant to be a thin scheduler: heavy steps run in spawns that return
+// a compact result, and durable state lives in the manifest. Watching a queue is the
+// opposite of heavy — it is a `gh pr view` every twenty seconds — but it is the single
+// largest consumer of foreground turns in a real run, and every one of those turns costs
+// context the scheduler needs for scheduling.
+//
+// Measured, in this repo's own runs: delivering one PR took 13 foreground `gh pr view`
+// calls. A Pi session delivering an epic spent 36 `gh pr view` + 18 `gh pr checks` + 17
+// `mergify queue` calls in the foreground — 71 polling calls, none of which produced a
+// decision, and that run ended with the orchestrator hand-patching its own manifest JSON
+// because its context had filled. Polling did not cause that on its own, but it is the
+// bulk of what filled the window.
+//
+// So the watch runs here: one launch, one terminal answer, no intermediate turns. What
+// does NOT move is the decision to enqueue or the recording of the outcome — those are
+// guarantee 4's authorization and the audit trail, and they stay with the orchestrator.
+// This script observes; it never acts on the PR, and it takes no merge authorization.
+//
+//   node watch-delivery.mjs --pr 557 --repo owner/name [--bound-minutes 10]
+//                           [--interval-seconds 20] [--provider mergify|github]
+//                           [--head <sha>]   # exact HEAD for the CI→delivery pipeline (#792)
+//
+// OUTPUT (stdout, always JSON): { terminal, outcome, mergedSha, reason, observations, elapsedMs, ciStatus? }
+//
+// EXIT CODES:
+//   0  merged — `mergedSha` is the PR's MERGE COMMIT, and the caller still owes the
+//      ancestry proof (`combine-and-verify.mjs delivered`). A merge tool's answer is a
+//      request; only ancestry is a result, and this script deliberately does not pretend
+//      otherwise.
+//   4  terminal but NOT merged — dequeued, closed, or stalled past the bound. Owes a
+//      hand-back with the reason, which is a routing class the caller maps through
+//      `dequeueRouting`.
+//   5  CI failed on the exact HEAD (`--head` set) — fold into a fix round; never a
+//      success. Distinct from stall so the orchestrator can route without re-deriving
+//      the failure class from detail strings.
+//   2  usage error.
+//
+// It never exits 0 on a timeout. "Still going" and "finished" must not collapse into one
+// code, because the caller writes a terminal delivery outcome from this and a wrong
+// `merged` there is the epic-986 shape (four units recorded merge-ready, mergedSha null).
+//
+// #792 / issue-664 / identity#669: when `--head` is set this is the single background
+// CI→delivery pipeline after PASS. Merge is still preferred over CI red (hybrid can
+// land while checks are still settling); CI red is only terminal while the PR is open.
+
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, resolve as resolvePath } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { checksForPhase, validateQueueExecutionArtifact } from '../../engineering-runtime/scripts/required-check-plan.mjs'
+
+// ---- pure, unit-testable core ----
+
+// A PR's own state is the authority on "did it merge". The queue's state answers "is it
+// still being worked", which is a different question and cannot settle this one.
+// `everQueued` / `absentStreak` carry the one piece of history a single observation cannot:
+// whether this PR was ever *in* the queue. The mergify skill's label lifecycle is explicit
+// that a still-open PR which has been seen queued and then LOSES the label is a queue exit,
+// not a healthy snapshot — and the first version of this function ignored that, treating
+// `{"queued": false}` after observed entry as "keep waiting", which is precisely the
+// reading delivery.md cites that skill to forbid. A watcher that waits out a PR the queue
+// already ejected reports nothing until its bound expires, and the unit looks alive
+// throughout.
+//
+// Absence is not read on sight, though: GitHub can briefly expose neither label mid-
+// transition, so one absent observation is only a suspicion. The rule is re-read, and a
+// second consecutive absence settles it — which is what "re-read labels immediately" means
+// operationally.
+// `provider` is load-bearing rather than decorative: the `queued`/`dequeued` labels are
+// **Mergify's** mechanics. GitHub's native merge queue does not write them, so applying the
+// label rules there would read every PR as never-queued and silently disable the transition
+// check. Same doctrine the delivery flow already follows — the mode picks the state
+// machine, the provider picks the mechanics — so the provider-neutral half (merged, closed)
+// runs for everyone and the label half runs only where labels exist.
+// CI rollup for the CI→delivery pipeline (#792). Pure and unit-testable: the poll loop
+// feeds it whatever `gh pr checks --json` returned (or a pre-rolled status) and it answers
+// pending / green / red without talking to the network.
+//
+// `state` may be a rollup string (`SUCCESS`/`FAILURE`/`PENDING`/`ERROR`/`NEUTRAL`/`SKIPPED`)
+// or an array of per-check objects (`{ state|conclusion|status, name? }`). GitHub's
+// vocabulary is wider than three buckets; anything not clearly success/neutral/skipped is
+// either still running (pending) or a failure (red). Empty/missing is pending — "no checks
+// yet" is not green.
+export function classifyCiState(input = {}) {
+  const raw = input.state ?? input.ciStatus ?? input.checks ?? null
+  if (raw == null) return { status: 'pending', reason: null }
+
+  const toBucket = (s) => {
+    const v = String(s ?? '').toUpperCase()
+    if (!v) return 'pending'
+    if (['SUCCESS', 'NEUTRAL', 'SKIPPED', 'PASS', 'PASSED', 'COMPLETED'].includes(v)) return 'green'
+    if (['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'FAIL', 'FAILED'].includes(v)) return 'red'
+    // PENDING, QUEUED, IN_PROGRESS, EXPECTED, REQUESTED, WAITING, …
+    return 'pending'
+  }
+
+  if (typeof raw === 'string') {
+    const status = toBucket(raw)
+    return { status, reason: status === 'red' ? 'ci-failed' : null }
+  }
+
+  if (Array.isArray(raw)) {
+    if (raw.length === 0) return { status: 'pending', reason: null }
+    let anyPending = false
+    let anyRed = false
+    const failed = []
+    for (const c of raw) {
+      // Prefer conclusion (final) over status (lifecycle). A completed check with
+      // conclusion FAILURE is red even when status is COMPLETED.
+      const bucket = toBucket(c?.conclusion ?? c?.state ?? c?.status)
+      if (bucket === 'red') {
+        anyRed = true
+        if (c?.name) failed.push(c.name)
+      } else if (bucket === 'pending') {
+        anyPending = true
+      }
+    }
+    if (anyRed) return { status: 'red', reason: 'ci-failed', failedChecks: failed }
+    if (anyPending) return { status: 'pending', reason: null }
+    return { status: 'green', reason: null }
+  }
+
+  return { status: 'pending', reason: null }
+}
+
+// Exact-HEAD identity for the CI→delivery pipeline (#792 guarantee 3).
+//
+// When `--head <sha>` is supplied, every terminal classification must be for THAT head.
+// GitHub's `headRefOid` is the PR's current tip; if it no longer matches the supplied
+// SHA, a merge or CI failure belongs to a different commit and must not be attributed
+// to the reviewed one. Fail closed with `reason: 'head-drift'` so the orchestrator can
+// route "rewritten head → re-review" instead of recording delivery for a stale SHA.
+//
+// Matching is prefix-tolerant: callers often pass a short SHA while GitHub returns the
+// full 40-char oid. Comparison is case-insensitive.
+export function headsMatch(supplied, observed) {
+  if (typeof supplied !== 'string' || typeof observed !== 'string') return false
+  const a = supplied.trim().toLowerCase()
+  const b = observed.trim().toLowerCase()
+  if (!a || !b) return false
+  return a === b || a.startsWith(b) || b.startsWith(a)
+}
+
+// Returns a terminal hand-back verdict when the PR tip has moved off `--head`, or null
+// when the exact-HEAD contract still holds (or when no head was required).
+// Only call on a readable observation — an unreadable poll has no tip to compare.
+export function headDriftVerdict({ suppliedHead, headRefOid } = {}) {
+  if (typeof suppliedHead !== 'string' || !suppliedHead.trim()) return null
+  const expected = suppliedHead.trim()
+  if (typeof headRefOid !== 'string' || !headRefOid.trim()) {
+    return {
+      terminal: true,
+      outcome: 'handed-back',
+      mergedSha: null,
+      reason: 'head-drift',
+      detail: `PR headRefOid is missing while --head ${expected} was required — cannot prove exact-HEAD delivery`,
+      expectedHead: expected,
+      observedHead: headRefOid ?? null,
+    }
+  }
+  if (headsMatch(expected, headRefOid)) return null
+  return {
+    terminal: true,
+    outcome: 'handed-back',
+    mergedSha: null,
+    reason: 'head-drift',
+    detail: `PR head moved from ${expected} to ${headRefOid} — exact-HEAD delivery contract broken; re-review the new head`,
+    expectedHead: expected,
+    observedHead: headRefOid,
+  }
+}
+
+// Combine PR lifecycle + CI into one poll decision for the CI→delivery pipeline.
+// Precedence is deliberate:
+//   0. head-drift (checked by the poll loop before this) — exact-HEAD contract first.
+//   1. MERGED / CLOSED / dequeued — delivery terminal wins over CI (hybrid can merge
+//      while checks are still red or pending; the PR's own state is the authority).
+//   2. CI red while still open — terminal `ci-failed` (exit 5). Fold into a fix round.
+//   3. Otherwise keep watching (CI pending/green is not terminal on its own — green is
+//      the condition under which enqueue/auto-merge may still fire; the watch ends on
+//      the delivery outcome or the stall/ceiling bound).
+export function classifyWatchPoll({ pr, ci } = {}) {
+  const prVerdict = classifyPrState(pr ?? {})
+  if (prVerdict.terminal) return { ...prVerdict, ciStatus: ci?.status ?? null }
+  const ciStatus = ci?.status ?? null
+  if (ciStatus === 'red') {
+    return {
+      terminal: true,
+      outcome: 'handed-back',
+      mergedSha: null,
+      reason: 'ci-failed',
+      ciStatus: 'red',
+      detail: ci?.failedChecks?.length
+        ? `CI failed on exact HEAD: ${ci.failedChecks.join(', ')}`
+        : 'CI failed on exact HEAD',
+      failedChecks: ci?.failedChecks ?? [],
+    }
+  }
+  return { terminal: false, outcome: null, mergedSha: null, reason: null, ciStatus }
+}
+
+export function classifyPrState({ state, mergedAt, mergeCommitOid, labels, everQueued = false, absentStreak = 0, provider = 'mergify', startedMs = null, dequeuedAtMs = null, queueActive = null } = {}) {
+  const tags = Array.isArray(labels) ? labels : []
+  const labelsAreMeaningful = provider === 'mergify'
+  if (state === 'MERGED' || mergedAt) {
+    // A merged PR with no merge commit is not a usable result: the caller records
+    // `mergedSha` and proves ancestry with it, and `null` there is unprovable.
+    // `mergedAt` is carried on the terminal answer so the orchestrator can store it on
+    // record-delivery-outcome (#791 / issue-664 / identity#669): hybrid/auto merges land
+    // without enqueue, and the postmortem clock needs the PR's own merge time rather than
+    // a late bookkeeping timestamp. Terminal regardless of everQueued — do not require a
+    // prior @mergifyio queue before observing a merge.
+    return mergeCommitOid
+      ? { terminal: true, outcome: 'merged', mergedSha: mergeCommitOid, mergedAt: mergedAt ?? null, reason: null }
+      : { terminal: true, outcome: 'handed-back', mergedSha: null, mergedAt: mergedAt ?? null, reason: 'merged-without-sha' }
+  }
+  if (state === 'CLOSED') {
+    return { terminal: true, outcome: 'handed-back', mergedSha: null, reason: 'manual' }
+  }
+  // The `dequeued` label is a terminal queue exit — the mergify skill owns this lifecycle
+  // and the reason it is not merely "not queued": GitHub can briefly expose neither label
+  // during a transition, so absence proves nothing and presence proves an exit.
+  //
+  // Issue #629: that label is a lifecycle MIRROR, never removed on re-enqueue, so a PR
+  // dequeued once, fixed, and re-enqueued still carries it into a watch launched for the
+  // second attempt. Two guards, cheapest first (sibling of the identical fix in the mergify
+  // skill's `watch-pr-delivery.mjs`):
+  //
+  // 1. A fresh `queued` label reports the PR active right now — a `dequeued` label alongside
+  //    it cannot be describing THIS moment, so it is ignored outright, no timestamp needed.
+  // 2. Otherwise the label is only THIS watch's terminal signal if it was applied at or after
+  //    this watch started (`dequeuedAtMs`, parsed from the relevant Mergify status comment's
+  //    "Left the queue" line — see `dequeuedAtFromComments`). Absent a reliable timestamp,
+  //    fail toward WAITING, never toward a terminal verdict: a watcher that waits is bounded
+  //    by --bound-minutes/--max-minutes and hands back honestly, whereas one that terminates
+  //    early reports the PREVIOUS attempt's outcome as this one's, as fact — and that outcome
+  //    is what routes the unit on the resolve-issues path this script serves.
+  //
+  //    NOTE-2 (review on PR #637): `dequeuedAtMs` is truncated to the minute (Mergify's
+  //    rendered "Left the queue" text has no seconds), while `startedMs` is millisecond-
+  //    precision — so without a grace period, a GENUINE dequeue landing in the same
+  //    wall-clock minute as the watch start always parses to a value below `startedMs` and
+  //    reads as stale, a systematic blind spot for the first minute of every watch. A flat
+  //    60s grace absorbs that truncation. It trades a symmetric, much narrower risk (a truly
+  //    stale dequeue from a PRIOR attempt coincidentally landing within 60s of THIS watch's
+  //    start reading as fresh) for closing a bug that fired on every watch's first minute;
+  //    #629's actual failure mode is stale labels persisting across minutes-to-hours-old
+  //    attempts, not a coincidence this narrow.
+  const DEQUEUE_TIMESTAMP_GRACE_MS = 60_000
+  // Membership is the OR of two sources, and the order matters. The labels are a mirror the
+  // queue writes; `mergify queue show` is the queue itself. A mirror can lag, can be missing,
+  // and can linger from a previous attempt — so a `queued` label proves membership but its
+  // ABSENCE proves nothing while the queue tool still reports the PR active. `queueActive` is
+  // `null` when the queue could not be consulted, which is deliberately not `false`: unknown
+  // must not read as "left the queue", the exact conflation that made dequeues resolve badly.
+  const activeNow = (labelsAreMeaningful && tags.includes('queued')) || queueActive === true
+  if (labelsAreMeaningful && tags.includes('dequeued') && !activeNow) {
+    const isThisWatchsDequeue = Number.isFinite(startedMs) && Number.isFinite(dequeuedAtMs) && dequeuedAtMs >= startedMs - DEQUEUE_TIMESTAMP_GRACE_MS
+    if (isThisWatchsDequeue) {
+      return { terminal: true, outcome: 'handed-back', mergedSha: null, reason: 'dequeued' }
+    }
+  }
+  // Seen queued, now not queued, still open and unmerged, and it has survived a re-read:
+  // the queue let go of this PR without the label ever appearing. Terminal.
+  // `!activeNow`, not `!tags.includes('queued')`. Adding the queue tool to `activeNow` above
+  // and leaving this branch on the label alone would have kept the exact bug being fixed: a
+  // PR the queue still holds, whose label lagged, settling as a dequeue on the re-read. Both
+  // membership witnesses have to be silent before this is a queue exit.
+  if (labelsAreMeaningful && everQueued && !activeNow && absentStreak >= 2) {
+    return {
+      terminal: true, outcome: 'handed-back', mergedSha: null, reason: 'dequeued',
+      // Issue #615 item 5 (sibling of the mergify watcher's identical wording fix): an
+      // unreadable poll carries `absentStreak` forward unchanged rather than resetting it
+      // (see `nextAbsentStreak` below), so the two absences that settle this can be
+      // separated by an arbitrarily long unreadable gap — they are consecutive READABLE
+      // reads, not consecutive reads.
+      detail: 'the PR was observed in the queue and then lost the `queued` label across two consecutive readable reads without merging — a queue exit, not a healthy snapshot',
+    }
+  }
+  return { terminal: false, outcome: null, mergedSha: null, reason: null }
+}
+
+// A failed `gh pr view` read (`readable: false`) carries no information about queue
+// membership — it is not evidence the PR is still queued, and it is not evidence it left the
+// queue either. Only a clean read that reports absence should move the counter that
+// eventually settles `dequeued` in `classifyPrState`. Fixes #611 defect 1 in this watcher too
+// (the mergify skill's `watch-pr-delivery.mjs` had the identical gap, closed there first by
+// `nextMissingActiveReads`, kept the same shape here as `nextAbsentStreak`): two consecutive
+// transient `gh` failures after `everQueued` were previously indistinguishable from two
+// consecutive genuine "not queued" reads, and both advanced the same counter.
+export function nextAbsentStreak({ queued, everQueued, absentStreak = 0, readable = true }) {
+  if (queued) return 0
+  if (!everQueued) return absentStreak
+  return readable ? absentStreak + 1 : absentStreak
+}
+
+// Compact, order-stable fingerprint of check-run progress for the stall clock.
+// Used so a PR that stays OPEN+queued while CI conclusions move still restarts the bound
+// (issue-799-800-resolve-release #807 / PR #810: skill-script-tests ran for ~12m under a
+// frozen OPEN+queued key and the watch handed back conditions-unmet two minutes before merge).
+export function checksFingerprint(checks) {
+  if (!Array.isArray(checks) || checks.length === 0) return null
+  const rows = checks.map((c) => {
+    const name = c?.name ?? c?.context ?? ''
+    const conclusion = c?.conclusion ?? ''
+    const status = c?.status ?? c?.state ?? ''
+    return `${name}|${status}|${conclusion}`
+  }).sort()
+  return rows.join(';')
+}
+
+// The stall clock restarts only when something the delivery surface actually CHANGES. A
+// repeat poll returning the same key reads as a stall rather than as life — the same
+// rule `record-delivery-observation` applies, kept identical here on purpose so a watch
+// and a recorded observation cannot disagree about whether a unit is progressing.
+//
+// The key is deliberately wider than the original (state, queueState, position, labels)
+// triple. issue-799-800-resolve-release #807 taught why: `runCli` built the key from the
+// `gh pr view` observation alone, while Mergify membership lived in a separate `qv`
+// object that never fed the key. A PR sitting in the queue with labels=['queued'] and
+// position frozen at 0 ("Preparing checks") looked identical every poll, so the 10m stall
+// bound fired while the queue was still holding the PR and CI was still running. Fold in:
+//   · queueState / position / queueActive from the queue tool (when available)
+//   · checksFingerprint so CI progress under a frozen queue picture also counts as life
+export function queueExecutionFingerprint(observation) {
+  if (!observation || typeof observation !== 'object' || Array.isArray(observation)) return null
+  return JSON.stringify([
+    observation.kind ?? null,
+    observation.repository ?? null,
+    observation.pr ?? null,
+    observation.prHeadSha ?? null,
+    observation.queuePr ?? null,
+    observation.queueHeadSha ?? null,
+    observation.provider ?? null,
+    observation.status ?? null,
+    checksFingerprint(observation.checks),
+  ])
+}
+
+export function observationKey({
+  state, queueState, position, labels, queueActive = null, checks = null, checksFp = null,
+  queueExecution = null,
+} = {}) {
+  const tags = Array.isArray(labels) ? [...labels].sort().join(',') : ''
+  const fp = checksFp != null ? checksFp : checksFingerprint(checks)
+  // queueActive is tri-state: true / false / null(unknown). Null must not collapse with
+  // false — unknown membership is not "left the queue" (same doctrine as classifyPrState).
+  const active = queueActive === true ? true : queueActive === false ? false : null
+  return JSON.stringify([
+    state ?? null, queueState ?? null, position ?? null, tags, active, fp,
+    queueExecutionFingerprint(queueExecution),
+  ])
+}
+
+// Bounded on STALL, not elapsed time. A unit can sit in `waiting_for_previous_batches` for
+// an hour while genuinely advancing, and a flat timeout hands back healthy units.
+export function stallVerdict({ lastChangeMs, nowMs, boundMinutes }) {
+  const bound = Number(boundMinutes)
+  if (!Number.isFinite(bound) || bound <= 0) {
+    return { stalled: false, reason: 'bound is not a positive number — refusing to time out on a bad bound' }
+  }
+  const stalledFor = nowMs - lastChangeMs
+  return stalledFor >= bound * 60_000
+    ? { stalled: true, reason: `no observable change for ${Math.round(stalledFor / 60_000)}m (bound ${bound}m) — the queue is not reporting progress`, stalledForMs: stalledFor }
+    : { stalled: false, stalledForMs: stalledFor }
+}
+
+// ---- impure observation ----
+
+// Fixes #611 defect 2 (the same gap as the mergify skill's `watch-pr-delivery.mjs`):
+// `execFileSync` had no `timeout`, so a stalled TLS handshake or hung `gh` invocation blocked
+// this watcher past both `--bound-minutes` and `--max-minutes` — those bounds are only
+// evaluated after a poll returns. The bound is a small multiple of the poll interval:
+// generous enough that normal network latency never trips it, bounded well under the
+// absolute ceiling so a hung child cannot outlive it. Floors at 10s so a very short poll
+// interval cannot turn this into a near-instant timeout — but that floor is itself clamped
+// against `boundMinutes` (the caller passes `min(--bound-minutes, --max-minutes)`) so a
+// single read's own timeout can never exceed the watch's own stall/ceiling bounds.
+//
+// Issue #615 item 1 (sibling of the mergify watcher's identical fix): the clamp divides by
+// `readsPerPoll`, the number of subprocess reads made per poll, so a poll's reads together
+// cannot outlive the bound even if every one of them hangs. This watcher makes exactly one
+// read per poll (`gh pr view` in `observe`, below), so `readsPerPoll` is 1 and dividing by it
+// is a no-op — the mergify watcher's sibling (`watch-pr-delivery.mjs`, two reads per poll)
+// is where the division actually changes behaviour.
+export function readTimeoutMs(intervalSeconds, boundMinutes, readsPerPoll = 1) {
+  const seconds = Number(intervalSeconds)
+  const bounded = Number.isFinite(seconds) && seconds > 0 ? seconds : 20
+  const computed = Math.max(bounded * 2000, 10_000)
+  const bound = Number(boundMinutes)
+  const reads = Number.isFinite(readsPerPoll) && readsPerPoll > 0 ? readsPerPoll : 1
+  return Number.isFinite(bound) && bound > 0 ? Math.min(computed, (bound * 60_000) / reads) : computed
+}
+
+// The single subprocess read this watcher makes per poll — `gh pr view` in `observe`. See
+// `readTimeoutMs` above.
+const READS_PER_POLL = 1
+
+export function tryRun(cmd, args, options = {}) {
+  try { return { ok: true, out: execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], ...options }) } }
+  catch (error) { return { ok: false, out: '', error } }
+}
+
+// Resolve the mergify skill's watcher so this one can borrow its queue read.
+//
+// Why a search rather than one path: the two skills are SIBLINGS once installed
+// (`~/.agents/skills/{resolve-issues,mergify}`) but not in the authoring repo, where mergify
+// lives under `cicd-pipeline/` and resolve-issues under `engineering/`. A single hardcoded
+// `<skillsRoot>/mergify/...` therefore resolves in a consumer repo and fails here — the exact
+// mirror of the relative-path defect this repo's script-hygiene gate exists to catch. Both
+// layouts are tried, relative to THIS file, so neither environment is the special case.
+//
+// `--queue-watcher` overrides for anything unusual. Returns null when nothing resolves.
+const QUEUE_WATCHER_CANDIDATES = [
+  // From `<root>/resolve-issues/scripts/` the sibling skill is up TWO levels; from the repo's
+  // `skills/engineering/resolve-issues/scripts/` it is up three and across into another scope.
+  '../../mergify/scripts/watch-pr-delivery-core.mjs',                  // installed farm: siblings
+  '../../../cicd-pipeline/mergify/scripts/watch-pr-delivery-core.mjs', // authoring repo
+]
+
+export function resolveQueueWatcher(explicit, fromUrl = import.meta.url) {
+  const here = fileURLToPath(fromUrl)
+  if (typeof explicit === 'string' && explicit.trim()) {
+    if (!existsSync(explicit)) return null
+    const siblingCore = resolvePath(dirname(explicit), 'watch-pr-delivery-core.mjs')
+    return explicit.endsWith('watch-pr-delivery.mjs') && existsSync(siblingCore) ? siblingCore : explicit
+  }
+  for (const rel of QUEUE_WATCHER_CANDIDATES) {
+    const p = resolvePath(dirname(here), rel)
+    if (existsSync(p)) return p
+  }
+  return null
+}
+
+// The queue's own view of membership, borrowed from the mergify skill rather than reimplemented.
+//
+// This watcher was label-only, and that is precisely why its dequeue resolution was weak: the
+// `queued`/`dequeued` labels are a MIRROR of the queue, so a label that lags, never lands, or
+// lingers from a previous attempt leaves the classifier with no second opinion. `mergify queue
+// show --json` is authoritative for membership — and it is the source that distinguishes "the
+// queue is holding this PR" from "nothing is holding it", which read identically in labels.
+//
+// Degradation is LOUD. If the mergify watcher cannot be resolved this returns `available:
+// false` and the caller says so in its output, because silently continuing label-only is the
+// failure being fixed: the watch still runs, still looks healthy, and still resolves dequeues
+// badly, with nothing reporting which mode it was in.
+// Import once, then hand back a synchronous per-poll reader — or null when the mergify
+// watcher is unavailable, which the caller reports rather than silently absorbing.
+async function loadMergifyObservationCore(watcherPath, { pr, repo, intervalSeconds, boundMinutes }) {
+  if (!watcherPath) return null
+  try {
+    const { queueObservation, dequeuedAtFromComments } = await import(pathToFileURL(watcherPath).href)
+    if (typeof queueObservation !== 'function' || typeof dequeuedAtFromComments !== 'function') return null
+    return {
+      dequeuedAtFromComments,
+      readQueue: () => {
+        try {
+          const q = queueObservation({ pr, repo, intervalSeconds, stallMinutes: boundMinutes, maxMinutes: boundMinutes })
+          // position must reach the stall key (issue-799-800 #807): dropping it here made
+          // every "Preparing checks" poll look identical even when position later moved.
+          return {
+            available: true,
+            active: q.queued === true,
+            readable: q.readable !== false,
+            queueState: q.queueState ?? null,
+            position: typeof q.position === 'number' ? q.position : null,
+          }
+        } catch { return { available: true, active: null, readable: false, queueState: null, position: null } }
+      },
+    }
+  } catch { return null }
+}
+
+function observe(pr, repo, intervalSeconds, boundMinutes, dequeuedAtFromComments = () => null) {
+  // `comments` costs nothing extra in this same call and carries the one signal
+  // `dequeuedAtFromComments` needs — no additional subprocess read, so the READS_PER_POLL
+  // budget below is unaffected by issue #629's fix.
+  // `headRefOid` is required for the exact-HEAD CI→delivery contract (#792): when
+  // `--head` is set the poll loop compares it to the supplied SHA before any terminal
+  // classification, so a rewritten tip cannot be reported as a merge/CI result for the
+  // old reviewed commit. Same single `gh pr view` call — no extra read budget.
+  const r = tryRun('gh', ['pr', 'view', String(pr), '--repo', repo, '--json', 'state,mergedAt,mergeCommit,labels,comments,statusCheckRollup,headRefOid'], { timeout: readTimeoutMs(intervalSeconds, boundMinutes, READS_PER_POLL) })
+  // An unreadable PR is NOT "still running" — it is an unknown, and treating it as life
+  // keeps the watch alive against a PR that may not exist. Report it and let the stall
+  // clock end the watch honestly.
+  if (!r.ok) return { readable: false, state: null, mergedAt: null, mergeCommitOid: null, labels: [], dequeuedAtMs: null, checks: null, headRefOid: null }
+  try {
+    const d = JSON.parse(r.out)
+    // statusCheckRollup is an array of CheckRun/StatusContext objects. Map to the shape
+    // classifyCiState accepts so the poll loop does not re-derive the vocabulary.
+    const checks = Array.isArray(d.statusCheckRollup)
+      ? d.statusCheckRollup.map((c) => ({
+          name: c.name ?? c.context ?? null,
+          // CheckRun uses conclusion + status; StatusContext uses state.
+          conclusion: c.conclusion ?? null,
+          state: c.state ?? null,
+          status: c.status ?? null,
+        }))
+      : null
+    return {
+      readable: true,
+      state: d.state ?? null,
+      mergedAt: d.mergedAt ?? null,
+      mergeCommitOid: d.mergeCommit?.oid ?? null,
+      labels: (d.labels ?? []).map((l) => l.name).filter(Boolean),
+      dequeuedAtMs: dequeuedAtFromComments(d.comments),
+      checks,
+      headRefOid: d.headRefOid ?? null,
+    }
+  } catch { return { readable: false, state: null, mergedAt: null, mergeCommitOid: null, labels: [], dequeuedAtMs: null, checks: null, headRefOid: null } }
+}
+
+// Every poll's observation, as one compact NDJSON record — the watcher's heartbeat.
+//
+// Same defect, same fix as the mergify skill's `watch-pr-delivery.mjs` (these two are
+// deliberately kept in step): the loop's only output sites were the terminal ones, so a watch
+// sitting in the healthy `queued`/not-yet-queued path wrote zero bytes for its whole life.
+// Reproduced live on a mergify-skill watch of PR #1396 — 25 minutes, log contained nothing but
+// the supervisor's spawn banner, and it was killed before the then-30-minute stall bound so it
+// never printed even a verdict. It matters MORE here: this watcher runs unattended inside the resolve-issues
+// delivery loop, where a silent process and a hung one look identical to the orchestrator
+// deciding whether a unit is progressing.
+//
+// stderr, not stdout, because stdout is the machine contract — exactly one terminal JSON
+// document the caller parses whole — and interleaving heartbeats would break every caller.
+// stderr is merged into the log by any supervisor that runs this, which is where a human looks.
+export function progressRecord({ observation, changed, sinceChangeMs, nowIso }) {
+  return JSON.stringify({ ...observation, progress: true, terminal: false, changed, sinceChangeMs, at: nowIso })
+}
+
+// Defaults, aligned with the mergify skill's watcher so the two siblings do not drift into
+// different cadences for the same job. `boundMinutes` is a NO-CHANGE bound — any observed
+// movement resets it — so 10 minutes of a frozen picture is already a long wait before handing
+// back: at a 90s poll that is still ~6 consecutive identical observations, well past a
+// transient blip. The 90s interval also bounds the API budget: one read per poll is 40 calls/hour per
+// watched PR, so even an epic-sized fan-out of concurrent watchers stays far inside an
+// authenticated token's 5,000/hour. The cost is at most 90s of extra merge-detection latency
+// against a queue that takes minutes per batch.
+export const DEFAULT_INTERVAL_SECONDS = 90
+export const DEFAULT_BOUND_MINUTES = 10
+export const DEFAULT_MAX_MINUTES = 60
+
+// Kept deliberately equal to the mergify watcher's `MAX_MINUTES_CEILING` — these two watchers
+// implement one contract, and a ceiling honoured by only one of them is not a ceiling. A
+// resolve-issues delivery that routed through this wrapper instead of the sibling would
+// otherwise still be able to wait two hours, which is the failure mode the cap exists to end.
+// Read the rationale there; enforced here the same way, as an exit-2 usage error rather than a
+// silent clamp.
+export const MAX_MINUTES_CEILING = 60
+
+export function invokeQueueExecutionProvider(providerPath, request, { timeoutMs = 30_000 } = {}) {
+  const input = JSON.stringify(request)
+  const result = spawnSync(process.execPath, [providerPath], {
+    input,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: timeoutMs,
+    maxBuffer: 32 * 1024 * 1024,
+  })
+  if (result.error?.code === 'ETIMEDOUT' || (result.status == null && result.signal)) {
+    return { ok: false, error: `queue-execution provider timed out after ${timeoutMs}ms` }
+  }
+  if (result.error) {
+    return { ok: false, error: `queue-execution provider failed to start: ${String(result.error.message || result.error)}` }
+  }
+  const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : ''
+  if (result.status !== 0) {
+    const detail = stderr ? `: ${stderr}` : ''
+    return { ok: false, error: `queue-execution provider exited with code ${result.status}${detail}` }
+  }
+  if (stderr) return { ok: false, error: `queue-execution provider wrote stderr: ${stderr}` }
+  const stdout = typeof result.stdout === 'string' ? result.stdout.trim() : ''
+  if (!stdout) return { ok: false, error: 'queue-execution provider returned empty stdout' }
+  try {
+    return { ok: true, value: JSON.parse(stdout), requestJson: input }
+  } catch (error) {
+    return { ok: false, error: `queue-execution provider returned malformed JSON: ${String(error.message || error)}` }
+  }
+}
+
+export function captureQueueExecution(provider, { repository, pr, prHeadSha, requiredCheckPlan }) {
+  const names = checksForPhase(requiredCheckPlan, 'queue-head').map((check) => check.name)
+  if (!names.length) return { artifact: null, errors: [] }
+  if (typeof provider !== 'function') return { artifact: null, errors: ['queue-execution provider is unavailable'] }
+  try {
+    const artifact = provider({ operation: 'read-queue-execution', repository, pr, prHeadSha, names })
+    const validation = validateQueueExecutionArtifact(requiredCheckPlan, artifact, {
+      expectedRepository: repository,
+      expectedPr: pr,
+      expectedPrHeadSha: prHeadSha,
+    })
+    return validation.ok ? { artifact, errors: [] } : { artifact: null, errors: validation.errors }
+  } catch (error) {
+    return { artifact: null, errors: [String(error.message || error)] }
+  }
+}
+
+export function parseArgs(argv) {
+  const f = { boundMinutes: DEFAULT_BOUND_MINUTES, intervalSeconds: DEFAULT_INTERVAL_SECONDS, maxMinutes: DEFAULT_MAX_MINUTES, provider: 'mergify' }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--pr') f.pr = argv[++i]
+    else if (a === '--repo') f.repo = argv[++i]
+    else if (a === '--provider') f.provider = argv[++i]
+    else if (a === '--bound-minutes') f.boundMinutes = Number(argv[++i])
+    else if (a === '--max-minutes') f.maxMinutes = Number(argv[++i])
+    else if (a === '--interval-seconds') f.intervalSeconds = Number(argv[++i])
+    else if (a === '--head') f.head = argv[++i]
+    else if (a === '--quiet') f.quiet = true
+    else if (a === '--queue-watcher') f.queueWatcher = argv[++i]
+    else if (a === '--required-check-plan') f.requiredCheckPlan = argv[++i]
+    else if (a === '--queue-execution-provider') f.queueExecutionProvider = argv[++i]
+    else if (a === '--help' || a === '-h') f.help = true
+  }
+  return f
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+export async function runCli(argv) {
+  const f = parseArgs(argv)
+  let requiredCheckPlan = null
+  if (f.requiredCheckPlan) {
+    try { requiredCheckPlan = JSON.parse(await (await import('node:fs/promises')).readFile(f.requiredCheckPlan, 'utf8')) }
+    catch { console.error('watch-delivery: --required-check-plan must name readable JSON'); return 2 }
+  }
+  if (f.help) {
+    console.log(`watch-delivery --pr <n> --repo <owner/name> [--bound-minutes 10] [--interval-seconds 90] [--head <sha>]
+               [--required-check-plan <json> --queue-execution-provider <provider.mjs>]
+Waits for a PR to reach a terminal delivery state (including hybrid/auto merge without enqueue), in ONE launch instead of a
+foreground poll loop. Observes only — never enqueues, never merges, never records.
+
+With --head, this is the single CI→delivery pipeline after PASS (#792 / issue-664 / identity#669):
+poll CI on that exact HEAD and the PR lifecycle together. Merge still wins over CI red (hybrid
+can land while checks settle). CI red while OPEN is exit 5 — fold into a fix round. If the PR
+tip moves off the supplied SHA, exit 4 with reason head-drift (never merged/ci-failed for the
+old SHA) so the orchestrator can re-review the rewritten head.
+
+  --bound-minutes  stall bound (default 10) — restarts on any change to the delivery surface
+                   (PR state, queue state/position/membership, labels, CI fingerprint)
+  --interval-seconds  poll interval (default 90)
+  --max-minutes    absolute ceiling (default 60, hard maximum 60) — a backstop so a queue
+                   whose position keeps moving cannot keep the watch alive forever
+  --head           exact HEAD SHA for the CI→delivery pipeline; without it CI is not classified
+  --required-check-plan  frozen plan whose queue-head checks require synthetic execution evidence
+  --queue-execution-provider  stdin/stdout JSON provider polled for synthetic PR/check progress;
+                   on merge its result must validate as the final queue-execution artifact
+  --quiet          suppress the per-poll progress heartbeat on stderr
+
+stdout = exactly one terminal JSON verdict, at exit. stderr = one compact JSON record per
+poll (progress:true) unless --quiet, including synthetic PR identity and required queue-head
+check states when observable, so a healthy watch is visibly alive rather than silent.
+
+exit 0 = merged (mergedSha is the MERGE COMMIT; the caller still owes the ancestry proof)
+exit 4 = terminal but not merged — reason distinguishes the route:
+           dequeued / conditions-unmet / head-drift / unreadable → unit hand-back
+           stall-while-queued → queue still holds the PR; re-observe or relaunch the watch
+                               (do NOT unit-hand-back or re-enqueue the same HEAD)
+exit 5 = CI failed on the exact HEAD (--head set) — fold into a fix round; never a success
+exit 2 = usage error
+
+Bounded on STALL, not elapsed time: a unit can sit in a queue for an hour while genuinely
+advancing. Never exits 0 on a timeout — "still going" and "finished" must not collapse.
+A PR observed in the queue that later loses the queued label across two consecutive
+reads is a queue exit, not a healthy snapshot.`)
+    return 0
+  }
+  if (!f.pr || !f.repo) {
+    console.error('watch-delivery: --pr and --repo are required')
+    return 2
+  }
+  if (!Number.isFinite(f.boundMinutes) || f.boundMinutes <= 0 || !Number.isFinite(f.intervalSeconds) || f.intervalSeconds <= 0 || !Number.isFinite(f.maxMinutes) || f.maxMinutes <= 0) {
+    console.error('watch-delivery: --bound-minutes, --interval-seconds and --max-minutes must be positive numbers')
+    return 2
+  }
+  if (f.maxMinutes > MAX_MINUTES_CEILING) {
+    console.error(`watch-delivery: --max-minutes ${f.maxMinutes} exceeds the ${MAX_MINUTES_CEILING}-minute ceiling; hand back and relaunch instead of waiting longer`)
+    return 2
+  }
+
+  // Resolved and imported ONCE, ahead of the loop. Two things are reported rather than
+  // assumed: which source is answering membership, and — when the mergify watcher cannot be
+  // found — that this watch is running label-only. Degrading quietly is what made a weak
+  // dequeue resolution look like a healthy watch.
+  const watcherPath = resolveQueueWatcher(f.queueWatcher)
+  const observationCore = await loadMergifyObservationCore(watcherPath, f)
+  const readQueue = observationCore?.readQueue ?? null
+  const queueSource = readQueue ? `mergify queue show (${watcherPath})` : 'labels only'
+  if (!readQueue && f.provider === 'mergify') {
+    console.error(`watch-delivery: the mergify skill's watch-pr-delivery.mjs was not found, so queue membership `
+      + `is read from the queued/dequeued LABELS alone. Labels mirror the queue and can lag, go missing, or linger `
+      + `from a previous attempt, so a dequeue may resolve late or not at all. Pass --queue-watcher <path> to fix.`)
+  }
+
+  const startedMs = Date.now()
+  let lastKey = null
+  let lastChangeMs = startedMs
+  let observations = 0
+  let everQueued = false
+  let absentStreak = 0
+
+  for (;;) {
+    const bounds = [f.boundMinutes, f.maxMinutes].filter((n) => Number.isFinite(n) && n > 0)
+    const obs = observe(
+      f.pr,
+      f.repo,
+      f.intervalSeconds,
+      bounds.length ? Math.min(...bounds) : undefined,
+      observationCore?.dequeuedAtFromComments,
+    )
+    observations += 1
+    // History the classifier needs but a single observation cannot carry.
+    const qv = readQueue ? readQueue() : { available: false, active: null, readable: false }
+    const queueChecks = requiredCheckPlan ? checksForPhase(requiredCheckPlan, 'queue-head') : []
+    const queueRequest = queueChecks.length ? {
+      operation: 'read-queue-execution',
+      repository: f.repo,
+      pr: Number(f.pr),
+      prHeadSha: f.head ?? requiredCheckPlan?.headSha,
+      names: queueChecks.map((check) => check.name),
+    } : null
+    let queueExecution = null
+    let queueExecutionError = null
+    if (queueRequest) {
+      if (!f.queueExecutionProvider) {
+        queueExecutionError = 'queue-execution provider is unavailable'
+      } else {
+        const timeoutMs = readTimeoutMs(
+          f.intervalSeconds,
+          bounds.length ? Math.min(...bounds) : undefined,
+          3,
+        )
+        const result = invokeQueueExecutionProvider(f.queueExecutionProvider, queueRequest, { timeoutMs })
+        if (result.ok) queueExecution = result.value
+        else queueExecutionError = result.error
+      }
+    }
+    // The label OR the queue tool. `absentStreak` — the counter that settles a dequeue — may
+    // only advance on a READABLE absence, so an unavailable queue read must not feed it.
+    const queued = obs.labels.includes('queued') || qv.active === true
+    if (queued) everQueued = true
+    absentStreak = nextAbsentStreak({ queued, everQueued, absentStreak, readable: obs.readable !== false && (!qv.available || qv.readable) })
+    const prInput = { ...obs, everQueued, absentStreak, provider: f.provider, startedMs, queueActive: qv.available ? qv.active : null }
+    // Exact-HEAD gate first (#792 guarantee 3). A readable tip that no longer matches
+    // `--head` is a distinct head-drift hand-back — never a merged/ci-failed verdict for
+    // the old SHA. Unreadable polls skip this and fall through to the stall clock.
+    if (f.head && obs.readable) {
+      const drift = headDriftVerdict({ suppliedHead: f.head, headRefOid: obs.headRefOid })
+      if (drift) {
+        console.log(JSON.stringify({
+          ...drift,
+          head: f.head,
+          observations,
+          elapsedMs: Date.now() - startedMs,
+          readable: obs.readable,
+          queueSource,
+        }, null, 2))
+        return 4
+      }
+    }
+    // With --head this is the CI→delivery pipeline (#792): classify CI + PR together so a
+    // single background launch reaches a terminal delivery or CI-failed signal without a
+    // human turn. Without --head, preserve the prior delivery-only classification.
+    const ci = f.head ? classifyCiState({ checks: obs.checks }) : null
+    const verdict = f.head
+      ? classifyWatchPoll({ pr: prInput, ci })
+      : classifyPrState(prInput)
+    if (verdict.terminal) {
+      const queueCapture = verdict.outcome === 'merged' && requiredCheckPlan
+        ? captureQueueExecution(
+          queueRequest
+            ? () => {
+                if (queueExecutionError) throw new Error(queueExecutionError)
+                return queueExecution
+              }
+            : null,
+          {
+            repository: f.repo,
+            pr: Number(f.pr),
+            prHeadSha: f.head ?? requiredCheckPlan?.headSha,
+            requiredCheckPlan,
+          },
+        )
+        : { artifact: null, errors: [] }
+      const terminal = {
+        ...verdict,
+        ...(f.head ? { head: f.head } : {}),
+        observations,
+        elapsedMs: Date.now() - startedMs,
+        readable: obs.readable,
+        queueSource,
+        ...(queueCapture.artifact ? { queueExecutionArtifact: queueCapture.artifact } : {}),
+        ...(queueCapture.errors.length ? { evidenceBlocked: true, evidenceErrors: queueCapture.errors } : {}),
+      }
+      console.log(JSON.stringify(terminal, null, 2))
+      if (verdict.outcome === 'merged' && !terminal.evidenceBlocked) return 0
+      if (verdict.outcome === 'merged') return 4
+      if (verdict.reason === 'ci-failed') return 5
+      return 4
+    }
+    // Key the stall clock on the full delivery surface — PR state + queue tool + CI
+    // fingerprint — not the gh-only observation. See observationKey's incident note.
+    const queueActive = qv.available ? qv.active : null
+    const key = observationKey({
+      state: obs.state,
+      labels: obs.labels,
+      queueState: qv.available ? (qv.queueState ?? null) : null,
+      position: qv.available ? (qv.position ?? null) : null,
+      queueActive,
+      checks: obs.checks,
+      queueExecution,
+    })
+    const changed = key !== lastKey
+    if (changed) { lastKey = key; lastChangeMs = Date.now() }
+
+    // Heartbeat before the bound checks below, so the last line in the log before a hand-back
+    // is the unchanging observation that caused it — see `progressRecord`.
+    if (!f.quiet) {
+      const nowMs = Date.now()
+      console.error(progressRecord({
+        observation: {
+          outcome: verdict.outcome, reason: verdict.reason ?? null,
+          state: obs.state, mergedAt: obs.mergedAt, labels: obs.labels ?? [], readable: obs.readable !== false,
+          everQueued, absentStreak, observations, elapsedMs: nowMs - startedMs, queueSource, queueActive,
+          queueState: qv.available ? (qv.queueState ?? null) : null,
+          position: qv.available ? (qv.position ?? null) : null,
+          ...(queueExecution ? { queueExecution } : {}),
+          ...(queueExecutionError ? { queueExecutionError } : {}),
+        },
+        changed, sinceChangeMs: nowMs - lastChangeMs, nowIso: new Date(nowMs).toISOString(),
+      }))
+    }
+    // The absolute ceiling, and why it exists alongside the stall bound. Stall is the
+    // right *primary* bound — a unit can sit in `waiting_for_previous_batches` for an hour
+    // while genuinely advancing, so a flat timeout hands back healthy units. But a stall
+    // clock that resets on any observed change has no upper bound at all: a busy queue
+    // whose position keeps moving (5→4→3→2→1→5…) resets it every poll, and this loop never
+    // returns. For a job designed to run unattended in the background, "never returns" is
+    // a hang, not patience. So the ceiling is a backstop, deliberately generous, and it
+    // reports itself as such rather than as a stall.
+    const elapsedMs = Date.now() - startedMs
+    if (elapsedMs >= f.maxMinutes * 60_000) {
+      console.log(JSON.stringify({
+        terminal: true, outcome: 'handed-back', mergedSha: null, reason: 'conditions-unmet',
+        detail: `watch hit its absolute ceiling of ${f.maxMinutes}m while still observing change (${observations} observations) — the queue is moving but not finishing; this is a backstop, not a stall`,
+        observations, elapsedMs, readable: obs.readable,
+      }, null, 2))
+      return 4
+    }
+    const stall = stallVerdict({ lastChangeMs, nowMs: Date.now(), boundMinutes: f.boundMinutes })
+    if (stall.stalled) {
+      // Distinguishing "still held by the queue, picture frozen" from "nothing is holding
+      // this PR and conditions never cleared" is load-bearing for the orchestrator.
+      // issue-799-800 #807: a healthy PR sat in Mergify "Preparing checks" with labels
+      // unchanged for the whole bound; the watch exited conditions-unmet and the unit was
+      // treated as a terminal hand-back — then the PR merged two minutes later and the
+      // outcome was only written after a multi-hour session gap (outcome-write-lag).
+      // When membership is still active, the reason is stall-while-queued: exit 4 still
+      // (watch process ends) but the orchestrator must re-observe (one gh pr view / relaunch
+      // the watch), never record unit-level handed-back or re-enqueue the same HEAD.
+      const stillHeld = queueActive === true || (everQueued && obs.labels?.includes('queued'))
+      const reason = !obs.readable
+        ? 'unreadable'
+        : stillHeld
+          ? 'stall-while-queued'
+          : 'conditions-unmet'
+      const detail = stillHeld
+        ? `${stall.reason}; queue still holds this PR — relaunch the watch or re-observe once, do not hand the unit back or re-enqueue`
+        : stall.reason
+      console.log(JSON.stringify({
+        terminal: true, outcome: 'handed-back', mergedSha: null,
+        reason, detail, observations, elapsedMs: Date.now() - startedMs, readable: obs.readable,
+        queueActive, everQueued,
+      }, null, 2))
+      return 4
+    }
+    await sleep(f.intervalSeconds * 1000)
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  runCli(process.argv.slice(2)).then((code) => { process.exitCode = code })
+}