@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,1065 @@
+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 }
+  }
+  if (Array.isArray(pr.failedChecks) && pr.failedChecks.length > 0) {
+    return {
+      terminal: true,
+      outcome: 'STALLED',
+      reason: 'admission-checks-failed',
+      detail: 'PR admission failed before active Mergify queue membership was observed.',
+      failedChecks: pr.failedChecks,
+      active,
+      seenQueued: seenQueued === true,
+      everActive: false,
+      preAdmission: true,
+    }
+  }
+  // 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(',') : ''
+  const checks = [...(pr.failedChecks || []), ...(pr.pendingChecks || [])]
+    .map((check) => `${check.name}:${check.status}`)
+    .sort()
+    .join(',')
+  return JSON.stringify([
+    pr.state ?? null,
+    pr.mergedAt ?? null,
+    pr.headRefOid ?? null,
+    labels,
+    checks,
+    queue.queued ?? null,
+    queue.queueState ?? queue.state ?? null,
+    queue.position ?? null,
+    queue.batchPrNumber ?? null,
+  ])
+}
+
+function stallPrSnapshot(pr = {}) {
+  return {
+    state: pr.state ?? null,
+    mergedAt: pr.mergedAt ?? null,
+    headRefOid: pr.headRefOid ?? null,
+    labels: Array.isArray(pr.labels) ? [...pr.labels] : [],
+    failedChecks: Array.isArray(pr.failedChecks) ? pr.failedChecks.map(({ name, status }) => ({ name, status })) : [],
+    pendingChecks: Array.isArray(pr.pendingChecks) ? pr.pendingChecks.map(({ name, status }) => ({ name, status })) : [],
+  }
+}
+
+function stallQueueSnapshot(queue = {}) {
+  return {
+    queued: queue.queued ?? null,
+    queueState: queue.queueState ?? queue.state ?? null,
+    position: queue.position ?? null,
+    batchPrNumber: queue.batchPrNumber ?? null,
+  }
+}
+
+// Retain each source's last readable contribution independently. A failed read carries no
+// replacement state, while a readable sibling can still move the effective stall snapshot.
+export function nextStallObservation({ cache = {}, pr = {}, queue = {} } = {}) {
+  const previous = cache && typeof cache === 'object' ? cache : {}
+  const prReadable = pr.readable !== false
+  const queueReadable = queue.readable !== false
+  const nextPr = prReadable ? stallPrSnapshot(pr) : (previous.pr ?? null)
+  const nextQueue = queueReadable ? stallQueueSnapshot(queue) : (previous.queue ?? null)
+
+  if (!prReadable && !queueReadable) {
+    return {
+      cache: { pr: nextPr, queue: nextQueue, key: previous.key ?? null },
+      key: previous.key ?? null,
+      changed: false,
+    }
+  }
+
+  const key = observationKey({ pr: nextPr ?? {}, queue: nextQueue ?? {} })
+  return {
+    cache: { pr: nextPr, queue: nextQueue, key },
+    key,
+    changed: key !== (previous.key ?? 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.
+// Before admission, a pending non-Mergify check means CI is running: Mergify admits the PR when
+// it passes, so the wait is progress, not a dead admission path, and gets the full bound
+// (2026-10-16: three enqueued PRs ended admission-stall after 3m while their CI waited on busy
+// runners). A failing check still ends the watch at once (admission-checks-failed).
+export function effectiveStallMinutes({
+  everActive = false,
+  stallMinutes = DEFAULT_STALL_MINUTES,
+  admissionStallMinutes = DEFAULT_ADMISSION_STALL_MINUTES,
+  ciPending = false,
+} = {}) {
+  const post = Number(stallMinutes)
+  if (!Number.isFinite(post) || post <= 0) return { minutes: NaN, phase: 'invalid' }
+  if (everActive === true) return { minutes: post, phase: 'queued' }
+  if (ciPending === true) return { minutes: post, phase: 'admission-ci' }
+  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
+// A queue run is one long CI run with no queue-state change until it ends: 20-48 min on
+// the self-hosted fleet (2026-10-10), and the queue sets no checks timeout. A 10-minute
+// bound ended healthy watches STALLED mid-run.
+export const DEFAULT_STALL_MINUTES = 45
+// 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
+// CI profiling: a single job that runs longer than this is reported as slow. Five minutes is
+// the budget a PR-lane job should fit in; a job over it is where queue wall time goes.
+export const DEFAULT_SLOW_JOB_MINUTES = 5
+
+// 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 }
+}
+
+const MERGIFY_CHECKS = new Set(['Mergify Merge Protections', 'Mergify Merge Queue'])
+const FAILED_CHECK_STATES = new Set(['ACTION_REQUIRED', 'CANCELLED', 'ERROR', 'FAILURE', 'STARTUP_FAILURE', 'TIMED_OUT'])
+const PENDING_CHECK_STATES = new Set(['EXPECTED', 'IN_PROGRESS', 'PENDING', 'QUEUED', 'REQUESTED', 'WAITING'])
+
+export function summarizeStatusChecks(rollup) {
+  const failedChecks = []
+  const pendingChecks = []
+  for (const check of Array.isArray(rollup) ? rollup : []) {
+    const name = check?.name || check?.context || 'unnamed-check'
+    if (MERGIFY_CHECKS.has(name)) continue
+    const status = String(check?.conclusion || check?.state || check?.status || 'UNKNOWN').toUpperCase()
+    const summary = {
+      name,
+      status,
+      detailsUrl: check?.detailsUrl || check?.targetUrl || null,
+    }
+    if (FAILED_CHECK_STATES.has(status)) failedChecks.push(summary)
+    else if (PENDING_CHECK_STATES.has(status)) pendingChecks.push(summary)
+  }
+  return { failedChecks, pendingChecks }
+}
+
+// ---- CI profiling -----------------------------------------------------------------------
+//
+// The watcher already reads `statusCheckRollup` every poll, and each CheckRun in it carries
+// `startedAt`/`completedAt`, so per-job timing costs no extra read. Mergify's own checks are
+// excluded: their "duration" is queue wait, not CI work, and so are jobs that did no work
+// (SKIPPED, NEUTRAL). A job is running only when GitHub says it is not COMPLETED; it is then
+// timed up to `nowMs`, so a slow job is flagged while it is still slow. Timestamps alone do not
+// decide "running": GitHub records a skipped job with `completedAt` a few seconds BEFORE
+// `startedAt` (seen on PR #1483), which a timestamp test read as "still running" and timed
+// for the whole watch. A completed job whose timestamps are out of order counts as 0s.
+// Profiling is observation only: it never changes a lifecycle verdict or an exit code.
+const NO_WORK_CONCLUSIONS = new Set(['SKIPPED', 'NEUTRAL'])
+export function checkTimings(rollup, { source = 'pr', nowMs = Date.now() } = {}) {
+  const jobs = []
+  for (const check of Array.isArray(rollup) ? rollup : []) {
+    const name = check?.name || check?.context || 'unnamed-check'
+    if (MERGIFY_CHECKS.has(name)) continue
+    if (NO_WORK_CONCLUSIONS.has(String(check?.conclusion || '').toUpperCase())) continue
+    const startedMs = Date.parse(check?.startedAt || '')
+    if (!Number.isFinite(startedMs) || startedMs <= 0) continue
+    const completedMs = Date.parse(check?.completedAt || '')
+    const statusText = String(check?.status || '').toUpperCase()
+    const running = statusText
+      ? statusText !== 'COMPLETED'
+      : !Number.isFinite(completedMs) || completedMs <= 0
+    jobs.push({
+      source,
+      name,
+      workflow: check?.workflowName || null,
+      status: String(check?.conclusion || check?.status || check?.state || 'UNKNOWN').toUpperCase(),
+      running,
+      startedAt: check.startedAt,
+      completedAt: running ? null : check.completedAt,
+      durationMs: running ? Math.max(0, nowMs - startedMs) : Math.max(0, (Number.isFinite(completedMs) ? completedMs : startedMs) - startedMs),
+      detailsUrl: check?.detailsUrl || check?.targetUrl || null,
+    })
+  }
+  return jobs
+}
+
+// One entry per job run (source + name + start), so a rerun of the same job is a separate
+// entry and the latest poll's reading of a running job replaces its earlier one.
+export function mergeCiJobs(previous = {}, jobs = []) {
+  const next = { ...(previous && typeof previous === 'object' ? previous : {}) }
+  for (const job of Array.isArray(jobs) ? jobs : []) next[`${job.source}|${job.name}|${job.startedAt}`] = job
+  return next
+}
+
+// Jobs that have crossed the threshold and were not warned about yet. Each job run is warned
+// about once, so a long job does not repeat its warning on every poll.
+export function newSlowJobs(jobsByKey = {}, { thresholdMs, warned = new Set() } = {}) {
+  const fresh = []
+  for (const [key, job] of Object.entries(jobsByKey || {})) {
+    if (job.durationMs > thresholdMs && !warned.has(key)) fresh.push({ key, job })
+  }
+  return fresh
+}
+
+export function slowJobWarning(job, { thresholdMs, nowIso }) {
+  return JSON.stringify({
+    warning: 'slow-ci-job',
+    name: job.name,
+    workflow: job.workflow,
+    source: job.source,
+    running: job.running,
+    durationSec: Math.round(job.durationMs / 1000),
+    thresholdSec: Math.round(thresholdMs / 1000),
+    detailsUrl: job.detailsUrl,
+    at: nowIso,
+  })
+}
+
+// Record the first time each lifecycle phase appeared, so the verdict can say how long the
+// PR waited for admission, sat in the queue, and so on.
+export function nextPhaseTimings(timings = [], phases = [], nowMs = Date.now()) {
+  const list = Array.isArray(timings) ? [...timings] : []
+  for (const phase of Array.isArray(phases) ? phases.slice(list.length) : []) list.push({ phase, enteredMs: nowMs })
+  return list
+}
+
+export function ciProfile(jobsByKey = {}, { thresholdMs, phaseTimings = [], startedMs, endMs } = {}) {
+  const jobs = Object.values(jobsByKey || {}).sort((a, b) => b.durationMs - a.durationMs)
+  const sec = (ms) => Math.round(ms / 1000)
+  const view = (job) => ({
+    source: job.source,
+    name: job.name,
+    workflow: job.workflow,
+    status: job.status,
+    running: job.running,
+    durationSec: sec(job.durationMs),
+    detailsUrl: job.detailsUrl,
+  })
+  const slow = jobs.filter((job) => job.durationMs > thresholdMs)
+  const phases = (Array.isArray(phaseTimings) ? phaseTimings : []).map((entry, index, all) => {
+    const next = all[index + 1]
+    const terminal = !next && ['MERGED', 'DEQUEUED', 'CLOSED_UNMERGED', 'STALLED'].includes(entry.phase)
+    return {
+      phase: entry.phase,
+      atSec: Number.isFinite(startedMs) ? sec(entry.enteredMs - startedMs) : null,
+      durationSec: terminal ? null : sec((next ? next.enteredMs : endMs) - entry.enteredMs),
+    }
+  })
+  return {
+    verdict: jobs.length === 0 ? 'no-timing-data' : (slow.length > 0 ? 'slow' : 'ok'),
+    slowJobMinutes: thresholdMs / 60_000,
+    jobCount: jobs.length,
+    slowestJob: jobs[0] ? view(jobs[0]) : null,
+    slowJobs: slow.map(view),
+    jobs: jobs.map(view),
+    phases,
+  }
+}
+
+// One compact line naming the outcome and the slow jobs, printed on stderr AFTER the verdict so
+// it is the last line of a combined log. A background runner that reports only an exit code and
+// a short log tail (Pi's bg_task_status / bg_task_log, 10 lines by default) otherwise shows the
+// tail of the pretty-printed verdict — the end of `phases` — and the profile is never read
+// (identity #894, 2026-09-29: a 338s job warned about, never seen). Capped at three named slow
+// jobs so the line stays short; the full list is on the verdict.
+export function ciProfileSummary(result, profile) {
+  const shown = (profile?.slowJobs || []).slice(0, 3).map((job) => `${job.name} ${job.durationSec}s`)
+  const hidden = (profile?.slowJobs || []).length - shown.length
+  return JSON.stringify({
+    ciProfileSummary: true,
+    outcome: result?.outcome ?? null,
+    verdict: profile?.verdict ?? 'no-timing-data',
+    jobCount: profile?.jobCount ?? 0,
+    slowJobMinutes: profile?.slowJobMinutes ?? null,
+    slowest: profile?.slowestJob ? `${profile.slowestJob.name} ${profile.slowestJob.durationSec}s` : null,
+    slowJobs: hidden > 0 ? [...shown, `+${hidden} more`] : shown,
+  })
+}
+
+// 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).
+//
+// Parse the selected dequeue comment once and retain all provider evidence used by the
+// terminal verdict. The rendered comment is also the only surviving source after Mergify's
+// queue API drops active membership and its synthetic PR relationship.
+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
+const BATCH_PR_RE = /\bon draft #(\d+)\b/i
+const REASON_RE = /^## Reason\s*\n+([^\n]+)/m
+const PROVIDER_CHECK_RE = /^-\s*(❌|🟠|🛑)\s*\[([^\]]+)\]\(([^)]+)\)/gmu
+
+export function dequeueInfoFromComments(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 { dequeuedAtMs: null, rawReason: null, batchPrNumber: null, providerFailedChecks: [] }
+  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
+  const dequeuedAtMs = last
+    ? Date.UTC(Number(last[1]), Number(last[2]) - 1, Number(last[3]), Number(last[4]), Number(last[5]))
+    : null
+  const reasonMatch = REASON_RE.exec(body)
+  const batchMatch = BATCH_PR_RE.exec(body)
+  const providerFailedChecks = []
+  PROVIDER_CHECK_RE.lastIndex = 0
+  while ((match = PROVIDER_CHECK_RE.exec(body))) {
+    providerFailedChecks.push({
+      name: match[2],
+      status: match[1] === '🟠' ? 'CANCELLED' : (match[1] === '🛑' ? 'TIMED_OUT' : 'FAILURE'),
+      detailsUrl: match[3] || null,
+    })
+  }
+  return {
+    dequeuedAtMs,
+    rawReason: reasonMatch?.[1]?.trim() || null,
+    batchPrNumber: batchMatch ? Number(batchMatch[1]) : null,
+    providerFailedChecks,
+  }
+}
+
+export function dequeuedAtFromComments(comments) {
+  return dequeueInfoFromComments(comments).dequeuedAtMs
+}
+
+// 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,headRefOid,labels,url,comments,statusCheckRollup'], { 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' }
+  const checks = summarizeStatusChecks(data.statusCheckRollup)
+  const dequeueInfo = dequeueInfoFromComments(data.comments)
+  return {
+    readable: true,
+    state: data.state || null,
+    mergedAt: data.mergedAt || null,
+    mergeCommitOid: data.mergeCommit?.oid || null,
+    headRefOid: data.headRefOid || null,
+    labels: (data.labels || []).map((label) => label.name).filter(Boolean),
+    url: data.url || null,
+    dequeuedAtMs: dequeueInfo.dequeuedAtMs,
+    dequeueInfo,
+    ciJobs: checkTimings(data.statusCheckRollup, { source: 'pr' }),
+    ...checks,
+  }
+}
+
+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,
+      batchPrNumber: positivePrNumber(
+        parsed.mergeability_check?.queue_pull_request_number
+          ?? parsed.queue_pull_request_number
+          ?? parsed.speculative_check_pr,
+      ),
+      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, batchPrNumber: null, raw: text }
+  return { readable: false, queued: false, queueState: null, position: null, batchPrNumber: null, raw: text || 'mergify queue show failed' }
+}
+
+function positivePrNumber(value) {
+  const number = Number(value)
+  return Number.isInteger(number) && number > 0 ? number : null
+}
+
+// The batch relationship is only queried after a terminal dequeue verdict, so normal polls
+// remain the documented two reads. This one-shot enrichment cannot influence lifecycle state.
+function batchPrObservation({ repo, batchPrNumber, intervalSeconds, stallMinutes, admissionStallMinutes, maxMinutes, everActive }) {
+  const result = run('gh', ['pr', 'view', String(batchPrNumber), '--repo', repo, '--json', 'state,url,statusCheckRollup'], { timeout: readTimeoutForArgs({ intervalSeconds, stallMinutes, admissionStallMinutes, maxMinutes, everActive }) })
+  if (!result.ok) return { readable: false, failedChecks: [], error: result.stderr || result.stdout }
+  const data = parseJson(result.stdout)
+  if (!data) return { readable: false, failedChecks: [], error: 'gh pr view returned invalid JSON for synthetic batch PR' }
+  return { readable: true, state: data.state || null, url: data.url || null, ciJobs: checkTimings(data.statusCheckRollup, { source: 'queue-batch' }), ...summarizeStatusChecks(data.statusCheckRollup) }
+}
+
+export function classifyDequeue({ rawReason = null, failedChecks = [] } = {}) {
+  const statuses = new Set((Array.isArray(failedChecks) ? failedChecks : []).map((check) => String(check?.status || '').toUpperCase()))
+  if (['FAILURE', 'ERROR', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].some((status) => statuses.has(status))) return 'checks-failed'
+  if (statuses.has('CANCELLED')) return 'checks-cancelled'
+  const raw = String(rawReason || '').trim().toLowerCase()
+  if (/failing checks|checks failed/.test(raw)) return 'checks-failed'
+  if (/pull[- ]request.*updated|draft[- ]pull[- ]request.*changed/.test(raw)) return 'pull-request-updated'
+  if (/conflict/.test(raw)) return 'conflict'
+  if (/conditions[- ]unmet/.test(raw)) return 'conditions-unmet'
+  if (/frozen/.test(raw)) return 'frozen'
+  if (/manual|manually dequeued|dequeued by .*\bdequeue\b.*command/.test(raw)) return 'manual'
+  return 'unknown'
+}
+
+// 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,
+    slowJobMinutes: DEFAULT_SLOW_JOB_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 === '--slow-job-minutes') args.slowJobMinutes = 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.
+Before admission, a completed failing non-Mergify GitHub check ends the watch as STALLED
+with reason admission-checks-failed; after admission, Mergify owns failure/dequeue routing.
+
+Options:
+  --interval-seconds <n>         Poll interval, default 90
+  --stall-minutes <n>            Post-entry stall bound (no-change, not elapsed), default 45
+  --admission-stall-minutes <n>  Pre-admission stall bound (never observed membership, no CI
+                                 check pending), default 3. While a check is pending, the
+                                 post-entry bound applies.
+  --max-minutes <n>              Absolute safety ceiling, default 60, hard maximum 60
+  --slow-job-minutes <n>         Warn when one CI job runs longer than this, default 5
+  --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;
+          plus one {"warning":"slow-ci-job"} record per CI job that runs past
+          --slow-job-minutes (emitted even with --quiet); and, last of all, one
+          {"ciProfileSummary":true} line (outcome, profile verdict, slow jobs) so a
+          short log tail shows the profile (emitted even with --quiet)
+
+The terminal verdict carries "ciProfile": every non-Mergify CI job's duration (PR checks
+from each poll, plus the queue batch PR's checks read once at the end), the slow ones,
+and how long each lifecycle phase lasted. Profiling never changes the verdict or exit code.
+
+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
+  }
+  if (!/^\d+$/.test(args.pr)) {
+    console.error(`--pr takes the bare PR number, not ${JSON.stringify(args.pr)}`)
+    return 2
+  }
+  if (!/^[\w.-]+\/[\w.-]+$/.test(args.repo)) {
+    console.error(`--repo takes owner/name, not ${JSON.stringify(args.repo)}`)
+    return 2
+  }
+  for (const key of ['intervalSeconds', 'stallMinutes', 'admissionStallMinutes', 'maxMinutes', 'slowJobMinutes']) {
+    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 stallObservationCache = null
+  let lastChangeMs = startedMs
+  let observations = 0
+  let phases = []
+  let lastBatchPrNumber = null
+  let phaseTimings = []
+  let ciJobs = {}
+  const warnedSlowJobs = new Set()
+  const slowThresholdMs = args.slowJobMinutes * 60_000
+  // Warn once per slow job run. Warnings go to stderr even under --quiet: they are the point
+  // of profiling, and --quiet only silences the routine heartbeat.
+  const warnSlowJobs = () => {
+    for (const { key, job } of newSlowJobs(ciJobs, { thresholdMs: slowThresholdMs, warned: warnedSlowJobs })) {
+      warnedSlowJobs.add(key)
+      console.error(slowJobWarning(job, { thresholdMs: slowThresholdMs, nowIso: new Date().toISOString() }))
+    }
+  }
+  // Every terminal path goes through here, so the profile is on every verdict. The queue
+  // batch PR (where the merge-queue CI actually runs) is read once, at the end, only if the
+  // dequeue path has not already read it — normal polls stay at two reads.
+  const finish = (result, { batchRead = null } = {}) => {
+    const endMs = Date.now()
+    let batch = batchRead
+    if (!batch && lastBatchPrNumber) batch = batchPrObservation({ ...args, everActive, batchPrNumber: lastBatchPrNumber })
+    if (batch?.readable && Array.isArray(batch.ciJobs)) ciJobs = mergeCiJobs(ciJobs, batch.ciJobs)
+    warnSlowJobs()
+    const timings = nextPhaseTimings(phaseTimings, result.phases || phases, endMs)
+    const profile = ciProfile(ciJobs, { thresholdMs: slowThresholdMs, phaseTimings: timings, startedMs, endMs })
+    console.log(JSON.stringify({ ...result, ciProfile: profile }, null, 2))
+    console.error(ciProfileSummary(result, profile))
+  }
+
+  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
+    if (pr.readable !== false && Array.isArray(pr.ciJobs)) {
+      ciJobs = mergeCiJobs(ciJobs, pr.ciJobs)
+      warnSlowJobs()
+    }
+    if (queue.readable !== false && queue.queued === true && queue.batchPrNumber) {
+      lastBatchPrNumber = queue.batchPrNumber
+    }
+    const active = (Array.isArray(pr.labels) && pr.labels.includes('queued')) || queue.queued === true
+    // Only the PR read can show a merge, so an absence counts only when it succeeded: Mergify
+    // also reads "not in the merge queue" for a PR that just merged (ai #1762).
+    const readable = pr.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
+    if (verdict.preAdmission === true) phases = nextPhases(phases, 'NOT_YET_QUEUED')
+    phases = nextPhases(phases, verdict.outcome)
+    phaseTimings = nextPhaseTimings(phaseTimings, phases)
+    let dequeue = null
+    if (verdict.outcome === 'DEQUEUED') {
+      const info = pr.dequeueInfo || { rawReason: null, batchPrNumber: null, providerFailedChecks: [] }
+      const batchPrNumber = lastBatchPrNumber ?? info.batchPrNumber ?? null
+      const batch = batchPrNumber ? batchPrObservation({ ...args, everActive, batchPrNumber }) : null
+      const failedChecks = batch?.readable && batch.failedChecks.length > 0
+        ? batch.failedChecks
+        : (info.providerFailedChecks || [])
+      const classifiedReason = classifyDequeue({ rawReason: info.rawReason, failedChecks })
+      dequeue = {
+        reason: classifiedReason === 'unknown' && !info.rawReason && failedChecks.length === 0
+          ? verdict.reason
+          : classifiedReason,
+        rawReason: info.rawReason || null,
+        batchPrNumber,
+        failedChecks,
+        batch,
+      }
+    }
+    const payload = {
+      outcome: verdict.outcome,
+      terminal: verdict.terminal,
+      reason: dequeue?.reason || verdict.reason || null,
+      rawReason: dequeue?.rawReason || null,
+      detail: verdict.detail || null,
+      mergedSha: verdict.mergedSha || null,
+      batchPrNumber: dequeue?.batchPrNumber || lastBatchPrNumber,
+      seenQueued,
+      everActive,
+      phases,
+      failedChecks: dequeue?.failedChecks || verdict.failedChecks || pr.failedChecks || [],
+      missingActiveReads,
+      observations,
+      elapsedMs: Date.now() - startedMs,
+      pr: {
+        state: pr.state || null,
+        mergedAt: pr.mergedAt || null,
+        headRefOid: pr.headRefOid || null,
+        labels: pr.labels || [],
+        url: pr.url || null,
+        readable: pr.readable !== false,
+        dequeuedAtMs: pr.dequeuedAtMs ?? null,
+        failedChecks: pr.failedChecks || [],
+        pendingChecks: pr.pendingChecks || [],
+      },
+      queue: {
+        queued: queue.queued === true,
+        queueState: queue.queueState || null,
+        position: queue.position ?? null,
+        batchPrNumber: queue.batchPrNumber || null,
+        lastBatchPrNumber,
+        readable: queue.readable !== false,
+      },
+      batchPr: dequeue?.batch ? {
+        number: dequeue.batchPrNumber,
+        state: dequeue.batch.state || null,
+        url: dequeue.batch.url || null,
+        readable: dequeue.batch.readable !== false,
+        error: dequeue.batch.error || null,
+      } : null,
+    }
+
+    if (verdict.terminal) {
+      finish(payload, { batchRead: dequeue?.batch || null })
+      return verdict.outcome === 'MERGED' ? 0 : 4
+    }
+
+    const stallObservation = nextStallObservation({ cache: stallObservationCache, pr, queue })
+    stallObservationCache = stallObservation.cache
+    const changed = stallObservation.changed
+    if (changed) {
+      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) {
+      finish({ ...payload, terminal: true, outcome: 'STALLED', phases: nextPhases(phases, 'STALLED'), reason: 'max-minutes', detail: `watch exceeded ${args.maxMinutes}m absolute ceiling` })
+      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 45). 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,
+      ciPending: (pr.pendingChecks || []).length > 0,
+    })
+    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')
+      finish({ ...payload, terminal: true, outcome: 'STALLED', phases: nextPhases(phases, 'STALLED'), reason, detail: stall.reason })
+      return 4
+    }
+
+    await sleep(args.intervalSeconds * 1000)
+  }
+}