@1aboveio/cicd-skills 0.1.21 → 0.1.22

package/skills/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/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) —

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

@@ -319,9 +319,8 @@ export const DEFAULT_SLOW_JOB_MINUTES = 5
 //
 // 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.
+// committed: stdout is exactly one terminal JSON verdict; stderr contains NDJSON transitions
+// and diagnostics. An exit-2 usage error is loud, immediate, and matches other bad bounds.
 export const MAX_MINUTES_CEILING = 60
 
 export function readTimeoutMs(intervalSeconds, boundMinutes, readsPerPoll = 1) {
@@ -730,28 +729,12 @@ export function classifyDequeue({ rawReason = null, failedChecks = [] } = {}) {
   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.
+// Emit the initial delivery snapshot and subsequent delivery/readability transitions.
+// Repeated snapshots stay quiet: process supervisors count newly written bytes as activity
+// even when a record says progress:false. A readability transition remains visible without
+// resetting the delivery change clock. stdout remains one terminal JSON verdict.
 export function progressRecord({ payload, changed, sinceChangeMs, nowIso }) {
-  return JSON.stringify({ ...payload, progress: true, changed, sinceChangeMs, at: nowIso })
+  return JSON.stringify({ ...payload, activity: true, progress: changed, changed, sinceChangeMs, at: nowIso })
 }
 
 // Defaults. `stallMinutes` is a NO-CHANGE bound, not an elapsed-time one — any observable
@@ -813,11 +796,12 @@ Options:
   --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
+  --quiet                        Suppress delivery/readability transition records 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;
+  stderr  one compact JSON record per delivery/readability change (activity:true, progress:<the delivery state
+          actually changed>), 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
@@ -882,6 +866,7 @@ export async function runCli(argv) {
   let missingActiveReads = 0
   let stallObservationCache = null
   let lastChangeMs = startedMs
+  let lastReadability = null
   let observations = 0
   let phases = []
   let lastBatchPrNumber = null
@@ -890,7 +875,7 @@ export async function runCli(argv) {
   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.
+  // of profiling, and --quiet only silences routine transition records.
   const warnSlowJobs = () => {
     for (const { key, job } of newSlowJobs(ciJobs, { thresholdMs: slowThresholdMs, warned: warnedSlowJobs })) {
       warnedSlowJobs.add(key)
@@ -1025,12 +1010,12 @@ export async function runCli(argv) {
       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 readability = JSON.stringify([pr.readable !== false, queue.readable !== false])
+    if (!args.quiet && (changed || readability !== lastReadability)) {
       const now = Date.now()
       console.error(progressRecord({ payload, changed, sinceChangeMs: now - lastChangeMs, nowIso: new Date(now).toISOString() }))
     }
+    lastReadability = readability
 
     const elapsedMs = Date.now() - startedMs
     if (elapsedMs >= args.maxMinutes * 60_000) {

package/skills/podman/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: podman
 description: "Debug, design, or fix Podman: rootless/rootful containers, pods, podman-compose, the socket and systemd services, Docker-compatible API (DOCKER_HOST/CONTAINER_HOST), networking, volumes, SELinux labels, Docker migration, and CI/SSH provisioning of rootless sockets (user lingering, XDG_RUNTIME_DIR). Covers FailedToOpenSocket and systemctl --user DBUS/XDG errors."
-release-version: 0.50.1
+release-version: 0.50.2
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Podman Operations