runspector 0.5.0__tar.gz

runspector-0.5.0/.githooks/pre-push

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Before main moves: what CI would fail on, here, in about a minute. Commits go
+# straight to main and CI only reports afterwards - and `uv tool install
+# git+...runspector` installs whatever main is at that moment.
+#
+#   git config core.hooksPath .githooks      # once per clone, opt-in
+#   git push --no-verify                     # skip, when you know why
+set -e
+cd "$(git rev-parse --show-toplevel)"
+
+zero=0000000000000000000000000000000000000000
+while read -r local_ref local_sha remote_ref remote_sha; do
+    case "$local_ref" in refs/tags/*) continue ;; esac
+    [ "$local_sha" = "$zero" ] && continue
+    [ "$remote_sha" = "$zero" ] && continue
+    changed=$(git diff --name-only "$remote_sha" "$local_sha")
+    # The coach's prompt is code with its own tests: a change to it ships with
+    # an eval run, which is what rewrites evals/RESULTS.md.
+    if echo "$changed" | grep -qE '^src/runspector/skills/|^evals/cases\.yaml$' &&
+       ! echo "$changed" | grep -qx 'evals/RESULTS.md'; then
+        echo "pre-push: the coach prompt or the eval cases changed, evals/RESULTS.md did not."
+        echo "          uv run python evals/run_evals.py   (or --no-verify, and say why)"
+        exit 1
+    fi
+done
+
+uv run ruff check
+uv run pytest -q -x -p no:cacheprovider
+uv run python scripts/pii_gate.py
+# The frontend lint, when node is here at all (same version as ci.yml).
+if command -v npx >/dev/null 2>&1; then
+    npx --yes @biomejs/biome@2.5.15 lint --error-on-warnings
+fi

runspector-0.5.0/.github/dependabot.yml

@@ -0,0 +1,28 @@
+# The workflow pins its actions to commit SHAs, which is only as good as the
+# habit of moving them: the first three pins aged into a Node 20 deprecation
+# notice within a week, and nothing said so. Dependabot files the PR; CI on the
+# PR is the check that the new SHA still does what the old one did.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    # Keeps the `# vX.Y.Z` comment next to the SHA up to date, so the pin stays
+    # readable by a human.
+    commit-message:
+      prefix: "ci"
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    # `garminconnect` tracks an unofficial API; a minor bump there is exactly
+    # the change that needs a human to run `runspector sync` once before merging.
+    commit-message:
+      prefix: "deps"
+    ignore:
+      # `pyproject.toml` pins `mcp<2` on purpose: 2.x renamed FastMCP and
+      # changed the server API. Dependabot's very first PR proposed 2.2.0
+      # anyway and CI rejected it; a major bump there is a port, not a bump.
+      - dependency-name: mcp
+        update-types: ["version-update:semver-major"]

runspector-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,142 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# One matrix per branch. Pushing twice in a minute otherwise leaves the first
+# six legs running against a commit nobody is waiting for any more. A push to
+# `main` is not cancelled: its result is the badge.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# Least privilege: nothing in this workflow writes to the repo, packages or
+# releases. Job-level grants stay opt-in from here.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    # The slowest leg (Windows) measures three to four minutes, so fifteen is
+    # around four times the headroom and still catches a hang early. Without it
+    # the default is six HOURS per leg — and this suite has already had one:
+    # headless Chrome on the macOS runners never returns, it only ever hit a
+    # timeout inside the test.
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        # `requires-python = ">=3.12"` is a promise about every version above it;
+        # one unpinned interpreter per OS tested none of them in particular.
+        python: ["3.12", "3.13"]
+        # Coverage is measured on ONE leg: the number is the same code on every
+        # OS, but a floor checked six times fails on whichever leg skips the most
+        # platform branches. 93 % at the time the floor was set (v0.4.1); the
+        # floor only stops it from eroding unnoticed.
+        include:
+          - os: ubuntu-latest
+            python: "3.12"
+            coverage: coverage   # the value lands in the check's name: keep it short
+    runs-on: ${{ matrix.os }}
+    steps:
+      # Actions are pinned to commit SHAs, not tags: a tag is mutable, and these
+      # three run with access to the workflow token before any test does.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: ${{ matrix.python }}
+          # Keyed on uv.lock, so the cache is only reused for the exact
+          # dependency set it was built from.
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+      # The matrix is only real if the interpreter actually changes with it.
+      # `.python-version` pins the local dev interpreter and could quietly win
+      # over the matrix, which would leave one leg testing the other's version
+      # and the README claiming two. So every `uv run` names the version, and
+      # this step fails the job if what arrives is not what was asked for.
+      - name: The interpreter is the one this leg is for
+        run: |
+          uv run --python ${{ matrix.python }} python -c "import sys; got = '%d.%d' % sys.version_info[:2]; want = '${{ matrix.python }}'; print('running', got); raise SystemExit(0 if got == want else f'expected {want}, got {got}')"
+
+      - name: Lint
+        run: uv run --python ${{ matrix.python }} ruff check
+      - name: Python tests (no database server, no network, no Garmin account)
+        shell: bash   # one syntax for the empty $COVERAGE on every leg, Windows included
+        env:
+          COVERAGE: ${{ matrix.coverage && '--cov=runspector --cov-branch --cov-report=term:skip-covered --cov-fail-under=92' || '' }}
+          # Outside the tree: the data file holds absolute paths, and pii_gate
+          # (two steps down) reads every file in the checkout.
+          COVERAGE_FILE: ${{ runner.temp }}/.coverage
+        run: uv run --python ${{ matrix.python }} pytest -q $COVERAGE
+      - name: Frontend logic tests
+        run: node --test "web-tests/*.test.mjs"
+      - name: Eval suite is well-formed (dry run, no model calls)
+        run: uv run --python ${{ matrix.python }} python evals/run_evals.py --dry-run
+      - name: Nothing personal in the tree
+        run: uv run --python ${{ matrix.python }} python scripts/pii_gate.py
+
+  # The shipped frontend has no build step, so nothing reads it before a
+  # browser does. Biome lints it (rules and the reasons for the ones switched
+  # off: biome.jsonc). Once, not per leg: the result cannot depend on the OS.
+  frontend:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+          package-manager-cache: false   # no package.json, nothing to cache
+      - name: Biome
+        run: npx --yes @biomejs/biome@2.5.15 lint --error-on-warnings
+
+  # The suite above proves the code from inside the checkout. This job proves
+  # the PACKAGE from outside it: build the wheel, `uv tool install` it into a
+  # throw-away tool dir the way a user would, and drive the installed
+  # executable through the README's quick start - demo over HTTP, doctor,
+  # sync, login without a terminal, the MCP handshake. It is the "other
+  # computer" the author does not have: a machine that has never seen the
+  # source tree. Standard-library Python drives it, so it runs on whatever
+  # interpreter the runner has, and the installed tool brings its own.
+  install:
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.12"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install the wheel as a user and use it as one
+        run: uv run --no-project python scripts/install_check.py
+
+  # The workflows themselves, audited: unpinned actions, template injection,
+  # credentials left in the checkout, caches feeding a release. Every workflow
+  # here runs with a token, and a Dependabot PR edits them weekly.
+  workflows:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - name: zizmor
+        run: uvx zizmor@1.31.1 --min-severity medium .github/workflows

runspector-0.5.0/.github/workflows/evals.yml

@@ -0,0 +1,143 @@
+name: evals
+
+# The coach-prompt evals (evals/run_evals.py) with a real model, once a week -
+# but only in a week in which main moved: an unchanged prompt on an unchanged
+# model measures the weather and spends the subscription for it. By hand
+# (workflow_dispatch) it always runs.
+#
+# The model calls go through the maintainer's Claude subscription: the secret
+# CLAUDE_CODE_OAUTH_TOKEN (from `claude setup-token`, valid one year) lives in
+# the environment `evals`, which only `main` may use. Forks and pull requests
+# never see it, and the job that decides whether to run does not touch it, so
+# a quiet week spends nothing. The result is the job summary and an artifact;
+# evals/RESULTS.md and the README badge stay a local, committed record.
+#
+# Renew the token:
+#   claude setup-token
+#   gh secret set CLAUDE_CODE_OAUTH_TOKEN --env evals -R edxleon/runspector
+#   gh variable set CLAUDE_TOKEN_CREATED --body YYYY-MM-DD -R edxleon/runspector
+
+on:
+  schedule:
+    - cron: "41 5 * * 1"     # Mondays, 05:41 UTC - after the sweep
+  workflow_dispatch:
+
+concurrency:
+  group: evals
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  changed:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      run: ${{ steps.check.outputs.run }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+          fetch-depth: 0               # the last week of history, not one commit
+      - name: Did main move in the last 7 days?
+        id: check
+        env:
+          EVENT: ${{ github.event_name }}
+        run: |
+          commits=$(git log --since="7 days ago" --format='%h %s' HEAD)
+          if [ "$EVENT" = "workflow_dispatch" ]; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+            echo "started by hand - the evals run"
+          elif [ -n "$commits" ]; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+            echo "commits on main in the last 7 days:"; echo "$commits"
+          else
+            echo "run=false" >> "$GITHUB_OUTPUT"
+            echo "no commit on main in the last 7 days - no evals, nothing spent" | tee -a "$GITHUB_STEP_SUMMARY"
+          fi
+
+  evals:
+    needs: changed
+    if: needs.changed.outputs.run == 'true'
+    runs-on: ubuntu-latest
+    environment: evals
+    # 29 cases at ~20 s for the answer and ~10 s for the judge: about 15 min.
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.12"
+          # No cache in the one job that holds the token: a cache any workflow
+          # run can write must not feed a step that sees it.
+          enable-cache: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+          package-manager-cache: false   # same reason as above
+      # Pinned: the version the committed evals/RESULTS.md was produced with.
+      # A new CLI is a deliberate bump here, not a surprise in a red run.
+      - name: Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code@2.1.312
+
+      - name: How long the token has left
+        env:
+          CREATED: ${{ vars.CLAUDE_TOKEN_CREATED }}
+        run: |
+          python3 - <<'EOF'
+          import datetime as dt, os
+          created = os.environ.get("CREATED", "").strip()
+          if not created:
+              print("::notice::set CLAUDE_TOKEN_CREATED (gh variable set ...) to be warned before the token expires")
+              raise SystemExit(0)
+          expires = dt.date.fromisoformat(created) + dt.timedelta(days=365)
+          left = (expires - dt.date.today()).days
+          print(f"Claude token created {created}, expires {expires} ({left} days)")
+          if left <= 30:
+              print(f"::warning::the Claude token expires on {expires} ({left} days) - renew it, see the head of evals.yml")
+          EOF
+
+      # One call before the suite: an expired or revoked token is one clear line, not
+      # every case red with the same auth error.
+      - name: The token works
+        env:
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          if [ -z "$CLAUDE_CODE_OAUTH_TOKEN" ]; then
+            echo "::error::no CLAUDE_CODE_OAUTH_TOKEN in the environment 'evals'"; exit 1
+          fi
+          if ! out=$(echo "Reply with the single word OK." |
+                     claude --print --safe-mode --tools "" --model sonnet 2>&1); then
+            echo "::error::Claude refused the token (expired, revoked or out of quota) - renew: claude setup-token, then gh secret set CLAUDE_CODE_OAUTH_TOKEN --env evals -R edxleon/runspector"
+            echo "$out" | tail -n 3
+            exit 1
+          fi
+          echo "token ok"
+
+      - name: Evals
+        env:
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        # pyyaml comes from the dev group in uv.lock, hash-checked (--locked):
+        # `--with pyyaml` would pull whatever PyPI serves today into the one
+        # job that holds the token.
+        run: uv run --python 3.12 --locked python evals/run_evals.py
+
+      - name: Result as the job summary
+        if: always()
+        run: |
+          if [ -f evals/RESULTS.md ]; then cat evals/RESULTS.md >> "$GITHUB_STEP_SUMMARY"; fi
+
+      # The answers and the judge's reasons of every case: what a red case is
+      # read from. Synthetic athletes only - nothing personal is in them.
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: evals-${{ github.run_number }}
+          path: |
+            evals/RESULTS.md
+            evals/last-run.json
+          retention-days: 30
+          if-no-files-found: ignore

runspector-0.5.0/.github/workflows/mutation.yml

@@ -0,0 +1,126 @@
+name: mutation
+
+# Mutation testing of the rule modules (`[tool.mutmut]` in pyproject.toml), once
+# a week. 93 % branch coverage says the tests RUN the rules; this says whether
+# they would NOTICE a rule changing: mutmut flips a comparison, a constant, an
+# `and` into an `or`, runs the tests that cover that function, and a mutant no
+# test kills is a change to the coach's decisions that would ship green.
+#
+# Code written with an AI and tested by the same AI tends to test what the code
+# does rather than what it should do; a survivor is where that shows. It is
+# the bug hunt, like sweep.yml, not a gate: survivors are expected, and the
+# useful ones become a scenario test in tests/test_what_comes_next.py, red
+# against the mutant first. Linux only: mutmut needs a clean fork().
+#
+# One job per module, side by side: all ~5,600 mutants on one 4-core runner
+# do not fit in three hours. Measured per module, 4 workers in a Linux
+# container (v0.4.1): habits 601 mutants in 4 min, planning 1,559 in 23, plan
+# 2,387 in 26; the summary 1-2 min after that.
+
+on:
+  schedule:
+    - cron: "23 2 * * 1"     # Mondays, 02:23 UTC
+  workflow_dispatch:
+
+concurrency:
+  group: mutation
+  cancel-in-progress: false   # a run by hand waits; it does not cancel the Monday run
+
+permissions:
+  contents: read
+
+jobs:
+  mutation:
+    strategy:
+      fail-fast: false
+      matrix:
+        module: [logic, planning, plan, habits]
+    runs-on: ubuntu-latest
+    timeout-minutes: 150
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.12"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      # The suite runs the shipped logic.js through node (test_js_python_contract).
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+          package-manager-cache: false
+
+      # mutmut and its dependencies come from the `mutation` group in uv.lock,
+      # hash-checked: `--with` would resolve them fresh from PyPI every week,
+      # into a job whose uv cache ci.yml and sweep.yml restore.
+      # Red only when mutmut itself cannot run (the clean suite fails in its
+      # copy of the tree) - surviving mutants are the result, not an error.
+      - name: Mutate the rule modules
+        # Its own limit, under the job's: the summary and the artifact still
+        # run after a cancel, and mutmut has saved every result so far.
+        timeout-minutes: 120
+        env:
+          MODULE: ${{ matrix.module }}
+        run: uv run --python 3.12 --locked --group mutation mutmut run --max-children 4 "runspector.$MODULE.*"
+
+      - name: Survivors as the job summary
+        if: always()
+        env:
+          MODULE: ${{ matrix.module }}
+        run: |
+          # `mutmut results` lists every mutant not killed, of every module (the
+          # other jobs' as "not checked"). Only this module's `survived` is a
+          # test that is missing; `timeout` and `no tests` are counted apart.
+          uv run --python 3.12 --locked --group mutation mutmut results \
+            | grep -E "^ *runspector\.$MODULE\." > results.txt || true
+          grep -E ': survived$' results.txt > survivors.txt || true
+          {
+            echo "## $MODULE.py - surviving mutants: $(wc -l < survivors.txt)"
+            echo
+            echo "Not survived, not killed: $(grep -cvE ': survived$' results.txt || true)"
+            echo "($(cut -d: -f2 results.txt | grep -vx ' survived' | sort | uniq -c | tr '\n' ' '))"
+            echo
+            echo "Per function (the full diffs are in the artifact):"
+            echo '```'
+            sed -E 's/__mutmut_[0-9]+.*//' survivors.txt | sort | uniq -c | sort -nr
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          # The diffs in one pass: `mutmut show` re-parses the whole mutated
+          # module per call (12 s for plan.py), which for a few hundred
+          # survivors outlasts the job. The mutated file holds every mutant as
+          # `<name>__mutmut_N` next to `<name>__mutmut_orig`.
+          python3 - survivors.txt > survivors.diff <<'PY'
+          import ast, difflib, os, sys
+
+          module = os.environ["MODULE"]
+          path = f"mutants/src/runspector/{module}.py"
+          source = open(path, encoding="utf-8").read()
+          funcs = {n.name: n for n in ast.walk(ast.parse(source))
+                   if isinstance(n, ast.FunctionDef | ast.AsyncFunctionDef)}
+          for line in open(sys.argv[1], encoding="utf-8"):
+              key = line.split(":")[0].strip()
+              name = key.removeprefix(f"runspector.{module}.")
+              base = name.rpartition("__mutmut_")[0]
+              orig, mutant = funcs.get(base + "__mutmut_orig"), funcs.get(name)
+              if orig is None or mutant is None:
+                  print(f"# {key}: not in {path}\n")
+                  continue
+              a = ast.get_source_segment(source, orig).replace(base + "__mutmut_orig", base)
+              b = ast.get_source_segment(source, mutant).replace(name, base)
+              print(f"# {key}")
+              print("\n".join(difflib.unified_diff(a.splitlines(), b.splitlines(), "original",
+                                                   "mutant", lineterm="", n=2)) + "\n")
+          PY
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: mutation-${{ github.run_number }}-${{ matrix.module }}
+          path: |
+            results.txt
+            survivors.txt
+            survivors.diff
+          retention-days: 30
+          if-no-files-found: ignore

runspector-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,188 @@
+name: release
+
+# A pushed tag `vX.Y.Z` becomes the GitHub release, with the wheel and the
+# sdist built HERE and signed with a build-provenance attestation, the same
+# files on PyPI, and the MCP registry entry pointing at them. `build` and
+# `test` run without rights; `release`, `pypi` and `mcp-registry` hold only the
+# rights their own step needs and run no project code. Until now a
+# release was four hand steps on one laptop (bump, build, create, upload), and
+# nothing checked that the tag, `pyproject.toml` and `__version__` agree - a
+# wheel named 0.3.0 on a v0.3.1 release would have passed.
+#
+#   git tag v0.3.2 && git push origin v0.3.2
+#
+# The notes come from `docs/releases/<tag>.md` when it exists, else GitHub
+# generates them from the commits. A release that already exists (created by
+# hand) keeps its notes and gets the files attached.
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  # The suite, with no rights at all. Everything the tests import - this code
+  # and every dependency - runs here, so it must not run where the job can
+  # mint an OIDC token or write a release.
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.12"
+          enable-cache: false   # no cache anywhere on the way to a release
+      # The Python suite runs the shipped logic.js through node
+      # (tests/test_js_python_contract.py): the same node as ci.yml.
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+          package-manager-cache: false
+      - name: The tag, pyproject.toml, __version__ and server.json name the same version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          uv run --python 3.12 --locked python - <<'EOF'
+          import json, os, re, tomllib
+          tag = os.environ["TAG"].removeprefix("v")
+          project = tomllib.load(open("pyproject.toml", "rb"))["project"]["version"]
+          init = re.search(r'__version__ = "([^"]+)"', open("src/runspector/__init__.py").read())[1]
+          # The registry entry pins the PyPI version a client installs: a stale
+          # one would hand every new user the previous release.
+          server = json.load(open("server.json"))
+          listed = [server["version"], *(p["version"] for p in server["packages"])]
+          print(f"tag {tag}, pyproject {project}, __version__ {init}, server.json {listed}")
+          raise SystemExit(0 if {tag, project, init, *listed} == {tag}
+                           else "versions disagree - bump all of them, re-tag")
+          EOF
+      # The matrix in ci.yml ran on this commit when it reached main; this is
+      # the short version again, so a tag on a commit that never went through
+      # CI (or a red one) cannot become a release.
+      - name: Lint and tests
+        run: |
+          uv run --python 3.12 --locked ruff check
+          uv run --python 3.12 --locked pytest -q
+          uv run --python 3.12 --locked python scripts/pii_gate.py
+
+  # The package, built with no rights: `uv build` runs the build backend
+  # (hatchling, pinned exactly in pyproject.toml) and nothing of this project.
+  # Built before anything else touches the tree, and handed on as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.12"
+          enable-cache: false   # no cache anywhere on the way to a release
+      - name: Build
+        run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          retention-days: 1
+          if-no-files-found: error
+
+  # Attest and publish - no Python, no project code, no dependency runs here,
+  # only the checkout (for the notes file), GitHub's attest action and `gh`.
+  release:
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write        # create the release, upload its files
+      id-token: write        # the attestation's OIDC identity
+      attestations: write    # store the attestation
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: dist/*
+
+      - name: Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber
+          elif [ -f "docs/releases/$TAG.md" ]; then
+            gh release create "$TAG" dist/* --verify-tag --title "$TAG" --notes-file "docs/releases/$TAG.md"
+          else
+            gh release create "$TAG" dist/* --verify-tag --title "$TAG" --generate-notes
+          fi
+
+  # PyPI through a trusted publisher: no token exists anywhere, PyPI trusts the
+  # OIDC identity of this workflow in the `pypi` environment. Like `release`, it
+  # runs no project code and uploads the files `build` made. After `release`, not
+  # beside it: a version on PyPI can never be replaced, so it goes out only once
+  # the attestation and the GitHub release for exactly these files exist.
+  pypi:
+    needs: [release]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write        # the trusted-publisher identity, nothing else
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  # The MCP registry entry points at the PyPI package and checks the `mcp-name`
+  # line in its README, so it runs after `pypi`. mcp-publisher is a downloaded
+  # binary in a job that can mint an OIDC token: pinned to a version and checked
+  # against the hash taken when it was pinned, so nothing floats in here.
+  mcp-registry:
+    needs: [pypi]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      id-token: write        # the registry's GitHub OIDC login for io.github.edxleon/*
+    env:
+      MCP_PUBLISHER_VERSION: v1.8.1
+      MCP_PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false   # nothing here pushes; no token left in .git/config
+      - name: mcp-publisher, verified
+        run: |
+          curl -fsSL -o mcp-publisher.tar.gz \
+            "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz"
+          echo "${MCP_PUBLISHER_SHA256}  mcp-publisher.tar.gz" | sha256sum -c -
+          tar -xzf mcp-publisher.tar.gz mcp-publisher
+      # PyPI serves a fresh upload's README a little after the upload returns,
+      # and the registry reads it from there - so a few tries, not one.
+      - name: Publish server.json
+        run: |
+          ./mcp-publisher login github-oidc
+          for attempt in 1 2 3 4 5 6; do
+            ./mcp-publisher publish && exit 0
+            echo "attempt $attempt failed - PyPI may not show the new release yet"
+            sleep 30
+          done
+          exit 1