@1aboveio/skills 1.0.21 → 1.0.22

package/skills/cicd/github-flow/scripts/watch-checks.mjs

@@ -0,0 +1,561 @@
+#!/usr/bin/env node
+// watch-checks — wait for a PR's checks to settle, and prove the merge when asked.
+// Read-only: it only reads `gh pr view`.
+//
+//   node watch-checks.mjs --pr <number> [--repo <owner>/<name>] [--until checks|merged]
+//     [--interval-seconds 45] [--stall-minutes 15] [--max-minutes 60]
+//     [--no-checks-minutes 5] [--slow-check-minutes 5] [--read-retries 2]
+//     [--unreadable-polls 3]
+//
+// Why this exists instead of `gh pr checks --watch --required --fail-fast`:
+//
+//   The delivery bar stays unchanged: required checks, or all checks when none are
+//   required. Monitoring must not turn optional checks into new merge gates.
+//   · `--watch` repaints its table — and its elapsed clock — every 30 seconds. Any
+//     supervisor that decides "the command printed something, so it is progressing"
+//     from output activity is fooled by that repaint: a job stuck in one step for
+//     twenty minutes looks exactly like a job making progress, and the moment of
+//     decision is spent on a status line rather than on the step that stopped.
+//
+// So this polls discrete JSON reads and defines progress the only way that survives a
+// log: the canonical state of the PR's checks actually changed. It carries no
+// repainting clock, so a stationary phase is quiet and a real transition speaks.
+//
+// Streams:
+//   stdout  exactly one terminal JSON verdict, at exit.
+//   stderr  one compact JSON record per observed check-state change (`kind:"transition"`,
+//           `progress:true`), one `{"warning":"slow-ci-check"}` record per slow check run,
+//           one `{"kind":"transition","progress":false,...}` the first time the provider
+//           becomes unreadable, one more (`progress:false`) when it recovers without the
+//           checks having moved, and one closing `{"summary":true}` line after the verdict.
+//           Readability is health, not CI progress: a health record never moves the clock
+//           the stall bound is measured from.
+//
+// The record's projection is `state` — the canonical check set, sorted, with no clock
+// fields. `at`, `elapsedMs` and `observations` are for humans reading the log; a
+// background-task predicate watches `progress` and `state`, never log size or mtime.
+//
+// Exit codes: 0 checks passed / no checks / merged. 4 terminal but not deliverable
+// (failing checks, stalled, unreadable, unknown check state, closed unmerged).
+// 2 usage error.
+
+import { execFileSync } from 'node:child_process'
+
+const PASSING = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED'])
+const FAILING = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'CANCELLED', 'STALE'])
+const PENDING = new Set(['QUEUED', 'IN_PROGRESS', 'PENDING', 'WAITING', 'REQUESTED', 'EXPECTED'])
+const MERGE_GATE = new Set(['BLOCKED', 'BEHIND', 'DIRTY', 'DRAFT'])
+const MERGEABLE = new Set(['CLEAN', 'HAS_HOOKS'])
+const PR_FIELDS = 'state,mergedAt,mergeCommit,mergeStateStatus,statusCheckRollup,autoMergeRequest,url,headRefOid'
+const MAX_MINUTES_CEILING = 240
+const MAX_READ_BYTES = 8 * 1024 * 1024
+
+function help() {
+  return `watch-checks --pr <number> [options]
+
+Wait for required PR checks, falling back to all checks when none are required.
+Read-only; never merges,
+never comments, never edits a PR.
+
+  --pr <number>              PR to watch (required)
+  --repo <owner>/<name>      repository; defaults to the current checkout
+  --until checks|merged      stop when the checks settle (default), or after proving
+                             the PR actually merged. 'merged' is never a success without
+                             a merge: a PR with no checks waits for the merge itself, and
+                             an unrecognised mergeStateStatus ends as UNKNOWN
+  --interval-seconds <n>     poll interval (default 45)
+  --stall-minutes <n>        no-observable-change bound (default 15). Suspended while a
+                             check is pending, and while an --until merged PR is
+                             mergeable and awaiting the provider: running CI and a
+                             provider-side merge are progress, not a stall. Also
+                             bounds a required context that stays pending with no start
+                             time (reason: check-never-started), suspended while other
+                             checks are still running
+  --max-minutes <n>          absolute ceiling (default 60, max ${MAX_MINUTES_CEILING})
+  --no-checks-minutes <n>    with --until checks, a PR with no checks for this long has
+                             no CI (default 5)
+  --slow-check-minutes <n>   warn once per check run longer than this (default 5)
+  --read-retries <n>         extra attempts inside one poll (default 2)
+  --unreadable-polls <n>     consecutive unreadable polls before UNKNOWN (default 3)
+
+Outcome values: CHECKS_PASSED, NO_CHECKS, MERGED, CHECKS_FAILED, CLOSED_UNMERGED,
+STALLED, UNKNOWN.
+
+Exit 0: CHECKS_PASSED, NO_CHECKS, MERGED. Exit 4: every other outcome. Exit 2: usage.`
+}
+
+function parseArgs(argv) {
+  const args = {
+    intervalSeconds: 45,
+    stallMinutes: 15,
+    maxMinutes: 60,
+    noChecksMinutes: 5,
+    slowCheckMinutes: 5,
+    readRetries: 2,
+    unreadablePolls: 3,
+    until: 'checks',
+  }
+  const numbers = {
+    '--interval-seconds': 'intervalSeconds',
+    '--stall-minutes': 'stallMinutes',
+    '--max-minutes': 'maxMinutes',
+    '--no-checks-minutes': 'noChecksMinutes',
+    '--slow-check-minutes': 'slowCheckMinutes',
+    '--read-retries': 'readRetries',
+    '--unreadable-polls': 'unreadablePolls',
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--pr') args.pr = argv[++i]
+    else if (arg === '--repo') args.repo = argv[++i]
+    else if (arg === '--until') args.until = argv[++i]
+    else if (numbers[arg]) args[numbers[arg]] = Number(argv[++i])
+    else if (arg === '--help' || arg === '-h') args.help = true
+    else args.unknown = arg
+  }
+  return args
+}
+
+function validate(args) {
+  if (args.unknown) return `unknown argument ${args.unknown}`
+  if (!/^[1-9][0-9]*$/.test(String(args.pr ?? ''))) return '--pr must be a positive integer'
+  if (args.repo != null && !/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(String(args.repo))) {
+    return '--repo must be owner/name'
+  }
+  if (args.until !== 'checks' && args.until !== 'merged') return '--until must be checks or merged'
+  for (const key of ['intervalSeconds', 'stallMinutes', 'maxMinutes', 'noChecksMinutes', 'slowCheckMinutes']) {
+    if (!Number.isFinite(args[key]) || args[key] <= 0) return `${key} must be a positive number`
+  }
+  for (const key of ['readRetries', 'unreadablePolls']) {
+    if (!Number.isInteger(args[key]) || args[key] < 0) return `${key} must be a non-negative integer`
+  }
+  if (args.unreadablePolls < 1) return '--unreadable-polls must be at least 1'
+  if (args.maxMinutes > MAX_MINUTES_CEILING) return `--max-minutes exceeds the ${MAX_MINUTES_CEILING}-minute ceiling`
+  return null
+}
+
+const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+// A bounded per-read timeout: long enough for a slow-but-working API call, short enough
+// that one hung read cannot outlive the bound that will fire STALLED on this poll.
+function readTimeoutMs({ intervalSeconds, maxMinutes, elapsedMs }) {
+  const perRead = Math.max(1000, intervalSeconds * 3000)
+  const remaining = Math.max(1000, maxMinutes * 60_000 - elapsedMs)
+  return Math.min(perRead, remaining, 60_000)
+}
+
+function ghJson(ghArgs, timeoutMs, array = false) {
+  try {
+    const stdout = execFileSync('gh', ghArgs, {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      killSignal: 'SIGKILL',
+      maxBuffer: MAX_READ_BYTES,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, GH_PROMPT_DISABLED: '1' },
+    })
+    const data = JSON.parse(stdout)
+    if (!data || typeof data !== 'object' || Array.isArray(data) !== array) return { ok: false, error: 'gh returned an unexpected JSON shape' }
+    return { ok: true, data }
+  } catch (error) {
+    const stderr = String(error?.stderr ?? '').trim()
+    if (array && [1, 8].includes(error?.status)) {
+      // `gh pr checks` returns JSON with non-zero status for red/pending checks.
+      try {
+        const data = JSON.parse(String(error.stdout))
+        if (Array.isArray(data)) return { ok: true, data }
+      } catch {}
+      if (/no required checks/i.test(stderr)) return { ok: true, data: [] }
+    }
+    return { ok: false, error: stderr || String(error?.message ?? 'gh pr view failed') }
+  }
+}
+
+function readPr(args, timeoutMs) {
+  const ghArgs = ['pr', 'view', String(args.pr), '--json', PR_FIELDS]
+  if (args.repo) ghArgs.push('--repo', args.repo)
+  const pr = ghJson(ghArgs, Math.max(1, Math.floor(timeoutMs / 2)))
+  if (!pr.ok) return pr
+  const requiredArgs = ['pr', 'checks', String(args.pr), '--required', '--json', 'name']
+  if (args.repo) requiredArgs.push('--repo', args.repo)
+  const required = ghJson(requiredArgs, Math.max(1, Math.floor(timeoutMs / 2)), true)
+  if (!required.ok) return required
+  if (required.data.some((check) => typeof check?.name !== 'string' || !check.name)) {
+    return { ok: false, error: 'required checks returned an invalid name' }
+  }
+  const names = new Set(required.data.map((check) => check.name))
+  if (names.size > 0) {
+    const rollup = Array.isArray(pr.data.statusCheckRollup) ? pr.data.statusCheckRollup : []
+    const selected = rollup.filter((check) => names.has(check?.name ?? check?.context))
+    if ([...names].some((name) => !selected.some((check) => (check.name ?? check.context) === name))) {
+      return { ok: false, error: 'required checks and PR rollup disagree; retrying the observation' }
+    }
+    pr.data.statusCheckRollup = selected
+  }
+  return pr
+}
+
+// One rollup entry -> {name, phase}. `statusCheckRollup` mixes CheckRun (status +
+// conclusion) and StatusContext (state only) shapes, and `gh` does not normalise them.
+// An entry that matches neither fails closed as `unknown` rather than reading as pending
+// or passing.
+function normalizeCheck(entry) {
+  const name = entry?.name || entry?.context || 'unnamed-check'
+  const status = String(entry?.status ?? entry?.state ?? '').toUpperCase()
+  const conclusion = String(entry?.conclusion ?? '').toUpperCase()
+  let phase = 'unknown'
+  if (conclusion) phase = PASSING.has(conclusion) ? 'success' : FAILING.has(conclusion) ? 'failure' : 'unknown'
+  else if (PENDING.has(status)) phase = 'pending'
+  else if (PASSING.has(status)) phase = 'success'
+  else if (FAILING.has(status)) phase = 'failure'
+  const started = Date.parse(entry?.startedAt ?? entry?.createdAt ?? '')
+  const completed = Date.parse(entry?.completedAt ?? '')
+  return {
+    name,
+    phase,
+    status: status || null,
+    conclusion: conclusion || null,
+    startedMs: Number.isFinite(started) && started > 0 ? started : null,
+    completedMs: Number.isFinite(completed) && completed > 0 ? completed : null,
+  }
+}
+
+// The canonical projection. Sorted, no clocks, no per-poll drift — this is the value a
+// change is defined against, and the value a background task can predicate on.
+function project(data) {
+  const checks = (Array.isArray(data.statusCheckRollup) ? data.statusCheckRollup : [])
+    .filter(Boolean)
+    .map(normalizeCheck)
+    .sort((a, b) => (a.name === b.name ? (a.phase < b.phase ? -1 : a.phase > b.phase ? 1 : 0) : a.name < b.name ? -1 : 1))
+  const names = (phase) => checks.filter((check) => check.phase === phase).map((check) => check.name)
+  return {
+    checks,
+    state: {
+      pr: {
+        state: data.state ?? null,
+        mergeStateStatus: data.mergeStateStatus ?? null,
+        mergedSha: data.mergeCommit?.oid ?? null,
+        autoMerge: Boolean(data.autoMergeRequest),
+      },
+      checks: checks.map(({ name, phase }) => ({ name, phase })),
+      failing: names('failure'),
+      pending: names('pending'),
+      unknown: names('unknown'),
+    },
+  }
+}
+
+const keyOf = (state) => JSON.stringify(state)
+
+function record(payload) {
+  return JSON.stringify(payload)
+}
+
+function slowCheckRecords(checks, { thresholdMs, warned, nowMs, url }) {
+  const out = []
+  for (const check of checks) {
+    if (!check.startedMs) continue
+    const key = `${check.name}|${check.startedMs}`
+    if (warned.has(key)) continue
+    const durationMs = (check.completedMs ?? nowMs) - check.startedMs
+    if (durationMs <= thresholdMs) continue
+    warned.add(key)
+    out.push(record({
+      warning: 'slow-ci-check',
+      name: check.name,
+      phase: check.phase,
+      durationSec: Math.round(durationMs / 1000),
+      thresholdSec: Math.round(thresholdMs / 1000),
+      url,
+    }))
+  }
+  return out
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    console.log(help())
+    return 0
+  }
+  const invalid = validate(args)
+  if (invalid) {
+    console.error(`watch-checks: ${invalid}`)
+    return 2
+  }
+
+  const startedMs = Date.now()
+  const slowThresholdMs = args.slowCheckMinutes * 60_000
+  const warnedSlow = new Set()
+  let lastSemanticKey = null
+  let lastUnreadableKey = null
+  let lastState = null
+  let unreadablePolls = 0
+  let observations = 0
+  let transitions = 0
+  let lastError = null
+  let noChecksSince = null
+  let gateStreak = 0
+  let lastReadable = true
+  let changedAtMs = startedMs
+  let lastUrl = null
+  // A pending check that never acquires a start time is the "expected forever" shape: a
+  // required context GitHub will never run. Tracked by name so the bound outlives the
+  // check's own appearance and disappearance from the rollup.
+  const neverStartedSince = new Map()
+
+  const finish = (result, state) => {
+    const endMs = Date.now()
+    const verdict = {
+      outcome: result.outcome,
+      terminal: true,
+      reason: result.reason ?? null,
+      detail: result.detail ?? null,
+      until: args.until,
+      pr: {
+        state: state?.pr?.state ?? null,
+        mergeStateStatus: state?.pr?.mergeStateStatus ?? null,
+        mergedSha: state?.pr?.mergedSha ?? null,
+        url: lastUrl,
+      },
+      checks: state?.checks?.map(({ name, phase }) => ({ name, phase })) ?? [],
+      failing: state?.failing ?? [],
+      pending: state?.pending ?? [],
+      unknown: state?.unknown ?? [],
+      slowChecks: [...warnedSlow].map((key) => key.slice(0, key.lastIndexOf('|'))),
+      observations,
+      transitions,
+      elapsedMs: endMs - startedMs,
+    }
+    console.log(JSON.stringify(verdict, null, 2))
+    console.error(record({
+      summary: true,
+      outcome: verdict.outcome,
+      reason: verdict.reason,
+      failing: verdict.failing,
+      pending: verdict.pending,
+      slowChecks: verdict.slowChecks,
+      checks: verdict.checks.length,
+    }))
+    return result.exitCode
+  }
+
+  for (;;) {
+    observations += 1
+    const elapsedMs = Date.now() - startedMs
+    const timeoutMs = readTimeoutMs({ intervalSeconds: args.intervalSeconds, maxMinutes: args.maxMinutes, elapsedMs })
+
+    let read = null
+    for (let attempt = 0; attempt <= args.readRetries; attempt += 1) {
+      read = readPr(args, timeoutMs)
+      if (read.ok) break
+      if (attempt < args.readRetries) await sleepMs(Math.min(1000, args.intervalSeconds * 1000))
+    }
+
+    if (!read.ok) {
+      unreadablePolls += 1
+      lastError = read.error
+      // An unreadable provider is information, not progress, and it is not a failed
+      // check either: it must not settle a verdict except through its own bound. It never
+      // moves the change clock — a provider we cannot read says nothing about the checks.
+      const unreadableKey = `unreadable|${read.error}`
+      if (lastReadable || unreadableKey !== lastUnreadableKey) {
+        lastUnreadableKey = unreadableKey
+        lastReadable = false
+        transitions += 1
+        console.error(record({
+          kind: 'transition',
+          progress: false,
+          reason: 'provider-unreadable',
+          at: new Date().toISOString(),
+          state: { readable: false, error: read.error },
+        }))
+      }
+      if (unreadablePolls >= args.unreadablePolls) {
+        return finish({
+          outcome: 'UNKNOWN',
+          reason: 'unreadable',
+          detail: `gh pr view failed ${unreadablePolls} polls in a row: ${lastError}`,
+          exitCode: 4,
+        }, lastState)
+      }
+      if (Date.now() - startedMs >= args.maxMinutes * 60_000) {
+        return finish({
+          outcome: 'UNKNOWN',
+          reason: 'max-minutes',
+          detail: `watch reached its ${args.maxMinutes}m ceiling while the provider was unreadable: ${lastError}`,
+          exitCode: 4,
+        }, lastState)
+      }
+      await sleepMs(args.intervalSeconds * 1000)
+      continue
+    }
+
+    unreadablePolls = 0
+    const { checks, state } = project(read.data)
+    lastUrl = read.data.url ?? null
+    lastState = state
+    const merged = state.pr.state === 'MERGED' || Boolean(read.data.mergedAt)
+    // An accepted auto-merge request means the provider owns the next step: the queue may
+    // hold the PR at BLOCKED/BEHIND while it does its own work, so that is not a human gate.
+    const providerHoldsMerge = state.pr.autoMerge === true
+
+    lastUnreadableKey = null
+    const wasReadable = lastReadable
+    lastReadable = true
+
+    const semanticKey = keyOf(state)
+    if (semanticKey !== lastSemanticKey) {
+      const reason = lastSemanticKey === null ? 'check-state-initial' : 'check-state'
+      lastSemanticKey = semanticKey
+      changedAtMs = Date.now()
+      transitions += 1
+      console.error(record({ kind: 'transition', progress: true, reason, at: new Date().toISOString(), state }))
+    } else if (!wasReadable) {
+      // Readable again and the checks are exactly where they were: health recovered, the
+      // semantic state did not change. Speak, but claim no progress and leave the change
+      // clock alone, so a provider outage cannot buy the PR another stall window.
+      transitions += 1
+      console.error(record({ kind: 'transition', progress: false, reason: 'provider-readable', at: new Date().toISOString(), state }))
+    }
+
+    for (const warning of slowCheckRecords(checks, { thresholdMs: slowThresholdMs, warned: warnedSlow, nowMs: Date.now(), url: lastUrl })) {
+      console.error(warning)
+    }
+
+    if (merged) return finish({ outcome: 'MERGED', reason: 'merged', exitCode: 0 }, state)
+    if (state.pr.state === 'CLOSED') {
+      return finish({ outcome: 'CLOSED_UNMERGED', reason: 'closed-without-merge', exitCode: 4 }, state)
+    }
+    // An unrecognised rollup entry is not a pass and not a pending check: stop and say
+    // which, rather than waiting for a state that will never settle.
+    if (state.unknown.length > 0) {
+      return finish({
+        outcome: 'UNKNOWN',
+        reason: 'unknown-check-state',
+        detail: `unrecognised check state: ${state.unknown.join(', ')}`,
+        exitCode: 4,
+      }, state)
+    }
+    if (state.failing.length > 0) {
+      return finish({
+        outcome: 'CHECKS_FAILED',
+        reason: 'checks-failed',
+        detail: state.failing.join(', '),
+        exitCode: 4,
+      }, state)
+    }
+
+    // "No checks" only answers the question `--until checks` asked. For `--until merged`
+    // an empty rollup means there is nothing to wait for on the CI side, and the merge
+    // itself is the whole remaining question: settling that as a success would report a
+    // green watch for a PR that never merged.
+    if (checks.length === 0 && args.until === 'checks') {
+      noChecksSince ??= Date.now()
+      if (Date.now() - noChecksSince >= args.noChecksMinutes * 60_000) {
+        return finish({
+          outcome: 'NO_CHECKS',
+          reason: 'no-checks-reported',
+          detail: `no checks reported for ${args.noChecksMinutes}m; verify repository CI policy before proceeding`,
+          exitCode: 0,
+        }, state)
+      }
+    } else if (checks.length > 0) {
+      noChecksSince = null
+    }
+
+    // Never-started contexts: a required context GitHub will never run is the "expected
+    // forever" shape, so bound it instead of waiting for a settlement that cannot come.
+    // While sibling checks are actually running the provider has simply not got to this
+    // one yet, so the diagnosis is suspended — and its clock is cleared, so the bound
+    // measures sustained no-CI time instead of time that belongs to a running suite.
+    const ciActivelyRunning = checks.some((check) => check.phase === 'pending' && check.startedMs)
+    if (ciActivelyRunning) {
+      neverStartedSince.clear()
+    } else {
+      const notStarted = new Set(checks.filter((check) => check.phase === 'pending' && !check.startedMs).map((check) => check.name))
+      for (const name of [...neverStartedSince.keys()]) if (!notStarted.has(name)) neverStartedSince.delete(name)
+      for (const name of notStarted) if (!neverStartedSince.has(name)) neverStartedSince.set(name, Date.now())
+      const stuck = [...neverStartedSince].filter(([, sinceMs]) => Date.now() - sinceMs >= args.stallMinutes * 60_000).map(([name]) => name)
+      if (stuck.length > 0) {
+        return finish({
+          outcome: 'STALLED',
+          reason: 'check-never-started',
+          detail: `${stuck.join(', ')} reported pending with no start time for ${args.stallMinutes}m`,
+          exitCode: 4,
+        }, state)
+      }
+    }
+
+    // Settled checks. An empty rollup counts as settled only for `--until merged`, where it
+    // means "nothing left to run" rather than "the answer is NO_CHECKS".
+    const settled = checks.length > 0 ? state.pending.length === 0 : args.until === 'merged'
+    if (settled && args.until === 'checks') return finish({ outcome: 'CHECKS_PASSED', reason: 'checks-passed', exitCode: 0 }, state)
+
+    // Awaiting a provider-side merge. An accepted auto-merge request outranks the status:
+    // the queue parks a queued PR at BLOCKED while it works, so that is not a human gate.
+    // A merge that cannot happen (review, stale base, conflict, draft) is a hand-back, not
+    // a wait to the ceiling, and a mergeStateStatus this tool does not recognise is never
+    // read as "mergeable": it is an explicit unknown, so nobody waits on a status the tool
+    // cannot name. One read is suspicion, so the hand-back needs two consecutive reads.
+    const gateStatus = String(state.pr.mergeStateStatus ?? '').toUpperCase()
+    const mergeDisposition = providerHoldsMerge
+      ? 'provider'
+      : MERGEABLE.has(gateStatus)
+        ? 'mergeable'
+        : MERGE_GATE.has(gateStatus)
+          ? 'gate'
+          : 'unknown'
+    const mergeAwaitBlocked = args.until === 'merged' && settled
+      && mergeDisposition !== 'provider' && mergeDisposition !== 'mergeable'
+    if (mergeAwaitBlocked) {
+      gateStreak += 1
+      if (gateStreak >= 2) {
+        if (mergeDisposition === 'unknown') {
+          return finish({
+            outcome: 'UNKNOWN',
+            reason: 'unknown-mergeability',
+            detail: `checks are settled but mergeStateStatus ${JSON.stringify(state.pr.mergeStateStatus)} is not a state this tool knows`,
+            exitCode: 4,
+          }, state)
+        }
+        return finish({
+          outcome: 'STALLED',
+          reason: `merge-gate:${gateStatus.toLowerCase()}`,
+          detail: `checks are green and the merge cannot proceed: mergeStateStatus ${state.pr.mergeStateStatus}`,
+          exitCode: 4,
+        }, state)
+      }
+    } else {
+      gateStreak = 0
+    }
+
+    const awaitingProvider = args.until === 'merged' && settled
+      && (mergeDisposition === 'provider' || mergeDisposition === 'mergeable')
+    const ciRunning = state.pending.length > 0
+
+    if (Date.now() - startedMs >= args.maxMinutes * 60_000) {
+      return finish({
+        outcome: 'STALLED',
+        reason: 'max-minutes',
+        detail: `watch reached its ${args.maxMinutes}m ceiling with the provider still reporting ${state.pr.state ?? 'an unknown state'}`,
+        exitCode: 4,
+      }, state)
+    }
+    if (!ciRunning && !awaitingProvider && Date.now() - changedAtMs >= args.stallMinutes * 60_000) {
+      return finish({
+        outcome: 'STALLED',
+        reason: 'stall-bound',
+        detail: `no observable check-state change for ${args.stallMinutes}m`,
+        exitCode: 4,
+      }, state)
+    }
+
+    await sleepMs(args.intervalSeconds * 1000)
+  }
+}
+
+process.exitCode = await main().catch((error) => {
+  console.error(record({ error: 'watch-checks-failed', detail: String(error?.message ?? error) }))
+  return 4
+})

package/skills/cicd/google-cloud/SKILL.md

@@ -5,7 +5,7 @@ description: >
   project management. Use when configuring GCP resources, managing service
   accounts, setting up IAP access, configuring VPC networks, managing secrets,
   or debugging cloud infrastructure.
-release-version: 0.50.1
+release-version: 0.50.2
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Google Cloud Platform (GCP) Skill

package/skills/cicd/mergify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mergify
 description: "Mergify merge queue and stacked PRs (`mergify stack`): config, rules, queue status, delivery. Use whenever a merge queue or stack is involved, including plain asks ('watch #123 till it merges', 'where is #412 in the queue', 'push this stack'): `gh pr view`/`gh pr checks` cannot see a dequeue; use `mergify queue show` and the bundled watcher. Also: a hook saying 'use mergify stack push', a missing Change-Id; authoring or debugging `.mergify.yml`, queue rules, merge protections, batch size, the ruleset making merges queue-only; enqueue policy (`@mergifyio queue` vs `auto_merge_conditions`); a push dequeuing a queued PR; bypass actors; freezing a branch. Failures: a PR stuck, queued but never merging, or merged unqueued; CI green on GitHub but unmet in Mergify; a batch going red or bisecting; a queue check missing rather than failing. Outranks the vendor mergify-* skills. NOT for pushing a PR in a repo without stack hooks (github-flow), workflow YAML (github-actions), or GCP deploy pipelines (cloud-deploy)."
-release-version: 0.50.1
+release-version: 0.50.2
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Mergify Merge Queue
@@ -23,7 +23,7 @@ Requires mergify CLI **2026.10.5 or newer** ([stacks.md](references/stacks.md#cl
 | **Push, open, or update a PR in a stack repo** (hook says "Use 'mergify stack push'", `Change-Id` missing) | [`references/stacks.md`](references/stacks.md) | Push with `scripts/stack-push.mjs`. One commit = one PR; amend to fix. Never `--no-verify`. |
 | A stacked PR gets no CI, conflicts after its parent lands, or is dequeued "could not be retargeted onto … `main`" | [`references/configuration.md`](references/configuration.md#stack-ready), then [`references/traps.md`](references/traps.md) | Make the repo stack-ready (native stacks: Mergify's ruleset bypass `exempt`; `Depends-On` stacks also need PR CI on every base, commits kept, auto-delete head branches); then `mergify stack push --force-rebase` for a stuck tip. |
 | Author or change `.mergify.yml` | [`references/configuration.md`](references/configuration.md) | [Rule 1](#rule-1--fetch-the-docs-before-writing-config): never write config from memory; finish with `validate` **and** `simulate`. |
-| **Watch a PR through the queue** | [`references/watch-contract.md`](references/watch-contract.md) | **[Rule 2](#rule-2--never-hand-roll-a-watcher): run the bundled watcher, never hand-roll one.** A watch observes a *progression*, not one state. |
+| **Watch a PR through the queue** | [`references/watch-contract.md`](references/watch-contract.md) | **[Rule 2](#rule-2--never-hand-roll-a-watcher): run the bundled watcher, never hand-roll one.** A watch observes a *progression*, not one state. It emits the initial snapshot and delivery/readability transitions; repeated identical polls stay quiet. |
 | **The queue feels slow, or is it worth it?** | [`references/diagnosis.md`](references/diagnosis.md#measuring-a-slow-queue) | Measure first-try merge rate and same-SHA requeues from the event log, then fix the flaky queue check. Never move a queue-only check onto the PR lane, and never rerun CI on push to `main` ([rules](references/configuration.md#the-queue-run-is-the-integration-run)). |
 | Check status — "where is my PR?", "why is it stuck?" | [`references/diagnosis.md`](references/diagnosis.md#querying-pr-and-queue-status) | `mergify queue show <number> -v` names the single blocking condition (bare number, never a URL; the CLI takes `--repository <owner/repo>`, never `--repo`; the bundled watcher below takes `--repo`); nothing else in the toolchain does. `gh pr checks` is CI truth, never queue truth. |
 | A PR merged without ever being queued | [`references/branch-protection.md`](references/branch-protection.md) | Make the queue mandatory with the ruleset's `update` rule; a required status check alone does not. |

package/skills/cicd/mergify/references/diagnosis.md

@@ -43,11 +43,16 @@ Queue states worth recognising:
 
 ```bash
 gh pr checks <PR>                          # check-run table, exit 1 if any failed
-gh pr checks <PR> --watch                  # block until they settle
 gh pr view <PR> --json state,isDraft,mergeable,mergeStateStatus,statusCheckRollup
 gh pr view <PR> --json labels --jq '.labels[].name'   # queued / dequeued labels
 ```
 
+A one-shot table is the right tool here. Waiting is not: `gh pr checks <PR> --watch` repaints
+its table and its elapsed clock every 30 seconds, which reads as progress to anything watching
+the log while the actual CI steps slide out of view. To wait for CI, run the delivery watcher
+([`watch-contract.md`](watch-contract.md)) — or, for a PR outside a queue, the `github-flow`
+skill's `scripts/watch-checks.mjs`, which emits one record per real check-state change.
+
 Mergify labels a PR `queued` on entry and `dequeued` on removal
 (`merge_queue.queued_label` / `dequeued_label`). These are **lifecycle** signals,
 not a cheap membership check — what they mean depends on what you saw before

package/skills/cicd/mergify/references/watch-contract.md

@@ -49,7 +49,7 @@ Two of the four were written *after* the agent had been told to check for dequeu
 
 ### `phases` — the progression as output
 
-The watcher emits `phases`: the ordered list of lifecycle phases actually observed, on both the terminal verdict and every heartbeat. It resolves the one ambiguity the terminal outcome cannot:
+The watcher emits `phases`: the ordered list of lifecycle phases actually observed, on both the terminal verdict and every transition record. It resolves the one ambiguity the terminal outcome cannot:
 
 | terminal | `phases` | meaning | fix |
 |---|---|---|---|
@@ -181,7 +181,8 @@ so the newest batch wins over stale comment fallback.
 - **Run the bundled script. Do not hand-roll a watcher** — see the progression section above for why the hand-rolled shape cannot hold the contract, whatever care goes into the code. (If you are reading a legacy shell watcher: avoid shell-reserved variable names such as `status`.)
 - Keep enqueue and watch separate. A watch observes only; it does not post `@mergifyio queue`, `@mergifyio dequeue`, or merge.
 - Confirm the PR is queued, or can become queued, *before* launching the watch — see [Enqueue Before You Watch](#enqueue-before-you-watch). A watch that cannot enqueue, on a PR nothing else will enqueue either, can only end `STALLED`.
-- Emit an observation record every poll, not only on the terminal verdict. `NOT_YET_QUEUED` and `QUEUED` are both non-terminal and cover the entire healthy path, so a watcher that speaks only at the end is silent for essentially its whole life — indistinguishable, to the caller trying to decide whether delivery is progressing, from a hung or dead process. Keep the heartbeat off the machine-contract stream: stdout carries exactly the one terminal JSON document callers parse, stderr carries the per-poll records.
+- Emit the initial observation, then delivery-state or provider-readability transitions. Repeated identical polls stay quiet. A process supervisor counts new log bytes as activity even when a JSON record says `progress: false`, so labelling every heartbeat is insufficient. The initial record makes a waiting watch visible; the terminal verdict and existing no-change bounds explain how it ended. stdout remains exactly one terminal JSON document; stderr carries transition records and diagnostics.
+- Mark observation records `activity: true`; set `progress`/`changed` only when the canonical delivery state changed. Provider readability changes remain visible without resetting that change clock. `at`, `sinceChangeMs` and `elapsedMs` are diagnostic clocks, never progress. Keep the queue memory, readable-source snapshots, and existing stall bounds across quiet polls.
 - Bound on stalled state, not total elapsed time alone. `waiting_for_previous_batches` can be slow but healthy if position/state changes.
 
 ## Script
@@ -203,14 +204,14 @@ Options:
 | `--admission-stall-minutes` | `3` | pre-admission terminal stall bound — no observable change *before this process has observed membership* is `STALLED` with `reason: "admission-stall"`. Shorter on purpose: after enqueue, queue entry should appear quickly, and a dead admission path must not wait out the full post-entry bound. Capped at `--stall-minutes` so a caller that shortens the post-entry bound keeps both phases tight. Applies only while no non-Mergify check is pending; while CI runs, the post-entry bound applies, so a CI-gated admission needs no relaunch |
 | `--max-minutes` | `60` | absolute safety ceiling; bounds the watch even while the queue keeps reporting change, so a busy queue whose position keeps moving cannot keep the stall clock resetting forever. **60 minutes is also a hard maximum** — a larger value exits `2` rather than being silently clamped, because a caller that believes it has a four-hour watch and has one hour is worse off than one told plainly to relaunch. An hour without a verdict is a queue to hand back to a human or relaunch. The sibling `resolve-issues` watcher enforces the same ceiling; a cap honoured by one of two watchers is not a cap |
 | `--slow-job-minutes` | `5` | warn when a single CI job runs longer than this (see [CI profile](#ci-profile)) |
-| `--quiet` | off | suppress the per-poll progress heartbeat on stderr (slow-job warnings and the closing profile summary still print) |
+| `--quiet` | off | suppress delivery/readability transition records on stderr (slow-job warnings and the closing profile summary still print) |
 
 Output streams:
 
 | stream | content |
 |---|---|
 | stdout | exactly one pretty-printed terminal JSON verdict, at exit — carrying `phases`, `seenQueued`, the outcome, and `ciProfile` |
-| stderr | one compact JSON record per poll (`progress: true`), with the live outcome, PR labels, queue membership/position, `phases`, `changed`, and `sinceChangeMs` — the stall clock made visible; plus one `{"warning":"slow-ci-job"}` record per slow CI job; and, last, one `{"ciProfileSummary":true}` line after the verdict |
+| stderr | one compact JSON record per delivery/readability transition, marked `activity: true` (an observation was emitted) with `progress` set to whether the delivery state actually changed, plus the live outcome, PR labels, queue membership/position, `phases`, `changed`, and `sinceChangeMs` — the stall clock made visible; plus one `{"warning":"slow-ci-job"}` record per slow CI job; and, last, one `{"ciProfileSummary":true}` line after the verdict |
 
 Each regular-poll subprocess read (`gh pr view`, `mergify queue show`) also carries its own bounded
 timeout — a small multiple of `--interval-seconds`, clamped to never exceed the **effective
@@ -265,9 +266,11 @@ returns the PR's check runs with their start and finish times.
   `{"ciProfileSummary":true,"outcome","verdict","jobCount","slowJobMinutes","slowest","slowJobs"}`,
   with at most three slow jobs named as `"<name> <sec>s"`. The verdict is pretty-printed over
   many lines, so a short log tail lands inside `phases` and misses the profile; this line is
-  what a 10-line tail shows. A background runner that reports only the exit code (Pi's
-  `bg_task_status`) shows neither: read the log tail (`bg_task_log`) when the watch ends, and
-  report the profile. Identity #894 (2026-09-29) warned about a 338s job that no one read.
+  what a 10-line tail shows. A background runner that reports only the exit code shows
+  neither: read the log tail when the watch ends, and report the profile. Diagnose movement
+  from the emitted `progress`/`outcome` and phases. Repeated polls stay quiet, so a process
+  supervisor cannot mistake periodic heartbeat writes for progress. Identity #894
+  (2026-09-29) warned about a 338s job that no one read.
 
 Profiling is observation only: it never changes the outcome or the exit code. A slow-job
 warning is a lead for whoever owns the CI (split the job, cache, move it to a nightly lane) —