diff --git a/.github/workflows/0-test-changeset-coverage.yaml b/.github/workflows/0-test-changeset-coverage.yaml
new file mode 100644
index 00000000..6d8a2d23
--- /dev/null
+++ b/.github/workflows/0-test-changeset-coverage.yaml
@@ -0,0 +1,41 @@
+name: 'Test: changeset/check-coverage'
+
+on:
+  workflow_call:
+  workflow_dispatch:   # manual escape hatch — also lets us re-run after a workflow edit
+  pull_request:
+    paths:
+      - 'actions/changeset/check-coverage/**'
+  push:
+    paths:
+      - 'actions/changeset/check-coverage/**'
+    branches: ['v4', 'v4-beta']
+
+jobs:
+  bats:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # No `version:` — the repo's root package.json sets `packageManager`,
+      # and pnpm/action-setup errors if both are specified.
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install bats
+        run: sudo apt-get update && sudo apt-get install -y bats
+
+      - name: Verify required tools are present
+        run: |
+          which jq yq pnpm bats
+          jq --version
+          yq --version
+          pnpm --version
+          bats --version
+
+      - name: Run changeset/check-coverage bats suite
+        working-directory: actions/changeset/check-coverage
+        run: bats test/coverage.bats
diff --git a/.github/workflows/node-simple-pnpm.yaml b/.github/workflows/node-simple-pnpm.yaml
index b35d737b..455171c9 100644
--- a/.github/workflows/node-simple-pnpm.yaml
+++ b/.github/workflows/node-simple-pnpm.yaml
@@ -582,6 +582,55 @@ jobs:
           run: |
             pnpm changeset status --since="origin/${BRANCH_NAME}"
 
+  changeset-coverage:
+    name: changeset coverage (diagnostic)
+    runs-on: ubuntu-latest
+    # Diagnostic only: surface per-package changeset gaps as a red check, never block.
+    # The check-coverage step omits continue-on-error, so a gap (exit 1) fails this
+    # job and its check turns red. Job-level continue-on-error keeps the run green and
+    # the merge available. Separate from check-changesets so the native
+    # `changeset status` gate keeps blocking. Keep this job out of required checks.
+    continue-on-error: true
+    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+    needs:
+      - metadata
+    steps:
+      - id: context
+        uses: milaboratory/github-ci/actions/context@v4
+
+      - uses: milaboratory/github-ci/actions/env@v4
+        with:
+          inputs: ${{ inputs.env }}
+          secrets: ${{ secrets.env }}
+
+      - uses: actions/checkout@v4
+        with:
+          lfs: ${{ inputs.checkout-git-lfs }}
+          submodules: ${{ inputs.checkout-submodules }}
+          fetch-depth: '0'
+
+      - name: Prepare environment for building a NodeJS application
+        uses: milaboratory/github-ci/actions/node/prepare-pnpm@v4
+        env:
+          PNPM_VERSION: ${{ needs.metadata.outputs.pnpm-version }}
+        with:
+          node-version: ${{ inputs.node-version }}
+          cache-version: ${{ inputs.cache-version }}
+          pnpm-version: ${{ env.PNPM_VERSION || inputs.pnpm-version }}
+          cache-hashfiles-search-path: ${{ inputs.cache-hashfiles-search-path }}
+          npmrc-config: ${{ inputs.npmrc-config }}
+
+      - name: Install NodeJS packages with pnpm
+        uses: milaboratory/github-ci/actions/shell@v4
+        with:
+          run: |
+            pnpm install --frozen-lockfile --prefer-offline
+
+      - name: Check changeset coverage
+        uses: milaboratory/github-ci/actions/changeset/check-coverage@v4
+        with:
+          base-branch: ${{ inputs.changeset-default-branch }}
+
   pre-calculated-build:
     name: pre-build
     runs-on: ${{ inputs.gha-runner-label }}
diff --git a/actions/changeset/check-coverage/action.yaml b/actions/changeset/check-coverage/action.yaml
new file mode 100644
index 00000000..07f97209
--- /dev/null
+++ b/actions/changeset/check-coverage/action.yaml
@@ -0,0 +1,30 @@
+name: Check changeset coverage
+author: 'MiLaboratories'
+description: |
+  Fail if a PR's changesets don't cover every workspace package it modifies.
+
+  Catches two common gaps:
+    - editing files inside a workspace package (e.g. block code under
+      packages/<pkg>/) without adding that package to the changeset;
+    - bumping a catalog version in pnpm-workspace.yaml without a matching
+      bump for the workflow packages that consume it via `catalog:`.
+
+  Runs after `pnpm install`. Requires the runner to have `pnpm`, `jq`, and
+  `yq` (mikefarah, v4+) on PATH — all pre-installed on GitHub-hosted
+  ubuntu-latest images.
+
+inputs:
+  base-branch:
+    description: Base branch to diff against (e.g. main).
+    required: true
+
+runs:
+  using: 'composite'
+
+  steps:
+    - name: Check changeset coverage
+      shell: bash
+      env:
+        ACTION_PATH: ${{ github.action_path }}
+        BASE_BRANCH: ${{ inputs.base-branch }}
+      run: '${ACTION_PATH}/check-coverage.sh'
diff --git a/actions/changeset/check-coverage/check-coverage.sh b/actions/changeset/check-coverage/check-coverage.sh
new file mode 100755
index 00000000..a7ad8311
--- /dev/null
+++ b/actions/changeset/check-coverage/check-coverage.sh
@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+#
+# Verify the PR's changesets bump every workspace package the PR modifies.
+# Exit 1 on a coverage gap; exit 2 on tooling failure; exit 0 otherwise.
+#
+# Two sources of "modified":
+#
+#   1. Direct edits to a workspace package's files, detected via
+#      `pnpm --filter '[<base>]' list` — pnpm runs the per-package
+#      git-diff check itself.
+#
+#   2. Catalog version bumps in pnpm-workspace.yaml: for each touched
+#      catalog key, find workspace packages that consume it via
+#      `"<key>": "catalog:..."` and require those packages to bump.
+#
+# Skips private (unpublished) workspace packages — they never appear in
+# the changeset's release set.
+#
+# Runs from the repo root after `pnpm install`.
+
+set -o nounset
+set -o errexit
+set -o pipefail
+
+: "${BASE_BRANCH:?BASE_BRANCH required}"
+
+log()  { printf '%s\n' "$*" >&2; }
+err()  { printf '::error::%s\n' "$*" >&2; }
+
+# Associative arrays (`declare -A`) require bash 4+. The GitHub-hosted
+# ubuntu-latest runners ship bash 5+, so this guard is a no-op in CI today.
+# It matters when running locally on macOS: /bin/bash is still 3.2, and
+# without homebrew's bash earlier on PATH the script would otherwise abort
+# at the first `declare -A` with a cryptic `invalid option`. Fail fast with
+# a useful message instead.
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+  err "check-coverage requires bash 4+ (found ${BASH_VERSION:-unknown})."
+  exit 2
+fi
+
+# Use cwd-relative paths for tmp files — changeset's --output mis-handles
+# absolute paths on macOS (prepends cwd, causing ENOENT). Cwd-relative is
+# safe on every platform.
+status_json=".changeset-coverage-status-$$.json"
+pkg_list_json=".changeset-coverage-pkgs-$$.json"
+
+# ---------------------------------------------------------------------------
+# 1. Bumped set from `changeset status --output=...`.
+# ---------------------------------------------------------------------------
+trap 'rm -f "${status_json}" "${pkg_list_json}"' EXIT
+
+# Invoke the binary directly. `pnpm exec` and `pnpm <script>` spawn subshells
+# that lose `node_modules/.bin` from PATH on repeated invocations. The action
+# runs from the repo root after `pnpm install`, so the binary is at this
+# fixed location in CI.
+changeset_bin='./node_modules/.bin/changeset'
+if [ ! -x "${changeset_bin}" ]; then
+  err 'changeset binary not found. Did `pnpm install` run before this step?'
+  exit 2
+fi
+
+# Capture stderr to distinguish the legitimate "no changesets yet" state
+# (exit 1 + "no changesets were found" message) from a real tooling failure.
+# The former is a coverage gap to report; the latter aborts with exit 2.
+cs_stdouterr=''
+set +e
+cs_stdouterr="$(
+  "${changeset_bin}" status \
+    --output="${status_json}" \
+    --since="origin/${BASE_BRANCH}" 2>&1
+)"
+cs_exit=$?
+set -e
+
+if [ ! -s "${status_json}" ]; then
+  if printf '%s' "${cs_stdouterr}" | grep -q 'no changesets were found'; then
+    # Legitimate empty-changeset case — keep going so the coverage check
+    # surfaces every modified package as missing.
+    echo '{"releases":[]}' >"${status_json}"
+  elif [ "${cs_exit}" -ne 0 ]; then
+    err "changeset status failed (exit ${cs_exit}):"
+    printf '%s\n' "${cs_stdouterr}" | sed 's/^/    /' >&2
+    exit 2
+  else
+    echo '{"releases":[]}' >"${status_json}"
+  fi
+fi
+
+declare -A bumped_set=()
+while IFS= read -r pkg; do
+  [ -n "${pkg}" ] && bumped_set["${pkg}"]=1
+done < <(jq -r '.releases[]?.name // empty' "${status_json}")
+
+if [ "${#bumped_set[@]}" -eq 0 ]; then
+  log 'Changeset bumps: <none>'
+else
+  log "Changeset bumps: ${!bumped_set[*]}"
+fi
+
+# ---------------------------------------------------------------------------
+# 2. Required-bump set.
+# ---------------------------------------------------------------------------
+declare -A required_set=()
+declare -A required_reason=()
+
+require_pkg() {
+  local pkg="$1" reason="$2"
+  [ -z "${pkg}" ] && return 0
+  required_set["${pkg}"]=1
+  required_reason["${pkg}"]="${required_reason[${pkg}]:-}${reason}; "
+}
+
+# 2a. Direct workspace-package edits.
+#
+# `pnpm --filter '[<since>]' list` selects packages whose own files changed
+# (pnpm runs the per-package `git diff` itself). Root-level paths like
+# `.github/`, `docs/`, `pnpm-workspace.yaml`, or `README.md` are not in any
+# package directory and so don't trigger inclusion — no manual ignore list
+# needed.
+#
+# The jq filter drops private packages here (they never appear in a
+# changeset's release set), so `require_pkg` doesn't need to re-check.
+while IFS= read -r pkg; do
+  [ -n "${pkg}" ] && require_pkg "${pkg}" 'direct edit'
+done < <(
+  pnpm -r --filter "[origin/${BASE_BRANCH}]" list --depth -1 --json 2>/dev/null \
+    | jq -r '.[] | select(.name != null and .name != "" and .private != true) | .name'
+)
+
+log "Direct-edit packages: ${#required_set[@]}"
+
+# 2b. Catalog version bumps in pnpm-workspace.yaml.
+#
+# Only runs when the workspace yaml itself changed. Builds a full
+# workspace map so we can find every consumer of each touched catalog key.
+if git diff --name-only "origin/${BASE_BRANCH}...HEAD" | grep -qx 'pnpm-workspace.yaml'; then
+  pnpm -r list --depth -1 --json >"${pkg_list_json}"
+
+  # pnpm returns canonical absolute paths; strip the workspace root via
+  # `pwd -P` so the result matches the workspace's view on either platform.
+  workspace_root="$(pwd -P)"
+  declare -A pkg_name_to_dir=()
+  declare -A pkg_is_private=()
+
+  while IFS=$'\t' read -r pkg_name pkg_path pkg_private; do
+    [ -z "${pkg_name}" ] && continue           # workspace root has no name
+    rel="${pkg_path#${workspace_root}/}"
+    [ "${rel}" = "${pkg_path}" ] && continue   # workspace root itself
+    pkg_name_to_dir["${pkg_name}"]="${rel}"
+    pkg_is_private["${pkg_name}"]="${pkg_private}"
+  done < <(jq -r '
+      .[]
+      | select(.name != null and .name != "")
+      | [.name, .path, (.private // false | tostring)]
+      | @tsv
+    ' "${pkg_list_json}")
+
+  # Extract catalog keys whose value changed (added, removed, or bumped).
+  # Parse both the base and head versions structurally with yq, flatten the
+  # default catalog and any named catalogs to `key=value` lines, then take
+  # entries unique to either side. Avoids the false-positive surface of a
+  # line-level regex on the raw diff.
+  cat_pairs() {
+    yq -e '
+      [
+        (.catalog // {} | to_entries[]),
+        (.catalogs // {} | to_entries[].value // {} | to_entries[])
+      ] | .[] | .key + "=" + .value
+    ' 2>/dev/null || true
+  }
+  old_pairs="$(git show "origin/${BASE_BRANCH}:pnpm-workspace.yaml" 2>/dev/null | cat_pairs || true)"
+  new_pairs="$(cat_pairs <pnpm-workspace.yaml || true)"
+  mapfile -t catalog_keys < <(
+    { printf '%s\n' "${old_pairs}"; printf '%s\n' "${new_pairs}"; } \
+      | sed '/^$/d' \
+      | sort | uniq -u \
+      | sed -E 's/=.*//' \
+      | sort -u
+  )
+
+  if [ "${#catalog_keys[@]}" -gt 0 ]; then
+    log "Catalog keys touched: ${catalog_keys[*]}"
+    # For each catalog key, find workspace pkgs that depend on it with "catalog:".
+    for key in "${catalog_keys[@]}"; do
+      for name in "${!pkg_name_to_dir[@]}"; do
+        [ "${pkg_is_private[${name}]:-false}" = 'true' ] && continue
+        pj="${pkg_name_to_dir[${name}]}/package.json"
+        [ -f "${pj}" ] || continue
+        if jq -e --arg k "${key}" '
+            [.dependencies?, .devDependencies?, .peerDependencies?, .optionalDependencies?]
+            | map(select(. != null) | to_entries) | add // []
+            | map(select(.key == $k and ((.value // "") | startswith("catalog:"))))
+            | length > 0
+          ' "${pj}" >/dev/null 2>&1; then
+          require_pkg "${name}" "catalog dep '${key}' bumped"
+        fi
+      done
+    done
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Compare required vs bumped.
+# ---------------------------------------------------------------------------
+missing=()
+for pkg in "${!required_set[@]}"; do
+  [ -z "${bumped_set[${pkg}]:-}" ] && missing+=("${pkg}")
+done
+
+if [ "${#missing[@]}" -eq 0 ]; then
+  log '✓ Changeset covers every modified package.'
+  exit 0
+fi
+
+err 'Changeset coverage gap. The following packages were modified but not bumped:'
+for pkg in "${missing[@]}"; do
+  reason="${required_reason[${pkg}]%; }"
+  err "  - ${pkg}  (${reason})"
+done
+err ''
+err "Add a changeset entry — run \`pnpm changeset\` and select the missing packages."
+exit 1
diff --git a/actions/changeset/check-coverage/test/README.md b/actions/changeset/check-coverage/test/README.md
new file mode 100644
index 00000000..e959a052
--- /dev/null
+++ b/actions/changeset/check-coverage/test/README.md
@@ -0,0 +1,74 @@
+# `check-coverage` tests
+
+Bats suite for `../check-coverage.sh`.
+
+## Run locally
+
+From the action directory:
+
+```bash
+cd actions/changeset/check-coverage
+bats test/coverage.bats
+```
+
+Or from anywhere in the worktree:
+
+```bash
+bats actions/changeset/check-coverage/test/coverage.bats
+```
+
+The first run takes ~30s (one `pnpm install` into the shared fixture).
+Subsequent assertions reuse that install — each test only does a tar copy
+and a couple of git ops.
+
+## Dependencies
+
+| Tool   | macOS                 | ubuntu-latest |
+| ------ | --------------------- | ------------- |
+| `bats` | `brew install bats-core` | `apt-get install -y bats` |
+| `yq`   | `brew install yq`     | preinstalled  |
+| `jq`   | preinstalled          | preinstalled  |
+| `pnpm` | `brew install pnpm`   | `pnpm/action-setup@v4` |
+| `node` | any modern version    | `actions/setup-node@v4` |
+
+## How it works
+
+- `helpers.bash` builds a single base workspace under `$BATS_FILE_TMPDIR/base`
+  in `setup_file`: copies the fixture, runs `pnpm install`, inits a git repo
+  with `gc.auto=0` (suppresses the async repack that would otherwise race
+  the tar copy), commits, and synthesizes an `origin/main` ref.
+- Each test (`setup`) tars the base into `$BATS_TEST_TMPDIR/ws`, switches
+  to a `feature` branch, applies mutations via the helpers
+  (`touch_file`, `add_changeset`, `bump_catalog`), and runs the script
+  with `BASE_BRANCH=main`. The test asserts on the script's exit code and
+  the captured `$output`.
+
+## Fixture
+
+`fixtures/minimal-workspace/` — small pnpm workspace:
+
+- `packages/pkg-a`, `packages/pkg-b` — both consume `is-number` via `catalog:`
+- `packages/pkg-c` — consumes `is-string` via `catalog:`
+- `packages/pkg-private` — `"private": true`, never requires a bump
+
+## CI
+
+`.github/workflows/0-test-changeset-coverage.yaml` runs the suite on
+`pull_request` and `push` (`v4`, `v4-beta`) whenever files under
+`actions/changeset/check-coverage/**` or the workflow itself change.
+
+## Adding a test
+
+```bats
+@test "describe the contract" {
+  touch_file 'packages/pkg-a/index.js'        # mutate
+  add_changeset '"@check-coverage-test/pkg-a": patch' 'edit pkg-a'
+  run_check                                   # sets $status, $output
+  [ "${status}" -eq 0 ]
+  [[ "${output}" == *'expected substring'* ]]
+}
+```
+
+The helpers in `helpers.bash` cover the common mutations. Drop down to
+raw `git -C "${WORKSPACE}"` calls or `yq -i` edits when you need
+something they don't.
diff --git a/actions/changeset/check-coverage/test/coverage.bats b/actions/changeset/check-coverage/test/coverage.bats
new file mode 100644
index 00000000..369a6d98
--- /dev/null
+++ b/actions/changeset/check-coverage/test/coverage.bats
@@ -0,0 +1,206 @@
+#!/usr/bin/env bats
+
+load helpers.bash
+
+setup_file() {
+  _build_base_workspace "${BATS_FILE_TMPDIR}/base"
+}
+
+setup() {
+  new_workspace
+}
+
+# ---------------------------------------------------------------------------
+# Direct edits.
+# ---------------------------------------------------------------------------
+
+@test "passes when nothing under any package changes" {
+  touch_file 'README.md' 'workspace-root readme edit'
+  run_check
+  [ "${status}" -eq 0 ]
+}
+
+@test "passes when only docs/ at workspace root changes" {
+  touch_file 'docs/overview.md' 'doc update'
+  run_check
+  [ "${status}" -eq 0 ]
+}
+
+@test "fails when a package is edited without a changeset" {
+  touch_file 'packages/pkg-a/index.js'
+  run_check
+  [ "${status}" -eq 1 ]
+  [[ "${output}" == *'@check-coverage-test/pkg-a'* ]]
+}
+
+@test "passes when a package is edited and a matching changeset is added" {
+  touch_file 'packages/pkg-a/index.js'
+  add_changeset '"@check-coverage-test/pkg-a": patch' 'edit pkg-a'
+  run_check
+  [ "${status}" -eq 0 ]
+}
+
+@test "edit to a private package never requires a bump" {
+  touch_file 'packages/pkg-private/index.js'
+  run_check
+  [ "${status}" -eq 0 ]
+}
+
+@test "reports every missing package, not just the first" {
+  touch_file 'packages/pkg-a/index.js'
+  touch_file 'packages/pkg-b/index.js'
+  run_check
+  [ "${status}" -eq 1 ]
+  [[ "${output}" == *'@check-coverage-test/pkg-a'* ]]
+  [[ "${output}" == *'@check-coverage-test/pkg-b'* ]]
+}
+
+@test "reports only the still-missing package when one of many is covered" {
+  touch_file 'packages/pkg-a/index.js'
+  touch_file 'packages/pkg-b/index.js'
+  add_changeset '"@check-coverage-test/pkg-a": patch' 'edit pkg-a'
+  run_check
+  [ "${status}" -eq 1 ]
+  [[ "${output}" == *'@check-coverage-test/pkg-b'* ]]
+  # The covered package should not appear in the missing list.
+  [[ "${output}" != *'- @check-coverage-test/pkg-a'* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Catalog bumps.
+# ---------------------------------------------------------------------------
+
+@test "catalog bump without consumer bumps fails and names every consumer" {
+  bump_catalog 'is-number' '^7.0.1'
+  run_check
+  [ "${status}" -eq 1 ]
+  [[ "${output}" == *'@check-coverage-test/pkg-a'* ]]
+  [[ "${output}" == *'@check-coverage-test/pkg-b'* ]]
+  # pkg-c consumes is-string, not is-number — should not be flagged.
+  [[ "${output}" != *'@check-coverage-test/pkg-c'* ]]
+}
+
+@test "catalog bump with both consumers bumped passes" {
+  bump_catalog 'is-number' '^7.0.1'
+  add_changeset '"@check-coverage-test/pkg-a": patch
+"@check-coverage-test/pkg-b": patch' 'bump is-number'
+  run_check
+  [ "${status}" -eq 0 ]
+}
+
+@test "catalog bump where only one consumer is bumped still fails for the other" {
+  bump_catalog 'is-number' '^7.0.1'
+  add_changeset '"@check-coverage-test/pkg-a": patch' 'bump is-number partial'
+  run_check
+  [ "${status}" -eq 1 ]
+  [[ "${output}" == *'@check-coverage-test/pkg-b'* ]]
+  [[ "${output}" != *'- @check-coverage-test/pkg-a'* ]]
+}
+
+@test "non-catalog YAML edits in pnpm-workspace.yaml don't trigger requirements" {
+  # An `overrides` entry that happens to share a name with a catalog key.
+  # Bumping it must NOT be treated as a catalog change — yq's structural
+  # parse ignores anything outside .catalog / .catalogs.
+  yq -i '.overrides."is-number" = "^7.0.5"' "${WORKSPACE}/pnpm-workspace.yaml"
+  git -C "${WORKSPACE}" commit --quiet -am 'bump override (not catalog)'
+  run_check
+  [ "${status}" -eq 0 ]
+}
+
+@test "catalog bump for an unused key does not require any package" {
+  # Add then bump a catalog entry no one consumes.
+  yq -i '.catalog."unused-pkg" = "^1.0.0"' "${WORKSPACE}/pnpm-workspace.yaml"
+  git -C "${WORKSPACE}" commit --quiet -am 'add unused catalog key'
+  bump_catalog 'unused-pkg' '^1.0.1'
+  run_check
+  [ "${status}" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Empty-changeset corner case.
+# ---------------------------------------------------------------------------
+
+@test "no changesets at all + irrelevant edit passes" {
+  touch_file 'README.md' 'no-package change'
+  run_check
+  [ "${status}" -eq 0 ]
+}
+
+@test "no changesets at all + package edit fails" {
+  touch_file 'packages/pkg-c/index.js'
+  run_check
+  [ "${status}" -eq 1 ]
+  [[ "${output}" == *'@check-coverage-test/pkg-c'* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Base-branch input.
+# ---------------------------------------------------------------------------
+
+# Production callers pass `inputs.changeset-default-branch` (typically `v4`
+# in this repo, `master` in others). The script touches `origin/${BASE_BRANCH}`
+# in five places — this guards against any of them regressing to a hardcoded
+# `main`.
+@test "respects BASE_BRANCH input (works against origin/v4, not just main)" {
+  git -C "${WORKSPACE}" update-ref refs/remotes/origin/v4 refs/remotes/origin/main
+  git -C "${WORKSPACE}" update-ref -d refs/remotes/origin/main
+  touch_file 'packages/pkg-a/index.js'
+  cd "${WORKSPACE}"
+  BASE_BRANCH=v4 run "${SCRIPT_UNDER_TEST}"
+  [ "${status}" -eq 1 ]
+  [[ "${output}" == *'@check-coverage-test/pkg-a'* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Tooling failures.
+# ---------------------------------------------------------------------------
+
+# Exit 2 is the contract for "tooling broken, can't determine coverage" —
+# distinct from exit 1 ("gap found"). Without this, a regression that turns
+# a missing binary into a silent pass-through wouldn't be caught.
+@test "exit 2 when changeset binary is missing" {
+  rm -f "${WORKSPACE}/node_modules/.bin/changeset"
+  touch_file 'packages/pkg-a/index.js'
+  run_check
+  [ "${status}" -eq 2 ]
+  [[ "${output}" == *'changeset binary not found'* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Known limitations (skipped — document deferred follow-ups).
+# ---------------------------------------------------------------------------
+
+# Documents the deferred bug from PR #168: the catalog-key flatten in
+# check-coverage.sh collapses `.catalogs.alpha.<key>` and `.catalogs.beta.<key>`
+# into a single key=value stream, losing which named catalog owns each entry.
+# When two named catalogs both pin the same package and only one bumps, the
+# symmetric diff still emits the bare key — so consumers of the *unchanged*
+# catalog get spuriously flagged. Un-skip once the script tracks the
+# catalog-name discriminator.
+@test "named-catalog change should not flag consumers of unchanged catalog" {
+  skip "Known limitation: catalog flatten loses named-catalog discriminator (PR #168 follow-up)"
+
+  yq -i '
+    .catalogs.alpha."is-number" = "^7.0.0" |
+    .catalogs.beta."is-number"  = "^7.0.0"
+  ' "${WORKSPACE}/pnpm-workspace.yaml"
+
+  # pkg-a → catalog:alpha; pkg-b → catalog:beta.
+  for pair in 'pkg-a:alpha' 'pkg-b:beta'; do
+    name="${pair%:*}"; cat="${pair#*:}"
+    pj="${WORKSPACE}/packages/${name}/package.json"
+    jq --arg c "catalog:${cat}" '.dependencies."is-number" = $c' "${pj}" >"${pj}.tmp"
+    mv "${pj}.tmp" "${pj}"
+  done
+  git -C "${WORKSPACE}" commit --quiet -am 'add named catalogs (alpha, beta)'
+
+  # Bump alpha only — beta is untouched.
+  yq -i '.catalogs.alpha."is-number" = "^7.0.1"' "${WORKSPACE}/pnpm-workspace.yaml"
+  git -C "${WORKSPACE}" commit --quiet -am 'bump alpha catalog only'
+
+  run_check
+  [ "${status}" -eq 1 ]
+  [[ "${output}" == *'@check-coverage-test/pkg-a'* ]]
+  # Currently fails: pkg-b is also flagged because of the catalog flatten.
+  [[ "${output}" != *'@check-coverage-test/pkg-b'* ]]
+}
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/.changeset/config.json b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/.changeset/config.json
new file mode 100644
index 00000000..d71982fe
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/.changeset/config.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.3/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "privatePackages": false,
+  "ignore": []
+}
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/README.md b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/README.md
new file mode 100644
index 00000000..2f5885ba
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/README.md
@@ -0,0 +1,9 @@
+# Test fixture workspace
+
+Minimal pnpm workspace used by `check-coverage` bats tests.
+
+- `packages/pkg-a` and `packages/pkg-b` both consume `is-number` via the catalog.
+- `packages/pkg-c` consumes `is-string` via the catalog.
+- `packages/pkg-private` is marked `private: true` and should never require a bump.
+
+Tests mutate this fixture inside a temp clone — the originals stay untouched.
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/docs/overview.md b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/docs/overview.md
new file mode 100644
index 00000000..224c0ef7
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/docs/overview.md
@@ -0,0 +1,3 @@
+# Overview
+
+Placeholder doc inside the workspace-root `docs/` directory.
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/package.json b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/package.json
new file mode 100644
index 00000000..ec7e4356
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/package.json
@@ -0,0 +1,8 @@
+{
+  "name": "@check-coverage-test/root",
+  "private": true,
+  "version": "0.0.0",
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0"
+  }
+}
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-a/index.js b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-a/index.js
new file mode 100644
index 00000000..02d53827
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-a/index.js
@@ -0,0 +1 @@
+module.exports = require('is-number');
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-a/package.json b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-a/package.json
new file mode 100644
index 00000000..1a24dfaa
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-a/package.json
@@ -0,0 +1,8 @@
+{
+  "name": "@check-coverage-test/pkg-a",
+  "version": "1.0.0",
+  "main": "index.js",
+  "dependencies": {
+    "is-number": "catalog:"
+  }
+}
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-b/index.js b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-b/index.js
new file mode 100644
index 00000000..02d53827
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-b/index.js
@@ -0,0 +1 @@
+module.exports = require('is-number');
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-b/package.json b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-b/package.json
new file mode 100644
index 00000000..7652bbeb
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-b/package.json
@@ -0,0 +1,8 @@
+{
+  "name": "@check-coverage-test/pkg-b",
+  "version": "1.0.0",
+  "main": "index.js",
+  "dependencies": {
+    "is-number": "catalog:"
+  }
+}
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-c/index.js b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-c/index.js
new file mode 100644
index 00000000..8d900016
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-c/index.js
@@ -0,0 +1 @@
+module.exports = require('is-string');
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-c/package.json b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-c/package.json
new file mode 100644
index 00000000..52c31ddf
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-c/package.json
@@ -0,0 +1,8 @@
+{
+  "name": "@check-coverage-test/pkg-c",
+  "version": "1.0.0",
+  "main": "index.js",
+  "dependencies": {
+    "is-string": "catalog:"
+  }
+}
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-private/index.js b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-private/index.js
new file mode 100644
index 00000000..02d53827
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-private/index.js
@@ -0,0 +1 @@
+module.exports = require('is-number');
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-private/package.json b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-private/package.json
new file mode 100644
index 00000000..fdd11a1f
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/packages/pkg-private/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "@check-coverage-test/pkg-private",
+  "version": "1.0.0",
+  "private": true,
+  "main": "index.js",
+  "dependencies": {
+    "is-number": "catalog:"
+  }
+}
diff --git a/actions/changeset/check-coverage/test/fixtures/minimal-workspace/pnpm-workspace.yaml b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/pnpm-workspace.yaml
new file mode 100644
index 00000000..31318b20
--- /dev/null
+++ b/actions/changeset/check-coverage/test/fixtures/minimal-workspace/pnpm-workspace.yaml
@@ -0,0 +1,6 @@
+packages:
+  - packages/*
+
+catalog:
+  is-number: ^7.0.0
+  is-string: ^1.0.7
diff --git a/actions/changeset/check-coverage/test/helpers.bash b/actions/changeset/check-coverage/test/helpers.bash
new file mode 100644
index 00000000..3df0476e
--- /dev/null
+++ b/actions/changeset/check-coverage/test/helpers.bash
@@ -0,0 +1,96 @@
+# Shared helpers for check-coverage bats tests.
+#
+# The expensive step is `pnpm install`. setup_file builds one shared install
+# under $BATS_FILE_TMPDIR/base and each test rsyncs from it — keeps the suite
+# under a few seconds even with many cases.
+
+TEST_DIR="${BATS_TEST_DIRNAME:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
+SCRIPT_UNDER_TEST="${TEST_DIR}/../check-coverage.sh"
+FIXTURE_SRC="${TEST_DIR}/fixtures/minimal-workspace"
+
+# Build the shared, pnpm-installed base workspace with an initial git commit
+# on `main` and a synthesized `origin/main` ref. Setting gc.auto=0 BEFORE the
+# first commit suppresses git's async auto-gc, which would otherwise repack
+# `.git/objects` mid-test and break the per-test tar copy.
+_build_base_workspace() {
+  local base="$1"
+  rm -rf "${base}"
+  cp -R "${FIXTURE_SRC}" "${base}"
+
+  # Capture output to a log file; only emit on failure. Without `set -e`
+  # inside the subshell, a failing `pnpm install` would corrupt the base
+  # silently and every test would then fail with a confusing error pointing
+  # at the script under test, not the install.
+  local log="${BATS_FILE_TMPDIR}/base-setup.log"
+  if ! (
+    set -e
+    cd "${base}"
+    pnpm install --silent --ignore-scripts
+    git init --quiet --initial-branch=main
+    git config gc.auto 0
+    git config gc.autoDetach false
+    git config user.email 'test@example.com'
+    git config user.name  'Test'
+    git add -A
+    git commit --quiet -m 'initial'
+    git update-ref refs/remotes/origin/main main
+  ) >"${log}" 2>&1; then
+    echo "base workspace setup failed; full log:" >&2
+    cat "${log}" >&2
+    return 1
+  fi
+}
+
+# Per-test: copy the base into a fresh workspace and switch to a feature
+# branch. The tar pipe avoids macOS xattr warnings that `cp -R` and
+# openrsync emit when cloning `.git/objects`.
+new_workspace() {
+  WORKSPACE="${BATS_TEST_TMPDIR}/ws"
+  rm -rf "${WORKSPACE}"
+  mkdir -p "${WORKSPACE}"
+  ( cd "${BATS_FILE_TMPDIR}/base" && tar -cf - . ) | ( cd "${WORKSPACE}" && tar -xf - )
+  git -C "${WORKSPACE}" checkout --quiet -b feature
+}
+
+# Run the script in $WORKSPACE with BASE_BRANCH=main. Sets $status and $output.
+run_check() {
+  cd "${WORKSPACE}"
+  BASE_BRANCH=main run "${SCRIPT_UNDER_TEST}"
+}
+
+# Drop a changeset markdown file. Args: bump-spec, then "title".
+# bump-spec is the YAML front-matter body, e.g. '@check-coverage-test/pkg-a: patch'.
+add_changeset() {
+  local body="$1"
+  local title="${2:-test changeset}"
+  local slug
+  slug="$(printf '%s' "${title}" | tr -cs 'a-z0-9' '-' | sed 's/^-\|-$//g')"
+  cat >"${WORKSPACE}/.changeset/${slug}.md" <<EOF
+---
+${body}
+---
+
+${title}
+EOF
+  git -C "${WORKSPACE}" add ".changeset/${slug}.md"
+  git -C "${WORKSPACE}" commit --quiet -m "add changeset: ${title}"
+}
+
+# Edit a file under $WORKSPACE, stage and commit. Args: relpath, content (or
+# defaults to appending a comment).
+touch_file() {
+  local rel="$1" content="${2:-// edit}"
+  mkdir -p "$(dirname "${WORKSPACE}/${rel}")"
+  printf '%s\n' "${content}" >>"${WORKSPACE}/${rel}"
+  git -C "${WORKSPACE}" add "${rel}"
+  git -C "${WORKSPACE}" commit --quiet -m "edit ${rel}"
+}
+
+# Bump a default-catalog entry in pnpm-workspace.yaml. Args: key, new-version.
+bump_catalog() {
+  local key="$1" version="$2"
+  # yq edits in place.
+  yq -i ".catalog.\"${key}\" = \"${version}\"" "${WORKSPACE}/pnpm-workspace.yaml"
+  git -C "${WORKSPACE}" add pnpm-workspace.yaml
+  git -C "${WORKSPACE}" commit --quiet -m "bump catalog ${key} to ${version}"
+}
diff --git a/fix-beta.sh b/fix-beta.sh
new file mode 100755
index 00000000..e5ee2323
--- /dev/null
+++ b/fix-beta.sh
@@ -0,0 +1,94 @@
+#!/bin/bash
+#
+# fix-beta.sh — re-sync v4-beta with v4 after they diverge.
+#
+# Use when:
+#   - Someone committed directly to v4 (bypassing the v4-beta → merge-beta.sh
+#     cycle) and you want v4-beta to incorporate those changes.
+#   - Post-promotion: v4 has the rename-sed commit from merge-beta.sh that
+#     v4-beta does not have; run this script to bring v4-beta back in sync.
+#
+# What it does:
+#   1. Refuses if the working tree is dirty.
+#   2. Re-execs itself from a tmp copy so the script survives the checkout.
+#   3. Switches to v4-beta, pulls latest.
+#   4. Merges v4 in with --strategy-option theirs (v4 content wins on conflict).
+#   5. Sed-flips @v4 -> @v4-beta across action.yaml + .github/workflows/*.yaml
+#      (mirrors merge-beta.sh's file scope, opposite direction).
+#   6. Commits the flip on top of the merge commit and pushes.
+#
+# Inverse of merge-beta.sh.
+#
+# Sed safety, two concerns:
+#   1. Prefix collision. @v4 is a prefix of @v4-beta, so a naive
+#      `s|@v4|@v4-beta|g` would produce @v4-beta-beta. We match @v4 only at
+#      end-of-line or followed by whitespace.
+#   2. Path scope. We must rewrite only milaboratory/github-ci self-refs.
+#      Third-party action pins (actions/checkout@v4, aws-actions/...@v4,
+#      pnpm/action-setup@v4, etc.) must stay at their upstream tags — those
+#      repos do not publish a v4-beta tag, and flipping them produced the
+#      "Unable to resolve action ...@v4-beta" failures fixed in this branch.
+# Both patterns therefore anchor the substitution to a leading
+# `milaboratory/github-ci...` path.
+
+set -o nounset
+set -o errexit
+set -o pipefail
+
+: ${TARGET_BRANCH:="v4-beta"}    # branch being fixed
+: ${SOURCE_BRANCH:="v4"}         # branch being merged in
+
+if git status --porcelain | grep -q .; then
+    echo ""
+    echo "# -------------------------------------------------------------- #"
+    echo "# Repository has local changes. Automatic merge is not possible. #"
+    echo "# -------------------------------------------------------------- #"
+    echo ""
+    git status --porcelain
+    exit 1
+fi
+
+if [ "${__REAL_RUN:-}" != "true" ]; then
+    echo "Copying script to temporary file to not lose original code during checkouts..."
+    tmp_script="$(mktemp)"
+    cat "${0}" > "${tmp_script}"
+    chmod +x "${tmp_script}"
+    __REAL_RUN="true" "${tmp_script}"
+    exit 0
+fi
+
+echo "Updating remote repository info..."
+git fetch --prune origin
+
+echo "Switching to '${TARGET_BRANCH}'..."
+git checkout "${TARGET_BRANCH}"
+git pull --ff-only
+
+echo "Merging 'origin/${SOURCE_BRANCH}' into '${TARGET_BRANCH}' (theirs wins on conflict)..."
+git merge \
+    --no-edit \
+    --message "Merge ${SOURCE_BRANCH} into ${TARGET_BRANCH}" \
+    "origin/${SOURCE_BRANCH}" \
+    --strategy-option theirs
+
+echo "Flipping @${SOURCE_BRANCH} -> @${TARGET_BRANCH} in milaboratory/github-ci self-refs..."
+{
+    find . -type f -name "action.yaml"
+    find .github/workflows -type f -name "*.yaml"
+} |
+    while read -r file; do
+        sed "s|\(milaboratory/github-ci[^[:space:]@]*\)@${SOURCE_BRANCH}\$|\1@${TARGET_BRANCH}|g; s|\(milaboratory/github-ci[^[:space:]@]*\)@${SOURCE_BRANCH}\([[:space:]]\)|\1@${TARGET_BRANCH}\2|g" "${file}" > "${file}.tmp"
+        mv "${file}.tmp" "${file}"
+    done
+
+if git diff --quiet; then
+    echo "No ref flips needed; merge alone was sufficient."
+else
+    git add -A
+    git commit -m "Re-flip @${SOURCE_BRANCH} -> @${TARGET_BRANCH} after merging ${SOURCE_BRANCH}"
+fi
+
+echo "Pushing '${TARGET_BRANCH}'..."
+git push origin "${TARGET_BRANCH}"
+
+echo "Done. ${TARGET_BRANCH} is now in sync with ${SOURCE_BRANCH}, with internal refs restored to @${TARGET_BRANCH}."
diff --git a/merge-beta.sh b/merge-beta.sh
index 9890559b..8906807a 100755
--- a/merge-beta.sh
+++ b/merge-beta.sh
@@ -69,13 +69,18 @@ git merge \
     "${SOURCE_BRANCH}" \
     --strategy-option theirs
 
-# Replace all v4-beta with v4 in all action.yaml and all workflows
+# Replace @v4-beta -> @v4 in milaboratory/github-ci self-refs only.
+# The substitution is anchored to the self-ref repo path so that third-party
+# action pins (actions/checkout@v4-beta, aws-actions/...@v4-beta, etc.) are
+# left alone. Without the anchor the sed would happily rewrite any token
+# ending in @v4-beta, which corrupts third-party refs on v4-beta when the
+# inverse sed (fix-beta.sh) flipped them from @v4 in the first place.
 {
     find . -type f -name "action.yaml"
     find .github/workflows -type f -name "*.yaml"
 } |
     while read -r file; do
-        sed "s/@${SOURCE_BRANCH}/@${TARGET_BRANCH}/g" "${file}" > "${file}.tmp"
+        sed "s|\(milaboratory/github-ci[^[:space:]@]*\)@${SOURCE_BRANCH}|\1@${TARGET_BRANCH}|g" "${file}" > "${file}.tmp"
         mv "${file}.tmp" "${file}"
     done