@1aboveio/cicd-skills 0.1.21 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/cicd-skills",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "GitHub Actions and flow, Mergify, Docker and Podman, Cloud Build, Cloud Deploy and Google Cloud.",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
     "id": "cicd",
     "core": "@1aboveio/core-skills",
     "coreSkills": [],
-    "digest": "24e2387878d5b0ea32ddb264a0f4bfde12e8f38eb8763b3a51fcd7c2f47f9192"
+    "digest": "6ba6fcb3f5bf1b6fdff64648f8c2d6537ed012c1d59430b5df3ae46fb464bd3d"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skills/cloud-build/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cloud-build
 description: "Build or debug Cloud Build pipelines for Cloud Run: cloudbuild.yaml, triggers, Artifact Registry, builds, migrations, deploys, secrets, VPC, notifications. Use cloud-deploy for staged promotion. NOT for GitHub Actions PR checks (github-actions)."
-release-version: 0.50.1
+release-version: 0.50.3
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Cloud Build Direct Deploy to Cloud Run

package/skills/cloud-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cloud-debug
 description: "Debug Cloud Build or Deploy failures: builds, deployments, health checks, and pipeline errors. Inputs: service, build ID, region. NOT for GitHub Actions runs (github-actions) or runtime errors in a running service (app-debug)."
-release-version: 0.50.1
+release-version: 0.50.3
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Cloud Build & Cloud Deploy Debug Skill

package/skills/cloud-deploy/SKILL.md

@@ -5,7 +5,7 @@ description: >
   CI/CD pipelines with staged promotion, verification gates, or GitFlow branching.
   Also use when debugging Cloud Deploy pipeline failures. NOT for simple single-container
   deploys — use cloud-build instead.
-release-version: 0.50.1
+release-version: 0.50.3
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Cloud Deploy + Skaffold + Kustomize for Cloud Run

package/skills/docker/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: docker
 description: Docker/Podman container architecture and build patterns. Read when designing or reviewing containerization, Dockerfile structure, multi-stage builds, PyPI mirror support, or docker-compose setup for Python/uv projects, and when a Dockerfile's dependency install misses the layer cache on every build (build args such as a commit SHA or version declared too early) or an image build is slow in CI.
-release-version: 0.50.1
+release-version: 0.50.3
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Docker Build Patterns

package/skills/github-actions/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: github-actions
 description: "Author, review, audit, profile, optimize, or debug GitHub Actions workflows (.github/workflows/*.yml): run-history audits, job and step timing, resource bottlenecks, before/after comparisons, conditional CI by changed path, the one required gate check, PR and merge-queue lanes, sharding, workers, caching, self-hosted runners, timeouts, concurrency, permissions and action pinning, post-deploy verification, npm publishing. Use for 'set up CI', 'CI is slow', 'profile CI', 'optimize our pipeline', 'audit CI for redundant or wasted jobs', 'why is this check stuck expected or never started', 'harden this workflow', or 'browser not found on the runner'. NOT for pushing, opening, or merging a PR, or writing CI conventions into CONTRIBUTING.md (github-flow), queue rules or a check unmet inside Mergify (mergify), Playwright config and specs (e2e-test), cloudbuild.yaml or Cloud Run deploys (cloud-build), or which gates a repo must prove (ensure-coverage)."
-release-version: 0.50.1
+release-version: 0.50.3
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # GitHub Actions
@@ -43,7 +43,9 @@ replacement of an established pipeline during an audit or performance-only chang
 7. **Add post-deploy and scheduled lanes** if the repo deploys or publishes.
    → [post-deploy-and-publishing.md](references/post-deploy-and-publishing.md)
 8. **Verify**: `actionlint`; one PR per area runs only that area's jobs; timings meet the SLA.
-   Failures → [debugging.md](references/debugging.md)
+   Failures → [debugging.md](references/debugging.md). Waiting on a live run, or on a publish
+   run → [debugging.md#watching-a-run](references/debugging.md#watching-a-run): `scripts/watch-run.mjs`
+   reports job/step transitions and slow steps, which `gh run watch`'s 30-second repaint hides.
 
 ## Principles
 

package/skills/github-actions/references/debugging.md

@@ -11,3 +11,24 @@
 - Queue/dequeue questions → `mergify` skill; `gh pr checks` can't see a dequeue.
 - Validate locally: `actionlint` for syntax and expression mistakes; `act` for simple jobs
   (not for self-hosted or service-container jobs).
+
+## Watching a run
+
+`gh run watch` repaints a status block and an elapsed clock every 30 seconds, and that repaint
+is not progress: a job wedged in one step reads exactly like a job moving, while the step names
+are what scrolls out of view. Watch with the bounded CLI instead:
+
+```bash
+node "$SKILL_DIR/scripts/watch-run.mjs" --run <id> [--repo owner/repo]
+```
+
+It reads `gh run view --json status,conclusion,jobs` on an interval and writes one record only
+when the run's state changes, naming the job/step transitions that caused it (`changes`). A job
+or step past `--slow-step-minutes` is warned about once **while it is still running**, with its
+duration and URL. The exit code is the verdict: 0 green; 4 names the failed job and its failed
+steps, or `STALLED` with `reason: no-progress` naming the jobs nothing has started, or
+`UNKNOWN` when the provider stays unreadable — an unreadable read is no information, never a
+red run.
+
+For a finished run's full job/step profile, that is the other tool:
+`scripts/ci-run-audit.mjs --profile-run <id>`.

package/skills/github-actions/references/post-deploy-and-publishing.md

@@ -31,3 +31,10 @@ npm packages: trusted publishing (OIDC, no token): `environment: npm-publish`,
 already published? then assert its provenance matches this commit), a pack-contents check,
 publish, poll the registry until visible, then create the tag and release idempotently.
 Restrict to the default branch; pin the npm version; keep `contents: write` off the install step.
+
+**The registry is the verdict, not the run.** A green publish workflow proves the job exited 0;
+the published version is what the registry reports. Wait on the artifact (`npm view
+<pkg>@<version> version`), and read the run for diagnosis with `scripts/watch-run.mjs` — its
+job/step transitions and slow-step warnings are the useful signal, while a repainted status
+line is not. A run that fails after the version appears is a hand-back naming what already
+shipped; a version that never appears is not a success however green the run was.

package/skills/github-actions/scripts/watch-run.mjs

@@ -0,0 +1,511 @@
+#!/usr/bin/env node
+// watch-run — wait for one GitHub Actions run and report only the job/step transitions it
+// actually makes. Read-only: it only reads `gh run view`.
+//
+//   node watch-run.mjs --run <id> [--repo <owner>/<name>]
+//     [--interval-seconds 30] [--stall-minutes 15] [--max-minutes 60]
+//     [--slow-step-minutes 5] [--read-retries 2] [--unreadable-polls 3]
+//
+// Why this exists instead of `gh run watch`:
+//
+//   `gh run watch` repaints a status block — and an elapsed clock — every 30 seconds. To
+//   anything that reads output activity as progress (a log tail, a file mtime, an agent
+//   skim), that repaint is indistinguishable from a run doing work, and the run's own steps
+//   are exactly what stops being visible: a job wedged in one step for twenty minutes reads
+//   the same as a job moving.
+//
+// So this polls discrete JSON reads and treats only a change in the canonical run state as
+// progress. Each change is reported as the job/step transition that caused it, with the
+// duration of the step that moved, and a slow step is called out once while it is still
+// running rather than discovered afterwards.
+//
+// Streams:
+//   stdout  exactly one terminal JSON verdict, at exit.
+//   stderr  one compact JSON record per observed run-state change (`kind:"transition"`,
+//           `progress:true`, with a `changes` list of job/step transitions), one
+//           `{"warning":"slow-ci-step"}` per slow job or step, one provider-unreadable
+//           record when reads fail, and one closing `{"summary":true}` line.
+//
+// The record's projection is `state` — run status/conclusion plus each job's status and
+// current step, no clocks. `at`, `elapsedMs` and `observations` are for humans; a
+// background-task predicate watches `progress`/`state`, never log size or mtime.
+//
+// Exit codes: 0 the run succeeded (or was neutral/skipped). 4 failed, cancelled, timed out,
+// stalled, unreadable, or an unknown run state. 2 usage error.
+
+import { execFileSync } from 'node:child_process'
+
+const PASSING = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED'])
+const STATUSES = new Set(['REQUESTED', 'WAITING', 'PENDING', 'QUEUED', 'IN_PROGRESS', 'COMPLETED'])
+const CONCLUSIONS = new Set([...PASSING, 'FAILURE', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STALE', 'STARTUP_FAILURE'])
+const RUN_FIELDS = 'status,conclusion,jobs,workflowName,headSha,url,attempt'
+const MAX_MINUTES_CEILING = 240
+const MAX_READ_BYTES = 16 * 1024 * 1024
+const MAX_REPORTED_CHANGES = 25
+
+function help() {
+  return `watch-run --run <id> [options]
+
+Wait for one Actions run, reporting job and step transitions. Read-only; it never
+re-runs, cancels, dispatches, or edits anything.
+
+  --run <id>                 run to watch (required)
+  --repo <owner>/<name>      repository; defaults to the current checkout
+  --interval-seconds <n>     poll interval (default 30)
+  --stall-minutes <n>        no-observable-change bound while nothing is in progress
+                             (default 15); suspended while a job or step is running
+  --max-minutes <n>          absolute ceiling (default 60, max ${MAX_MINUTES_CEILING})
+  --slow-step-minutes <n>    warn once per job or step running longer (default 5)
+  --read-retries <n>         extra attempts inside one poll (default 2)
+  --unreadable-polls <n>     consecutive unreadable polls before UNKNOWN (default 3)
+
+Outcome values: SUCCESS, NEUTRAL, FAILED, CANCELLED, STALLED, UNKNOWN.
+
+Exit 0: SUCCESS, NEUTRAL. Exit 4: every other outcome. Exit 2: usage.`
+}
+
+function parseArgs(argv) {
+  const args = {
+    intervalSeconds: 30,
+    stallMinutes: 15,
+    maxMinutes: 60,
+    slowStepMinutes: 5,
+    readRetries: 2,
+    unreadablePolls: 3,
+  }
+  const numbers = {
+    '--interval-seconds': 'intervalSeconds',
+    '--stall-minutes': 'stallMinutes',
+    '--max-minutes': 'maxMinutes',
+    '--slow-step-minutes': 'slowStepMinutes',
+    '--read-retries': 'readRetries',
+    '--unreadable-polls': 'unreadablePolls',
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--run') args.run = argv[++i]
+    else if (arg === '--repo') args.repo = 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.run ?? ''))) return '--run 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'
+  }
+  for (const key of ['intervalSeconds', 'stallMinutes', 'maxMinutes', 'slowStepMinutes']) {
+    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))
+
+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) {
+  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)) return { ok: false, error: 'gh run view returned no object' }
+    return { ok: true, data }
+  } catch (error) {
+    const stderr = String(error?.stderr ?? '').trim()
+    return { ok: false, error: stderr || String(error?.message ?? 'gh run view failed') }
+  }
+}
+
+function readRun(args, timeoutMs) {
+  const ghArgs = ['run', 'view', String(args.run), '--json', RUN_FIELDS]
+  if (args.repo) ghArgs.push('--repo', args.repo)
+  return ghJson(ghArgs, timeoutMs)
+}
+
+const upper = (value) => String(value ?? '').toUpperCase()
+const timeMs = (value) => {
+  const parsed = Date.parse(value ?? '')
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null
+}
+
+function normalizeSteps(job) {
+  return (Array.isArray(job?.steps) ? job.steps : []).map((step, index) => ({
+    index: Number.isFinite(step?.number) ? step.number : index + 1,
+    name: step?.name || `step-${index + 1}`,
+    status: upper(step?.status) || null,
+    conclusion: upper(step?.conclusion) || null,
+    startedMs: timeMs(step?.startedAt),
+    completedMs: timeMs(step?.completedAt),
+  }))
+}
+
+function normalizeJob(job) {
+  const steps = normalizeSteps(job)
+  const current = steps.filter((step) => step.status === 'IN_PROGRESS').at(-1)
+    ?? steps.filter((step) => step.status !== null).at(-1)
+    ?? null
+  return {
+    id: String(job?.databaseId ?? job?.url ?? job?.name ?? 'unnamed-job'),
+    name: job?.name || 'unnamed-job',
+    status: upper(job?.status) || null,
+    conclusion: upper(job?.conclusion) || null,
+    startedMs: timeMs(job?.startedAt),
+    completedMs: timeMs(job?.completedAt),
+    url: typeof job?.url === 'string' && job.url.startsWith('http') ? job.url : null,
+    steps,
+    current,
+  }
+}
+
+// The canonical projection: run status/conclusion plus each job's status and the step it is
+// on. Sorted by job name, no clocks — this is what "the run changed" means, and what a
+// background task can predicate on.
+function project(data) {
+  const jobs = (Array.isArray(data.jobs) ? data.jobs : [])
+    .filter(Boolean)
+    .map(normalizeJob)
+    .sort((a, b) => {
+      const key = (job) => JSON.stringify([job.name, job.id, job.status, job.conclusion,
+        job.steps.map((step) => [step.index, step.name, step.status, step.conclusion])])
+      return key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0
+    })
+  const state = {
+    run: {
+      attempt: data.attempt ?? null,
+      status: upper(data.status) || null,
+      conclusion: upper(data.conclusion) || null,
+      workflow: data.workflowName ?? null,
+      sha: data.headSha ?? null,
+    },
+    jobs: jobs.map((job) => ({
+      id: job.id,
+      name: job.name,
+      status: job.status,
+      conclusion: job.conclusion,
+      step: job.current?.name ?? null,
+      stepStatus: job.current?.status ?? null,
+    })),
+    running: jobs.flatMap((job) => job.steps
+      .filter((step) => step.status === 'IN_PROGRESS')
+      .map((step) => `${job.name} / ${step.name}`)),
+    waiting: jobs.filter((job) => job.status !== 'COMPLETED' && job.status !== 'IN_PROGRESS')
+      .map((job) => `${job.name}:${job.status ?? 'unknown'}`),
+  }
+  // The change key is finer than the emitted projection: a step moving is a change even
+  // when the job and run statuses are unchanged. It is never emitted — only compared.
+  const key = JSON.stringify([
+    state.run,
+    jobs.map((job) => [job.id, job.name, job.status, job.conclusion, job.steps.map((step) => [step.index, step.name, step.status, step.conclusion])]),
+  ])
+  return { jobs, state, key }
+}
+
+const label = (status, conclusion) => conclusion || status || 'unknown'
+
+// The transitions between two projections, as lines a human can read in a log tail.
+function describeChanges(previousState, previousJobs, { jobs, state }) {
+  const changes = []
+  if (previousState && previousJobs) {
+    if (previousState.run.status !== state.run.status || previousState.run.conclusion !== state.run.conclusion) {
+      changes.push(`run: ${label(previousState.run.status, previousState.run.conclusion)} -> ${label(state.run.status, state.run.conclusion)}`)
+    }
+    if (previousState.run.attempt !== state.run.attempt) {
+      changes.push(`run attempt: ${previousState.run.attempt} -> ${state.run.attempt}`)
+    }
+    const before = new Map(previousJobs.map((job) => [job.id, job]))
+    for (const job of jobs) {
+      const prior = before.get(job.id)
+      if (!prior) changes.push(`job ${job.name}: appeared (${label(job.status, job.conclusion)})`)
+      else if (prior.status !== job.status || prior.conclusion !== job.conclusion) {
+        changes.push(`job ${job.name}: ${label(prior.status, prior.conclusion)} -> ${label(job.status, job.conclusion)}`)
+      }
+      const priorSteps = new Map((prior?.steps ?? []).map((step) => [step.index, label(step.status, step.conclusion)]))
+      for (const step of job.steps) {
+        const was = priorSteps.get(step.index)
+        const now = label(step.status, step.conclusion)
+        if (!was) changes.push(`step ${job.name} / ${step.name}: appeared (${now})`)
+        else if (was !== now) changes.push(`step ${job.name} / ${step.name}: ${was} -> ${now}`)
+      }
+    }
+  }
+  if (previousState && changes.length === 0) changes.push('run state changed (job, step, or run metadata)')
+  const extra = Math.max(0, changes.length - MAX_REPORTED_CHANGES)
+  return {
+    changes: changes.slice(0, MAX_REPORTED_CHANGES),
+    changesOmitted: extra,
+  }
+}
+
+// One warning per job run and per step run, emitted while they are still running.
+function slowRecords(jobs, { thresholdMs, warned, nowMs, runUrl }) {
+  const out = []
+  const emit = (kind, key, { durationMs, ...fields }) => {
+    if (warned.has(key) || durationMs <= thresholdMs) return
+    warned.add(key)
+    out.push(JSON.stringify({
+      warning: 'slow-ci-step',
+      kind,
+      durationSec: Math.round(durationMs / 1000),
+      thresholdSec: Math.round(thresholdMs / 1000),
+      ...fields,
+    }))
+  }
+  for (const job of jobs) {
+    const jobEnd = job.completedMs ?? nowMs
+    if (job.startedMs) {
+      emit('job', `job|${job.name}|${job.startedMs}`, {
+        job: job.name,
+        step: null,
+        status: label(job.status, job.conclusion),
+        durationMs: jobEnd - job.startedMs,
+        url: job.url ?? runUrl,
+      })
+    }
+    for (const step of job.steps) {
+      if (!step.startedMs) continue
+      emit('step', `step|${job.name}|${step.name}|${step.startedMs}`, {
+        job: job.name,
+        step: step.name,
+        status: label(step.status, step.conclusion),
+        durationMs: (step.completedMs ?? nowMs) - step.startedMs,
+        url: job.url ?? runUrl,
+      })
+    }
+  }
+  return out
+}
+
+function failureDetail(jobs) {
+  const failed = jobs.filter((job) => job.conclusion && !PASSING.has(job.conclusion))
+  const named = failed.map((job) => {
+    const steps = job.steps.filter((step) => step.conclusion && !PASSING.has(step.conclusion)).map((step) => step.name)
+    return steps.length > 0 ? `${job.name} (${job.conclusion}: ${steps.join(', ')})` : `${job.name} (${job.conclusion})`
+  })
+  return {
+    failedJobs: named,
+    detail: named.length > 0 ? named.join('; ') : 'the run finished without a conclusion',
+  }
+}
+
+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-run: ${invalid}`)
+    return 2
+  }
+
+  const startedMs = Date.now()
+  const slowThresholdMs = args.slowStepMinutes * 60_000
+  const warnedSlow = new Set()
+  let lastKey = null
+  let lastState = null
+  let previousState = null
+  let previousJobs = null
+  let lastRunUrl = null
+  let unreadablePolls = 0
+  let observations = 0
+  let transitions = 0
+  let lastError = null
+  let changedAtMs = startedMs
+  let lastReadable = true
+  let lastUnreadableKey = null
+  let latestJobs = []
+
+  const finish = (result) => {
+    const endMs = Date.now()
+    const failures = failureDetail(latestJobs)
+    const verdict = {
+      outcome: result.outcome,
+      terminal: true,
+      reason: result.reason ?? null,
+      detail: result.detail ?? null,
+      run: {
+        id: Number(args.run),
+        attempt: lastState?.run?.attempt ?? null,
+        status: lastState?.run?.status ?? null,
+        conclusion: lastState?.run?.conclusion ?? null,
+        workflow: lastState?.run?.workflow ?? null,
+        sha: lastState?.run?.sha ?? null,
+        url: lastRunUrl,
+      },
+      jobs: lastState?.jobs ?? [],
+      failedJobs: failures.failedJobs,
+      slowJobs: [...warnedSlow].filter((key) => key.startsWith('job|')).map((key) => key.slice(4, key.lastIndexOf('|'))),
+      slowSteps: [...warnedSlow].filter((key) => key.startsWith('step|')).map((key) => {
+        const [, job, ...rest] = key.split('|')
+        return `${job} / ${rest.slice(0, -1).join('|')}`
+      }),
+      observations,
+      transitions,
+      elapsedMs: endMs - startedMs,
+    }
+    console.log(JSON.stringify(verdict, null, 2))
+    console.error(JSON.stringify({
+      summary: true,
+      outcome: verdict.outcome,
+      reason: verdict.reason,
+      failedJobs: verdict.failedJobs,
+      slowSteps: verdict.slowSteps,
+      running: lastState?.running ?? [],
+    }))
+    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 = readRun(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
+      const key = `unreadable|${read.error}`
+      if (lastReadable || key !== lastUnreadableKey) {
+        lastUnreadableKey = key
+        lastReadable = false
+        transitions += 1
+        console.error(JSON.stringify({
+          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 run view failed ${unreadablePolls} polls in a row: ${lastError}`, exitCode: 4 })
+      }
+      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 })
+      }
+      await sleepMs(args.intervalSeconds * 1000)
+      continue
+    }
+
+    unreadablePolls = 0
+    const { jobs, state, key } = project(read.data)
+    latestJobs = jobs
+    lastState = state
+    lastRunUrl = read.data.url ?? null
+
+    if (!STATUSES.has(state.run.status)) {
+      return finish({ outcome: 'UNKNOWN', reason: 'unknown-run-state', detail: `unsupported run status: ${state.run.status ?? 'missing'}`, exitCode: 4 })
+    }
+    if ((state.run.conclusion && !CONCLUSIONS.has(state.run.conclusion)) ||
+        (state.run.status === 'COMPLETED' && !state.run.conclusion)) {
+      return finish({ outcome: 'UNKNOWN', reason: 'unknown-run-conclusion', detail: `unsupported run conclusion: ${state.run.conclusion ?? 'missing'}`, exitCode: 4 })
+    }
+
+    const malformed = jobs.find((job) => !STATUSES.has(job.status) ||
+      (job.conclusion && !CONCLUSIONS.has(job.conclusion)) ||
+      job.steps.some((step) => !STATUSES.has(step.status) ||
+        (step.conclusion && !CONCLUSIONS.has(step.conclusion))))
+    if (malformed) {
+      return finish({ outcome: 'UNKNOWN', reason: 'unknown-job-state', detail: `unsupported job or step state in ${malformed.name}`, exitCode: 4 })
+    }
+
+    if (key !== lastKey || !lastReadable) {
+      const stateChanged = key !== lastKey
+      const { changes, changesOmitted } = describeChanges(previousState, previousJobs, { jobs, state })
+      const reason = lastKey === null ? 'run-state-initial' : lastReadable ? 'run-state' : 'provider-readable'
+      lastKey = key
+      if (stateChanged) changedAtMs = Date.now()
+      transitions += 1
+      lastReadable = true
+      console.error(JSON.stringify({
+        kind: 'transition',
+        progress: stateChanged,
+        reason,
+        at: new Date().toISOString(),
+        ...(reason === 'run-state-initial' ? {} : { changes: stateChanged ? changes : [], changesOmitted: stateChanged ? changesOmitted : 0 }),
+        state,
+      }))
+    }
+    previousState = state
+    previousJobs = jobs
+
+    for (const warning of slowRecords(jobs, { thresholdMs: slowThresholdMs, warned: warnedSlow, nowMs: Date.now(), runUrl: lastRunUrl })) {
+      console.error(warning)
+    }
+
+    if (state.run.status === 'COMPLETED') {
+      const conclusion = state.run.conclusion
+      if (PASSING.has(conclusion)) {
+        return finish({
+          outcome: conclusion === 'SUCCESS' ? 'SUCCESS' : 'NEUTRAL',
+          reason: `run-${String(conclusion).toLowerCase()}`,
+          exitCode: 0,
+        })
+      }
+      const failures = failureDetail(jobs)
+      return finish({
+        outcome: conclusion === 'CANCELLED' ? 'CANCELLED' : 'FAILED',
+        reason: `run-${String(conclusion || 'unknown').toLowerCase()}`,
+        detail: failures.detail,
+        exitCode: 4,
+      })
+    }
+
+    const inProgress = state.running.length > 0 || jobs.some((job) => job.status === 'IN_PROGRESS')
+
+    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 run still ${state.run.status ?? 'unknown'}`,
+        exitCode: 4,
+      })
+    }
+    // Nothing progressed and nothing is running: this is the shape that hides behind a
+    // repainting status line — a job queued for a runner that will never match it.
+    if (!inProgress && Date.now() - changedAtMs >= args.stallMinutes * 60_000) {
+      return finish({
+        outcome: 'STALLED',
+        reason: 'no-progress',
+        detail: state.waiting.length > 0
+          ? `no job or step started for ${args.stallMinutes}m; waiting on ${state.waiting.join(', ')}`
+          : `no observable run-state change for ${args.stallMinutes}m`,
+        exitCode: 4,
+      })
+    }
+
+    await sleepMs(args.intervalSeconds * 1000)
+  }
+}
+
+process.exitCode = await main().catch((error) => {
+  console.error(JSON.stringify({ error: 'watch-run-failed', detail: String(error?.message ?? error) }))
+  return 4
+})