@miroshnik/elves 0.0.0 → 2026.1018.0

package/package.json

@@ -1 +1,70 @@
-{"name":"@miroshnik/elves","version":"0.0.0","description":"Elves: placeholder, releases are published by CI"}
+{
+  "name": "@miroshnik/elves",
+  "version": "2026.1018.0",
+  "type": "module",
+  "description": "Elves — a development flow with AI agents: shared rules and skills for any agent; install — bunx @miroshnik/elves install -g; the installer and skill scripts — TypeScript under Bun, tests — bun test in tests/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miroshnik/elves.git"
+  },
+  "bin": {
+    "elves": "bin/elves.ts"
+  },
+  "exports": {
+    "./spec/harness": {
+      "types": "./skills/spec/scripts/harness.ts",
+      "bun": "./skills/spec/scripts/harness.ts",
+      "default": "./dist/spec/scripts/harness.js"
+    },
+    "./spec/architecture": {
+      "types": "./skills/spec/scripts/architecture.ts",
+      "bun": "./skills/spec/scripts/architecture.ts",
+      "default": "./dist/spec/scripts/architecture.js"
+    },
+    "./spec/eslint-config": {
+      "types": "./skills/spec/scripts/eslint-config.ts",
+      "bun": "./skills/spec/scripts/eslint-config.ts",
+      "default": "./dist/spec/scripts/eslint-config.js"
+    },
+    "./github": {
+      "types": "./skills/github/scripts/github.ts",
+      "bun": "./skills/github/scripts/github.ts",
+      "default": "./dist/github/scripts/github.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "AGENTS.md",
+    "claude",
+    "docs/*.md",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.4.3",
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "scripts": {
+    "test": "bun --no-env-file skills/slot/scripts/slot.ts 'bun test --path-ignore-patterns=\"**/*.slow.test.ts\" --path-ignore-patterns=\"tests/standards/**\"'",
+    "test:slow": "bun --no-env-file skills/slot/scripts/slot.ts 'bun test .slow.test.ts'",
+    "test:spec": "bun --no-env-file skills/slot/scripts/slot.ts 'bun test tests/standards'",
+    "typecheck": "bun --no-env-file skills/slot/scripts/slot.ts 'bun check'",
+    "spec:doc": "bun test --reporter=junit --reporter-outfile=.spec-report.xml && bun --no-env-file skills/spec/scripts/spec-doc.ts .spec-report.xml --strict",
+    "spec:diff": "bun --no-env-file skills/spec/scripts/spec-diff.ts",
+    "spec:publish": "bun --no-env-file skills/spec/scripts/spec-publish.ts"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.2",
+    "eslint": "^10.11.0",
+    "eslint-plugin-boundaries": "^7.2.0",
+    "knip": "^6.41.0"
+  },
+  "gitHead": "e6b283ff871be91cc91f33e2a5637893d1f5e538"
+}

package/skills/ci-wait/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: ci-wait
+description: Waiting for all checks of a PR or commit (CI in GitHub Actions, the host's deploy, an external check) with a script that shows progress and has the outcomes PASS / FAIL / TIMEOUT / ERROR. When — after a push, before merging a PR; after a merge, before reporting "done", if the merge triggers a deploy (`merged <N>` — the script takes the merge SHA itself); whenever you need to wait for CI or a deploy, instead of `gh pr checks --watch`, `sleep` in a loop and manual polling; `issue <N>` — for the closing of the bug on a red main (`github pr premerge`, exit code 3).
+allowed-tools: Bash(bash *skills/ci-wait/scripts/wait-ci.sh *) Bash(gh pr checks *) Bash(gh pr view *) Bash(git rev-parse *)
+---
+
+# ci-wait — wait for checks, don't guess
+
+Waiting for CI and deploys must be observable, time-bounded and complete in
+its outcomes. `gh pr checks --watch` right after a push confuses "checks not
+registered yet" with "passed", `sleep` in a loop doesn't show what is
+happening, and manual polling gets forgotten. The `scripts/wait-ci.sh` script
+next to this file does it all deterministically; the agent only reads the
+outcome.
+
+Run it from the repository directory or with `--repo owner/repo` in any mode
+(as in the `github` scripts; or `GH_REPO=owner/repo`); in the
+background — from a directory that will outlive the wait (the main checkout,
+not a worktree that will be removed earlier): a directory removed meanwhile
+gives `ERROR getcwd`. As a background command — **without `| tail` or other
+filters**: the state lines land in the output file as the checks change, a
+filter holds them back until the end. A background wait dies with the app's
+process: a session resumed after a restart gets the command to restart it from
+the `SessionStart` hook (`github task resume`).
+
+```bash
+bash <skill dir>/scripts/wait-ci.sh pr <N> [--interval 30] [--timeout 1800] [--expect 0] [--wait-all]
+bash <skill dir>/scripts/wait-ci.sh status <sha> [--context <name>] [--interval 20] [--timeout 1200] [--expect 0] [--wait-all]
+bash <skill dir>/scripts/wait-ci.sh merged <N> [--context <name>] [--interval 20] [--timeout 1200] [--expect 0] [--wait-all]
+bash <skill dir>/scripts/wait-ci.sh issue <N> [--interval 60] [--timeout 7200]
+```
+
+## What to run when
+
+| Moment | Command |
+|---|---|
+| Pushed the PR branch, before merging | `pr <N>` — waits for the PR head's checks, the base branch's required checks and a run of every workflow whose `on:` fires on the PR; a conflict with the base — ERROR on the second poll of the same head, without waiting for the checks |
+| Merged, and the merge triggers a deploy or CI on `main` | `merged <N>` as a background command in the same turn as `github task actualize` — waits for all checks of the PR's merge commit: GitHub Actions check-runs and the statuses of the host and external services; takes the SHA from the PR itself, an unmerged PR — ERROR |
+| A commit's checks by SHA (my own commit without a PR) | `status <sha>` — the same as `merged`, by the full SHA |
+| One check of a commit is needed (the deploy among others) | `merged <N> --context <name>` or `status <sha> --context <name>` |
+| `github pr premerge` — exit code 3, `main` is red | `issue <N>` as a background command — waits for the bug on the red `main` to close: PASS when it is closed (with the reason: `completed`, `not_planned`); no such issue — ERROR; then `premerge` again |
+
+Don't fetch the SHA of your own merge — `merged <N>` takes it from the PR
+itself: separate `gh pr view` turns for it were the main source of extra turns
+after a merge (#285), and `git rev-parse origin/main` with parallel merges
+returns someone else's later commit. The `<sha>` for `status` is the full one;
+don't fill in a short one: for a nonexistent SHA the API silently returns an
+empty status, and the wait hangs until the timeout with a false "not ready".
+
+The name for `--context` is a status context or a check-run name (an Actions
+job); the state lines of a run without `--context` name the awaited ones, all
+of them — `gh pr checks <N>`.
+
+## How to read the result
+
+**The result is the exit code: don't read the output file** — neither while
+waiting (the command's completion wakes the session) nor after code `0`
+(PASS); only a non-zero code sends you to its `RESULT:` line.
+
+- stdout — a state line only when the state changes: the time, how long the
+  wait has run, how many checks are done and what is awaited —
+  `12:04:31 +3m10s pr#42@1a2b3c4: 3/5 done; waiting: tests, e2e; missing
+  required: lint` (`no run of workflow: <path>`, `failed: …` with
+  `--wait-all`, `API rate limit — next poll in …`); the final line `RESULT:
+  PASS|FAIL|TIMEOUT|ERROR …`.
+- stderr — `gh` errors and notes (the base branch's required checks, the
+  workflows due on the PR).
+- Exit code: `0` PASS · `1` FAIL (the failed ones are listed) · `2` TIMEOUT ·
+  `3` ERROR (a conflict with the base, PR or SHA not found, five `gh` errors
+  in a row, a wrong invocation).
+
+What to do next:
+
+- **PASS** — before merging a PR, `github pr premerge <N>` (if `main` moved
+  after CI — a check of the merge with a fresh one), exit code `0` — merge;
+  after the merge — `github task close` (the epic refresh ran in parallel with
+  the wait — the `github` skill, `task actualize`) and the "done" report.
+- **PASS only on the host's checks, without Actions** (the state lines named
+  only preview and comment statuses) in a repository with CI in Actions —
+  suspicious: `gh run list --commit <sha>` — was there a run and how did it
+  end.
+- **FAIL `workflow not parsed: <path> <link>`** — the workflow file on this
+  SHA doesn't parse (YAML), a run without a single job; `workflow failed
+  without jobs` — it didn't start (a reference to a nonexistent reusable
+  workflow, a policy ban). Fix the file; the reason is on the run's page at
+  the link.
+- **FAIL** — came on the first failed check, the others may still have been
+  running (a full snapshot — `--wait-all`). Read the failed check's logs
+  (`gh run view <id> --log-failed`), fix the cause; a "known red first
+  build" — re-run your own run (`gh run rerun <id> --failed`) and `ci-wait`
+  again. Don't merge. Jobs didn't start, with the annotation "recent account
+  payments have failed…" — the owner's billing, not the code
+  (`docs/pr-checks.md`).
+- **TIMEOUT** — count it neither as a success nor as a failure; the result
+  names what was still awaited: `no checks yet` — none registered; `waiting:
+  …` — a stuck runner or a long job; `waiting: workflow queued: <path>` — the
+  runner never picked up the run; `missing required` — a required check never
+  appeared (the workflow didn't start or was renamed); `no run of workflow:
+  <path>` — by its `on:` the workflow should have fired on the PR, but there
+  is no run on the head (Actions disabled, a GitHub incident, a PR from a fork
+  with a file that doesn't parse). If needed, repeat with a larger
+  `--timeout`.
+- **ERROR `conflict with base`** — nothing to wait for: rebase onto
+  `origin/<base>`, `git push --force-with-lease`, `ci-wait` again. Any other
+  ERROR is an access or invocation problem: the repository, `gh` permissions,
+  the PR number, the SHA.
+
+## Details the script exists for
+
+- An empty check list is pending, not "passed": checks register with a delay
+  after a push.
+- A commit has checks in two places: statuses (`commits/<sha>/status`) are
+  written by hosts and external services, check-runs
+  (`commits/<sha>/check-runs`) by GitHub Actions. Waiting for statuses alone
+  on a commit whose whole CI is Actions hangs until the timeout; `status`
+  waits for both. `pr` waits the same way, by the PR head's SHA.
+- One SHA holds the check-runs of all runs: one cancelled by a new push stays
+  when the head is moved back to the earlier commit, and re-running a job
+  adds a new one. The result follows the latest check-run of a name from the
+  same app, otherwise an early `cancelled` gives a false FAIL while the latest
+  one is green; a name from several apps gets the worst of their states.
+  `github task show` reads a check by the same table (standard
+  `check-run-state`).
+- REST only: `gh pr checks` goes to GraphQL, whose quota (5000 points per
+  hour) is shared by all of the user's sessions — with parallel sessions it
+  runs out. The PR head (`pulls/<N>`) is read on every poll: a new push
+  changes the SHA. A REST rate limit means waiting until the quota resets
+  (`gh api rate_limit`), not ERROR; that wait doesn't count toward
+  `--timeout` (up to an hour).
+- The poll interval grows with the wait: `--interval` is the first one, then a
+  tenth of the elapsed time, at most 5 minutes — a long deploy is polled
+  several times less often, the quota lasts, and the outcome comes at most a
+  tenth of the wait late. The confirming poll before PASS — at the first
+  interval.
+- A `gh` failure isn't an outcome, in the requests before the first poll too
+  (the commit for `status`, the required checks for `pr`): a retry, ERROR
+  after five in a row. "Commit not found" is only the API's answer "no" (422,
+  404); otherwise a one-off failure during a GitHub incident ended the wait
+  with a false "not found".
+- A PR with a conflict with the base (`mergeable: false`): there is no
+  merge-ref, and workflows on `pull_request` don't start at all — without
+  this check the wait ended with a result from the host's statuses alone.
+  `mergeable: null` — GitHub is still computing; keep waiting. Right after a
+  push GitHub still returns the previous head's `false` — the conflict that
+  was the reason for the rebase: a conflict counts only when the next poll of
+  the same head repeats it; until then — `waiting: conflict with base <base>:
+  rechecking`.
+- The base branch's required checks (ruleset and classic protection) are
+  awaited by name: while any one is missing there is no final result, even if
+  the rest have finished.
+- An Actions run that failed without a single job gives no check-run: when
+  the workflow isn't parsed, GitHub leaves a "dummy" run (the name is the
+  file path, event `push`, `conclusion: failure`), and the result came down
+  to the host's statuses alone — PASS without a single test run. So every
+  poll also reads the Actions runs on the SHA (`actions/runs?head_sha=`).
+- A queued run hasn't produced check-runs yet — without it the result also
+  came down to the host's statuses (#360). An unfinished run without
+  check-runs is pending `workflow queued: <path>` (or `in_progress`) until
+  the checks of its jobs appear.
+- `pr` waits for a run of every active workflow that, by its `on:` on the
+  head SHA, fires on the PR (`bun` parses the YAML; without it the check is
+  skipped with a note in stderr): `pull_request` without filters or with
+  branches that let the base through. A paths filter, `types` without
+  `synchronize`, a negation in branches can't be decided without the diff —
+  such a workflow isn't awaited; a file that doesn't parse is awaited: a PR
+  from a fork doesn't even get the "dummy".
+- The spec publish job (`spec-publish`, also `<job> / spec-publish` from a
+  reusable workflow — the `spec` skill, `ci.md`) isn't a check: it publishes
+  the documentation, so it is neither awaited nor a FAIL — after a merge the
+  deploy and `main`'s checks are awaited without it (#443). `--context
+  spec-publish` waits for it like any check.
+- A failed check means the result is already known: a long check next to it
+  (a preview deploy) won't change it, so FAIL comes at once.
+- PASS counts only when a snapshot without pending repeats for two polls in
+  a row; `--expect N` — the minimum number of checks, below which we keep
+  waiting.
+- Without branch protection `gh pr merge --auto` merges without waiting for
+  CI — so `--auto` doesn't replace waiting.
+- One wait at a time: don't start a second `ci-wait` on the same PR in
+  parallel.

package/skills/ci-wait/scripts/wait-ci.sh

@@ -0,0 +1,377 @@
+#!/usr/bin/env bash
+#
+# wait-ci.sh — waiting for the checks of a PR or a commit with visible progress and the full set
+# of outcomes. Run from the repository directory (gh resolves {owner}/{repo}), with --repo owner/repo or GH_REPO.
+#
+#   wait-ci.sh pr <N> | status <sha> | merged <N> | issue <N> [options] — the modes and options: wait-ci.sh --help,
+#   a mode's — wait-ci.sh <mode> --help (the help() function below).
+#
+# An Actions run at the SHA that failed without a single job (workflow not parsed, not started) — FAIL with the file path:
+# it gives no check-run, and without it the outcome came down to hosting statuses alone. An unfinished run without
+# check-runs (queued) — pending: there is a run at the SHA, but it has no checks yet.
+# The spec publish job (spec-publish) is not a check: neither awaited nor a FAIL — only by --context.
+# An empty list of checks — pending; PASS counts when a snapshot without pending repeats
+# two polls in a row (late-registering checks don't slip through) and there are no fewer checks
+# than --expect. The first failed check — FAIL right away; --wait-all — FAIL when all have finished.
+# --interval is the first interval: it grows with the wait — a tenth of the elapsed time, up to 5 min.
+# REST only: the GraphQL quota is shared by all sessions; a REST rate limit — waiting until the reset, and that wait
+# doesn't count toward --timeout (up to an hour). A gh failure (also in requests before the first poll) — retry, ERROR
+# after five in a row; "not found" — only on 404/422.
+#
+# Output: stdout — a state line only when the state changes ("<time> +<elapsed> <what>: 3/5 done; waiting: …")
+#         and the final line "RESULT: PASS|FAIL|TIMEOUT|ERROR …"; stderr — gh errors and notes.
+# Exit:  0 PASS · 1 FAIL · 2 TIMEOUT · 3 ERROR or a wrong call. The outcome is the exit code.
+set -uo pipefail
+
+# help [mode]: the mode's synopsis, what it does and examples, otherwise the overview (tests/standards/cli-help);
+# printf is a builtin — help runs no commands. The overview takes a mode's first line by command substitution, not a
+# pipeline (#495): `help "$m" | { read -r line; … }` — the reader leaves after one line, bash writes stdout line by line,
+# and the writer got SIGPIPE under load; with pipefail the last mode's 141 broke the && chain, and the tail was lost
+help() {
+  local m synopsis exits=("Exit: 0 PASS · 1 FAIL · 2 TIMEOUT · 3 ERROR or a wrong call — the outcome is the exit code; stdout — a state" \
+    "line when the state changes and the final line RESULT: PASS|FAIL|TIMEOUT|ERROR …, stderr — gh errors and notes.")
+  case "${1:-}" in
+    pr) printf '%s\n' \
+      "wait-ci pr <N> [--repo owner/repo] [--interval 30] [--timeout 1800] [--expect 0] [--wait-all]" "" \
+      "Waits for the checks of the PR head (like status), the base branch's required checks — by name, and the run of each" \
+      "workflow that, by its on: at the head SHA, fires on the PR (needs bun). A conflict with the base — ERROR once the next" \
+      "poll of the same head confirms it: CI won't start on such a PR; right after a push GitHub still reports the previous" \
+      "head's conflict. The first failed check — FAIL right away; --wait-all — FAIL when all have finished." \
+      "${exits[@]}" "" "Examples:" "  wait-ci pr 57" "  wait-ci pr 57 --repo octo/app --timeout 3600 --wait-all" ;;
+    status) printf '%s\n' \
+      "wait-ci status <sha> [--repo owner/repo] [--context <name>] [--interval 20] [--timeout 1200] [--expect 0] [--wait-all]" "" \
+      "Waits for all checks of a commit: commit statuses (hosting, external services) and check-runs (GitHub Actions)." \
+      "--context — one check by name, among both. The SHA is the full one, from git." \
+      "${exits[@]}" "" "Examples:" "  wait-ci status \"\$(git rev-parse HEAD)\"" "  wait-ci status \"\$(git rev-parse HEAD)\" --context Vercel --timeout 600" ;;
+    merged) printf '%s\n' \
+      "wait-ci merged <N> [--repo owner/repo] [--context <name>] [--interval 20] [--timeout 1200] [--expect 0] [--wait-all]" "" \
+      "Waits for all checks of the PR's merge commit (like status): takes the SHA from the PR itself — don't look it up" \
+      "after the merge. PR not merged — ERROR." \
+      "${exits[@]}" "" "Examples:" "  wait-ci merged 57" "  wait-ci merged 57 --context Vercel" ;;
+    issue) printf '%s\n' \
+      "wait-ci issue <N> [--repo owner/repo] [--interval 60] [--timeout 7200]" "" \
+      "Waits for an issue to close — the bug on a red main (github pr premerge, code 3): PASS when it is closed; no such" \
+      "issue — ERROR." \
+      "${exits[@]}" "" "Examples:" "  wait-ci issue 61" ;;
+    *) printf '%s\n' \
+      "wait-ci — waiting for the checks of a PR or a commit with visible progress and the full set of outcomes; the" \
+      "repository — --repo owner/repo (as in the github scripts), otherwise GH_REPO or the current directory's." ""
+      for m in pr status merged issue; do synopsis=$(help "$m"); printf '  %s\n' "${synopsis%%$'\n'*}"; done
+      printf '%s\n' "" "wait-ci <command> --help — the command's details and examples" ;;
+  esac
+}
+usage() { help "${mode:-}" >&2; exit 3; }
+
+for arg in "$@"; do
+  case "$arg" in --help|-h) help "${1:-}"; exit 0 ;; esac
+done
+
+mode=${1:-}; target=${2:-}
+[ -n "$mode" ] && [ -n "$target" ] || usage
+shift 2
+interval=""; timeout=""; expect=0; context=""; wait_all=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --interval) interval=$2; shift 2 ;;
+    --timeout)  timeout=$2;  shift 2 ;;
+    --expect)   expect=$2;   shift 2 ;;
+    --context)  context=$2;  shift 2 ;;
+    --wait-all) wait_all=1;  shift ;;
+    # the repository for gh, as --repo of the github scripts (#514): gh api resolves {owner}/{repo} from GH_REPO
+    --repo) [[ "${2:-}" == [!-]*/?* ]] || { echo "--repo expects owner/repo, got: ${2:-}" >&2; usage; }
+            export GH_REPO=$2; shift 2 ;;
+    *) echo "unknown arg: $1" >&2; usage ;;
+  esac
+done
+ts() { date +%H:%M:%S; }
+finish() { echo "RESULT: $1"; exit "$2"; }
+rate_limited() { grep -qi 'rate limit' <<<"$1"; }
+
+# checks <sha>: the commit's checks into $out — a JSON array {name, bucket}; bucket as in `gh pr checks`:
+# pending | pass | fail | cancel | skipping; paths of the workflows that produced a run at the SHA — into $ran. Code 1 — a gh
+# error, the text in $out.
+# The API already reduces statuses to the latest per context, but not check-runs: the SHA holds check-runs of all
+# runs (one cancelled by a new push when the head went back to an earlier commit; a job rerun) — CHECK_STATES below
+# reads them. An Actions run that failed without jobs gives no check-run: the workflow wasn't parsed (the run's name is
+# the file path) or didn't start (its check suite has no check-runs); such a run is a failed check with the file path
+# and a link. An unfinished run without check-runs (queued) — pending with the path: there is a run at the SHA, and
+# without this line the outcome came down to hosting statuses (#360).
+# The spec publish job (the spec skill, ci.md; "<job> / spec-publish" — the same job in a reusable workflow) — publishing
+# the documentation, not a check: it is neither awaited nor a FAIL, only by --context (#443). A copy — in the github
+# skill's premerge (SPEC_PUBLISH): its red isn't a red main; both answer by one table, tests/standards/spec-publish-job.
+SPEC_PUBLISH='^(.+ / )?spec-publish$'
+# The state of each check-run name (jq check_states over REST check-runs): not completed — pending; success — pass;
+# neutral, skipped — skipping; cancelled — cancel; any other conclusion — fail. Reruns of one name — the last check-run
+# of each app (the id grows with creation), not the best one and not the order of the response; several apps — the
+# worst of their states. A copy — in the github skill (checkStates: task show, project check): both answer by one table,
+# tests/standards/check-run-state.
+CHECK_STATES='def check_states:
+  group_by([.name, .app.id]) | map(max_by(.id))
+  | map({ name, bucket: (if .status != "completed" then "pending"
+                         elif .conclusion == "success" then "pass"
+                         elif .conclusion == "neutral" or .conclusion == "skipped" then "skipping"
+                         elif .conclusion == "cancelled" then "cancel"
+                         else "fail" end) })
+  | group_by(.name) | map(min_by(.bucket as $b | ["fail", "cancel", "pending", "skipping", "pass"] | index($b)));'
+ran='[]'
+checks() {
+  local statuses runs wruns
+  statuses=$(gh api "repos/{owner}/{repo}/commits/$1/status" 2>&1) || { out=$statuses; return 1; }
+  runs=$(gh api "repos/{owner}/{repo}/commits/$1/check-runs?per_page=100" 2>&1) || { out=$runs; return 1; }
+  wruns=$(gh api "repos/{owner}/{repo}/actions/runs?head_sha=$1&per_page=100" 2>&1) || { out=$wruns; return 1; }
+  ran=$(jq -c '[(.workflow_runs // [])[].path] | unique' <<<"$wruns")
+  out=$(jq -n --argjson s "$statuses" --argjson r "$runs" --argjson w "$wruns" --arg ctx "$context" --arg publish "$SPEC_PUBLISH" "$CHECK_STATES"'
+    [ $s.statuses[] | { name: .context,
+        bucket: (if .state == "success" then "pass" elif .state == "pending" then "pending" else "fail" end) } ]
+    + ($r.check_runs | check_states)
+    + [ [$r.check_runs[].check_suite.id] as $suites
+        | ($w.workflow_runs // []) | group_by([.path, .event]) | map(max_by(.id)) | .[]
+        | (.check_suite_id as $id | any($suites[]; . == $id) | not) as $nojobs
+        | if .status != "completed" then
+            select($nojobs) | { name: "workflow \(.status): \(.path) \(.html_url)", bucket: "pending" }
+          else
+            select((.conclusion == "failure" or .conclusion == "startup_failure") and (.name == .path or $nojobs))
+            | { name: "workflow \(if .name == .path then "not parsed" else "failed without jobs" end): \(.path) \(.html_url)",
+                bucket: "fail" }
+          end ]
+    | if $ctx != "" then map(select(.name == $ctx)) else map(select(.name | test($publish) | not)) end' 2>&1)
+}
+
+# required: names of the base branch's required checks — a ruleset and classic protection. No rules
+# or no right to read them (a private repo on Free answers 403, no branch — 404) — no required checks;
+# a rate limit or another failure — code 1, like a poll error: a one-off failure must not erase the required checks.
+required='[]'; required_loaded=""
+absent() { [[ "$1" == *"HTTP 403"* || "$1" == *"HTTP 404"* ]] && ! rate_limited "$1"; }
+load_required() {
+  local rules branch
+  rules=$(gh api "repos/{owner}/{repo}/rules/branches/$1" 2>&1) || { absent "$rules" || { out=$rules; return 1; }; rules='[]'; }
+  branch=$(gh api "repos/{owner}/{repo}/branches/$1" 2>&1) || { absent "$branch" || { out=$branch; return 1; }; branch='{}'; }
+  required=$(jq -nc --argjson r "$rules" --argjson b "$branch" '
+    [ ($r | arrays | .[] | select(.type == "required_status_checks") | .parameters.required_status_checks[].context),
+      ($b | objects | .protection.required_status_checks // {} | select(.enforcement_level != "off") | (.contexts // [])[]) ]
+    | unique' 2>/dev/null) || required='[]'
+  required_loaded=1
+  [ "$required" != '[]' ] && echo "$(ts) required on $1: $(jq -r 'join(", ")' <<<"$required")" >&2
+  return 0
+}
+
+# expected: paths of the workflows that should produce a run at the head on a PR event — by the `on:` of their files at
+# its SHA (#356). We wait for `pull_request` without filters or with branches that let the base in; a path filter, `types`
+# without `synchronize`, negation and other special characters in branches can't be decided without the PR diff — we
+# don't wait: a false TIMEOUT is worse. A file that doesn't parse — we wait: a "dummy" run will give FAIL, and a PR from a
+# fork has none at all. Active workflows only.
+expected='[]'; expected_for=""; workflows=""
+pr_expects() {  # stdin — a workflow as JSON (null — not parsed); code 0 — wait for its run on a PR into branch $1
+  jq -e --arg base "$1" '
+    def list: if type == "array" then . else [.] end;
+    def rx: "^" + (split("**") | map(split("*") | map(gsub("(?<c>[.^$(){}|\\\\])"; "\\\(.c)")) | join("[^/]*")) | join(".*")) + "$";
+    def match_base: list | if any(.[]; tostring | test("[?+\\[!]")) then null else any(.[]; tostring | rx as $r | $base | test($r)) end;
+    if type != "object" then true
+    else .on
+      | if type == "string" then (if . == "pull_request" then {} else null end)
+        elif type == "array" then (if any(.[]; . == "pull_request") then {} else null end)
+        elif type == "object" and has("pull_request") then (.pull_request // {})
+        else null end
+      | if type != "object" then false
+        elif has("paths") or has("paths-ignore") then false
+        elif has("types") and (.types | list | any(.[]; . == "synchronize") | not) then false
+        elif has("branches") then (.branches | match_base) == true
+        elif has("branches-ignore") then (.["branches-ignore"] | match_base) == false
+        else true end
+    end' >/dev/null
+}
+load_expected() {  # <sha> <base>
+  local list path raw doc exp='[]'
+  if [ -z "$workflows" ]; then
+    list=$(gh api "repos/{owner}/{repo}/actions/workflows?per_page=100" 2>&1) || { absent "$list" || { out=$list; return 1; }; list='{}'; }
+    workflows=$(jq -c '[(.workflows // [])[] | select(.state == "active" and (.path | startswith(".github/workflows/"))) | .path]' <<<"$list")
+  fi
+  if [ "$workflows" != '[]' ] && ! command -v bun >/dev/null; then
+    echo "$(ts) bun not found — workflows due on PR are not checked" >&2; workflows='[]'
+  fi
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    raw=$(gh api "repos/{owner}/{repo}/contents/$path?ref=$1" 2>&1) || { [[ "$raw" == *"HTTP 404"* ]] && continue; out=$raw; return 1; }
+    # not parsed — null; bun itself failing is a poll error, not "not parsed": retry
+    doc=$(jq -r '.content // "" | gsub("\n"; "") | @base64d' <<<"$raw" | bun -e '
+      const t = await Bun.stdin.text();
+      let d = null; try { d = Bun.YAML.parse(t) ?? null } catch {}
+      process.stdout.write(JSON.stringify(d))') || { out="bun failed on $path"; return 1; }
+    pr_expects "$2" <<<"$doc" && exp=$(jq -c --arg p "$path" '. + [$p]' <<<"$exp")
+  done < <(jq -r '.[]' <<<"$workflows")
+  expected=$exp; expected_for=$1
+  [ "$expected" != '[]' ] && echo "$(ts) workflows due on PR: $(jq -r 'join(", ")' <<<"$expected")" >&2
+  return 0
+}
+
+# poll: checks into $out (see checks). Code 1 — a gh error, 2 — waiting is pointless (ERROR); the text in $out.
+case "$mode" in
+  pr)
+    [[ "$target" =~ ^[0-9]+$ ]] || finish "ERROR PR number expected, got: $target" 3
+    : "${interval:=30}" "${timeout:=1800}"
+    label="pr#$target"; conflict_head=""
+    poll() {
+      local pull base mergeable
+      pull=$(gh api "repos/{owner}/{repo}/pulls/$target" 2>&1) || {
+        out=$pull; [[ "$pull" == *"HTTP 404"* ]] && { out="PR #$target not found: $pull"; return 2; }; return 1; }
+      base=$(jq -r .base.ref <<<"$pull")
+      # the head — on every poll: a new push changes the SHA, we must wait for the checks of the current one
+      head_sha=$(jq -r .head.sha <<<"$pull")
+      label="pr#$target@${head_sha:0:7}"
+      # GitHub computes mergeable in the background: null — doesn't know yet, false — a conflict, there is no
+      # merge-ref, and workflows on pull_request won't start at all. Right after a push it still gives the false of the
+      # previous head, whose conflict was the reason for the rebase (#472): a conflict is the current head's only when
+      # the next poll of the same head repeats it; until then — pending, not a PASS
+      mergeable=$(jq -r .mergeable <<<"$pull")
+      if [ "$mergeable" == false ] && [ "$conflict_head" == "$head_sha" ]; then
+        out="conflict with base $base — CI will not run; rebase onto origin/$base"; return 2
+      fi
+      [ "$mergeable" == false ] && conflict_head=$head_sha || conflict_head=""
+      [ -n "$required_loaded" ] || load_required "$base" || return 1
+      [ "$expected_for" == "$head_sha" ] || load_expected "$head_sha" "$base" || return 1
+      checks "$head_sha" || return 1
+      [ -z "$conflict_head" ] || out=$(jq -c --arg n "conflict with base $base: rechecking" '. + [{ name: $n, bucket: "pending" }]' <<<"$out")
+    }
+    ;;
+  status)
+    [[ "$target" =~ ^[0-9a-f]{40}$ ]] || finish "ERROR sha must be full 40-hex (take it from git: git rev-parse origin/main)" 3
+    : "${interval:=20}" "${timeout:=1200}"
+    label="${context:-commit}@${target:0:7}"; commit_found=""
+    poll() {
+      local commit
+      # for a nonexistent SHA the API silently returns an empty status — the commit is checked before the checks. "Not
+      # found" — only 422 "No commit found" or 404; another failure is a poll error: a one-off API failure is not an outcome
+      if [ -z "$commit_found" ]; then
+        commit=$(gh api "repos/{owner}/{repo}/commits/$target" --jq .sha 2>&1) || {
+          out=$commit; [[ "$commit" == *"HTTP 422"* || "$commit" == *"HTTP 404"* ]] && { out="commit $target not found in repository: $commit"; return 2; }; return 1; }
+        commit_found=1
+      fi
+      checks "$target"
+    }
+    ;;
+  merged)
+    [[ "$target" =~ ^[0-9]+$ ]] || finish "ERROR PR number expected, got: $target" 3
+    : "${interval:=20}" "${timeout:=1200}"
+    label="merge#$target"; merge_sha=""
+    poll() {
+      local pull
+      if [ -z "$merge_sha" ]; then
+        pull=$(gh api "repos/{owner}/{repo}/pulls/$target" 2>&1) || {
+          out=$pull; [[ "$pull" == *"HTTP 404"* ]] && { out="PR #$target not found: $pull"; return 2; }; return 1; }
+        [ "$(jq -r .merged <<<"$pull")" == true ] || { out="PR #$target not merged (state $(jq -r .state <<<"$pull")) — nothing to wait for"; return 2; }
+        # the SHA of our own merge — from the PR: with parallel merges git rev-parse origin/main returns someone else's commit
+        merge_sha=$(jq -r .merge_commit_sha <<<"$pull")
+        label="${context:-merge#$target}@${merge_sha:0:7}"
+      fi
+      checks "$merge_sha"
+    }
+    ;;
+  issue)
+    [[ "$target" =~ ^[0-9]+$ ]] || finish "ERROR issue number expected, got: $target" 3
+    : "${interval:=60}" "${timeout:=7200}"
+    label="issue#$target"
+    poll() {
+      local issue
+      issue=$(gh api "repos/{owner}/{repo}/issues/$target" 2>&1) || {
+        out=$issue; [[ "$issue" == *"HTTP 404"* ]] && { out="issue #$target not found: $issue"; return 2; }; return 1; }
+      # closed — the outcome is known right away: a repeated poll, as for checks, is needed for late-registering checks, not for an issue
+      [ "$(jq -r .state <<<"$issue")" == closed ] && finish "PASS issue #$target closed ($(jq -r '.state_reason // "closed"' <<<"$issue"))" 0
+      out=$(jq -nc --arg n "issue #$target" '[{ name: $n, bucket: "pending" }]')
+    }
+    ;;
+  *) usage ;;
+esac
+
+# rate_limit_wait: seconds until the core quota resets; a secondary limit (the quota isn't exhausted) — a minute
+rate_limit_wait() {
+  local core w=60
+  core=$(gh api rate_limit 2>/dev/null | jq -c .resources.core 2>/dev/null)
+  if [ "$(jq -r .remaining <<<"$core" 2>/dev/null)" == 0 ]; then
+    w=$(( $(jq -r .reset <<<"$core") - $(date +%s) + 1 ))
+  fi
+  [ "$w" -lt "$interval" ] && w=$interval
+  echo "$w"
+}
+
+# state <max>: the last poll's checks ($out) in words — how many are done and what we wait for: pending ones, required
+# ones not registered yet, workflows due on the PR without a run at the head; failed ones (--wait-all). A list longer
+# than <max> names is cut ("+N more"), 0 — the whole list.
+state() {
+  jq -r --argjson req "$required" --argjson due "$expected" --argjson ran "$ran" --argjson max "$1" '
+    def names: sort | if $max > 0 and length > $max then .[:$max] + ["+\(length - $max) more"] else . end | join(", ");
+    map(select(.bucket == "pending") | .name) as $wait
+    | [ if length == 0 then "no checks yet" else "\(length - ($wait | length))/\(length) done" end,
+        ($wait | select(. != []) | "waiting: \(names)"),
+        ($req - map(.name) | select(. != []) | "missing required: \(names)"),
+        ($due - $ran | select(. != []) | "no run of workflow: \(names)"),
+        (map(select(.bucket == "fail" or .bucket == "cancel") | .name) | select(. != []) | "failed: \(names)") ]
+    | join("; ")' <<<"$out"
+}
+
+# dur <seconds>: 45s, 3m05s, 1h20m
+dur() {
+  if [ "$1" -lt 60 ]; then echo "${1}s"
+  elif [ "$1" -lt 3600 ]; then printf '%dm%02ds\n' $(($1 / 60)) $(($1 % 60))
+  else printf '%dh%02dm\n' $(($1 / 3600)) $(($1 % 3600 / 60)); fi
+}
+
+# say <state>: a state line — only when it differs from the previous one: the output file of a background wait shows
+# what we wait for and since when, not a heartbeat per poll (#432)
+said=""
+say() {
+  [ "$label: $1" == "$said" ] && return
+  said="$label: $1"
+  echo "$(ts) +$(dur $(( $(date +%s) - start ))) $label: $1"
+}
+
+start=$(date +%s); deadline=$(( start + timeout ))
+prev_terminal=""; errors=0; quota_wait=0; full="no checks yet"
+while :; do
+  poll; rc=$?
+  # the interval grows with the wait — a tenth of the elapsed time, up to 5 min: a long deploy is polled several times
+  # less often, the REST quota shared by parallel sessions lasts, and the outcome comes at most a tenth of the wait late
+  nap=$(( ($(date +%s) - start) / 10 )); [ "$nap" -gt 300 ] && nap=300; [ "$nap" -lt "$interval" ] && nap=$interval
+  if [ "$rc" -eq 0 ]; then
+    errors=0
+    snapshot=$(printf '%s' "$out" | jq -r 'sort_by(.name) | .[] | "\(.name)\t\(.bucket)"')
+    total=$(printf '%s' "$out" | jq 'length')
+    pending=$(printf '%s' "$out" | jq '[.[] | select(.bucket=="pending")] | length')
+    failed=$(printf '%s' "$out" | jq -r '[.[] | select(.bucket=="fail" or .bucket=="cancel") | .name] | join(", ")')
+    missing=$(printf '%s' "$out" | jq -r --argjson req "$required" '$req - map(.name) | join(", ")')
+    # a workflow that by its `on:` fires on the PR but produced no run at the head is not final, like a required check
+    unrun=$(jq -rn --argjson e "$expected" --argjson r "$ran" '$e - $r | join(", ")')
+    full=$(state 0)
+    say "$(state 5)"
+    # a failed check — the outcome is known: long checks alongside it (a preview deploy) won't change it
+    [ -n "$failed" ] && [ -z "$wait_all" ] && finish "FAIL $failed" 1
+    if [ "$total" -gt 0 ] && [ "$total" -ge "$expect" ] && [ "$pending" -eq 0 ] && [ -z "$missing" ] && [ -z "$unrun" ]; then
+      if [ "$snapshot" == "$prev_terminal" ]; then
+        [ -n "$failed" ] && finish "FAIL $failed" 1
+        finish "PASS ($total checks)" 0
+      fi
+      prev_terminal=$snapshot
+      # the confirming poll — at the first interval: everything has finished, a grown interval would only delay PASS
+      nap=$interval
+    else
+      prev_terminal=""
+    fi
+  elif [ "$rc" -eq 2 ]; then
+    finish "ERROR $out" 3
+  elif rate_limited "$out"; then
+    # a rate limit is not a call error: the checks go on by themselves, we wait for the quota. That wait doesn't count
+    # toward --timeout — the quota resets within an hour, and a reset 40 min away under a 30 min timeout gave TIMEOUT
+    # without a single poll after it; at most an hour in total, so a limit that never lifts still ends the wait
+    nap=$(rate_limit_wait)
+    extra=$nap; [ $((quota_wait + extra)) -gt 3600 ] && extra=$((3600 - quota_wait))
+    quota_wait=$((quota_wait + extra)); deadline=$((deadline + extra))
+    say "API rate limit — next poll in $(dur "$nap")"
+  else
+    errors=$((errors + 1))
+    echo "$(ts) $label: gh error ($errors): ${out:0:200}" >&2
+    [ "$errors" -ge 5 ] && finish "ERROR gh: ${out:0:200}" 3
+  fi
+  now=$(date +%s)
+  [ "$now" -ge "$deadline" ] && finish "TIMEOUT after $(dur $((now - start))) ($full)" 2
+  [ "$nap" -gt $((deadline - now)) ] && nap=$((deadline - now))
+  sleep "$nap"
+done