@1aboveio/skills 0.10.0

package/skills/cicd-pipeline/mergify/scripts/watch-pr-delivery-core.mjs

@@ -0,0 +1,663 @@
+import { execFileSync } from 'node:child_process'
+
+export function classifyObservation({
+  pr = {},
+  queue = {},
+  seenQueued = false,
+  // Process-local: membership was active at least once THIS run. Distinct from
+  // `seenQueued`, which `--seen-queued` may seed before any poll has confirmed
+  // membership (resume intent). Lost-membership DEQUEUED requires everActive —
+  // otherwise a pre-admission watch with `--seen-queued` false-fires after two
+  // clean "not in queue" reads (epic-824 #859 watch-859-component-818).
+  //
+  // Default `null` = "not supplied" so pure unit callers that only pass seenQueued
+  // keep the pre-everActive lost-membership semantics. The poll loop always passes
+  // an explicit boolean.
+  everActive = null,
+  missingActiveReads = 0,
+  startedMs = null,
+  dequeuedAtMs = null,
+} = {}) {
+  const labels = Array.isArray(pr.labels) ? pr.labels : []
+  const hasQueuedLabel = labels.includes('queued')
+  const hasDequeuedLabel = labels.includes('dequeued')
+  const queueQueued = queue.queued === true
+  const active = hasQueuedLabel || queueQueued
+  // Sticky true once observed or supplied; false only when explicitly false and inactive.
+  const ever = everActive === true || active
+  // Lost-membership may fire when: (a) caller did not supply everActive and seenQueued
+  // is true (legacy), or (b) everActive is true (process observed membership).
+  // Explicit everActive=false with seeded seenQueued is the pre-admission resume case.
+  const mayCountLoss = everActive === null ? seenQueued === true : ever
+
+  if (pr.state === 'MERGED' || pr.mergedAt) {
+    if (!pr.mergeCommitOid) {
+      return { terminal: true, outcome: 'CLOSED_UNMERGED', reason: 'merged-without-sha', active, seenQueued: seenQueued || active, everActive: ever }
+    }
+    return { terminal: true, outcome: 'MERGED', mergedSha: pr.mergeCommitOid, active, seenQueued: seenQueued || active, everActive: ever }
+  }
+  if (pr.state === 'CLOSED') {
+    return { terminal: true, outcome: 'CLOSED_UNMERGED', reason: 'closed-unmerged', active, seenQueued: seenQueued || active, everActive: ever }
+  }
+  // Issue #629: a `dequeued` label is a lifecycle MIRROR of Mergify's queue, never removed on
+  // re-enqueue — so a PR dequeued once, fixed, and re-enqueued still carries the label from
+  // the first attempt into a watch launched for the second one. Two guards, both from the
+  // issue, cheapest first:
+  //
+  // 1. Mergify (or a fresh `queued` label) is authoritative for membership. When either
+  //    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 the phase-aware stall / --max-minutes and hands back honestly, whereas one that
+  //    terminates early reports the PREVIOUS attempt's outcome as this one's, as fact — and
+  //    on the resolve-issues path that outcome is what routes the unit.
+  //
+  //    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
+  if (hasDequeuedLabel && !active) {
+    const isThisWatchsDequeue = Number.isFinite(startedMs) && Number.isFinite(dequeuedAtMs) && dequeuedAtMs >= startedMs - DEQUEUE_TIMESTAMP_GRACE_MS
+    if (isThisWatchsDequeue) {
+      return { terminal: true, outcome: 'DEQUEUED', reason: 'dequeued-label', active, seenQueued: true, everActive: ever }
+    }
+  }
+  if (active) {
+    return {
+      terminal: false,
+      outcome: 'QUEUED',
+      active,
+      seenQueued: true,
+      everActive: true,
+      queueState: queue.queueState || queue.state || null,
+      position: queue.position ?? null,
+    }
+  }
+  // Lost-membership needs mayCountLoss (everActive observed, or legacy seenQueued-only
+  // callers). Explicit everActive=false with seeded seenQueued is pre-admission resume:
+  // do not count absences or fire DEQUEUED (epic-824 #859 first watch).
+  if (mayCountLoss && missingActiveReads >= 2) {
+    return {
+      terminal: true,
+      outcome: 'DEQUEUED',
+      reason: 'lost-queue-membership',
+      // Issue #615 item 5: an unreadable poll now carries `missingActiveReads` forward
+      // unchanged rather than resetting it (see `nextMissingActiveReads` above), so the
+      // two absences that settle this can be separated by an arbitrarily long unreadable
+      // gap — "consecutive reads" over-claims. They are consecutive READABLE reads.
+      detail: 'PR was observed queued, then active Mergify queue membership disappeared across consecutive readable reads without a merge.',
+      active,
+      seenQueued: true,
+      everActive: ever,
+    }
+  }
+  if (mayCountLoss) {
+    return { terminal: false, outcome: 'WAITING', reason: 'queue-membership-missing-reread', active, seenQueued: true, everActive: ever }
+  }
+  // Seeded seenQueued with explicit everActive=false: still pre-admission for THIS process.
+  // Keep seenQueued so phases/callers retain the resume hint, but do not start the
+  // lost-membership counter until membership is observed.
+  return { terminal: false, outcome: 'NOT_YET_QUEUED', active, seenQueued: seenQueued === true, everActive: false }
+}
+
+// The ordered list of lifecycle phases this watch has actually passed through — the
+// progression the contract is about, made visible to the caller.
+//
+// Why it is worth carrying: the terminal outcome alone is ambiguous in exactly the place the
+// contract is subtle. `STALLED` after `["NOT_YET_QUEUED"]` means the PR was NEVER admitted —
+// on a manual-delivery repo that almost always means nobody enqueued it, and the fix is an
+// enqueue, not an investigation. `STALLED` after `["NOT_YET_QUEUED","QUEUED"]` means it was
+// admitted and then wedged INSIDE the queue, where the fix is reading the blocking condition.
+// Same verdict string, opposite diagnosis; `seenQueued` carries the bit but not the shape, and
+// a caller reconstructing the shape from the heartbeat stream has to have kept every record.
+//
+// `WAITING` is deliberately not a phase. It is the re-read suspicion state that sits INSIDE
+// `QUEUED` (membership missing once, not yet settled — see `classifyObservation`), so recording
+// it would make a healthy queued PR oscillate QUEUED/WAITING/QUEUED and turn this into noise
+// rather than a progression. Anything not in `LIFECYCLE_PHASES` leaves the list untouched.
+export const LIFECYCLE_PHASES = new Set(['NOT_YET_QUEUED', 'QUEUED', 'MERGED', 'DEQUEUED', 'CLOSED_UNMERGED', 'STALLED'])
+
+export function nextPhases(phases = [], outcome) {
+  const list = Array.isArray(phases) ? phases : []
+  if (!LIFECYCLE_PHASES.has(outcome)) return list
+  if (list[list.length - 1] === outcome) return list
+  return [...list, outcome]
+}
+
+export function observationKey({ pr = {}, queue = {} } = {}) {
+  const labels = Array.isArray(pr.labels) ? [...pr.labels].sort().join(',') : ''
+  return JSON.stringify([
+    pr.state ?? null,
+    pr.mergedAt ?? null,
+    labels,
+    queue.queued ?? null,
+    queue.queueState ?? queue.state ?? null,
+    queue.position ?? null,
+  ])
+}
+
+// A failed subprocess 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 `lost-queue-membership` in `classifyObservation`. Fixes #611 defect 1: two
+// consecutive transient `gh`/`mergify` failures were previously indistinguishable from two
+// consecutive genuine "not queued" reads, and both incremented the same counter.
+export function nextMissingActiveReads({
+  active,
+  // Prefer everActive when supplied. Fall back to seenQueued for older callers so a
+  // genuine post-entry loss still counts; new callers pass everActive=false until
+  // membership is observed in-process (closes the --seen-queued pre-admission false DEQUEUE).
+  everActive = null,
+  seenQueued = false,
+  missingActiveReads = 0,
+  readable = true,
+} = {}) {
+  if (active) return 0
+  const mayCount = everActive === null ? seenQueued === true : everActive === true
+  if (!mayCount) return missingActiveReads
+  return readable ? missingActiveReads + 1 : missingActiveReads
+}
+
+export function stallVerdict({ lastChangeMs, nowMs, stallMinutes }) {
+  const bound = Number(stallMinutes)
+  if (!Number.isFinite(bound) || bound <= 0) return { stalled: false, reason: 'invalid stall bound' }
+  const stalledForMs = nowMs - lastChangeMs
+  return stalledForMs >= bound * 60_000
+    ? { stalled: true, stalledForMs, reason: `no observable Mergify delivery-state change for ${Math.round(stalledForMs / 60_000)}m` }
+    : { stalled: false, stalledForMs }
+}
+
+// Phase-aware no-change bound. Pre-admission (`everActive` still false) uses the shorter
+// admission stall — queue entry after a real enqueue should appear quickly, and burning the
+// full post-entry bound on a dead admission path is pure wait cost. Once this process has
+// observed membership, use the full stall bound: batch wait / bisect can sit still for longer
+// while still being healthy. Admission is never allowed to exceed the post-entry stall, so a
+// caller that shortens `--stall-minutes` for tests or a suspect PR keeps both phases tight.
+export function effectiveStallMinutes({
+  everActive = false,
+  stallMinutes = DEFAULT_STALL_MINUTES,
+  admissionStallMinutes = DEFAULT_ADMISSION_STALL_MINUTES,
+} = {}) {
+  const post = Number(stallMinutes)
+  if (!Number.isFinite(post) || post <= 0) return { minutes: NaN, phase: 'invalid' }
+  if (everActive === true) return { minutes: post, phase: 'queued' }
+  const admission = Number(admissionStallMinutes)
+  const pre = Number.isFinite(admission) && admission > 0 ? Math.min(admission, post) : post
+  return { minutes: pre, phase: 'admission' }
+}
+
+// Fixes #611 defect 2: `execFileSync` had no `timeout`, so a stalled TLS handshake or hung
+// `gh`/`mergify` invocation blocked the watcher past both `--stall-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 (measured
+// ~4.5s wall for a healthy `gh pr view`) never trips it, but 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 the effective phase stall bound capped by `--max-minutes`)
+// so a single read's own timeout can never exceed the watch's own stall/ceiling bounds;
+// otherwise a small `--stall-minutes` / `--admission-stall-minutes` on a slow/misconfigured
+// `--interval-seconds` could let one hung read alone outlive the bound it is meant to sit
+// inside of. Pre-admission uses the shorter admission bound; post-entry uses the full stall.
+//
+// Issue #615 item 1 (round-2 NOTE-2 on #612): clamping to the *whole* bound is only correct
+// for a watcher that makes ONE read per poll. This watcher makes TWO (`gh pr view` +
+// `mergify queue show`), and the stall/ceiling bounds are evaluated only after both reads in
+// a poll return — so clamping each read to the full bound let a single poll take up to
+// `2 x min(effectiveStall, max)` before the loop ever checked it, a 2x overrun the reviewer
+// measured live as 58s against a 12s stall bound. Dividing the clamp by `readsPerPoll` keeps
+// the *sum* of a poll's reads inside the bound: this watcher passes 2 (`READS_PER_POLL`
+// below), the sibling (`watch-delivery.mjs`, one read per poll) passes 1 and is unaffected
+// (dividing by 1 is a no-op) — matching `references/watch-contract.md`'s claim, made true
+// rather than aspirational.
+// Shared by `parseArgs` and `readTimeoutMs`'s defensive fallback, so the two can never drift
+// apart and make the "falls back to the documented default" claim quietly false.
+export const DEFAULT_INTERVAL_SECONDS = 90
+export const DEFAULT_STALL_MINUTES = 10
+// Pre-admission only: never observed membership this process. After enqueue, queue entry
+// should show up well inside a few minutes; waiting the full post-entry stall on a dead
+// admission path (stale Mergify status, unreadable queue API, forgotten enqueue) is pure cost.
+export const DEFAULT_ADMISSION_STALL_MINUTES = 3
+export const DEFAULT_MAX_MINUTES = 60
+
+// A hard ceiling on the absolute ceiling, enforced in `runCli` rather than left to the caller's
+// judgement. `--max-minutes` is the backstop that bounds a watch whose queue keeps reporting
+// change — the case `--stall-minutes` deliberately cannot catch, because movement resets it. So
+// it is the only bound standing between "the queue is busy" and a watch that outlives the
+// session that launched it, and a value nobody sanity-checks is exactly how that happens.
+//
+// One hour is chosen against what the bound is actually protecting: a batch takes minutes, so an
+// hour of continuous movement without finishing is already a queue worth handing back to a human
+// rather than waiting out. Handing back at 60m and relaunching is strictly better than a blind
+// 120m wait — the caller gets a `phases`-carrying verdict it can route on, an hour sooner.
+//
+// Over-ceiling values are REFUSED (exit 2), not silently clamped. Clamping would let a caller
+// believe it had a four-hour watch while getting one hour, and the two streams here are already
+// committed: stdout is exactly one terminal JSON verdict, stderr is one NDJSON heartbeat per
+// poll, so there is no channel for a warning that would not break a documented contract. An
+// exit-2 usage error is loud, immediate, and matches how every other bad bound is handled.
+export const MAX_MINUTES_CEILING = 60
+
+export function readTimeoutMs(intervalSeconds, boundMinutes, readsPerPoll = 1) {
+  const seconds = Number(intervalSeconds)
+  const bounded = Number.isFinite(seconds) && seconds > 0 ? seconds : DEFAULT_INTERVAL_SECONDS
+  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
+}
+
+// Both subprocess reads this watcher makes per poll — `gh pr view` in `prObservation`,
+// `mergify queue show` in `queueObservation`. See `readTimeoutMs` above.
+const READS_PER_POLL = 2
+
+export function run(cmd, args, options = {}) {
+  try {
+    return { ok: true, stdout: execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...options }) }
+  } catch (error) {
+    return { ok: false, stdout: error.stdout?.toString?.() || '', stderr: error.stderr?.toString?.() || error.message || '', error }
+  }
+}
+
+// Issue #615 items 3-4 (round-2 NOTE-1 on #612): `JSON.parse(text || '{}')` treated an
+// empty string as a valid, truthy `{}` object rather than the honest "not JSON" answer —
+// the same manufactured-informative-read shape `queueObservation`'s BLOCK-1 fix closed for
+// the mergify-CLI path. `prObservation` calls this on `result.ok === true` output only, so
+// the live BLOCK-1 defect never reached it (a failed/timed-out `gh` is caught earlier by
+// `if (!result.ok)`), but a `gh` that exits 0 with empty stdout — unreachable by any
+// current caller, never reproduced against a real `gh` — would have manufactured a
+// `readable: true` observation from nothing. Dropping the fallback closes the class at its
+// root for both call sites: `JSON.parse('')` throwing is the honest answer, matching the
+// sibling watcher's raw `JSON.parse` (`watch-delivery.mjs`'s `observe()`), which was already
+// safe by construction for exactly this reason.
+function parseJson(text) {
+  try { return JSON.parse(text) } catch { return null }
+}
+
+// Issue #629: the one piece of history a single `labels` snapshot cannot carry — WHEN a
+// `dequeued` label was applied. `gh pr view --json` has no `timelineItems` field in the CLI
+// version this was built against (`gh pr view --json timelineItems` errors "Unknown JSON
+// field"), so this reads the other source the issue names: Mergify's own status comment.
+//
+// BLOCK-1/2 fix (independent review on PR #637): the first version of this function read
+// `mergifyComments[mergifyComments.length - 1]` — "the last mergify-authored comment" — on the
+// premise that it "reflects the most recent cycle". That premise is false: Mergify also
+// authors merge-protection summaries and command acknowledgements from the same account, and
+// those interleave with (and are very often more recent than) the actual queue-status
+// comments. Verified against the REAL payload of PR #620 — the PR issue #629 reproduces on —
+// via `gh pr view --json comments`: of its 4 mergify-authored comments, the one carrying
+// `Left the queue — 2026-07-28 11:04 UTC` is NOT the last one; the last one is a
+// `> queue` / "Command ignored because it is already running" acknowledgement with no payload
+// at all. The shipped helper returned `null` against this exact real data, which made guard 2
+// (the freshness check below) dead code in production: for a GENUINE dequeue the watcher never
+// saw `queued` for, neither this path nor the `missingActiveReads`/`absentStreak` fallback
+// (which requires having observed `queued` first) can fire, so the watch ran to
+// `--max-minutes` instead of settling (reproduced: `reason: 'conditions-unmet',
+// observations: 7`).
+//
+// Fix: every Mergify status comment opens with a machine-readable, HTML-commented payload —
+// `<!--- DO NOT EDIT -*- Mergify Payload -*- {"version":1,"state":"dequeued",...} -*- Mergify
+// Payload End -*- -->` (NOTE-3) — which is exactly the discriminator "is this comment a queue-
+// status comment at all" that the length-based pick was missing. Scan ALL mergify comments,
+// parse each one's payload, and select the LAST one whose `state` is `"dequeued"`.
+//
+// Deliberate choice, because getting it wrong the other way reproduces the same class of bug:
+// this reads for the most recent comment whose STATE HAPPENS TO BE "dequeued" — not simply
+// "the most recent status comment, whatever its state" (on #620 that is the `state:"merged"`
+// comment, and keying off it would read a freshly-MERGED PR as still dequeued). The `dequeued`
+// label lingers on the PR without being cleared across a later re-enqueue, so the label's own
+// claim is "the last attempt that dequeued was THIS one" — the comment that actually made that
+// claim is the one this function must find. If a later attempt is active or merged, the
+// `active`/merged branches in the callers below already win before this function is even
+// consulted for a terminal verdict.
+//
+// The payload has no millisecond-precision exit timestamp of its own (only `queued_at`, the
+// ENTRY time for that attempt) — so the actual "Left the queue" instant still comes from that
+// selected comment's rendered text (kept as NOTE-3's suggested fallback source, not replaced
+// by it). That text is minute-precision with no timezone beyond a literal `UTC` suffix, and
+// it is Mergify's SERVER clock, compared below against this machine's local `Date.now()`
+// (`startedMs`) — a locally-slow clock could in principle make a stale dequeue read as fresh;
+// low risk on an NTP-synced host, called out here rather than silently assumed away (NOTE-2).
+//
+// Returns epoch milliseconds, or null when no mergify comment's payload reports
+// `state: "dequeued"`, or that comment has no parseable "Left the queue" line — callers must
+// treat null as "no reliable timestamp", never as "not dequeued".
+const MERGIFY_PAYLOAD_RE = /-\*- Mergify Payload -\*-\s*\n(\{[\s\S]*?\})\s*\n-\*- Mergify Payload End -\*-/
+const LEFT_QUEUE_RE = /Left the queue\*\*[^`\n]*`(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}) UTC`/g
+
+export function dequeuedAtFromComments(comments) {
+  const list = Array.isArray(comments) ? comments : []
+  const mergifyComments = list.filter((c) => c && c.author && c.author.login === 'mergify')
+  let target = null
+  for (const comment of mergifyComments) {
+    const body = typeof comment.body === 'string' ? comment.body : ''
+    const payloadMatch = MERGIFY_PAYLOAD_RE.exec(body)
+    if (!payloadMatch) continue
+    let payload
+    try { payload = JSON.parse(payloadMatch[1]) } catch { continue }
+    if (payload && payload.state === 'dequeued') target = comment // last match wins — comments are chronological
+  }
+  if (!target) return null
+  const body = typeof target.body === 'string' ? target.body : ''
+  let match
+  let last = null
+  LEFT_QUEUE_RE.lastIndex = 0
+  while ((match = LEFT_QUEUE_RE.exec(body))) last = match
+  if (!last) return null
+  const [, y, mo, d, h, mi] = last
+  return Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi))
+}
+
+// Exported so tests can pin that the live read timeout uses the same phase-aware bound the
+// stall clock will fire on — a hung pre-admission poll must not outlive admission-stall, and
+// a post-entry poll must not be clamped to the shorter admission bound forever.
+export function readTimeoutForArgs({
+  intervalSeconds,
+  stallMinutes,
+  admissionStallMinutes,
+  maxMinutes,
+  everActive = false,
+} = {}) {
+  const { minutes: phaseBound } = effectiveStallMinutes({
+    everActive,
+    stallMinutes,
+    admissionStallMinutes,
+  })
+  const bounds = [phaseBound, maxMinutes].filter((n) => Number.isFinite(n) && n > 0)
+  return readTimeoutMs(intervalSeconds, bounds.length ? Math.min(...bounds) : undefined, READS_PER_POLL)
+}
+
+function prObservation({ repo, pr, intervalSeconds, stallMinutes, admissionStallMinutes, maxMinutes, everActive = false }) {
+  // `comments` costs nothing extra to request 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.
+  const result = run('gh', ['pr', 'view', String(pr), '--repo', repo, '--json', 'state,mergedAt,mergeCommit,labels,url,comments'], { timeout: readTimeoutForArgs({ intervalSeconds, stallMinutes, admissionStallMinutes, maxMinutes, everActive }) })
+  if (!result.ok) return { readable: false, error: result.stderr || result.stdout }
+  const data = parseJson(result.stdout)
+  if (!data) return { readable: false, error: 'gh pr view returned invalid JSON' }
+  return {
+    readable: true,
+    state: data.state || null,
+    mergedAt: data.mergedAt || null,
+    mergeCommitOid: data.mergeCommit?.oid || null,
+    labels: (data.labels || []).map((label) => label.name).filter(Boolean),
+    url: data.url || null,
+    dequeuedAtMs: dequeuedAtFromComments(data.comments),
+  }
+}
+
+export function mergifyQueueShowArgs({ pr, repo }) {
+  return ['queue', '--repository', repo, 'show', String(pr), '--json']
+}
+
+// Exported so the resolve-issues delivery watcher can use THIS reading of queue membership
+// rather than keeping a second copy. That watcher is label-only today, which is why its
+// dequeue resolution is weak: a `queued` label that lags or a `dequeued` label that never
+// lands leaves it with no second opinion, while `mergify queue show --json` is authoritative
+// for membership. Two copies of this inference would drift — and the `queued`-field trap
+// below is exactly the kind of detail one copy would miss.
+export function queueObservation({ pr, repo, intervalSeconds, stallMinutes, admissionStallMinutes, maxMinutes, everActive = false }) {
+  const result = run('mergify', mergifyQueueShowArgs({ pr, repo }), { timeout: readTimeoutForArgs({ intervalSeconds, stallMinutes, admissionStallMinutes, maxMinutes, everActive }) })
+  // BLOCK-1 fix (independent review on #612): `parseJson` falls back to `'{}'` on empty
+  // input, and `{}` is truthy — so a failed or timed-out `mergify` process (empty stdout,
+  // its message on stderr) parsed to a truthy `{}` and fell into the "successfully read"
+  // branch below, reporting `readable: true, queued: false`. That made `queueObservation`
+  // the one place in this file that DID treat an unreadable read as informative, defeating
+  // the exact fix `nextMissingActiveReads` exists for: two consecutive `mergify` failures
+  // read as two consecutive genuine "not queued" reads and settled a false DEQUEUED, and a
+  // timed-out `mergify` (defect 2's fix) fed the same false path, arriving *faster* than the
+  // stall bound rather than routing through it. `result.ok` (exit code) AND non-empty stdout
+  // are both required before the parsed body is trusted; a non-zero exit or empty stdout is
+  // exactly the shape of a failed/timed-out subprocess, not a real answer.
+  const stdoutText = typeof result.stdout === 'string' ? result.stdout.trim() : ''
+  const parsed = result.ok && stdoutText ? parseJson(stdoutText) : null
+  if (parsed) {
+    return {
+      readable: true,
+      queued: parsed.queued === true || Boolean(parsed.queue_rule_name || parsed.queue_rule),
+      queueState: parsed.status || parsed.state || parsed.mergeability_check?.state || null,
+      position: typeof parsed.position === 'number' ? parsed.position : null,
+      raw: parsed,
+    }
+  }
+  const text = `${result.stdout}\n${result.stderr}`.trim()
+  if (/not in the merge queue|not queued|not found/i.test(text)) return { readable: true, queued: false, queueState: 'not-queued', position: null, raw: text }
+  return { readable: false, queued: false, queueState: null, position: null, raw: text || 'mergify queue show failed' }
+}
+
+// Every poll's observation, as one compact NDJSON record — the watcher's heartbeat.
+//
+// Before this existed the loop's ONLY output sites were the three terminal ones (`MERGED`/
+// `DEQUEUED`/`CLOSED_UNMERGED` below, plus the two `STALLED` paths), so a watch sitting in
+// `NOT_YET_QUEUED` or `QUEUED` — the overwhelmingly common case, and the entire healthy path —
+// wrote zero bytes for its whole life. Reproduced live on PR #1396: 25 minutes of watching a
+// PR that was never queued produced a log containing only the harness's own spawn banner, and
+// the watch was killed 4 minutes short of the then-30-minute stall bound, so it never printed
+// even its terminal verdict. (The bound is 10 now, so that same watch would settle on its own
+// well before a human gave up on it — but the heartbeat is what makes the wait legible while
+// it runs, and no bound short enough to substitute for it would be long enough to be correct.) A silent process is indistinguishable from a hung or dead one, which is
+// exactly the state the caller is trying to resolve, and the hand-written shell watchers this
+// script is meant to replace all printed a per-poll status line. Losing that on the way to a
+// correct state machine traded one failure (wrong answers) for another (no answers).
+//
+// Deliberately stderr, not stdout: stdout is the machine contract — exactly one pretty-printed
+// terminal JSON object, which callers parse whole — and interleaving heartbeats into it would
+// break every such caller. stderr is unparsed by the contract and is merged into the log by
+// every process supervisor that would run this, which is the place a human actually looks.
+// `terminal: false` and the separate stream both distinguish these from the real verdict.
+export function progressRecord({ payload, changed, sinceChangeMs, nowIso }) {
+  return JSON.stringify({ ...payload, progress: true, changed, sinceChangeMs, at: nowIso })
+}
+
+// Defaults. `stallMinutes` is a NO-CHANGE bound, not an elapsed-time one — any observable
+// movement (queue position, label, queue state) resets it — so 10 minutes of a completely
+// frozen picture is already a long time to wait before handing back, and the earlier 30 (then
+// 15) multiplied every dead watch's cost for no added signal. At a 90s poll, 10 minutes is
+// still ~6 consecutive identical observations before the watch calls it — comfortably more
+// than a transient blip. `intervalSeconds` at 90 also cuts the
+// API budget: two reads per poll is 80/hour per watched PR, against 240/hour at the old 30s,
+// which is what makes an epic-sized fan-out of concurrent watchers fit inside an authenticated
+// token's 5,000/hour limit. The cost is at most 90s of extra merge-detection latency on a
+// queue that takes minutes per batch.
+export function parseArgs(argv) {
+  const args = {
+    intervalSeconds: DEFAULT_INTERVAL_SECONDS,
+    stallMinutes: DEFAULT_STALL_MINUTES,
+    admissionStallMinutes: DEFAULT_ADMISSION_STALL_MINUTES,
+    maxMinutes: DEFAULT_MAX_MINUTES,
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--repo') args.repo = argv[++i]
+    else if (arg === '--pr') args.pr = argv[++i]
+    else if (arg === '--interval-seconds') args.intervalSeconds = Number(argv[++i])
+    else if (arg === '--stall-minutes') args.stallMinutes = Number(argv[++i])
+    else if (arg === '--admission-stall-minutes') args.admissionStallMinutes = Number(argv[++i])
+    else if (arg === '--max-minutes') args.maxMinutes = Number(argv[++i])
+    else if (arg === '--seen-queued') args.seenQueued = true
+    else if (arg === '--quiet') args.quiet = true
+    else if (arg === '--help' || arg === '-h') args.help = true
+    else args.unknown = arg
+  }
+  return args
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function help() {
+  return `watch-pr-delivery --repo <owner/name> --pr <number> [options]
+
+Observe a Mergify-queued PR until MERGED, DEQUEUED, CLOSED_UNMERGED, or STALLED.
+The script observes only; it never queues, dequeues, merges, or records state.
+
+Enqueue first. On a repo with manual delivery (no auto_merge_conditions, autoqueue: false)
+an unqueued PR never enters the queue on its own, so this watch can only ever end STALLED.
+
+Options:
+  --interval-seconds <n>         Poll interval, default 90
+  --stall-minutes <n>            Post-entry stall bound (no-change, not elapsed), default 10
+  --admission-stall-minutes <n>  Pre-admission stall bound (never observed membership), default 3.
+                                 For CI-gated admission (Mergify waiting on a check), relaunch
+                                 with 15 and raise --stall-minutes to at least 15; do not use 60.
+  --max-minutes <n>              Absolute safety ceiling, default 60, hard maximum 60
+  --seen-queued                  Resume hint only: keep phases/callers aware the PR was queued.
+                                 Does NOT seed lost-membership counting — membership must be
+                                 observed in this process (everActive) before DEQUEUED can fire.
+  --quiet                        Suppress the per-poll progress heartbeat on stderr
+
+Output:
+  stdout  exactly one pretty-printed terminal JSON verdict, at exit
+  stderr  one compact JSON progress record per poll (progress:true), unless --quiet
+
+Both carry "phases": the lifecycle progression observed so far, in order — e.g.
+["NOT_YET_QUEUED"] ending STALLED reason admission-stall means never admitted (enqueue it),
+while ["NOT_YET_QUEUED","QUEUED"] ending STALLED reason stall-bound means admitted then
+wedged in the queue.
+
+Exit codes:
+  0  MERGED; stdout JSON includes mergedSha, which still needs ancestry proof
+  4  terminal but not merged: DEQUEUED, CLOSED_UNMERGED, or STALLED
+  2  usage error
+
+Contract: this watches a progression, not a state. Once queue entry has been observed,
+queued:false is a queue exit unless the PR merged.`
+}
+
+export async function runCli(argv) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    console.log(help())
+    return 0
+  }
+  if (args.unknown || !args.repo || !args.pr) {
+    console.error(help())
+    return 2
+  }
+  for (const key of ['intervalSeconds', 'stallMinutes', 'admissionStallMinutes', 'maxMinutes']) {
+    if (!Number.isFinite(args[key]) || args[key] <= 0) {
+      console.error(`${key} must be a positive number`)
+      return 2
+    }
+  }
+  if (args.maxMinutes > MAX_MINUTES_CEILING) {
+    console.error(
+      `--max-minutes ${args.maxMinutes} exceeds the ${MAX_MINUTES_CEILING}-minute ceiling. ` +
+      'A watch that outlives its session is worse than one that hands back: relaunch after a ' +
+      `${MAX_MINUTES_CEILING}m verdict instead. See MAX_MINUTES_CEILING for why.`,
+    )
+    return 2
+  }
+
+  const startedMs = Date.now()
+  // `--seen-queued` seeds resume intent only. everActive flips only after THIS process
+  // observes membership — required before lost-queue-membership can fire.
+  let seenQueued = args.seenQueued === true
+  let everActive = false
+  let missingActiveReads = 0
+  let lastKey = null
+  let lastChangeMs = startedMs
+  let observations = 0
+  let phases = []
+
+  for (;;) {
+    // Pass everActive into the reads so their per-child timeout tracks the phase bound that
+    // will actually fire STALLED this poll. Dropping it left admissionStallMinutes on args
+    // unused (destructuring stripped it) and hung pre-admission polls could outlive the 3m
+    // admission clock while still being clamped only to the 10m post-entry bound.
+    const pr = prObservation({ ...args, everActive })
+    const queue = queueObservation({ ...args, everActive })
+    observations += 1
+    const active = (Array.isArray(pr.labels) && pr.labels.includes('queued')) || queue.queued === true
+    const readable = pr.readable !== false || queue.readable !== false
+    if (active) {
+      seenQueued = true
+      everActive = true
+    }
+    missingActiveReads = nextMissingActiveReads({ active, everActive, seenQueued, missingActiveReads, readable })
+
+    const verdict = classifyObservation({
+      pr,
+      queue,
+      seenQueued,
+      everActive,
+      missingActiveReads,
+      startedMs,
+      dequeuedAtMs: pr.dequeuedAtMs ?? null,
+    })
+    if (verdict.everActive === true) everActive = true
+    if (verdict.seenQueued === true) seenQueued = true
+    phases = nextPhases(phases, verdict.outcome)
+    const payload = {
+      outcome: verdict.outcome,
+      terminal: verdict.terminal,
+      reason: verdict.reason || null,
+      detail: verdict.detail || null,
+      mergedSha: verdict.mergedSha || null,
+      seenQueued,
+      everActive,
+      phases,
+      missingActiveReads,
+      observations,
+      elapsedMs: Date.now() - startedMs,
+      pr: { state: pr.state || null, mergedAt: pr.mergedAt || null, labels: pr.labels || [], url: pr.url || null, readable: pr.readable !== false, dequeuedAtMs: pr.dequeuedAtMs ?? null },
+      queue: { queued: queue.queued === true, queueState: queue.queueState || null, position: queue.position ?? null, readable: queue.readable !== false },
+    }
+
+    if (verdict.terminal) {
+      console.log(JSON.stringify(payload, null, 2))
+      return verdict.outcome === 'MERGED' ? 0 : 4
+    }
+
+    const key = observationKey({ pr, queue })
+    const changed = key !== lastKey
+    if (changed) {
+      lastKey = key
+      lastChangeMs = Date.now()
+    }
+
+    // Heartbeat before the bound checks below, so the last thing in the log before a STALLED
+    // verdict is the unchanging observation that produced it — see `progressRecord`.
+    if (!args.quiet) {
+      const now = Date.now()
+      console.error(progressRecord({ payload, changed, sinceChangeMs: now - lastChangeMs, nowIso: new Date(now).toISOString() }))
+    }
+
+    const elapsedMs = Date.now() - startedMs
+    if (elapsedMs >= args.maxMinutes * 60_000) {
+      console.log(JSON.stringify({ ...payload, terminal: true, outcome: 'STALLED', phases: nextPhases(phases, 'STALLED'), reason: 'max-minutes', detail: `watch exceeded ${args.maxMinutes}m absolute ceiling` }, null, 2))
+      return 4
+    }
+    // Phase-aware bound: pre-admission uses --admission-stall-minutes (default 3); once this
+    // process has observed membership, use the full --stall-minutes (default 10). Outcome
+    // stays STALLED either way — only reason/detail (and wall time) change. Callers already
+    // route on phases for never-admitted vs wedged-in-queue.
+    const bound = effectiveStallMinutes({
+      everActive,
+      stallMinutes: args.stallMinutes,
+      admissionStallMinutes: args.admissionStallMinutes,
+    })
+    const stall = stallVerdict({ lastChangeMs, nowMs: Date.now(), stallMinutes: bound.minutes })
+    if (stall.stalled) {
+      // Same theme as `nextMissingActiveReads`, surfaced for a human/caller reading the
+      // terminal payload: a stall reached while the most recent poll was unreadable is not
+      // the same situation as a stall reached on clean, unchanging reads — the sibling
+      // watcher (`watch-delivery.mjs`) already makes this distinction on its own stall path.
+      // Readable pre-admission stalls are `admission-stall` so a dead admission path is not
+      // mistaken for a queue that admitted and then froze.
+      const reason = !readable ? 'unreadable' : (bound.phase === 'admission' ? 'admission-stall' : 'stall-bound')
+      console.log(JSON.stringify({ ...payload, terminal: true, outcome: 'STALLED', phases: nextPhases(phases, 'STALLED'), reason, detail: stall.reason }, null, 2))
+      return 4
+    }
+
+    await sleep(args.intervalSeconds * 1000)
+  }
+}